FAQ & Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• regif.py
• readme.md
• setup.py
• regif/__main__.py (not provided, but referenced for structural completeness)
• regif/__init__.py (not provided, but referenced for structural completeness)

This document provides answers to frequently asked questions and guidance for troubleshooting common issues encountered while using the regif tool. It covers installation problems, usage errors, validation failures from the Excel template, and issues with the generated output files.

Installation and Setup

This section addresses problems related to installing regif and its dependencies.

Q: Why am I getting an ImportError when running the script?

The regif script depends on external Python libraries to function. An ImportError indicates that one or more of these are not installed in your Python environment.

Solution:

1. Ensure you have Python 3.3 or newer installed.
   • Sources: [setup.py:25](https://github.com/jijingg/regif/blob/HEAD/setup.py#L25)
2. Install the required dependencies using pip. The script has a built-in check that will tell you which libraries are missing.
   • Sources: [regif.py:27-38](https://github.com/jijingg/regif/blob/HEAD/regif.py#L27-L38)

The dependency check process is as follows:

This diagram shows the dependency check flow within regif.py.

The required packages are listed in setup.py and checked in regif.py.

Package	Required Version	Installation Command
xlrd	>=1.1.0	pip install xlrd
python_docx	>=1.11.3	pip install python-docx

Sources: setup.py:27-30, regif.py:27-38

Command-Line Usage

This section covers common questions and errors related to using the regif command-line interface.

Q: How do I use the regif command?

There are two primary modes of operation for the regif tool.

User Workflow:

This diagram illustrates the standard workflow for a user of the regif tool.

• Initialization: To create a new template file, run regif --init <module_name>. This will create a file named <module_name>_regif.xls in the current directory.
  • Sources: [readme.md:31](https://github.com/jijingg/regif/blob/HEAD/readme.md#L31), [regif.py:1264-1265](https://github.com/jijingg/regif/blob/HEAD/regif.py#L1264-L1265)
• Generation: After filling out the .xls template, run regif <path_to_your_excel_file.xls> to generate the Verilog and documentation files.
  • Sources: [readme.md:33](https://github.com/jijingg/regif/blob/HEAD/readme.md#L33), [regif.py:1266-1277](https://github.com/jijingg/regif/blob/HEAD/regif.py#L1266-L1277)

Q: I'm getting a "file not found" error.

This error occurs if the script cannot find the specified Excel file.

Solution:

• Ensure the path to the .xls file is correct and that you have read permissions for the file.
• The script explicitly checks if the file exists before attempting to open it.

# regif.py:1268-1271
if (not os.path.exists(args.excel)):
    print("%s not found, check please, 'regif -h' for help" % args.excel)
    exit(0)

Sources: regif.py:1268-1271

Excel Template Validation Errors

The script performs extensive validation on the Excel template before generating code. Failures at this stage are common and are designed to prevent generating broken Verilog.

Q: What are Static and Dynamic checks?

The validation process is split into two main phases:

1. Static Check: This phase checks for basic formatting and uniqueness constraints. It does not evaluate logical relationships between fields.
   • Sources: [regif.py:1010-1036](https://github.com/jijingg/regif/blob/HEAD/regif.py#L1010-L1036), [regif.py:1120-1129](https://github.com/jijingg/regif/blob/HEAD/regif.py#L1120-L1129)
2. Dynamic Check: This phase checks for logical consistency, such as bit-range continuity and valid protection schemes.
   • Sources: [regif.py:440-445](https://github.com/jijingg/regif/blob/HEAD/regif.py#L440-L445), [regif.py:1131-1141](https://github.com/jijingg/regif/blob/HEAD/regif.py#L1131-L1141)

Validation Flow:

This diagram shows the sequence of validation checks performed when processing an Excel file.

Q: I received a "format error" during the Static Check.

This means a value in a cell does not match the expected regular expression pattern. The error message will point to the exact cell and suggest the correct format.

Common Format Rules:

Header/Field	Column(s)	Expected Format (Regex)	Example Suggestion
offset	A	0x[\da-fA-F]+\Z	"0x001C"
regname	B	[a-zA-Z]\w*\Z	"M_DMA_CFG"
section	E	`[(\d+	\d+:\d+)]\Z`
RW type	G	(RW|RC|BP|CP|RO|WO|RWW|RWC|RWT|RWP)\Z	RW,RC,BP,CP,RO,WO...
reset	H	(\d+'(h|H)[\da-fA-F]+\Z|\d+'(d|D)\d+\Z|\...	"0", "3'd7", "12'hFFF"
wprotect	I	`BITWISE|bitwise|[(\d+	\d+:\d+)]\Z|\A\Z`

Sources: regif.py:46-61, regif.py:1039-1045

Q: I received an error during the Dynamic Check.

Dynamic check errors relate to the logical correctness of the register definitions.

Common Dynamic Errors:

• "section not continuity": The bit ranges of the fields within a register are not contiguous. For example, if one field ends at bit [7] and the next one starts at bit [9], this error will be triggered.
  • Sources: [regif.py:456-461](https://github.com/jijingg/regif/blob/HEAD/regif.py#L456-L461)
• "width don't match it reset value": The bit width defined in the section (e.g., [7:0] is 8 bits) does not match the width specified in the reset value (e.g., 4'hF).
  • Sources: [regif.py:898-901](https://github.com/jijingg/regif/blob/HEAD/regif.py#L898-L901)
• "reset value exceed ... supported max value": The decimal value of the reset is larger than what the field's bit width can represent.
  • Sources: [regif.py:914-916](https://github.com/jijingg/regif/blob/HEAD/regif.py#L914-L916)
• "protect section not exists": A field is configured to be protected by another field (e.g., a CP or BP field), but the specified protection field does not exist in the register.
  • Sources: [regif.py:466-469](https://github.com/jijingg/regif/blob/HEAD/regif.py#L466-L469)

Generated Output

This section covers questions about the files generated by regif.

Q: Why was a _regif_wrap.v file created?

A wrapper module (<modulename>_regif_wrap.v) is generated only when one or more register fields use the "lock" feature. This is identified by a non-empty locksig column for a field type that supports locking (e.g., RW, RWC, RWW). The wrapper module contains the logic for the lock signals.

• The getlockdict() method collects all fields that have a lock_sig.
• The genverilog() method checks if the returned dictionary is empty. If not, it proceeds to generate the wrapper file.

# regif.py:1248-1252
if lock_io:
    fp2 = open(modulename + "_regif_wrap.v", "w")
    fp2.write(w_file)
    fp2.close()
    print(modulename + "_regif_wrap.v generate done!\n")

Sources: regif.py:1186-1195, regif.py:1248-1252

Q: Why am I getting an IOError when generating the .docx file?

The script will fail with an IOError or a similar permission-related error if the target .docx file is already open in another application (like Microsoft Word).

Solution:

• Close the file _Register_Manual.docx and re-run the script. The script prints a specific hint for this case.

Make sure the {}_Register_Manual.docx is not opened first

Sources: regif.py:1279-1282

Q: What does the "bmi_rdvld have 2 cycle delay" message mean?

This informational message is printed when you use the "read group" feature, configured by setting a value for group_size in the Excel template (cell K5). When registers are grouped for reading, an extra pipeline stage (rd_dly1) is added to the read logic, resulting in a 2-cycle latency for bmi_rdvld after bmi_rd is asserted. If group_size is 0, the delay is 1 cycle.

Sources: regif.py:221-237, regif.py:1212-1219