Getting Started

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
• .github/workflows/pypi-publish.yml

The regif tool is a Python-based script that automates the generation of Verilog RTL (Register Transfer Level) code for register interfaces. It parses a specially formatted Microsoft Excel file (.xls) to produce Verilog modules (_regif.v, _regif_wrap.v) and a corresponding register documentation file in .docx format. The primary goal is to streamline the hardware design process by ensuring consistency, performing safety checks, and generating human-readable code and documentation from a single source of truth.

This guide covers the installation, basic usage workflow, and core concepts of the regif generator. It details how to initialize a project, define registers in the Excel template, and generate the final hardware and documentation files.

Sources: readme.md:13-14, regif.py:5-12, 1437-1438

Installation

The tool can be installed as a Python package via pip. It requires Python 3.3+ and has dependencies on xlrd for parsing Excel files and python-docx for generating Word documents.

Sources: readme.md:27, setup.py:21-26

Dependencies

Before running, the script checks for necessary libraries. If they are missing, it will print an error and exit.

# regif.py:21-32
def checklib():
    info = ""
    try:
        import xlrd
    except ImportError as e:
        info += str(e) + ", 'pip install xlrd' first!! \n"
    try:
        from docx import Document
    except ImportError as e:
        info += str(e) + ", 'pip install python_docx' first!! \n"
    if(info):
        info = "Error: \n" + info 
        print(info)
        exit(0)

Sources: regif.py:21-32, setup.py:24-25

Usage Workflow

The process of using regif involves three main steps, from project initialization to final artifact generation.

This diagram illustrates the standard user workflow for regif.

1. Initialize Template: Run regif --init <module_name> to create a new Excel template file named <module_name>_regif.xls in the current directory. This file contains the required structure and headers for defining registers.
   Sources: readme.md:33, regif.py:1443, 1453-1454

2. Define Registers: Open the generated .xls file and define the module's registers, including their offsets, names, fields, access types, and reset values.
   Sources: readme.md:34, regif/regif_template.xls

3. Generate Code: Run regif <module_name>_regif.xls to parse the Excel file, perform validation checks, and generate the Verilog and documentation files.
   Sources: readme.md:35, regif.py:1455-1474

Command-Line Interface

The script is executed from the command line with the following arguments.

Argument	metavar	Description
excel	xxx_regif.xls	(Positional) Parses the specified Excel file to generate .v and .docx files.
--init	xxx	Creates a template Excel file named xxx_regif.xls.

Sources: regif.py:1439-1444

Core Architecture

The script's architecture is centered around parsing an Excel sheet and mapping its contents to a set of Python classes that model the register interface. These classes then generate the Verilog code segments.

Core Classes

This diagram shows the main classes in regif.py and their relationships.

• Regif: The main class that orchestrates the entire process. It reads the Excel sheet, holds global configuration (module name, address/data widths), and manages a list of Reg objects.
• Reg: Represents a single register, containing its address, name, and a RegFields object.
• RegFields: Manages all the fields within a single register. It groups fields by type (e.g., RW, RC) to generate corresponding Verilog logic blocks.
• Field: Represents a single bit or a range of bits within a register, holding properties like name, access type, and reset value.

Sources: regif.py:359, 401, 843, 1162

Generation Process

The generation process begins when the main function is executed. It involves parsing, checking, and generating files in a specific sequence.

This sequence diagram shows the high-level flow of control during file generation.

Validation Checks

Before generating any code, regif performs two stages of validation:

1. Static Check: Verifies the format of each cell in the Excel file against predefined regular expressions. It also checks for duplicate register names and addresses. This ensures the input data is syntactically correct.
   Sources: regif.py:65, 74, 86, 1106-1121
2. Dynamic Check: Performs logical checks on the register definitions. This includes verifying that bit field sections are contiguous and do not overlap, and that reset values are valid for their specified bit widths.
   Sources: regif.py:448-453, 455-472

Excel Template Structure

The .xls file is the source of truth. It contains global settings in the header and register definitions in the main table.

Header Configuration

The first few rows of the sheet define module-level parameters.

Cell Position	Parameter	Description
C2	moudle	The name of the Verilog module.
F4	addr_wdith	The bit width of the register address bus (bmi_addr).
F5	data_width	The bit width of the data bus (bmi_wdata, bmi_rdata).
F7	reg_pre	A prefix to be added to the internal signal name for each field.
K4	rw_cg	YES enables clock gating for certain register types.
K5	group_size	Defines the size for read grouping to optimize read logic.
B6	cdc	SYNC or ASYNC mode for handling clock-domain crossing.
K6	reset-macro	YES enables the use of a reset macro (ctrl_always_ff_begin).

Sources: regif.py:86-91, 1166-1179

Register and Field Definition

Each register and its fields are defined in subsequent rows.

Column	Name	Description	Example
A	offset	The hexadecimal address offset of the register.	0x0004
B	regname	The name of the register.	M_DMA_CFG
C	reg_des	A description of the register's purpose.	DMA configuration
D	width	The total bit width of the register (for documentation).	32
E	section	The bit(s) for the field, e.g., [0] or [15:8].	[7:0]
F	fd_name	The name of the field.	DMA_EN
G	RW	The access type for the field.	RW
H	reset	The reset value in Verilog format.	8'h01
I	wprotect	Defines write protection conditions.	[0] or bitwise
J	locksig	An external signal to lock the field from writes.	sys_lock

Sources: regif.py:65-84

Supported Access Types

regif supports a wide range of access types, each generating specific logic.

Type	Name	Description
RO	Read Only	The field can only be read by the bus. Its value is driven by hardware.
WO	Write Only	The field can only be written by the bus. Its value is output to hardware.
RW	Read/Write	The field can be read from and written to by the bus.
RC	Read, Clear on HW event	A read-only status bit that is cleared by a hardware signal.
RWC	Read/Write, Clear on HW event	A read/write field that can also be cleared by a hardware signal.
RWT	Read/Write, Toggle on write	A read/write field where writing a '1' toggles its value.
RWP	Read/Write, Protected	A standard read/write field that is only writable at reset.
RWW	Read/Write, HW settable	A read/write field that can also be set by a hardware signal.
CP	Condition Protection	A field that, when written with a specific value, enables writes to other fields in the same register.
BP	Bitwise Protection	A field where each bit acts as a write-enable for the corresponding bit in another field.

Sources: readme.md:37-47, regif.py:79