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.

Files changed (79) hide show
  1. pcileechfwgenerator-2.0.0/.dockerignore +130 -0
  2. pcileechfwgenerator-2.0.0/CHANGELOG.md +184 -0
  3. pcileechfwgenerator-2.0.0/CONTRIBUTING.md +408 -0
  4. pcileechfwgenerator-2.0.0/Containerfile +101 -0
  5. pcileechfwgenerator-2.0.0/LICENSE +201 -0
  6. pcileechfwgenerator-2.0.0/MANIFEST.in +49 -0
  7. pcileechfwgenerator-2.0.0/PKG-INFO +557 -0
  8. pcileechfwgenerator-2.0.0/README.md +501 -0
  9. pcileechfwgenerator-2.0.0/docs/BEHAVIOR_PROFILING.md +220 -0
  10. pcileechfwgenerator-2.0.0/docs/CROSS_PLATFORM_SUPPORT.md +187 -0
  11. pcileechfwgenerator-2.0.0/docs/DEVELOPMENT.md +103 -0
  12. pcileechfwgenerator-2.0.0/docs/INSTALLATION.md +426 -0
  13. pcileechfwgenerator-2.0.0/docs/QUICK_START.md +266 -0
  14. pcileechfwgenerator-2.0.0/docs/TEST_SUITE_README.md +439 -0
  15. pcileechfwgenerator-2.0.0/docs/TUI_README.md +444 -0
  16. pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/PKG-INFO +557 -0
  17. pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/SOURCES.txt +77 -0
  18. pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/dependency_links.txt +1 -0
  19. pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/entry_points.txt +4 -0
  20. pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/requires.txt +25 -0
  21. pcileechfwgenerator-2.0.0/pcileechfwgenerator.egg-info/top_level.txt +1 -0
  22. pcileechfwgenerator-2.0.0/pyproject.toml +179 -0
  23. pcileechfwgenerator-2.0.0/pytest.ini +29 -0
  24. pcileechfwgenerator-2.0.0/requirements-dev.txt +41 -0
  25. pcileechfwgenerator-2.0.0/requirements-test.txt +44 -0
  26. pcileechfwgenerator-2.0.0/requirements-tui.txt +17 -0
  27. pcileechfwgenerator-2.0.0/requirements.txt +8 -0
  28. pcileechfwgenerator-2.0.0/setup.cfg +4 -0
  29. pcileechfwgenerator-2.0.0/setup.py +11 -0
  30. pcileechfwgenerator-2.0.0/src/__init__.py +28 -0
  31. pcileechfwgenerator-2.0.0/src/__version__.py +16 -0
  32. pcileechfwgenerator-2.0.0/src/advanced_sv_error.py +432 -0
  33. pcileechfwgenerator-2.0.0/src/advanced_sv_generator.py +1719 -0
  34. pcileechfwgenerator-2.0.0/src/advanced_sv_main.py +684 -0
  35. pcileechfwgenerator-2.0.0/src/advanced_sv_perf.py +616 -0
  36. pcileechfwgenerator-2.0.0/src/advanced_sv_power.py +367 -0
  37. pcileechfwgenerator-2.0.0/src/behavior_profiler.py +920 -0
  38. pcileechfwgenerator-2.0.0/src/build.py +1572 -0
  39. pcileechfwgenerator-2.0.0/src/donor_dump/Makefile +99 -0
  40. pcileechfwgenerator-2.0.0/src/donor_dump/README.md +271 -0
  41. pcileechfwgenerator-2.0.0/src/donor_dump/donor_dump.c +416 -0
  42. pcileechfwgenerator-2.0.0/src/donor_dump_manager.py +862 -0
  43. pcileechfwgenerator-2.0.0/src/flash_fpga.py +38 -0
  44. pcileechfwgenerator-2.0.0/src/generate_cli.py +33 -0
  45. pcileechfwgenerator-2.0.0/src/manufacturing_variance.py +463 -0
  46. pcileechfwgenerator-2.0.0/src/scripts/driver_scrape.py +693 -0
  47. pcileechfwgenerator-2.0.0/src/state_machine_extractor.py +845 -0
  48. pcileechfwgenerator-2.0.0/src/tui/__init__.py +13 -0
  49. pcileechfwgenerator-2.0.0/src/tui/core/__init__.py +13 -0
  50. pcileechfwgenerator-2.0.0/src/tui/core/build_orchestrator.py +977 -0
  51. pcileechfwgenerator-2.0.0/src/tui/core/config_manager.py +245 -0
  52. pcileechfwgenerator-2.0.0/src/tui/core/device_manager.py +271 -0
  53. pcileechfwgenerator-2.0.0/src/tui/core/status_monitor.py +307 -0
  54. pcileechfwgenerator-2.0.0/src/tui/main.py +794 -0
  55. pcileechfwgenerator-2.0.0/src/tui/models/__init__.py +18 -0
  56. pcileechfwgenerator-2.0.0/src/tui/models/config.py +177 -0
  57. pcileechfwgenerator-2.0.0/src/tui/models/device.py +74 -0
  58. pcileechfwgenerator-2.0.0/src/tui/models/error.py +174 -0
  59. pcileechfwgenerator-2.0.0/src/tui/models/progress.py +125 -0
  60. pcileechfwgenerator-2.0.0/src/tui/styles/main.tcss +190 -0
  61. pcileechfwgenerator-2.0.0/src/tui_cli.py +45 -0
  62. pcileechfwgenerator-2.0.0/tests/test_advanced_sv.py +680 -0
  63. pcileechfwgenerator-2.0.0/tests/test_behavior_profiler.py +733 -0
  64. pcileechfwgenerator-2.0.0/tests/test_build.py +673 -0
  65. pcileechfwgenerator-2.0.0/tests/test_build_integration.py +565 -0
  66. pcileechfwgenerator-2.0.0/tests/test_donor_dump.py +1073 -0
  67. pcileechfwgenerator-2.0.0/tests/test_driver_scrape.py +740 -0
  68. pcileechfwgenerator-2.0.0/tests/test_external_integration.py +591 -0
  69. pcileechfwgenerator-2.0.0/tests/test_flash_fpga.py +522 -0
  70. pcileechfwgenerator-2.0.0/tests/test_generate.py +662 -0
  71. pcileechfwgenerator-2.0.0/tests/test_integration.py +544 -0
  72. pcileechfwgenerator-2.0.0/tests/test_local_build.py +391 -0
  73. pcileechfwgenerator-2.0.0/tests/test_manufacturing_variance.py +230 -0
  74. pcileechfwgenerator-2.0.0/tests/test_pci_validation.py +138 -0
  75. pcileechfwgenerator-2.0.0/tests/test_profiler_generator_compatibility.py +279 -0
  76. pcileechfwgenerator-2.0.0/tests/test_profiler_integration.py +283 -0
  77. pcileechfwgenerator-2.0.0/tests/test_state_machine_extractor.py +744 -0
  78. pcileechfwgenerator-2.0.0/tests/test_sv_validation.py +347 -0
  79. 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
+ [![PyPI version](https://badge.fury.io/py/pcileech-fw-generator.svg)](https://badge.fury.io/py/pcileech-fw-generator)
4
+ [![Python Support](https://img.shields.io/pypi/pyversions/pcileech-fw-generator.svg)](https://pypi.org/project/pcileech-fw-generator/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
+ [![PyPI version](https://badge.fury.io/py/pcileech-fw-generator.svg)](https://badge.fury.io/py/pcileech-fw-generator)
4
+ [![Python Support](https://img.shields.io/pypi/pyversions/pcileech-fw-generator.svg)](https://pypi.org/project/pcileech-fw-generator/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+ [![CI](https://github.com/ramseymcgrath/PCILeechFWGenerator/workflows/CI/badge.svg)](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