Excel Template: Overview

Relevant source files

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

• regif.py
• readme.md
• setup.py
• img/regif.png
• regif/regif_template.xls (referenced in regif.py)

The regif tool uses a single Microsoft Excel (.xls) file as its primary input to define a complete register interface. This file serves as the single source of truth for the module's register map, detailing global configurations, individual registers, and their specific bit-fields. The script parses this template to automatically generate Verilog RTL for the register interface (_regif.v), an optional wrapper with lock logic (_regif_wrap.v), and a user-facing register manual in .docx format. This automated approach ensures consistency between hardware implementation and documentation.

The process begins when a user creates a template using regif --init <module_name>, which copies a predefined regif_template.xls. After the user populates the template with the register design, running regif <module_name>.xls initiates the parsing and generation flow.

Sources: readme.md, regif.py:1423-1449

File Structure

The Excel template consists of a single sheet organized into two main parts: a header for global module configurations and a body for defining registers and their fields. The xlrd library is used to read this .xls file.

Sources: regif.py:22, setup.py:25, img/regif.png

This diagram illustrates the visual layout of the Excel template.

Sources: readme.md

Header: Module Configuration

The top section of the sheet (specifically, rows 1-7) is used for defining module-wide parameters. The script performs checks on these values using regular expressions defined in the other_format variable.

Cell Position	Parameter	Description	Validation Rule
C2	moudle	The base name for the generated module.	Must be a valid Verilog module name (e.g., [a-zA-Z]\w*).
F4	addr_wdith	The bit width of the address bus.	Must be a number from 2 to 999.
F5	data_width	The bit width of the data bus.	Must be a number from 4 to 999.
B6	SYNC/ASYNC	Specifies if CDC (Clock Domain Crossing) logic is needed. SYNC disables it.	SYNC or any other value (implies ASYNC).
K4	RW_CG	Enables (YES) or disables clock gating for RW/RWT/WO registers.	YES or any other value.
K5	Group_Size	Specifies the size for read grouping. If non-zero, read logic is grouped to reduce logic depth. Must be a power of 2.	An integer that is a power of 2 (e.g., 32, 64).
K6	Reset-Macro	Enables (YES) or disables usage of a reset macro (ctrl_always_ff_begin).	YES or any other value.
F7	reg_pre	A prefix to be added to all internal register field signals.	A string, typically like "if_" or "reg_".

Sources: regif.py:86-92, 1228-1243

Body: Register and Field Definitions

Starting from row 10, the template defines the actual registers and their bit-fields. A row with an entry in the "offset" column (column A) signifies the start of a new register definition. Subsequent rows with a blank "offset" column are treated as fields belonging to the preceding register.

This hierarchical data is parsed by the extract_regs method within the Regif class.

# regif.py:1245-1257
def extract_regs(self, bs):
    regs = []
    nrows = bs.nrows
    ncols = bs.ncols
    address_idx = 0
    for i in range(9, nrows):
        row_data = bs.row_values(i)
        if row_data[0] != u'':
            regs.append(row_data[0:4])
            regs[address_idx].append([])
            regs[address_idx][4].append(row_data[4:ncols])
            address_idx += 1
        else:
            regs[address_idx - 1][4].append(row_data[4:ncols])
    return regs

Sources: regif.py:1245-1257

Data Structures and Formats

The script uses predefined format lists (reg_format, field_format) containing regular expressions to validate the structure and content of each cell for both registers and fields.

Register Definition

A register is defined by a single row with the following columns:

Column	Name	Description	Example	Regex Validation
A	offset	The hexadecimal address offset of the register.	0x001C	r"0x[\da-fA-F]+\Z"
B	regname	The unique name of the register.	M_DMA_CFG	r"[a-zA-Z]\w*\Z"
C	reg_des	A description of the register's purpose. Special keywords RTL_FREE and FIFO_IF can be included.	DMA configuration	r".*"
D	width	The total width of the register in bits. This is checked against the sum of its fields.	32	r"[1-9]\d{1,2}\Z"

Sources: regif.py:46-50, 413-415

Field Definition

Each field of a register is defined in a row immediately following the register row or another field row.

Column	Name	Description	Example	Regex Validation
E	section	The bit position or range (MSB:LSB).	[0] or [15:7]	`r"[(\d+
F	fd_name	The name of the field. RESERVED is a special keyword.	dma_en	r"[a-zA-Z]\w*\Z"
G	RW	The access type for the field.	RW	`(RW
H	reset	The reset value for the field, in Verilog format.	1'b0, 8'hFF	`(\d+'(h
I	wprotect	Defines write protection. Can be a bit section [x:y], BITWISE, or empty.	[0]	`BITWISE|bitwise|[(\d+
J	locksig	An external signal name that locks this field from being written.	sys_lock	[a-zA-Z]\w*\Z|\A\Z
K	fd_des	A description of the field's purpose.	Enable for DMA	.*
L	other	Reserved for future use.		.*

Sources: regif.py:52-61

Supported Access Types

The regif tool supports a comprehensive set of access types, each generating specific hardware logic.

Type	Name	Description
RO	Read Only	Field can only be read.
WO	Write Only	Field can only be written.
RW	Read/Write	Field can be read and written.
RC	Read, Clear on HW event	Readable by bus. Cleared to '1' by a hardware event signal, then cleared to '0' by a bus write. Used for status bits that are set by hardware.
RWC	Read, Write to Clear	Readable by bus. Set to '1' by a hardware event. Cleared to '0' by writing a '1' to it.
RWT	Read, Write to Toggle	Readable by bus. Writing a '1' to it toggles its value.
RWW	Read, Write by HW	Readable by bus. Can be written by both the bus and a dedicated hardware signal.
RWP	Read, Write Protected	Readable by bus. Can only be written once after reset.
BP	Bitwise Protection	A field that controls write access to another field on a bit-by-bit basis.
CP	Condition Protection	A field whose value (reset value) must be written to enable writes to another protected field.

Sources: readme.md, regif.py:54

Parsing and Validation Flow

The script follows a multi-stage process to parse the Excel file, validate its contents, and generate the output files.

This diagram shows the main execution flow from parsing the Excel file to generating the final Verilog and documentation outputs.
Sources: regif.py:1439-1450

Static Validation

The static_check function is the first validation pass. It iterates through all registers and fields, applying regex-based checks defined in reg_format and field_format. It also ensures that all register names and addresses are unique within the module.

Sources: regif.py:1143-1168

Dynamic Validation

After the initial parsing and static checks, the _dynamic_check method performs more complex, contextual validation on the object model. This is handled by the dynamic_check method in the Reg and RegFields classes. Key checks include:

• Section Continuity (_section_continue_check): Ensures that the bit-fields within a register are contiguous, cover the entire register width from 0 to data_width - 1, and have no gaps or overlaps.
• Reset Value (rst_val_check): Verifies that the bit-width specified in the reset value (e.g., 8 in 8'hFF) matches the field's section width and that the value itself does not exceed the maximum possible for that width.
• Protection Logic (_protect_check): Validates that fields marked for protection (wprotect column) are correctly linked to a BP or CP field and that the bit-widths are compatible for bitwise protection.

Sources: regif.py:461-465, 467-483, 485-500, 1264-1274

Conclusion

The Excel template is the cornerstone of the regif automation flow. By providing a structured and human-readable format for defining a register map, it allows hardware designers to specify complex register behaviors like clock gating, protection, and various access types in a centralized location. The tool's robust validation stages catch common errors early, and the automated generation of both RTL and documentation ensures that the hardware implementation stays perfectly synchronized with its specification, significantly improving design efficiency and reducing bugs.