# excel-pyral Converter
A comprehensive tool for converting Excel register specifications into Python PyUVM Register Abstraction Layer (RAL) models via SystemRDL intermediate representation.
⚠️ **Note:**
excel-pyral is currently **under active development**. Features and interfaces may change, and some functionalities might be incomplete or unstable.
Please use it **carefully** and report any issues or feedback to help improve the project. 🙏
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com)
## 🚀 Features
- **Excel to PyUVM RAL**: Convert Excel register specs directly to Python PyUVM RAL models
- **Proper UVM Structure**: Generates hierarchical RAL models matching industry standards
- **SystemRDL Integration**: Uses SystemRDL as intermediate representation for accuracy
- **Submodule Support**: Handles complex hierarchical designs with multiple IP blocks
- **Field-Level Detail**: Supports register fields with access types, reset values, descriptions
- **Memory Support**: Handles both registers and memories in the same design
- **Debug Support**: Comprehensive logging and intermediate file preservation options
## 📁 Project Structure
```
excel-pyral/ # Root project directory
├── README.md # This file
├── requirements.txt # required python package list
├── pyproject.toml # Build system and configuration for your Python project
├── excel_pyral/ # Main Python package
│ ├── __init__.py # Package initialization
│ ├── excel_importer.py # Excel to SystemRDL converter
│ ├── systemrdl_compiler.py # SystemRDL compiler wrapper
│ ├── pyuvm_generator.py # PyUVM RAL generator
│ └── main.py # Main converter logic
├── docs/ # Documentation
| └── README_api.md # README file for API
├── examples/ # Example files
| ├── mychip.rdl # Genearted systemrdl file
| ├── mychip.xlsx # Input excel file to generate pyral model
| └── mychip_ral.py # Generate pyral model
└── setup.py # Package installation
```
## 📋 Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Excel File Format](#excel-file-format)
- [Usage Examples](#usage-examples)
- [Command Line Interface](#command-line-interface)
- [Python API](#python-api)
- [Generated PyUVM Structure](#generated-pyuvm-structure)
- [Advanced Features](#advanced-features)
- [Testing](#testing)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
## 🔧 Installation
### Prerequisites
```bash
# Required dependencies
pip install systemrdl-compiler
pip install pyuvm
pip install pandas
pip install openpyxl
```
### Install Package
```bash
# Clone the repository
git clone https://github.com/SanCodex/excel-pyral.git
cd excel-pyral
# Install in development mode
pip install -e .
```
## ⚡ Quick Start
### 1. Prepare Your Excel File
Create an Excel file with register specifications:
**Sheet: "Submodules"**
| Submodule Name | Instances | Base Addresses |
|----------------|-------------|----------------|
| GPIO | gpio0,gpio1 | 0x1000,0x1100 |
| UART | uart0,uart1 | 0x2000,0x3000 |
**Sheet: "GPIO"**
| Register Name | Offset | Width | Reset Value | Field Name | Field Bits | Field Description | SW Access | HW Access |
|---------------|--------|-------|-------------|------------|------------|-------------------|-----------|-----------|
| CRTL_REG | 0x0 | 32 | 0x00 | ENABLE | [0:0] | Enable GPIO | rw | r |
| CRTL_REG | 0x0 | 32 | 0x00 | MODE | [3:1] | Mode Select | rw | r |
| STATUS_REG | 0x4 | 32 | 0x00 | READY | [0:0] | Ready flag | rw | r |
**Sheet: "UART"**
| Register Name | Offset | Width | Reset Value | Field Name | Field Bits | Field Description | SW Access | HW Access |
|---------------|--------|-------|-------------|------------|------------|-------------------|-----------|-----------|
| RESET_REG | 0x8 | 32 | 0x00 | PAUSE | [0:0] | Pause txn UART | rw | r |
| RESET_REG | 0x8 | 32 | 0x00 | START | [3:1] | Start txn UART | rw | r |
| STOP_REG | 0x16 | 32 | 0x00 | END | [0:0] | Stop txn UART | rw | r |
### 2. Run Conversion
```bash
# Command line usage
pyral mychip.xlsx --keep-rdl
# Or using Python API
from excel_pyral import ExcelToPyRALConverter
converter = ExcelToPyRALConverter()
result = converter.convert("mychip.xlsx", "output/")
print(f"Generated PyUVM RAL: {result['pyuvm_file']}")
```
### 3. Use Generated PyUVM RAL
```python
# Import the generated RAL model
from output.mychip_ral import build_ral_model
# Build the RAL model in your test class
class MyTest(uvm_test):
def __init__(self, name, parent):
super().__init__(name, parent)
self.ral = build_ral_model()
async def run_phase(self, phase):
# Access registers through proper hierarchy
await self.ral.gpio0.CRTL_REG.write(0x5)
data = await self.ral.uart0.RESET_REG.read()
# Access individual fields
await self.ral.gpio0.CRTL_REG.ENABLE.write(1)
enable_val = await self.ral.gpio0.CRTL_REG.ENABLE.read()
# Use with sequences
reg_seq = uvm_reg_sequence.type_id.create("reg_seq")
reg_seq.model = self.ral
await reg_seq.start(None)
```
## 📊 Excel File Format
### Required Sheets
#### 1. **"Submodules" Sheet** (Required for hierarchical designs)
Defines the top-level module hierarchy:
| Column | Description | Example |
|--------|-------------|---------|
| Submodule Name | Name of the module type/class | GPIO, UART, SPI |
| Instances | Unique instance name | gpio0, uart_primary |
| Base Addresses | Hexadecimal base address | 0x1000, 0x2000 |
#### 2. **Module Type Sheets** (One per module type)
Define registers and fields for each module type:
| Column | Description | Example |
|--------|-------------|---------|
| Register Name | Name of the register | CONTROL_REG |
| Offset | Offset within module | 0x0, 0x4 |
| Width | Register Width | 32, 64 |
| Reset Value | Reset value (hex/decimal) | 0, 0x5A |
| Field Name | Name of the register field | ENABLE, MODE |
| Field Bits | Field bit positions | [0:0], [7:4] |
| Field Descripton | Description of field bits | Start txn UART |
| SW Access | Access type | rw |
| HW Access | Hardware access | r |
#### 3. **"default" Sheet** (Optional)
Global default properties:
| Property | Value | Description |
|----------|-------|-------------|
| regwidth | 32 | Default register width |
| accesswidth | 32 | Default access width |
| addressing | regalign | Address alignment |
## 💻 Command Line Interface
### Basic Usage
```bash
pyral [OPTIONS] EXCEL_FILE
```
### Options
| Option | Description | Default |
|--------|-------------|---------|
| `-o` or `--output DIR` | Output directory | `output` |
| `-t` or `--top-name NAME` | Override top module name | From filename |
| `--package-name NAME` | Python package name | `{top_name}_ral` |
| `-r` or `--keep-rdl` | Keep intermediate SystemRDL file | False |
| `--submodule-sheet NAME` | Submodules sheet name | `Submodules` |
| `--default-sheet NAME` | Default properties sheet | `default` |
| `--enhanced-classes` | Use enhanced PyUVM classes | True |
### Examples
```bash
# Basic conversion
pyral registers.xlsx
# Custom output directory and keep SystemRDL
pyral chip_spec.xlsx --output-dir results/ --keep-rdl
# Custom sheet names
pyral design.xlsx --submodule-sheet "Modules" --default-sheet "Properties"
# Custom package name
pyral my_chip.xlsx --package-name custom_ral
```
## 🐍 Python API
### ExcelToPyRALConverter Class
```python
from excel_pyral import ExcelToPyRALConverter
converter = ExcelToPyRALConverter()
result = converter.convert(
excel_file="registers.xlsx",
output="output",
top_name="my_chip",
package_name="my_chip_ral",
keep_rdl=True,
use_enhanced_classes=True
)
print(f"Generated files: {result}")
```
### Individual Components
```python
# Use individual components
from excel_pyral import (
ExcelToSystemRDLImporter,
SystemRDLCompiler,
PyUVMRALGenerator
)
# Step 1: Excel to SystemRDL
excel_importer = ExcelToSystemRDLImporter()
systemrdl_content = excel_importer.excel_to_systemrdl(
excel_file="registers.xlsx",
top_name="my_chip"
)
# Step 2: Compile SystemRDL
rdl_compiler = SystemRDLCompiler()
compiled_root = rdl_compiler.compile_string(systemrdl_content)
# Step 3: Generate PyUVM RAL
ral_generator = PyUVMRALGenerator()
ral_generator.generate(
root_node=compiled_root,
output_file="my_chip_ral.py"
)
```
## 🏗️ Generated PyUVM Structure
The generated PyUVM RAL follows proper UVM hierarchical structure:
### Type-Based Register Classes
```python
class GpioCrtlReg(uvm_reg):
"""Register: GPIO::CRTL_REG"""
def __init__(self, name="CRTL_REG"):
super().__init__(name, 32, has_coverage=uvm_cvr_t.UVM_CVR_ALL)
# Fields
self.ENABLE = uvm_reg_field.type_id.create("ENABLE")
self.MODE = uvm_reg_field.type_id.create("MODE")
```
### Type-Based Block Classes
```python
class GPIO(uvm_reg_block):
"""Register Block: GPIO"""
def __init__(self, name="GPIO"):
super().__init__(name, has_coverage=uvm_cvr_t.UVM_CVR_ALL)
# Register instances
self.CRTL_REG = GpioCrtlReg.type_id.create("CRTL_REG")
self.STATUS_REG = GpioStatusReg.type_id.create("STATUS_REG")
def build_phase(self, phase):
# Create register map and add registers
self.default_map = uvm_reg_map.type_id.create("default_map")
self.default_map.add_reg(self.CRTL_REG, 0x0, "RW")
self.default_map.add_reg(self.STATUS_REG, 0x4, "RW")
```
### Top-Level Class with Sub-Block Instances
```python
class Mychip(uvm_reg_block):
"""Top-level register block: mychip"""
def __init__(self, name="mychip"):
super().__init__(name, has_coverage=uvm_cvr_t.UVM_CVR_ALL)
# Sub-block instances (like SystemVerilog UVM)
self.gpio0 = GPIO.type_id.create("gpio0")
self.gpio1 = GPIO.type_id.create("gpio1")
self.uart0 = UART.type_id.create("uart0")
self.uart1 = UART.type_id.create("uart1")
def build_phase(self, phase):
# Add submaps at proper addresses (like add_submap)
self.default_map.add_submap(self.gpio0.default_map, 0x1000)
self.default_map.add_submap(self.gpio1.default_map, 0x1100)
self.default_map.add_submap(self.uart0.default_map, 0x2000)
self.default_map.add_submap(self.uart1.default_map, 0x3000)
```
## 🔧 Advanced Features
### Memory Support
Add memories to your module sheets:
| Memory Name | Address Offset | Size | Width | Access | Description |
|-------------|----------------|------|-------|--------|-------------|
| DATA_MEM | 0x100 | 1024 | 32 | RW | Data buffer |
### Array Registers
Support for register arrays (future feature):
| Register Name | Address Offset | Array Size | Field Name | Bit Range |
|---------------|----------------|------------|------------|-----------|
| CH_CFG[4] | 0x20 | 4 | ENABLE | [0:0] |
### Enhanced PyUVM Classes
Enable enhanced PyUVM classes for additional features:
```python
converter.convert(
excel_file="registers.xlsx",
use_enhanced_classes=True # Enables coverage, callbacks, etc.
)
```
## Best Practices
### Excel File Organization
1. **Use consistent naming:** Keep module, register, and field names consistent
2. **Group related functionality:** Put similar registers together
3. **Document thoroughly:** Use description fields extensively
4. **Validate addresses:** Ensure no overlapping address ranges
5. **Standard bit ranges:** Use standard field sizes where possible
### Module Design
1. **Logical grouping:** Group related registers in the same module
2. **Address alignment:** Align register addresses to natural boundaries
3. **Reserved fields:** Include reserved fields for future expansion
### PyUVM Integration
1. **Register model early:** Create RAL model during build phase
2. **Use callbacks:** Implement register callbacks for monitoring
3. **Enable coverage:** Turn on register coverage for verification
4. **Sequence integration:** Use with standard UVM register sequences
### Development Workflow
1. **Start simple:** Begin with basic register definitions
2. **Test incrementally:** Test after each module addition
3. **Use version control:** Track changes to Excel files
4. **Keep intermediate files:** Use `--keep-rdl` for debugging
5. **Validate generated code:** Review generated PyUVM RAL model
## 🐛 Troubleshooting
### Common Issues
#### "Walker did not find any top-level addrmap block"
**Cause:** Missing or incorrectly formatted Submodules sheet
**Solution:**
- Ensure Submodules sheet exists
- Check column names match exactly: "Module Type", "Instance Name", "Base Address", "Description"
- Verify sheet name is exactly "Submodules"
#### "SystemRDL compilation failed"
**Cause:** Invalid register/field definitions
**Solution:**
- Check bit ranges are valid: `[MSB:LSB]` where MSB >= LSB
- Verify access types are supported: RW, RO, WO, etc.
- Ensure no address overlaps between registers
- Use `--keep-rdl --verbose` to inspect SystemRDL file
#### "No registers found in design"
**Cause:** Module type sheets missing or incorrectly named
**Solution:**
- Ensure each Module Type in Submodules sheet has corresponding sheet
- Check sheet names match Module Type exactly (case-sensitive)
- Verify register definitions have all required columns
#### Import errors in generated PyUVM
**Cause:** PyUVM not installed or wrong version
**Solution:**
- Install PyUVM: `pip install pyuvm`
- Check Python environment is correct
- Verify all dependencies are installed
### Debug Mode
Enable detailed debugging:
```bash
pyral registers.xlsx --keep-rdl --verbose
```
This provides:
- Step-by-step conversion progress
- Intermediate SystemRDL file for inspection
- Detailed error messages with context
- Generated file locations and sizes
### Validation Checklist
Before conversion, verify your Excel file:
- [ ] Submodules sheet exists with correct column names
- [ ] All module types have corresponding sheets
- [ ] Register definitions have all required columns
- [ ] Bit ranges are in correct format `[MSB:LSB]`
- [ ] Access types are valid (RW, RO, WO, etc.)
- [ ] Addresses are in hexadecimal format
- [ ] No overlapping address ranges
- [ ] Field names are valid identifiers
- [ ] Reset values are properly formatted
### Validation
Validate your Excel file before conversion:
```python
from excel_pyral import ExcelToSystemRDLImporter
importer = ExcelToSystemRDLImporter()
validation = importer.validate_excel_file("registers.xlsx")
if not validation['valid']:
print("Validation errors:", validation['errors'])
```
## 📈 Performance
### File Size Guidelines
| Excel File Size | Processing Time | Memory Usage |
|------------------|-----------------|--------------|
| < 1MB | < 5 seconds | < 50MB |
| 1-10MB | 5-30 seconds | 50-200MB |
| > 10MB | > 30 seconds | > 200MB |
### Optimization Tips
1. **Minimize sheets**: Only include necessary module types
2. **Reduce fields**: Combine related fields where possible
3. **Use templates**: Reuse register/field definitions
4. **Batch processing**: Process multiple files in sequence
## 🤝 Contributing
### Development Setup
```bash
git clone https://github.com/SanCodex/excel-pyral.git
cd excel-pyral
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\\Scripts\\activate # Windows
# Install development dependencies
pip install -r requirements-dev.txt
pip install -e .
```
### Code Style
```bash
# Format code
black excel_pyral/
isort excel_pyral/
# Lint code
flake8 excel_pyral/
mypy excel_pyral/
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [SystemRDL Compiler](https://github.com/SystemRDL/systemrdl-compiler) for SystemRDL support
- [PyUVM](https://github.com/pyuvm/pyuvm) for Python UVM framework
- [PeakRDL](https://github.com/SystemRDL/PeakRDL) ecosystem for inspiration
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/SanCodex/excel-pyral/issues)
- **Discussions**: [GitHub Discussions](https://github.com/SanCodex/excel-pyral/discussions)
---
**⭐ If this project helped you, please consider giving it a star on GitHub!**
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/excel-pyral",
"name": "excel2pyral",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "SystemRDL, PyUVM, RAL, Register, Excel, UVM",
"author": "Your Name",
"author_email": "Sanjay Singh <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/35/26/5efe2cb013e84c63f3c4941c6a6e05fc448959ab3117f23bbdbb33b74038/excel2pyral-1.1.0.tar.gz",
"platform": null,
"description": "# excel-pyral Converter\n\nA comprehensive tool for converting Excel register specifications into Python PyUVM Register Abstraction Layer (RAL) models via SystemRDL intermediate representation.\n\n\u26a0\ufe0f **Note:** \nexcel-pyral is currently **under active development**. Features and interfaces may change, and some functionalities might be incomplete or unstable. \nPlease use it **carefully** and report any issues or feedback to help improve the project. \ud83d\ude4f\n\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://github.com)\n\n## \ud83d\ude80 Features\n\n- **Excel to PyUVM RAL**: Convert Excel register specs directly to Python PyUVM RAL models\n- **Proper UVM Structure**: Generates hierarchical RAL models matching industry standards \n- **SystemRDL Integration**: Uses SystemRDL as intermediate representation for accuracy\n- **Submodule Support**: Handles complex hierarchical designs with multiple IP blocks\n- **Field-Level Detail**: Supports register fields with access types, reset values, descriptions\n- **Memory Support**: Handles both registers and memories in the same design\n- **Debug Support**: Comprehensive logging and intermediate file preservation options\n\n## \ud83d\udcc1 Project Structure\n\n```\nexcel-pyral/ # Root project directory\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 requirements.txt # required python package list\n\u251c\u2500\u2500 pyproject.toml # Build system and configuration for your Python project\n\u251c\u2500\u2500 excel_pyral/ # Main Python package\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 excel_importer.py # Excel to SystemRDL converter\n\u2502 \u251c\u2500\u2500 systemrdl_compiler.py # SystemRDL compiler wrapper\n\u2502 \u251c\u2500\u2500 pyuvm_generator.py # PyUVM RAL generator\n\u2502 \u2514\u2500\u2500 main.py # Main converter logic\n\u251c\u2500\u2500 docs/ # Documentation\n| \u2514\u2500\u2500 README_api.md # README file for API\n\u251c\u2500\u2500 examples/ # Example files\n| \u251c\u2500\u2500 mychip.rdl # Genearted systemrdl file\n| \u251c\u2500\u2500 mychip.xlsx # Input excel file to generate pyral model\n| \u2514\u2500\u2500 mychip_ral.py # Generate pyral model\n\u2514\u2500\u2500 setup.py # Package installation\n```\n\n## \ud83d\udccb Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Excel File Format](#excel-file-format)\n- [Usage Examples](#usage-examples)\n- [Command Line Interface](#command-line-interface)\n- [Python API](#python-api)\n- [Generated PyUVM Structure](#generated-pyuvm-structure)\n- [Advanced Features](#advanced-features)\n- [Testing](#testing)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n\n## \ud83d\udd27 Installation\n\n### Prerequisites\n\n```bash\n# Required dependencies\npip install systemrdl-compiler\npip install pyuvm\npip install pandas\npip install openpyxl\n```\n\n### Install Package\n\n```bash\n# Clone the repository\ngit clone https://github.com/SanCodex/excel-pyral.git\ncd excel-pyral\n\n# Install in development mode\npip install -e .\n```\n\n## \u26a1 Quick Start\n\n### 1. Prepare Your Excel File\n\nCreate an Excel file with register specifications:\n\n**Sheet: \"Submodules\"**\n| Submodule Name | Instances | Base Addresses |\n|----------------|-------------|----------------|\n| GPIO | gpio0,gpio1 | 0x1000,0x1100 | \n| UART | uart0,uart1 | 0x2000,0x3000 |\n\n**Sheet: \"GPIO\"**\n| Register Name | Offset | Width | Reset Value | Field Name | Field Bits | Field Description | SW Access | HW Access |\n|---------------|--------|-------|-------------|------------|------------|-------------------|-----------|-----------|\n| CRTL_REG | 0x0 | 32 | 0x00 | ENABLE | [0:0] | Enable GPIO | rw | r |\n| CRTL_REG | 0x0 | 32 | 0x00 | MODE | [3:1] | Mode Select | rw | r |\n| STATUS_REG | 0x4 | 32 | 0x00 | READY | [0:0] | Ready flag | rw | r |\n\n**Sheet: \"UART\"**\n| Register Name | Offset | Width | Reset Value | Field Name | Field Bits | Field Description | SW Access | HW Access |\n|---------------|--------|-------|-------------|------------|------------|-------------------|-----------|-----------|\n| RESET_REG | 0x8 | 32 | 0x00 | PAUSE | [0:0] | Pause txn UART | rw | r |\n| RESET_REG | 0x8 | 32 | 0x00 | START | [3:1] | Start txn UART | rw | r |\n| STOP_REG | 0x16 | 32 | 0x00 | END | [0:0] | Stop txn UART | rw | r |\n\n### 2. Run Conversion\n\n```bash\n# Command line usage\npyral mychip.xlsx --keep-rdl\n\n# Or using Python API\nfrom excel_pyral import ExcelToPyRALConverter\n\nconverter = ExcelToPyRALConverter()\nresult = converter.convert(\"mychip.xlsx\", \"output/\")\nprint(f\"Generated PyUVM RAL: {result['pyuvm_file']}\")\n```\n\n### 3. Use Generated PyUVM RAL\n\n```python\n# Import the generated RAL model\nfrom output.mychip_ral import build_ral_model\n\n# Build the RAL model in your test class\nclass MyTest(uvm_test):\n def __init__(self, name, parent):\n super().__init__(name, parent)\n self.ral = build_ral_model()\n \n async def run_phase(self, phase):\n # Access registers through proper hierarchy\n await self.ral.gpio0.CRTL_REG.write(0x5)\n data = await self.ral.uart0.RESET_REG.read()\n \n # Access individual fields\n await self.ral.gpio0.CRTL_REG.ENABLE.write(1)\n enable_val = await self.ral.gpio0.CRTL_REG.ENABLE.read()\n \n # Use with sequences\n reg_seq = uvm_reg_sequence.type_id.create(\"reg_seq\")\n reg_seq.model = self.ral\n await reg_seq.start(None)\n```\n\n## \ud83d\udcca Excel File Format\n\n### Required Sheets\n\n#### 1. **\"Submodules\" Sheet** (Required for hierarchical designs)\nDefines the top-level module hierarchy:\n\n| Column | Description | Example |\n|--------|-------------|---------|\n| Submodule Name | Name of the module type/class | GPIO, UART, SPI |\n| Instances | Unique instance name | gpio0, uart_primary |\n| Base Addresses | Hexadecimal base address | 0x1000, 0x2000 |\n\n#### 2. **Module Type Sheets** (One per module type)\nDefine registers and fields for each module type:\n\n| Column | Description | Example |\n|--------|-------------|---------|\n| Register Name | Name of the register | CONTROL_REG |\n| Offset | Offset within module | 0x0, 0x4 |\n| Width | Register Width | 32, 64 |\n| Reset Value | Reset value (hex/decimal) | 0, 0x5A |\n| Field Name | Name of the register field | ENABLE, MODE |\n| Field Bits | Field bit positions | [0:0], [7:4] |\n| Field Descripton | Description of field bits | Start txn UART |\n| SW Access | Access type | rw |\n| HW Access | Hardware access | r |\n\n#### 3. **\"default\" Sheet** (Optional)\nGlobal default properties:\n\n| Property | Value | Description |\n|----------|-------|-------------|\n| regwidth | 32 | Default register width |\n| accesswidth | 32 | Default access width |\n| addressing | regalign | Address alignment |\n\n## \ud83d\udcbb Command Line Interface\n\n### Basic Usage\n\n```bash\npyral [OPTIONS] EXCEL_FILE\n```\n\n### Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-o` or `--output DIR` | Output directory | `output` |\n| `-t` or `--top-name NAME` | Override top module name | From filename |\n| `--package-name NAME` | Python package name | `{top_name}_ral` |\n| `-r` or `--keep-rdl` | Keep intermediate SystemRDL file | False |\n| `--submodule-sheet NAME` | Submodules sheet name | `Submodules` |\n| `--default-sheet NAME` | Default properties sheet | `default` |\n| `--enhanced-classes` | Use enhanced PyUVM classes | True |\n\n### Examples\n\n```bash\n# Basic conversion\npyral registers.xlsx\n\n# Custom output directory and keep SystemRDL\npyral chip_spec.xlsx --output-dir results/ --keep-rdl\n\n# Custom sheet names\npyral design.xlsx --submodule-sheet \"Modules\" --default-sheet \"Properties\"\n\n# Custom package name\npyral my_chip.xlsx --package-name custom_ral\n```\n\n## \ud83d\udc0d Python API\n\n### ExcelToPyRALConverter Class\n\n```python\nfrom excel_pyral import ExcelToPyRALConverter\n\nconverter = ExcelToPyRALConverter()\n\nresult = converter.convert(\n excel_file=\"registers.xlsx\",\n output=\"output\",\n top_name=\"my_chip\",\n package_name=\"my_chip_ral\",\n keep_rdl=True,\n use_enhanced_classes=True\n)\n\nprint(f\"Generated files: {result}\")\n```\n\n### Individual Components\n\n```python\n# Use individual components\nfrom excel_pyral import (\n ExcelToSystemRDLImporter,\n SystemRDLCompiler, \n PyUVMRALGenerator\n)\n\n# Step 1: Excel to SystemRDL\nexcel_importer = ExcelToSystemRDLImporter()\nsystemrdl_content = excel_importer.excel_to_systemrdl(\n excel_file=\"registers.xlsx\",\n top_name=\"my_chip\"\n)\n\n# Step 2: Compile SystemRDL\nrdl_compiler = SystemRDLCompiler()\ncompiled_root = rdl_compiler.compile_string(systemrdl_content)\n\n# Step 3: Generate PyUVM RAL\nral_generator = PyUVMRALGenerator()\nral_generator.generate(\n root_node=compiled_root,\n output_file=\"my_chip_ral.py\"\n)\n```\n\n## \ud83c\udfd7\ufe0f Generated PyUVM Structure\n\nThe generated PyUVM RAL follows proper UVM hierarchical structure:\n\n### Type-Based Register Classes\n```python\nclass GpioCrtlReg(uvm_reg):\n \"\"\"Register: GPIO::CRTL_REG\"\"\"\n def __init__(self, name=\"CRTL_REG\"):\n super().__init__(name, 32, has_coverage=uvm_cvr_t.UVM_CVR_ALL)\n \n # Fields\n self.ENABLE = uvm_reg_field.type_id.create(\"ENABLE\")\n self.MODE = uvm_reg_field.type_id.create(\"MODE\")\n```\n\n### Type-Based Block Classes \n```python\nclass GPIO(uvm_reg_block):\n \"\"\"Register Block: GPIO\"\"\"\n def __init__(self, name=\"GPIO\"):\n super().__init__(name, has_coverage=uvm_cvr_t.UVM_CVR_ALL)\n \n # Register instances\n self.CRTL_REG = GpioCrtlReg.type_id.create(\"CRTL_REG\")\n self.STATUS_REG = GpioStatusReg.type_id.create(\"STATUS_REG\")\n \n def build_phase(self, phase):\n # Create register map and add registers\n self.default_map = uvm_reg_map.type_id.create(\"default_map\")\n self.default_map.add_reg(self.CRTL_REG, 0x0, \"RW\")\n self.default_map.add_reg(self.STATUS_REG, 0x4, \"RW\")\n```\n\n### Top-Level Class with Sub-Block Instances\n```python\nclass Mychip(uvm_reg_block):\n \"\"\"Top-level register block: mychip\"\"\"\n def __init__(self, name=\"mychip\"):\n super().__init__(name, has_coverage=uvm_cvr_t.UVM_CVR_ALL)\n \n # Sub-block instances (like SystemVerilog UVM)\n self.gpio0 = GPIO.type_id.create(\"gpio0\")\n self.gpio1 = GPIO.type_id.create(\"gpio1\") \n self.uart0 = UART.type_id.create(\"uart0\")\n self.uart1 = UART.type_id.create(\"uart1\")\n \n def build_phase(self, phase):\n # Add submaps at proper addresses (like add_submap)\n self.default_map.add_submap(self.gpio0.default_map, 0x1000)\n self.default_map.add_submap(self.gpio1.default_map, 0x1100)\n self.default_map.add_submap(self.uart0.default_map, 0x2000) \n self.default_map.add_submap(self.uart1.default_map, 0x3000)\n```\n\n## \ud83d\udd27 Advanced Features\n\n### Memory Support\n\nAdd memories to your module sheets:\n\n| Memory Name | Address Offset | Size | Width | Access | Description |\n|-------------|----------------|------|-------|--------|-------------|\n| DATA_MEM | 0x100 | 1024 | 32 | RW | Data buffer |\n\n### Array Registers\n\nSupport for register arrays (future feature):\n\n| Register Name | Address Offset | Array Size | Field Name | Bit Range |\n|---------------|----------------|------------|------------|-----------|\n| CH_CFG[4] | 0x20 | 4 | ENABLE | [0:0] |\n\n### Enhanced PyUVM Classes\n\nEnable enhanced PyUVM classes for additional features:\n\n```python\nconverter.convert(\n excel_file=\"registers.xlsx\",\n use_enhanced_classes=True # Enables coverage, callbacks, etc.\n)\n```\n\n## Best Practices\n\n### Excel File Organization\n\n1. **Use consistent naming:** Keep module, register, and field names consistent\n2. **Group related functionality:** Put similar registers together \n3. **Document thoroughly:** Use description fields extensively\n4. **Validate addresses:** Ensure no overlapping address ranges\n5. **Standard bit ranges:** Use standard field sizes where possible\n\n### Module Design\n\n1. **Logical grouping:** Group related registers in the same module\n2. **Address alignment:** Align register addresses to natural boundaries\n3. **Reserved fields:** Include reserved fields for future expansion\n\n### PyUVM Integration\n\n1. **Register model early:** Create RAL model during build phase\n2. **Use callbacks:** Implement register callbacks for monitoring\n3. **Enable coverage:** Turn on register coverage for verification\n4. **Sequence integration:** Use with standard UVM register sequences\n\n### Development Workflow\n\n1. **Start simple:** Begin with basic register definitions\n2. **Test incrementally:** Test after each module addition\n3. **Use version control:** Track changes to Excel files\n4. **Keep intermediate files:** Use `--keep-rdl` for debugging\n5. **Validate generated code:** Review generated PyUVM RAL model\n\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n#### \"Walker did not find any top-level addrmap block\"\n**Cause:** Missing or incorrectly formatted Submodules sheet\n**Solution:** \n- Ensure Submodules sheet exists\n- Check column names match exactly: \"Module Type\", \"Instance Name\", \"Base Address\", \"Description\"\n- Verify sheet name is exactly \"Submodules\"\n\n#### \"SystemRDL compilation failed\"\n**Cause:** Invalid register/field definitions \n**Solution:**\n- Check bit ranges are valid: `[MSB:LSB]` where MSB >= LSB\n- Verify access types are supported: RW, RO, WO, etc.\n- Ensure no address overlaps between registers\n- Use `--keep-rdl --verbose` to inspect SystemRDL file\n\n#### \"No registers found in design\"\n**Cause:** Module type sheets missing or incorrectly named\n**Solution:**\n- Ensure each Module Type in Submodules sheet has corresponding sheet\n- Check sheet names match Module Type exactly (case-sensitive)\n- Verify register definitions have all required columns\n\n#### Import errors in generated PyUVM\n**Cause:** PyUVM not installed or wrong version\n**Solution:**\n- Install PyUVM: `pip install pyuvm`\n- Check Python environment is correct\n- Verify all dependencies are installed\n\n### Debug Mode\n\nEnable detailed debugging:\n\n```bash\npyral registers.xlsx --keep-rdl --verbose\n```\n\nThis provides:\n- Step-by-step conversion progress\n- Intermediate SystemRDL file for inspection\n- Detailed error messages with context\n- Generated file locations and sizes\n\n\n### Validation Checklist\n\nBefore conversion, verify your Excel file:\n\n- [ ] Submodules sheet exists with correct column names\n- [ ] All module types have corresponding sheets\n- [ ] Register definitions have all required columns\n- [ ] Bit ranges are in correct format `[MSB:LSB]`\n- [ ] Access types are valid (RW, RO, WO, etc.)\n- [ ] Addresses are in hexadecimal format\n- [ ] No overlapping address ranges\n- [ ] Field names are valid identifiers\n- [ ] Reset values are properly formatted\n\n\n### Validation\n\nValidate your Excel file before conversion:\n\n```python\nfrom excel_pyral import ExcelToSystemRDLImporter\n\nimporter = ExcelToSystemRDLImporter()\nvalidation = importer.validate_excel_file(\"registers.xlsx\")\n\nif not validation['valid']:\n print(\"Validation errors:\", validation['errors'])\n```\n\n## \ud83d\udcc8 Performance\n\n### File Size Guidelines\n\n| Excel File Size | Processing Time | Memory Usage |\n|------------------|-----------------|--------------|\n| < 1MB | < 5 seconds | < 50MB |\n| 1-10MB | 5-30 seconds | 50-200MB |\n| > 10MB | > 30 seconds | > 200MB |\n\n### Optimization Tips\n\n1. **Minimize sheets**: Only include necessary module types\n2. **Reduce fields**: Combine related fields where possible \n3. **Use templates**: Reuse register/field definitions\n4. **Batch processing**: Process multiple files in sequence\n\n## \ud83e\udd1d Contributing\n\n### Development Setup\n\n```bash\ngit clone https://github.com/SanCodex/excel-pyral.git\ncd excel-pyral\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # Linux/Mac\n# venv\\\\Scripts\\\\activate # Windows\n\n# Install development dependencies\npip install -r requirements-dev.txt\npip install -e .\n```\n\n### Code Style\n\n```bash\n# Format code\nblack excel_pyral/\nisort excel_pyral/\n\n# Lint code\nflake8 excel_pyral/\nmypy excel_pyral/\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- [SystemRDL Compiler](https://github.com/SystemRDL/systemrdl-compiler) for SystemRDL support\n- [PyUVM](https://github.com/pyuvm/pyuvm) for Python UVM framework\n- [PeakRDL](https://github.com/SystemRDL/PeakRDL) ecosystem for inspiration\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/SanCodex/excel-pyral/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/SanCodex/excel-pyral/discussions)\n\n---\n\n**\u2b50 If this project helped you, please consider giving it a star on GitHub!**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert Excel register specifications to PyUVM RAL models via SystemRDL",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/yourusername/excel-pyral",
"Issues": "https://github.com/yourusername/excel-pyral/issues",
"Repository": "https://github.com/yourusername/excel-pyral"
},
"split_keywords": [
"systemrdl",
" pyuvm",
" ral",
" register",
" excel",
" uvm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e358cb935d6a2c08e82c301ec8925b2260ca4b4aeb5d8a9ef1fd2883ee157e0d",
"md5": "7c2c961721002c61c0d333fbbef19772",
"sha256": "2363de1351a09bbea0840e0e231887e570643a2111cd6278bf3cd011ff83b74e"
},
"downloads": -1,
"filename": "excel2pyral-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c2c961721002c61c0d333fbbef19772",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22429,
"upload_time": "2025-08-23T18:04:17",
"upload_time_iso_8601": "2025-08-23T18:04:17.029481Z",
"url": "https://files.pythonhosted.org/packages/e3/58/cb935d6a2c08e82c301ec8925b2260ca4b4aeb5d8a9ef1fd2883ee157e0d/excel2pyral-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "35265efe2cb013e84c63f3c4941c6a6e05fc448959ab3117f23bbdbb33b74038",
"md5": "d71b7f88b1e3ef0ecd46dbef24c05049",
"sha256": "7f1b5f1d16249f3c3b42b12a6374d4b92077ea4de5d29ad851c28861d38cd9f8"
},
"downloads": -1,
"filename": "excel2pyral-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d71b7f88b1e3ef0ecd46dbef24c05049",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 21503,
"upload_time": "2025-08-23T18:04:18",
"upload_time_iso_8601": "2025-08-23T18:04:18.618225Z",
"url": "https://files.pythonhosted.org/packages/35/26/5efe2cb013e84c63f3c4941c6a6e05fc448959ab3117f23bbdbb33b74038/excel2pyral-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 18:04:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "excel-pyral",
"github_not_found": true,
"lcname": "excel2pyral"
}
JSON
