Advanced Feature: Interrupt Generation

Relevant source files

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

• regif.py
• readme.md
• setup.py
• img/regif.png
• img/regif-ico.png

Introduction

The regif tool provides a streamlined method for generating register interfaces, including support for common hardware scenarios like interrupt handling. While the tool does not generate a full interrupt controller, it supports special register field access types that are fundamental for creating interrupt status and clear registers. These fields react to hardware events and allow for CPU-based acknowledgement, forming the building blocks of an interrupt-driven system.

The primary mechanism for interrupt implementation involves using the RC (Read-Clear) and RWC (Read-Write-Clear) access types for register fields. These types define specific behaviors for how a bit is set (typically by a hardware event) and how it is cleared (by CPU write or another hardware signal). The system also includes robust support for Clock Domain Crossing (CDC) to safely handle interrupt-triggering signals from asynchronous clock domains.

Sources: readme.md:39, regif.py:61, regif.py:441

Architecture Overview

Interrupt logic in regif-generated modules is managed at the individual register field level. The core architecture relies on a handshake between hardware signals and the CPU via the register bus.

1. Event Trigger: An external hardware event asserts a signal connected to the regif module.
2. Status Bit Set: For a field typed as RC, this hardware signal sets a status bit in a register. This bit's state now indicates a pending interrupt.
3. CPU Interaction: The CPU can read this register to poll interrupt statuses. To clear the interrupt, the CPU performs a write operation to the RC field.
4. Hardware Clear: For fields typed as RWC, a separate hardware signal is used to clear the status bit, often as part of a hardware-level acknowledgement mechanism.

The following diagram illustrates the general data flow for handling an interrupt using an RC field.

This diagram shows the flow of an interrupt signal from a hardware event to the CPU.
Sources: regif.py:134-142, regif.py:734-741

Key Access Types for Interrupts

The behavior of interrupt-related fields is determined by the access type specified in the Excel configuration file. The RC and RWC types are most relevant for this purpose.

Sources: regif.py:61

RC (Read-Clear) Type

Fields with the RC access type are designed to be set by a hardware signal and cleared by a CPU write. This is a common pattern for interrupt status bits where the CPU must explicitly acknowledge and clear the interrupt source.

The generated Verilog logic for an RC field is defined by the RC_ALWYAS_L0 template.

// From RC_ALWYAS_L0 template
always @(posedge bmi_clk or negedge bmi_rstn)
    if(!bmi_rstn) 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

• Set Condition: The field is set to 1 when the hardware signal ({name}{hw}{syncd}) is asserted.
• Clear Condition: The field is cleared to 0 when the CPU performs a write (bmi_wr) to the corresponding register address (bmi_addr) with the relevant bit in bmi_wdata being asserted. This effectively acts as a "write-to-clear" mechanism.

Sources: regif.py:134-142, regif.py:734-741

The sequence diagram below shows the interaction for an RC field.

This diagram shows the sequence of setting and clearing an RC interrupt bit.
Sources: regif.py:134-142

RWC (Read-Write-Clear) Type

The RWC type defines a field that is cleared by a hardware signal. This is useful in scenarios where a hardware handshake, rather than a CPU write, is responsible for clearing a status bit. The field is typically written by the CPU and cleared by hardware.

The clearing logic is defined in the RWC_RST_L1 template, which is part of the ELSE_PART_L2 block that executes when there is no CPU write.

// From RWC_RST_L1 template
if({name}{hw}{syncd}) begin
    {if_name:{fd_align}}  <= {rstval:6}  ;//RWC
end 

• Clear Condition: The field is reset to its default value (rstval) when the hardware clear signal ({name}{hw}{syncd}) is asserted.

Sources: regif.py:165-168, regif.py:633-639

Access Type Summary

Access Type	Set By	Cleared By	Typical Use Case
RC	Hardware Signal	CPU Write	Standard interrupt status bit. CPU acknowledges and clears.
RWC	CPU Write	Hardware Signal	Status or control bit cleared by a hardware handshake.

Sources: regif.py:61, regif.py:134-142, regif.py:165-168

Clock Domain Crossing (CDC) for Interrupt Signals

regif provides built-in CDC logic to safely synchronize hardware signals (like interrupt triggers) from an external clock domain (hw_clk) to the register bus clock domain (bmi_clk). This feature is enabled by setting the SYNC mode in the Excel template.

When enabled, the tool generates a 2-flop synchronizer and a pulse generator for each RC or RWC input signal.

The logic is defined in the CDC_PART_L2 template:

//cdc porecess, sync signal from HW to Bmi_clk domain
//only support RC/RWC, not support RWW
{always_ff_begin}{cdc_sync_rsts}
    end else begin {cdc_sync_ffs}
    end

//we suppose the signals from HW are pluse which width cover one bmi_clk cycle at least {cdc_sync_plss}

This block instantiates:

1. Reset logic (cdc_sync_rsts) for the synchronizer flops.
2. Two-flop synchronizer (cdc_sync_ffs) to mitigate metastability.
3. Pulse generation logic (cdc_sync_plss) to create a single-cycle pulse (_syncd) in the bmi_clk domain from the synchronized signal.

Sources: regif.py:186-194, regif.py:178-184, regif.py:441

The following diagram shows the generated CDC structure.

This diagram shows a 2-flop synchronizer followed by an edge detector to generate a safe, single-cycle pulse.
Sources: regif.py:178-184

Configuration

To implement an interrupt field, a user must correctly specify its properties in the regif Excel template.

For an interrupt status field named dma_done_irq, the configuration would be as follows:

section	fd_name	RW	reset	fd_des
[0]	dma_done_irq	RC	1'b0	DMA done interrupt status. Set by HW, cleared by SW write.

• fd_name: The base name for the field. The tool will automatically create a hardware input port named dma_done_irq_hw_set.
• RW: Set to RC to enable the "set-by-hardware, clear-by-CPU-write" behavior.
• reset: The initial value of the interrupt bit.

Sources: regif.py:57-65, img/regif.png

Conclusion

The regif tool provides an effective and automated way to generate the register-level logic for interrupt handling. By using the RC and RWC access types, developers can quickly define interrupt status and clear mechanisms directly from an Excel spreadsheet. The inclusion of automatic CDC logic ensures that interrupt signals from different clock domains are handled safely and robustly, reducing the risk of metastability issues. This feature significantly simplifies the creation of complex register maps with interrupt capabilities.

Sources: regif.py, readme.md