Home

Relevant source files

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

• regif.py
• readme.md
• setup.py

regif is a command-line tool written in Python for automatically generating Verilog RTL and Microsoft Word documentation for register interfaces. It parses a specially formatted Microsoft Excel file (.xls) to define registers, their fields, and associated properties. The primary goal of regif is to streamline the hardware design process by ensuring consistency, readability, and correctness of register map implementations. It includes built-in validation checks to prevent the generation of broken Verilog code.

The tool is cross-platform and supports a wide range of register access types and design scenarios, including clock gating, interrupt handling, and FIFO interfaces. It generates a primary Verilog module (<modulename>_regif.v) containing the core register logic and an optional wrapper module (<modulename>_regif_wrap.v) for handling features like field locking.

Sources: readme.md:14-16, regif.py:1-15

Core Workflow

The usage of regif follows a simple three-step process, starting with template creation and ending with the generation of output files.

Sources: readme.md:27-31

This diagram illustrates the standard workflow for using the regif tool.

Sources: readme.md:29-31, regif.py:1396-1416

Architecture

The script's architecture is centered around a set of classes that model the register map structure, parsing logic to read the Excel file, and generation logic to produce the final Verilog and Docx files.

Sources: regif.py

Class Structure

The core logic is encapsulated in four main classes: Regif, Reg, RegFields, and Field. They form a hierarchical structure representing the entire register interface definition.

This diagram shows the relationship between the main classes responsible for parsing and modeling the register data.

Sources: regif.py:314-339, 342-378, 381-1025, 1073-1243

Main Processing Classes

• Regif: The main orchestrator class. It is initialized with an xlrd sheet object. It extracts top-level configuration, performs static and dynamic checks, and drives the generation of Verilog and documentation files.
  Sources: regif.py:1073-1095
• Reg: Represents a single register. It holds the register's name, address, and a RegFields object containing all its fields.
  Sources: regif.py:314-321
• RegFields: Manages the collection of Field objects for a single register. It contains the logic for generating Verilog write blocks (w_block), read expressions, and I/O declarations.
  Sources: regif.py:342-350
• Field: Represents a single bit-field within a register. It stores properties like name, access type, reset value, and bit section.
  Sources: regif.py:734-752

Key Features

Verilog Generation

The genverilog method within the Regif class is responsible for creating the Verilog output. It iterates through the register objects and assembles the final file from various string templates defined globally in the script.

Sources: regif.py:1299-1335

Write Logic

The script generates always blocks for handling register writes based on the field's access type.

• Normal Writes (RW, WO): A standard always block handles writes on bmi_wr.
• Clock Gating (rw_cg): If enabled for RW, WO, or RWT fields, a separate clock-gated always block is generated to save power.
• Read-Clear (RC): Logic is generated to clear the field to '0' upon a write or set it to '1' based on a hardware event.
• Write Protection (CP, BP): Conditional (CP) or bitwise (BP) protection logic is generated to guard writes to protected fields.

The following Verilog template is used for the main write always block:

{always_ff_begin}{field_rst}
    end else if(bmi_wr && (bmi_addr==`{reg_name})) begin{normal_wr}{rwt_wr}{protect_wr}{else_part}
    end 

Sources: regif.py:133-136, regif.py:587-595

Read Logic

A single always block with a case statement on bmi_addr is generated to handle all register reads. For each register, it concatenates the values of its fields to form the bmi_rdata output.

//register bus read interface 
reg    [{data_width}-1 :0]     {bmi}_rdata      ;
reg                  {bmi}_rdvld      ;
{always_ff_begin}
    // ... reset logic ...
    end else if(bmi_rd && ~bmi_wr) begin
        case(bmi_addr){reads}
            default : begin {bmi}_rdvld <= 1'b0; {bmi}_rdata <= {data_width}'b0 ;end
        endcase
    end else begin
        // ...
    end

Sources: regif.py:202-217

Lockable Fields

Fields can be "locked" by providing a locksig in the Excel file. This generates a _wrap.v file with an always block that prevents the field from being updated unless the locksig is asserted.

always @(posedge hw_clk or negedge hw_rstn)
    if(!hw_rstn) begin{lock_rsts}    
    end else if({lock_en}) begin
{lock_express}    end

Sources: regif.py:288-294, regif.py:1255-1271

Documentation Generation

The tool automatically generates a .docx register manual using the python-docx library. The gen_regif_doc function orchestrates this process.

• creat_regs_detail: Iterates through each register and creates a heading with its name and address.
• creat_reg_table: Creates a table for each register.
• fill_reg_fields: Populates the table with details for each field: bit section, name, access type, reset value, and description.

Sources: regif.py:1366-1386

Command-Line Interface

The script uses Python's argparse module to provide a simple command-line interface.

Command	Description
regif --init <name>	Creates a template Excel file named <name>_regif.xls in the current directory.
regif <file.xls>	Parses the specified Excel file and generates the .v and .docx output files.

Sources: regif.py:1389-1395, readme.md:29-31

Supported Access Types

regif supports a comprehensive set of access types for register fields, which are validated against a predefined list.

Type	Description
RO	Read Only
WO	Write Only
RW	Read/Write
RC	Read/Clear (HW sets, SW clears by writing)
RWC	Read/Write/Clear (HW clears)
RWT	Read/Write/Toggle (Write '1' to toggle)
RWW	Read/Write/Write (HW can also set value)
RWP	Read/Write Protection (Write to reset value)
BP	Bitwise Protection (Controls write to another field)
CP	Condition Protection (Controls write to another field)

Sources: regif.py:68-71, readme.md:33-44

Dependencies

The tool relies on two external Python libraries for its core functionality.

Package	Version	Purpose
xlrd	>=1.1.0	To read data from .xls files.
python_docx	>=1.11.3	To generate .docx documentation.

These dependencies are declared in setup.py and checked at runtime by the checklib() function.

Sources: setup.py:22-25, regif.py:20-29