Excel Template: 'top' Sheet

Relevant source files

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

• regif.py
• readme.md
• setup.py
• regif/regif_template.xls
• regif/init.py

Introduction

The regif tool utilizes a single Microsoft Excel (.xls) file as the source of truth for generating register interface Verilog RTL and corresponding documentation. The primary input is the first sheet in the Excel workbook, referred to as the 'top' sheet. This sheet contains all global configuration parameters for the register module, followed by a detailed breakdown of each register and its constituent fields.

The script regif.py is responsible for parsing this sheet, performing extensive validation, and generating the output files. The command regif --init <name> creates a template file named <name>_regif.xls which serves as the starting point for register definition. The structure of this sheet is rigid and must conform to the format expected by the parser to ensure the generation of correct hardware and documentation.

Sources: readme.md:25-31, regif.py:1445-1453, setup.py:23-26

Parsing and Validation Flow

The script processes the Excel file through a multi-stage flow that includes parsing, static checks, and dynamic checks before code generation. This ensures that formatting errors and logical inconsistencies in the register definitions are caught early.

The following diagram illustrates the high-level processing flow within the Regif class.

Global Configuration

The top-left area of the sheet is reserved for global configuration parameters that define the overall behavior and dimensions of the generated register interface module. These settings are validated by the title_check function against predefined regular expressions.

Sources: regif.py:80-85, regif.py:1169-1176, regif.py:1198-1216

Cell Position	Parameter	Description	Example
C2	moudle	The base name for the generated Verilog module and documentation files. Must be a valid Verilog module name.	my_ip
F4	addr_width	The width of the register address bus (bmi_addr). Must be between 2 and 999.	8
K4	rw_cg	Enables (YES) or disables (NO) clock gating for RW, RWT, and WO registers.	YES
F5	data_width	The width of the data bus (bmi_wdata, bmi_rdata). Must be between 4 and 999.	32
K5	group_size	Specifies the number of registers to group for read operations to optimize timing. Must be a power of 2. If 0, grouping is disabled.	32
B6	cdc	Specifies if the hardware signals are in a different clock domain. SYNC for synchronous, any other value for asynchronous, enabling CDC logic.	ASYNC
F7	reg_pre	A string prefix to be added to all internal register field signal names.	"if_"
K6	reset-macro	Enables (YES) or disables (NO) the use of a Verilog reset macro (ctrl_always_ff_begin) for synchronous/asynchronous reset flexibility.	YES

Register and Field Structure

Register definitions begin at row 10. The layout is hierarchical: a row with a value in the 'offset' column defines a new register, and all subsequent contiguous rows with a blank 'offset' column define the fields within that register.

Sources: regif.py:1218-1231

Register-Level Columns

These columns define the properties of a register block.

Column	Header	Description	Validation Rule
A	offset	The base address of the register.	r"0x[\da-fA-F]+\Z"
B	regname	The name of the register. Used to generate Verilog defines.	r"[a-zA-Z]\w*\Z"
C	reg_des	A text description. Can include RTL_FREE to exclude from Verilog generation or FIFO_IF for a FIFO interface.	r".*"
D	width	The bit width of the register. Must match the sum of its fields.	r"[1-9]\d{1,2}\Z"

Sources: regif.py:61-65, regif.py:373-376

Field-Level Columns

These columns, starting from column E, define the individual bit fields within a register.

Column	Header	Description	Validation Rule / Allowed Values
E	section	The bit position or range of the field.	`r"[(\d+
F	fd_name	The name of the field. RESERVED is a special name for unused bits.	r"[a-zA-Z]\w*\Z"
G	RW	The access type of the field.	RW, RC, BP, CP, RO, WO, RWW, RWC, RWT, RWP
H	reset	The reset value of the field.	`r"(\d+'(h
I	wprotect	Defines a write-protection dependency on another field.	BITWISE, [bit_section], or empty.
J	locksig	Name of an external signal that locks this field from being written.	r"[a-zA-Z]\w*\Z" or empty.
K	fd_des	A text description of the field.	r".*"
L	other	Reserved for future use.	r".*"

Sources: regif.py:67-75, readme.md:46-58

The relationship between registers and fields is parsed by the extract_regs function.

Key Features and Implementations

Access Types

The RW column determines the hardware behavior of a field. The regif tool supports a rich set of access types.

Type	Name	Description
RO	Read Only	Field can only be read by the bus. Value is driven from hardware inputs.
WO	Write Only	Field can only be written by the bus. Value is driven to hardware outputs.
RW	Read/Write	Field can be read and written by the bus.
RC	Read-Clear	A hardware-settable bit that is cleared to 0 upon a read of the register. The script generates CDC logic if the domain is async.
RWC	Read/Write-Clear	A software-writable bit that is cleared to its reset value by a hardware clear signal (<field_name>_hw_clc).
RWT	Read/Write-Toggle	Writing a '1' to a bit in this field toggles its current value. Writing '0' has no effect.
RWW	Read/Write-While	A software-writable field that can also be set to a specific value by a hardware signal (<field_name>_hw_set).
RWP	Read/Write-Protect	A software-writable field that is protected from writes when a lock signal is active.
BP / CP	Bit/Condition Protect	Special fields whose values act as write-enables for other fields in the same register.

Sources: regif.py:70, readme.md:46-58

Protection Mechanism (wprotect and CP/BP)

The tool provides a mechanism to conditionally protect fields from being written based on the value of another field within the same register.

• CP (Condition Protection): A field with type CP acts as a write-enable gate. Other fields in the register that reference the CP field's section in their wprotect column can only be written when the value written to the CP field matches its reset value.
• BP (Bitwise Protection): A field with type BP provides bit-level write protection. For another field to be write-protected by a BP field, it must reference the BP field's section in its wprotect column and have BITWISE specified. Each bit in the protected field can only be written if the corresponding bit in the data written to the BP field is '1'.

This logic is validated in _protect_check and implemented in protect_w_L1.

Sources: regif.py:72, regif.py:531-545, regif.py:618-641

Field Locking (locksig)

The locksig column allows a field's value to be locked by an external hardware signal. If a name is provided in this column for a writable field (e.g., RW, RWW), the script generates a wrapper module (<modulename>_regif_wrap.v). This wrapper contains logic that prevents the field from being updated if the external locksig signal is asserted. The gen_lock_segment function is responsible for creating this logic.

Sources: regif.py:73, regif.py:1297-1314, regif.py:341-343

Conclusion

The Excel template is the cornerstone of the regif automation flow, acting as a "single source of truth" for the entire register map. Its structured format, combined with the script's rigorous multi-stage validation, ensures that the generated Verilog RTL and technical documentation are syntactically correct, logically consistent, and perfectly synchronized. This methodology significantly reduces manual effort and eliminates a common source of errors in hardware design projects.

Sources: regif.py, readme.md