Advanced Feature: Trigger or Start Registers

Relevant source files

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

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

The regif tool provides functionality for generating Verilog register interfaces that can act as triggers or start/stop signals for hardware operations. This is not a standalone feature but is implemented through specific access types assigned to register fields within the input Excel file. The readme.md lists "trigger or start" as a primary scenario supported by the generator.

This functionality is primarily achieved using the RC (Read-Clear, implemented as Hardware-Set/Write-1-to-Clear) and RWT (Read-Write-Toggle) access types. These allow for creating status bits that are set by hardware and cleared by software, or control bits that can be toggled to initiate an action. The configuration is done declaratively in the Excel sheet, and regif automatically generates the corresponding stateful Verilog logic.

Sources: readme.md, regif.py:65-66

Implementation via Access Types

The core of the trigger functionality lies in the access types defined for each register field. The regif.py script validates the access type against a predefined list. The types relevant to trigger behavior are RC and RWT.

Sources: regif.py:65-66

RC (Hardware-Set, Write-1-to-Clear) for Status/Interrupt Triggers

The RC field type is designed for status or interrupt registers. A hardware event sets the register bit to 1, signaling a condition (the "trigger"). The software can then clear this bit back to 0 by writing a 1 to it, effectively acknowledging the event.

Despite its name "Read-Clear", the generated logic does not clear the register on a read operation. Instead, it implements a "Write-1-to-Clear" (W1C) behavior, which is a common pattern for interrupt handling.

The logic for this is generated from the RC_ALWYAS_L0 template in regif.py.

# regif.py:121-129
RC_ALWYAS_L0 = \
    '''
{always_ff_begin}
        {if_name}{bitsel} <= 1'b0;
    end else if({name}{hw}{syncd}{bitsel}) begin 
        {if_name}{bitsel} <= 1'b1;//RC
    end else if(bmi_wr && (bmi_addr==`{reg_name}) && bmi_wdata{bmibitsel}) begin 
        {if_name}{bitsel} <= 1'b0;//RC
    end  
'''

Sources: regif.py:121-129, regif.py:441-442

The following diagram illustrates the state transitions for an RC register bit.

RWT (Read-Write-Toggle) for Start/Stop Triggers

The RWT field type allows a register bit to toggle its value. When software writes a 1 to this bit, its state is inverted (0 becomes 1, 1 becomes 0). Writing a 0 has no effect. This is useful for creating a start/stop signal where successive writes can enable and disable a hardware feature.

The logic for this behavior is defined in the RWT_L1 template.

# regif.py:151-152
RWT_L1 = \
    "\n        {tab}{if_name:{fd_align}}  <= bmi_wdata{section}? ~{if_name}:{if_name};//{type}"

Sources: regif.py:151-152, regif.py:427-428

The diagram below shows the toggle behavior of an RWT register bit.

Configuration in Excel

Users configure these trigger registers in the project's .xls file, which is parsed using the xlrd library. The structure and validation rules are defined within regif.py. To create a trigger field, the user specifies the fd_name and sets the RW column to RC or RWT.

Sources: setup.py:24, regif.py:1396-1401, regif/regif_template.xls

section	fd_name	RW	reset	fd_des
[0]	proc_start	RWT	1'b0	Toggles processing on/off.
[1]	dma_done_irq	RC	1'b0	DMA done interrupt status.

The field_format data structure in regif.py enforces the allowed values for these columns.

# regif.py:62-70
field_format = [
    ("section", r"\[(\d+|\d+\:\d+)\]\Z", '"[0]" or "[15:7]" '),
    ("fd_name", r"[a-zA-Z]\w*\Z", 'must be one word '),
    ("RW     ", r"(RW|RC|BP|CP|RO|WO|RWW|RWC|RWT|RWP)\Z", "RW,RC,BP,CP,RO,WO,RWW,RWC,RWT,RWP only"),
    ("reset  ", r"(\d+'(h|H)[\da-fA-F]+\Z|\d+'(d|D)\d+\Z|\d+'(b|B)[01]+\Z|0\Z)", '''"0","3'd7", "12'hFFF", "2'b11"'''),
    # ...
]

Sources: regif.py:62-70

Verilog Code Generation Flow

The regif.py script orchestrates the code generation by parsing the Excel file and using a class-based structure to build the final Verilog output. The Regif class manages the overall process, while Reg and RegFields handle individual registers and their fields, respectively.

The following sequence diagram shows how a trigger register field is processed from the Excel file to the final Verilog code.

Conclusion

The regif tool effectively supports the creation of trigger and start/stop registers by leveraging specific access types (RC and RWT). This approach allows developers to define complex stateful behavior in a simple, declarative manner within an Excel spreadsheet. The tool then automates the generation of robust and readable Verilog code, handling the underlying logic for hardware-set/software-clear and toggle operations, which are fundamental patterns in digital design for managing interrupts and control signals.

Sources: readme.md, regif.py