pcileechfwgenerator 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of pcileechfwgenerator might be problematic. Click here for more details.
- pcileechfwgenerator-2.0.0/.dockerignore +130 -0
- pcileechfwgenerator-2.0.0/CHANGELOG.md +184 -0
- pcileechfwgenerator-2.0.0/CONTRIBUTING.md +408 -0
- pcileechfwgenerator-2.0.0/Containerfile +101 -0
- pcileechfwgenerator-2.0.0/LICENSE +201 -0
- pcileechfwgenerator-2.0.0/MANIFEST.in +49 -0
- pcileechfwgenerator-2.0.0/PKG-INFO +557 -0
- pcileechfwgenerator-2.0.0/README.md +501 -0
- pcileechfwgenerator-2.0.0/docs/BEHAVIOR_PROFILING.md +220 -0
- pcileechfwgenerator-2.0.0/docs/CROSS_PLATFORM_SUPPORT.md +187 -0
- pcileechfwgenerator-2.0.0/docs/DEVELOPMENT.md +103 -0
- pcileechfwgenerator-2.0.0/docs/INSTALLATION.md +426 -0
- pcileechfwgenerator-2.0.0/docs/QUICK_START.md +266 -0
- pcileechfwgenerator-2.0.0/docs/TEST_SUITE_README.md +439 -0
- pcileechfwgenerator-2.0.0/docs/TUI_README.md +444 -0
- pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/PKG-INFO +557 -0
- pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/SOURCES.txt +77 -0
- pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/dependency_links.txt +1 -0
- pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/entry_points.txt +4 -0
- pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/requires.txt +25 -0
- pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/top_level.txt +1 -0
- pcileechfwgenerator-2.0.0/pyproject.toml +179 -0
- pcileechfwgenerator-2.0.0/pytest.ini +29 -0
- pcileechfwgenerator-2.0.0/requirements-dev.txt +41 -0
- pcileechfwgenerator-2.0.0/requirements-test.txt +44 -0
- pcileechfwgenerator-2.0.0/requirements-tui.txt +17 -0
- pcileechfwgenerator-2.0.0/requirements.txt +8 -0
- pcileechfwgenerator-2.0.0/setup.cfg +4 -0
- pcileechfwgenerator-2.0.0/setup.py +11 -0
- pcileechfwgenerator-2.0.0/src/__init__.py +28 -0
- pcileechfwgenerator-2.0.0/src/__version__.py +16 -0
- pcileechfwgenerator-2.0.0/src/advanced_sv_error.py +432 -0
- pcileechfwgenerator-2.0.0/src/advanced_sv_generator.py +1719 -0
- pcileechfwgenerator-2.0.0/src/advanced_sv_main.py +684 -0
- pcileechfwgenerator-2.0.0/src/advanced_sv_perf.py +616 -0
- pcileechfwgenerator-2.0.0/src/advanced_sv_power.py +367 -0
- pcileechfwgenerator-2.0.0/src/behavior_profiler.py +920 -0
- pcileechfwgenerator-2.0.0/src/build.py +1572 -0
- pcileechfwgenerator-2.0.0/src/donor_dump/Makefile +99 -0
- pcileechfwgenerator-2.0.0/src/donor_dump/README.md +271 -0
- pcileechfwgenerator-2.0.0/src/donor_dump/donor_dump.c +416 -0
- pcileechfwgenerator-2.0.0/src/donor_dump_manager.py +862 -0
- pcileechfwgenerator-2.0.0/src/flash_fpga.py +38 -0
- pcileechfwgenerator-2.0.0/src/generate_cli.py +33 -0
- pcileechfwgenerator-2.0.0/src/manufacturing_variance.py +463 -0
- pcileechfwgenerator-2.0.0/src/scripts/driver_scrape.py +693 -0
- pcileechfwgenerator-2.0.0/src/state_machine_extractor.py +845 -0
- pcileechfwgenerator-2.0.0/src/tui/__init__.py +13 -0
- pcileechfwgenerator-2.0.0/src/tui/core/__init__.py +13 -0
- pcileechfwgenerator-2.0.0/src/tui/core/build_orchestrator.py +977 -0
- pcileechfwgenerator-2.0.0/src/tui/core/config_manager.py +245 -0
- pcileechfwgenerator-2.0.0/src/tui/core/device_manager.py +271 -0
- pcileechfwgenerator-2.0.0/src/tui/core/status_monitor.py +307 -0
- pcileechfwgenerator-2.0.0/src/tui/main.py +794 -0
- pcileechfwgenerator-2.0.0/src/tui/models/__init__.py +18 -0
- pcileechfwgenerator-2.0.0/src/tui/models/config.py +177 -0
- pcileechfwgenerator-2.0.0/src/tui/models/device.py +74 -0
- pcileechfwgenerator-2.0.0/src/tui/models/error.py +174 -0
- pcileechfwgenerator-2.0.0/src/tui/models/progress.py +125 -0
- pcileechfwgenerator-2.0.0/src/tui/styles/main.tcss +190 -0
- pcileechfwgenerator-2.0.0/src/tui_cli.py +45 -0
- pcileechfwgenerator-2.0.0/tests/test_advanced_sv.py +680 -0
- pcileechfwgenerator-2.0.0/tests/test_behavior_profiler.py +733 -0
- pcileechfwgenerator-2.0.0/tests/test_build.py +673 -0
- pcileechfwgenerator-2.0.0/tests/test_build_integration.py +565 -0
- pcileechfwgenerator-2.0.0/tests/test_donor_dump.py +1073 -0
- pcileechfwgenerator-2.0.0/tests/test_driver_scrape.py +740 -0
- pcileechfwgenerator-2.0.0/tests/test_external_integration.py +591 -0
- pcileechfwgenerator-2.0.0/tests/test_flash_fpga.py +522 -0
- pcileechfwgenerator-2.0.0/tests/test_generate.py +662 -0
- pcileechfwgenerator-2.0.0/tests/test_integration.py +544 -0
- pcileechfwgenerator-2.0.0/tests/test_local_build.py +391 -0
- pcileechfwgenerator-2.0.0/tests/test_manufacturing_variance.py +230 -0
- pcileechfwgenerator-2.0.0/tests/test_pci_validation.py +138 -0
- pcileechfwgenerator-2.0.0/tests/test_profiler_generator_compatibility.py +279 -0
- pcileechfwgenerator-2.0.0/tests/test_profiler_integration.py +283 -0
- pcileechfwgenerator-2.0.0/tests/test_state_machine_extractor.py +744 -0
- pcileechfwgenerator-2.0.0/tests/test_sv_validation.py +347 -0
- pcileechfwgenerator-2.0.0/tests/test_tcl_validation.py +186 -0
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Git files and version control
|
|
2
|
+
.git/
|
|
3
|
+
.gitignore
|
|
4
|
+
.gitattributes
|
|
5
|
+
.gitmodules
|
|
6
|
+
|
|
7
|
+
# Documentation and markdown files
|
|
8
|
+
README.md
|
|
9
|
+
*.md
|
|
10
|
+
docs/
|
|
11
|
+
CHANGELOG*
|
|
12
|
+
CONTRIBUTING*
|
|
13
|
+
AUTHORS*
|
|
14
|
+
|
|
15
|
+
# Build artifacts and output
|
|
16
|
+
output/
|
|
17
|
+
build/
|
|
18
|
+
dist/
|
|
19
|
+
*.bin
|
|
20
|
+
*.bit
|
|
21
|
+
*.log
|
|
22
|
+
*.out
|
|
23
|
+
*.exe
|
|
24
|
+
*.dll
|
|
25
|
+
*.dylib
|
|
26
|
+
*.a
|
|
27
|
+
*.lib
|
|
28
|
+
|
|
29
|
+
# Python cache and bytecode
|
|
30
|
+
__pycache__/
|
|
31
|
+
*.pyc
|
|
32
|
+
*.pyo
|
|
33
|
+
*.pyd
|
|
34
|
+
.Python
|
|
35
|
+
*.so
|
|
36
|
+
*.egg-info/
|
|
37
|
+
.pytest_cache/
|
|
38
|
+
.coverage
|
|
39
|
+
.tox/
|
|
40
|
+
.mypy_cache/
|
|
41
|
+
.dmypy.json
|
|
42
|
+
dmypy.json
|
|
43
|
+
|
|
44
|
+
# IDE and editor files
|
|
45
|
+
.vscode/
|
|
46
|
+
.idea/
|
|
47
|
+
*.swp
|
|
48
|
+
*.swo
|
|
49
|
+
*~
|
|
50
|
+
.vim/
|
|
51
|
+
.emacs.d/
|
|
52
|
+
*.sublime-*
|
|
53
|
+
|
|
54
|
+
# OS-specific files
|
|
55
|
+
.DS_Store
|
|
56
|
+
.DS_Store?
|
|
57
|
+
._*
|
|
58
|
+
.Spotlight-V100
|
|
59
|
+
.Trashes
|
|
60
|
+
ehthumbs.db
|
|
61
|
+
Thumbs.db
|
|
62
|
+
desktop.ini
|
|
63
|
+
|
|
64
|
+
# Temporary and cache files
|
|
65
|
+
*.tmp
|
|
66
|
+
*.temp
|
|
67
|
+
*.cache
|
|
68
|
+
/tmp/
|
|
69
|
+
.cache/
|
|
70
|
+
node_modules/
|
|
71
|
+
|
|
72
|
+
# Container and deployment files
|
|
73
|
+
Containerfile
|
|
74
|
+
Dockerfile*
|
|
75
|
+
.dockerignore
|
|
76
|
+
docker-compose*.yml
|
|
77
|
+
.env
|
|
78
|
+
.env.*
|
|
79
|
+
|
|
80
|
+
# Installation and setup scripts (not needed in container)
|
|
81
|
+
install.sh
|
|
82
|
+
setup.sh
|
|
83
|
+
configure.sh
|
|
84
|
+
|
|
85
|
+
# License and legal files (not needed for runtime)
|
|
86
|
+
LICENSE*
|
|
87
|
+
COPYING*
|
|
88
|
+
COPYRIGHT*
|
|
89
|
+
|
|
90
|
+
# Test files and directories
|
|
91
|
+
tests/
|
|
92
|
+
test/
|
|
93
|
+
*_test.py
|
|
94
|
+
test_*.py
|
|
95
|
+
*.test
|
|
96
|
+
|
|
97
|
+
# Configuration files that shouldn't be in container
|
|
98
|
+
.editorconfig
|
|
99
|
+
.pre-commit-config.yaml
|
|
100
|
+
pyproject.toml
|
|
101
|
+
setup.cfg
|
|
102
|
+
tox.ini
|
|
103
|
+
|
|
104
|
+
# Backup files
|
|
105
|
+
*.bak
|
|
106
|
+
*.backup
|
|
107
|
+
*.orig
|
|
108
|
+
*.rej
|
|
109
|
+
|
|
110
|
+
# Archive files
|
|
111
|
+
*.tar
|
|
112
|
+
*.tar.gz
|
|
113
|
+
*.tar.bz2
|
|
114
|
+
*.tar.xz
|
|
115
|
+
*.zip
|
|
116
|
+
*.rar
|
|
117
|
+
*.7z
|
|
118
|
+
|
|
119
|
+
# Security and secrets (extra safety)
|
|
120
|
+
*.key
|
|
121
|
+
*.pem
|
|
122
|
+
*.crt
|
|
123
|
+
*.p12
|
|
124
|
+
secrets/
|
|
125
|
+
.secrets/
|
|
126
|
+
|
|
127
|
+
flash_fpga.py
|
|
128
|
+
.github/
|
|
129
|
+
.pytest_cache/
|
|
130
|
+
.benchmarks/
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# 📝 Changelog
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/py/pcileech-fw-generator)
|
|
4
|
+
[](https://pypi.org/project/pcileech-fw-generator/)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
|
|
7
|
+
All notable changes to the PCILeech Firmware Generator will be documented in this file.
|
|
8
|
+
|
|
9
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
10
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v0.1.2.html).
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 📑 Table of Contents
|
|
15
|
+
|
|
16
|
+
- [Version 2.0.0 (2025-01-02)](#200---2025-01-02)
|
|
17
|
+
- [Version 1.0.0 (2024-12-01)](#100---2024-12-01)
|
|
18
|
+
- [Release Notes](#release-notes)
|
|
19
|
+
- [Backward Compatibility](#backward-compatibility)
|
|
20
|
+
- [Future Roadmap](#future-roadmap)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## [Unreleased] - Container Flow Improvements
|
|
25
|
+
|
|
26
|
+
### 🔧 Fixed
|
|
27
|
+
- **🐳 Container Dependency Installation**: Fixed missing Python dependencies in container build
|
|
28
|
+
- Added proper `pip install` commands for `requirements.txt` and `requirements-tui.txt`
|
|
29
|
+
- Fixed import errors for `psutil`, `pydantic`, and other required packages
|
|
30
|
+
- **📁 Container File Structure**: Corrected file paths and directory structure
|
|
31
|
+
- Fixed `build.py` path from `/app/build.py` to `/app/src/build.py`
|
|
32
|
+
- Updated all container usage examples and documentation
|
|
33
|
+
- **🔒 Container Security Improvements**: Enhanced security posture
|
|
34
|
+
- Replaced `--privileged` with specific capabilities (`--cap-add=SYS_RAWIO --cap-add=SYS_ADMIN`)
|
|
35
|
+
- Maintained non-root user execution while preserving functionality
|
|
36
|
+
- **✅ Container Health Checks**: Improved dependency validation
|
|
37
|
+
- Enhanced health check to validate Python imports
|
|
38
|
+
- Added comprehensive dependency testing
|
|
39
|
+
|
|
40
|
+
### ✨ Added
|
|
41
|
+
- **🔨 Container Build Script**: New automated build and test script
|
|
42
|
+
- Added `scripts/build_container.sh` with comprehensive testing
|
|
43
|
+
- Supports both Podman and Docker container engines
|
|
44
|
+
- Includes security validation and usage examples
|
|
45
|
+
- **🚀 Container CI Pipeline**: Automated container testing workflow
|
|
46
|
+
- Added `.github/workflows/container-ci.yml` for continuous integration
|
|
47
|
+
- Tests container build, dependencies, security, and integration
|
|
48
|
+
- Validates file structure and user permissions
|
|
49
|
+
|
|
50
|
+
### 📚 Improved
|
|
51
|
+
- **📖 Documentation Updates**: Enhanced container usage documentation
|
|
52
|
+
- Updated `podman_demo.md` with security best practices
|
|
53
|
+
- Added troubleshooting section for container issues
|
|
54
|
+
- Included capability-based security examples
|
|
55
|
+
|
|
56
|
+
### 🗂️ Changed
|
|
57
|
+
- **📦 Container File Inclusion**: Updated `.dockerignore` configuration
|
|
58
|
+
- Removed exclusion of `src/tui/` components
|
|
59
|
+
- Included necessary requirements files
|
|
60
|
+
- Optimized build context for better performance
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## [2.0.0] - 2025-01-02
|
|
65
|
+
|
|
66
|
+
### ✨ Added
|
|
67
|
+
- **🖥️ Interactive TUI Interface**: Complete text-based user interface with real-time monitoring
|
|
68
|
+
- Visual PCIe device browser with enhanced device information
|
|
69
|
+
- Guided configuration workflows with validation
|
|
70
|
+
- Real-time build monitoring with progress tracking
|
|
71
|
+
- System status monitoring for Podman, Vivado, USB devices
|
|
72
|
+
- Intelligent error guidance with suggested fixes
|
|
73
|
+
- Profile management for build configurations
|
|
74
|
+
- **📦 Enhanced Package Structure**: Professional Python packaging with pip installability
|
|
75
|
+
- Console script entry points (`pcileech-generate`, `pcileech-tui`, `pcileech-build`)
|
|
76
|
+
- Proper package metadata and dependency management
|
|
77
|
+
- Optional TUI dependencies for lightweight installations
|
|
78
|
+
- **⚡ Advanced SystemVerilog Features**: Comprehensive PCIe device controller improvements
|
|
79
|
+
- Modular architecture with enhanced power management
|
|
80
|
+
- Performance counters and monitoring capabilities
|
|
81
|
+
- Error handling and recovery mechanisms
|
|
82
|
+
- Manufacturing variance simulation for realistic behavior
|
|
83
|
+
- **📊 Behavioral Profiling**: Dynamic device behavior capture and simulation
|
|
84
|
+
- Real-time register access pattern analysis
|
|
85
|
+
- Timing characteristic profiling
|
|
86
|
+
- Device-specific behavior modeling
|
|
87
|
+
- **🧪 Quality Assurance**: Comprehensive testing and code quality tools
|
|
88
|
+
- Unit and integration test suites
|
|
89
|
+
- Code formatting with Black and isort
|
|
90
|
+
- Type checking with mypy
|
|
91
|
+
- Pre-commit hooks for development workflow
|
|
92
|
+
- **🐳 Container Improvements**: Enhanced containerized build environment
|
|
93
|
+
- Updated Containerfile with TUI support
|
|
94
|
+
- Improved resource management and monitoring
|
|
95
|
+
- Better error handling and logging
|
|
96
|
+
|
|
97
|
+
### 🔄 Changed
|
|
98
|
+
- **🔢 Major Version Bump**: Incremented to v0.1.2 to reflect significant TUI addition
|
|
99
|
+
- **📚 Improved Documentation**: Enhanced README with TUI features and installation instructions
|
|
100
|
+
- **🐛 Better Error Handling**: More informative error messages and recovery suggestions
|
|
101
|
+
- **📋 Enhanced Logging**: Improved logging throughout the application with structured output
|
|
102
|
+
|
|
103
|
+
### 🔧 Technical Details
|
|
104
|
+
- **📦 Dependencies**: Added Textual, Rich, Watchdog for TUI functionality
|
|
105
|
+
- **🐍 Python Support**: Requires Python 3.9+ with support through 3.12
|
|
106
|
+
- **📂 Package Structure**: Reorganized as proper Python package with setuptools/pip support
|
|
107
|
+
- **⌨️ Entry Points**: Added console scripts for easy command-line access
|
|
108
|
+
- **🧪 Testing**: Comprehensive test suite with pytest and coverage reporting
|
|
109
|
+
|
|
110
|
+
### 🚀 Installation
|
|
111
|
+
```bash
|
|
112
|
+
# Basic installation
|
|
113
|
+
pip install pcileech-fw-generator
|
|
114
|
+
|
|
115
|
+
# With TUI support
|
|
116
|
+
pip install pcileech-fw-generator[tui]
|
|
117
|
+
|
|
118
|
+
# Development installation
|
|
119
|
+
pip install pcileech-fw-generator[dev]
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### 🎮 Usage
|
|
123
|
+
```bash
|
|
124
|
+
# Command line interface (traditional)
|
|
125
|
+
pcileech-generate
|
|
126
|
+
|
|
127
|
+
# Interactive TUI interface (new)
|
|
128
|
+
pcileech-tui
|
|
129
|
+
|
|
130
|
+
# Direct build command
|
|
131
|
+
pcileech-build --bdf 0000:03:00.0 --board 75t
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## [1.0.0] - 2024-12-01
|
|
135
|
+
|
|
136
|
+
### ✨ Added
|
|
137
|
+
- Initial release of PCILeech Firmware Generator
|
|
138
|
+
- Basic command-line interface for firmware generation
|
|
139
|
+
- Donor hardware analysis and configuration extraction
|
|
140
|
+
- Containerized build pipeline with Vivado integration
|
|
141
|
+
- USB-JTAG flashing support for DMA boards
|
|
142
|
+
- Basic SystemVerilog generation for PCIe devices
|
|
143
|
+
- Podman-based isolated build environment
|
|
144
|
+
|
|
145
|
+
### 🎯 Features
|
|
146
|
+
- PCIe device enumeration and selection
|
|
147
|
+
- Configuration space extraction from donor hardware
|
|
148
|
+
- FPGA bitstream generation for Artix-7 boards
|
|
149
|
+
- Automated driver binding and VFIO operations
|
|
150
|
+
- Basic logging and error handling
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## 📋 Release Notes
|
|
155
|
+
|
|
156
|
+
### 🚀 v0.1.2 Highlights
|
|
157
|
+
|
|
158
|
+
This major release introduces a modern, interactive TUI that transforms the user experience while maintaining full backward compatibility with the original command-line interface. The TUI provides guided workflows, real-time monitoring, and intelligent error handling that makes firmware generation more accessible and reliable.
|
|
159
|
+
|
|
160
|
+
Key improvements include:
|
|
161
|
+
- **🎯 Zero Learning Curve**: Intuitive interface guides users through the entire process
|
|
162
|
+
- **📊 Real-time Feedback**: Live monitoring of build progress and system resources
|
|
163
|
+
- **🛡️ Error Prevention**: Validation and checks prevent common configuration mistakes
|
|
164
|
+
- **📦 Professional Packaging**: Easy installation via pip with proper dependency management
|
|
165
|
+
|
|
166
|
+
### 🔄 Backward Compatibility
|
|
167
|
+
|
|
168
|
+
All existing command-line workflows continue to work unchanged. The TUI is an optional enhancement that requires additional dependencies, ensuring lightweight installations remain possible.
|
|
169
|
+
|
|
170
|
+
### 🔮 Future Roadmap
|
|
171
|
+
|
|
172
|
+
- Web-based interface for remote build management
|
|
173
|
+
- Enhanced device compatibility and detection
|
|
174
|
+
- Advanced firmware customization options
|
|
175
|
+
- Integration with additional FPGA toolchains
|
|
176
|
+
- Cloud-based build services
|
|
177
|
+
|
|
178
|
+
## ⚠️ Disclaimer
|
|
179
|
+
|
|
180
|
+
This tool is intended for educational research and legitimate PCIe development purposes only. Users are responsible for ensuring compliance with all applicable laws and regulations. The authors assume no liability for misuse of this software.
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
**Version 0.1.6** - Major release with TUI interface and professional packaging
|
|
@@ -0,0 +1,408 @@
|
|
|
1
|
+
# 🤝 Contributing to PCILeech Firmware Generator
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/py/pcileech-fw-generator)
|
|
4
|
+
[](https://pypi.org/project/pcileech-fw-generator/)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://github.com/ramseymcgrath/PCILeechFWGenerator/actions)
|
|
7
|
+
|
|
8
|
+
Thank you for your interest in contributing to the PCILeech Firmware Generator! This document provides guidelines and information for contributors.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 📑 Table of Contents
|
|
13
|
+
|
|
14
|
+
- [📜 Code of Conduct](#-code-of-conduct)
|
|
15
|
+
- [🚀 Getting Started](#-getting-started)
|
|
16
|
+
- [Prerequisites](#prerequisites)
|
|
17
|
+
- [Development Setup](#development-setup)
|
|
18
|
+
- [📋 Contributing Guidelines](#-contributing-guidelines)
|
|
19
|
+
- [Types of Contributions](#types-of-contributions)
|
|
20
|
+
- [Bug Reports](#bug-reports)
|
|
21
|
+
- [Feature Requests](#feature-requests)
|
|
22
|
+
- [🔄 Development Workflow](#-development-workflow)
|
|
23
|
+
- [Branch Strategy](#branch-strategy)
|
|
24
|
+
- [Making Changes](#making-changes)
|
|
25
|
+
- [Commit Message Format](#commit-message-format)
|
|
26
|
+
- [🧪 Testing](#-testing)
|
|
27
|
+
- [Test Structure](#test-structure)
|
|
28
|
+
- [Writing Tests](#writing-tests)
|
|
29
|
+
- [Running Tests](#running-tests)
|
|
30
|
+
- [💻 Code Style](#-code-style)
|
|
31
|
+
- [Python Style Guide](#python-style-guide)
|
|
32
|
+
- [Formatting Tools](#formatting-tools)
|
|
33
|
+
- [Pre-commit Hooks](#pre-commit-hooks)
|
|
34
|
+
- [📚 Documentation](#-documentation)
|
|
35
|
+
- [Code Documentation](#code-documentation)
|
|
36
|
+
- [Documentation Style](#documentation-style)
|
|
37
|
+
- [📤 Submitting Changes](#-submitting-changes)
|
|
38
|
+
- [Pull Request Process](#pull-request-process)
|
|
39
|
+
- [Pull Request Template](#pull-request-template)
|
|
40
|
+
- [Review Process](#review-process)
|
|
41
|
+
- [📦 Release Process](#-release-process)
|
|
42
|
+
- [Version Management](#version-management)
|
|
43
|
+
- [Release Steps](#release-steps)
|
|
44
|
+
- [Distribution](#distribution)
|
|
45
|
+
- [❓ Getting Help](#-getting-help)
|
|
46
|
+
- [Communication Channels](#communication-channels)
|
|
47
|
+
- [Development Resources](#development-resources)
|
|
48
|
+
- [🏆 Recognition](#-recognition)
|
|
49
|
+
- [⚠️ Disclaimer](#️-disclaimer)
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## 📜 Code of Conduct
|
|
54
|
+
|
|
55
|
+
This project adheres to a code of conduct that promotes a welcoming and inclusive environment. By participating, you are expected to uphold this code.
|
|
56
|
+
|
|
57
|
+
## 🚀 Getting Started
|
|
58
|
+
|
|
59
|
+
### Prerequisites
|
|
60
|
+
|
|
61
|
+
- Python 3.9 or higher
|
|
62
|
+
- Git
|
|
63
|
+
- Podman or Docker
|
|
64
|
+
- Vivado (for FPGA synthesis)
|
|
65
|
+
- Linux environment (required for PCIe operations)
|
|
66
|
+
|
|
67
|
+
### Development Setup
|
|
68
|
+
|
|
69
|
+
1. **Fork and Clone**
|
|
70
|
+
```bash
|
|
71
|
+
git clone https://github.com/yourusername/PCILeechFWGenerator.git
|
|
72
|
+
cd PCILeechFWGenerator
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
2. **Create Virtual Environment**
|
|
76
|
+
```bash
|
|
77
|
+
python3 -m venv venv
|
|
78
|
+
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
3. **Install Development Dependencies**
|
|
82
|
+
```bash
|
|
83
|
+
pip install -r requirements-dev.txt
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
4. **Install Pre-commit Hooks**
|
|
87
|
+
```bash
|
|
88
|
+
pre-commit install
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
5. **Verify Installation**
|
|
92
|
+
```bash
|
|
93
|
+
python -m pytest tests/
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## 📋 Contributing Guidelines
|
|
97
|
+
|
|
98
|
+
### Types of Contributions
|
|
99
|
+
|
|
100
|
+
We welcome several types of contributions:
|
|
101
|
+
|
|
102
|
+
- **Bug Reports**: Help us identify and fix issues
|
|
103
|
+
- **Feature Requests**: Suggest new functionality
|
|
104
|
+
- **Code Contributions**: Implement features or fix bugs
|
|
105
|
+
- **Documentation**: Improve or add documentation
|
|
106
|
+
- **Testing**: Add or improve test coverage
|
|
107
|
+
|
|
108
|
+
### Bug Reports
|
|
109
|
+
|
|
110
|
+
When reporting bugs, please include:
|
|
111
|
+
|
|
112
|
+
- **Environment Details**: OS, Python version, hardware setup
|
|
113
|
+
- **Steps to Reproduce**: Clear, step-by-step instructions
|
|
114
|
+
- **Expected vs Actual Behavior**: What should happen vs what does happen
|
|
115
|
+
- **Error Messages**: Full error output and logs
|
|
116
|
+
- **Hardware Configuration**: PCIe devices, DMA boards, etc.
|
|
117
|
+
|
|
118
|
+
### Feature Requests
|
|
119
|
+
|
|
120
|
+
For feature requests, please provide:
|
|
121
|
+
|
|
122
|
+
- **Use Case**: Why is this feature needed?
|
|
123
|
+
- **Proposed Solution**: How should it work?
|
|
124
|
+
- **Alternatives Considered**: Other approaches you've thought about
|
|
125
|
+
- **Implementation Ideas**: Technical approach if you have one
|
|
126
|
+
|
|
127
|
+
## 🔄 Development Workflow
|
|
128
|
+
|
|
129
|
+
### Branch Strategy
|
|
130
|
+
|
|
131
|
+
- `main`: Stable release branch
|
|
132
|
+
- `develop`: Integration branch for new features
|
|
133
|
+
- `feature/feature-name`: Feature development branches
|
|
134
|
+
- `bugfix/issue-description`: Bug fix branches
|
|
135
|
+
- `hotfix/critical-fix`: Critical fixes for production
|
|
136
|
+
|
|
137
|
+
### Making Changes
|
|
138
|
+
|
|
139
|
+
1. **Create Feature Branch**
|
|
140
|
+
```bash
|
|
141
|
+
git checkout -b feature/your-feature-name
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
2. **Make Changes**
|
|
145
|
+
- Write code following our style guidelines
|
|
146
|
+
- Add tests for new functionality
|
|
147
|
+
- Update documentation as needed
|
|
148
|
+
|
|
149
|
+
3. **Test Changes**
|
|
150
|
+
```bash
|
|
151
|
+
# Run full test suite
|
|
152
|
+
python -m pytest tests/
|
|
153
|
+
|
|
154
|
+
# Run specific tests
|
|
155
|
+
python -m pytest tests/test_specific_module.py
|
|
156
|
+
|
|
157
|
+
# Run with coverage
|
|
158
|
+
python -m pytest --cov=src tests/
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
4. **Commit Changes**
|
|
162
|
+
```bash
|
|
163
|
+
git add .
|
|
164
|
+
git commit -m "feat: add new TUI feature for device selection"
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Commit Message Format
|
|
168
|
+
|
|
169
|
+
We use conventional commits for clear history:
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
<type>(<scope>): <description>
|
|
173
|
+
|
|
174
|
+
[optional body]
|
|
175
|
+
|
|
176
|
+
[optional footer]
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
**Types:**
|
|
180
|
+
- `feat`: New feature
|
|
181
|
+
- `fix`: Bug fix
|
|
182
|
+
- `docs`: Documentation changes
|
|
183
|
+
- `style`: Code style changes (formatting, etc.)
|
|
184
|
+
- `refactor`: Code refactoring
|
|
185
|
+
- `test`: Adding or updating tests
|
|
186
|
+
- `chore`: Maintenance tasks
|
|
187
|
+
|
|
188
|
+
**Examples:**
|
|
189
|
+
```
|
|
190
|
+
feat(tui): add real-time build progress monitoring
|
|
191
|
+
fix(build): resolve SystemVerilog generation error for network devices
|
|
192
|
+
docs(readme): update installation instructions for TUI
|
|
193
|
+
test(core): add unit tests for device manager
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## 🧪 Testing
|
|
197
|
+
|
|
198
|
+
### Test Structure
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
tests/
|
|
202
|
+
├── unit/ # Unit tests for individual modules
|
|
203
|
+
├── integration/ # Integration tests for workflows
|
|
204
|
+
├── fixtures/ # Test data and fixtures
|
|
205
|
+
└── conftest.py # Pytest configuration
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Writing Tests
|
|
209
|
+
|
|
210
|
+
- **Unit Tests**: Test individual functions and classes
|
|
211
|
+
- **Integration Tests**: Test complete workflows
|
|
212
|
+
- **Mock External Dependencies**: Use pytest-mock for external services
|
|
213
|
+
- **Test Edge Cases**: Include error conditions and boundary cases
|
|
214
|
+
|
|
215
|
+
### Running Tests
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
# All tests
|
|
219
|
+
python -m pytest
|
|
220
|
+
|
|
221
|
+
# Specific test file
|
|
222
|
+
python -m pytest tests/test_build.py
|
|
223
|
+
|
|
224
|
+
# With coverage
|
|
225
|
+
python -m pytest --cov=src --cov-report=html
|
|
226
|
+
|
|
227
|
+
# Parallel execution
|
|
228
|
+
python -m pytest -n auto
|
|
229
|
+
|
|
230
|
+
# Specific markers
|
|
231
|
+
python -m pytest -m "not slow"
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## 💻 Code Style
|
|
235
|
+
|
|
236
|
+
### Python Style Guide
|
|
237
|
+
|
|
238
|
+
We follow PEP 8 with some modifications:
|
|
239
|
+
|
|
240
|
+
- **Line Length**: 88 characters (Black default)
|
|
241
|
+
- **Import Sorting**: Use isort with Black profile
|
|
242
|
+
- **Type Hints**: Required for all public functions
|
|
243
|
+
- **Docstrings**: Google style for all modules, classes, and functions
|
|
244
|
+
|
|
245
|
+
### Formatting Tools
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
# Format code
|
|
249
|
+
black src/ tests/
|
|
250
|
+
|
|
251
|
+
# Sort imports
|
|
252
|
+
isort src/ tests/
|
|
253
|
+
|
|
254
|
+
# Lint code
|
|
255
|
+
flake8 src/ tests/
|
|
256
|
+
|
|
257
|
+
# Type checking
|
|
258
|
+
mypy src/
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Pre-commit Hooks
|
|
262
|
+
|
|
263
|
+
Our pre-commit configuration automatically runs:
|
|
264
|
+
- Black (code formatting)
|
|
265
|
+
- isort (import sorting)
|
|
266
|
+
- flake8 (linting)
|
|
267
|
+
- mypy (type checking)
|
|
268
|
+
- pytest (basic tests)
|
|
269
|
+
|
|
270
|
+
## 📚 Documentation
|
|
271
|
+
|
|
272
|
+
### Code Documentation
|
|
273
|
+
|
|
274
|
+
- **Docstrings**: All public functions, classes, and modules
|
|
275
|
+
- **Type Hints**: All function parameters and return values
|
|
276
|
+
- **Comments**: Explain complex logic and business rules
|
|
277
|
+
- **README Updates**: Keep installation and usage instructions current
|
|
278
|
+
|
|
279
|
+
### Documentation Style
|
|
280
|
+
|
|
281
|
+
```python
|
|
282
|
+
def generate_firmware(device_bdf: str, board_type: str) -> Path:
|
|
283
|
+
"""Generate firmware for specified PCIe device.
|
|
284
|
+
|
|
285
|
+
Args:
|
|
286
|
+
device_bdf: PCIe device Bus:Device.Function identifier
|
|
287
|
+
board_type: Target FPGA board type (35t, 75t, 100t)
|
|
288
|
+
|
|
289
|
+
Returns:
|
|
290
|
+
Path to generated firmware binary
|
|
291
|
+
|
|
292
|
+
Raises:
|
|
293
|
+
DeviceNotFoundError: If specified device doesn't exist
|
|
294
|
+
BuildError: If firmware generation fails
|
|
295
|
+
|
|
296
|
+
Example:
|
|
297
|
+
>>> firmware_path = generate_firmware("0000:03:00.0", "75t")
|
|
298
|
+
>>> print(f"Firmware generated: {firmware_path}")
|
|
299
|
+
"""
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
## 📤 Submitting Changes
|
|
303
|
+
|
|
304
|
+
### Pull Request Process
|
|
305
|
+
|
|
306
|
+
1. **Update Documentation**: Ensure README, docstrings, and comments are current
|
|
307
|
+
2. **Add Tests**: Include tests for new functionality
|
|
308
|
+
3. **Run Full Test Suite**: Ensure all tests pass
|
|
309
|
+
4. **Update Changelog**: Add entry to CHANGELOG.md
|
|
310
|
+
5. **Create Pull Request**: Use our PR template
|
|
311
|
+
|
|
312
|
+
### Pull Request Template
|
|
313
|
+
|
|
314
|
+
```markdown
|
|
315
|
+
## Description
|
|
316
|
+
Brief description of changes
|
|
317
|
+
|
|
318
|
+
## Type of Change
|
|
319
|
+
- [ ] Bug fix
|
|
320
|
+
- [ ] New feature
|
|
321
|
+
- [ ] Breaking change
|
|
322
|
+
- [ ] Documentation update
|
|
323
|
+
|
|
324
|
+
## Testing
|
|
325
|
+
- [ ] Unit tests added/updated
|
|
326
|
+
- [ ] Integration tests added/updated
|
|
327
|
+
- [ ] Manual testing completed
|
|
328
|
+
|
|
329
|
+
## Checklist
|
|
330
|
+
- [ ] Code follows style guidelines
|
|
331
|
+
- [ ] Self-review completed
|
|
332
|
+
- [ ] Documentation updated
|
|
333
|
+
- [ ] Tests pass locally
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### Review Process
|
|
337
|
+
|
|
338
|
+
1. **Automated Checks**: CI/CD pipeline runs tests and linting
|
|
339
|
+
2. **Code Review**: Maintainers review code and provide feedback
|
|
340
|
+
3. **Testing**: Changes are tested in development environment
|
|
341
|
+
4. **Approval**: At least one maintainer approval required
|
|
342
|
+
5. **Merge**: Changes merged to appropriate branch
|
|
343
|
+
|
|
344
|
+
## 📦 Release Process
|
|
345
|
+
|
|
346
|
+
### Version Management
|
|
347
|
+
|
|
348
|
+
We use semantic versioning (MAJOR.MINOR.PATCH):
|
|
349
|
+
|
|
350
|
+
- **MAJOR**: Breaking changes
|
|
351
|
+
- **MINOR**: New features (backward compatible)
|
|
352
|
+
- **PATCH**: Bug fixes (backward compatible)
|
|
353
|
+
|
|
354
|
+
### Release Steps
|
|
355
|
+
|
|
356
|
+
1. **Update Version**: Increment version in `src/__version__.py`
|
|
357
|
+
2. **Update Changelog**: Add release notes to CHANGELOG.md
|
|
358
|
+
3. **Create Release Branch**: `release/vX.Y.Z`
|
|
359
|
+
4. **Final Testing**: Comprehensive testing of release candidate
|
|
360
|
+
5. **Tag Release**: Create git tag with version
|
|
361
|
+
6. **Build Distribution**: Create wheel and source distributions
|
|
362
|
+
7. **Publish**: Upload to PyPI
|
|
363
|
+
8. **GitHub Release**: Create GitHub release with notes
|
|
364
|
+
|
|
365
|
+
### Distribution
|
|
366
|
+
|
|
367
|
+
```bash
|
|
368
|
+
# Build distributions
|
|
369
|
+
python -m build
|
|
370
|
+
|
|
371
|
+
# Check distributions
|
|
372
|
+
twine check dist/*
|
|
373
|
+
|
|
374
|
+
# Upload to PyPI
|
|
375
|
+
twine upload dist/*
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
## ❓ Getting Help
|
|
379
|
+
|
|
380
|
+
### Communication Channels
|
|
381
|
+
|
|
382
|
+
- **GitHub Issues**: Bug reports and feature requests
|
|
383
|
+
- **GitHub Discussions**: General questions and community discussion
|
|
384
|
+
- **Email**: Direct contact for security issues
|
|
385
|
+
|
|
386
|
+
### Development Resources
|
|
387
|
+
|
|
388
|
+
- **Architecture Documentation**: See `docs/` directory
|
|
389
|
+
- **API Reference**: Generated from docstrings
|
|
390
|
+
- **Examples**: See `examples/` directory
|
|
391
|
+
- **Test Cases**: See `tests/` directory
|
|
392
|
+
|
|
393
|
+
## 🏆 Recognition
|
|
394
|
+
|
|
395
|
+
Contributors are recognized in:
|
|
396
|
+
- **CHANGELOG.md**: Release notes mention contributors
|
|
397
|
+
- **GitHub Contributors**: Automatic recognition
|
|
398
|
+
- **Release Notes**: Major contributions highlighted
|
|
399
|
+
|
|
400
|
+
## ⚠️ Disclaimer
|
|
401
|
+
|
|
402
|
+
This tool is intended for educational research and legitimate PCIe development purposes only. Users are responsible for ensuring compliance with all applicable laws and regulations. The authors assume no liability for misuse of this software.
|
|
403
|
+
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
Thank you for contributing to PCILeech Firmware Generator!
|
|
407
|
+
|
|
408
|
+
**Version 0.1.6** - Major release with TUI interface and professional packaging
|