RadDebugHub Datasheet

Use Cases

Debug and observability hooks for generated FPGA systems.

Block Diagram

VHDL Include And Instantiation Template

File Header

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

library radhdl;
-- Direct entity instantiation below does not require importing the entity name.
use radhdl.debug.all;

Component Declaration

component RadDebugHub is
  generic (
    DATA_WIDTH : integer := 32;
    REG_ADDR_WIDTH : integer := 16;
    SAMPLE_WIDTH : integer := 32;
    EVENT_WIDTH : integer := 8;
    DEPTH : integer := 1024;
    ADDR_WIDTH : integer := 10;
    CMD_LANES : integer := 4;
    VENDOR_TAG : string := "XILINX";
    PRODUCT_SERIES_TAG : string := "7SERIES"
  );
  port (
    sample_clk : in std_logic;
    sample_rstn : in std_logic;
    sample_i : in std_logic_vector(SAMPLE_WIDTH - 1 downto 0);
    event_i : in std_logic_vector(EVENT_WIDTH - 1 downto 0);
    irq_o : out std_logic;
    reg_clk : in std_logic;
    reg_rstn : in std_logic;
    reg_wr_addr : in std_logic_vector(REG_ADDR_WIDTH - 1 downto 0);
    reg_rd_addr : in std_logic_vector(REG_ADDR_WIDTH - 1 downto 0);
    reg_wr_en : in std_logic;
    reg_rd_en : in std_logic;
    reg_data_in : in std_logic_vector(DATA_WIDTH - 1 downto 0);
    reg_data_out : out std_logic_vector(DATA_WIDTH - 1 downto 0);
    reg_wr_rdy : out std_logic;
    reg_rd_rdy : out std_logic;
    reg_wr_valid : out std_logic;
    reg_rd_valid : out std_logic;
    reg_error : out std_logic
  );
end component;

Direct Entity Instantiation

u_raddebughub : entity radhdl.RadDebugHub
  generic map (
    DATA_WIDTH         => 32,
    REG_ADDR_WIDTH     => 16,
    SAMPLE_WIDTH       => 32,
    EVENT_WIDTH        => 8,
    DEPTH              => 1024,
    ADDR_WIDTH         => 10,
    CMD_LANES          => 4,
    VENDOR_TAG         => "XILINX",
    PRODUCT_SERIES_TAG => "7SERIES"
  )
  port map (
    sample_clk   => <sample_clk_signal>,
    sample_rstn  => <sample_rstn_signal>,
    sample_i     => <sample_i_signal>,
    event_i      => <event_i_signal>,
    irq_o        => <irq_o_signal>,
    reg_clk      => <reg_clk_signal>,
    reg_rstn     => <reg_rstn_signal>,
    reg_wr_addr  => <reg_wr_addr_signal>,
    reg_rd_addr  => <reg_rd_addr_signal>,
    reg_wr_en    => <reg_wr_en_signal>,
    reg_rd_en    => <reg_rd_en_signal>,
    reg_data_in  => <reg_data_in_signal>,
    reg_data_out => <reg_data_out_signal>,
    reg_wr_rdy   => <reg_wr_rdy_signal>,
    reg_rd_rdy   => <reg_rd_rdy_signal>,
    reg_wr_valid => <reg_wr_valid_signal>,
    reg_rd_valid => <reg_rd_valid_signal>,
    reg_error    => <reg_error_signal>
  );

Generics

Name	Type	Default	Description
DATA_WIDTH	integer	32	Register data width for the RADIF register target.
REG_ADDR_WIDTH	integer	16	Register byte-address width for the RADIF register target.
SAMPLE_WIDTH	integer	32	Total captured sample bus width in bits.
EVENT_WIDTH	integer	8	Width of event/trigger metadata sampled beside each captured value.
DEPTH	integer	1024	Number of samples stored in the RadILA capture RAM.
ADDR_WIDTH	integer	10	Capture RAM address width.
CMD_LANES	integer	4	Narrow command link width between RadDebugHub and RadILA.
VENDOR_TAG	string	"XILINX"	Vendor selector used by generate blocks for vendor-specific primitives.
PRODUCT_SERIES_TAG	string	"7SERIES"	Device-family selector used by vendor primitive wrappers.

Ports

Name	Direction	Type	Description
sample_clk	in	std_logic	Sample clock for the observed logic and capture RAM write side.
sample_rstn	in	std_logic	Active-low reset for the sample clock domain.
sample_i	in	std_logic_vector(SAMPLE_WIDTH - 1 downto 0)	Input sample vector captured by the analyzer.
event_i	in	std_logic_vector(EVENT_WIDTH - 1 downto 0)	Event or trigger metadata associated with the current sample stream.
irq_o	out	std_logic	Interrupt asserted when capture completion is enabled and the core is done.
reg_clk	in	std_logic	Clock for the RADIF register interface and capture RAM read side.
reg_rstn	in	std_logic	Active-low reset for the RADIF register interface.
reg_wr_addr	in	std_logic_vector(REG_ADDR_WIDTH - 1 downto 0)	Register write address.
reg_rd_addr	in	std_logic_vector(REG_ADDR_WIDTH - 1 downto 0)	Register read address.
reg_wr_en	in	std_logic	One-cycle register write request.
reg_rd_en	in	std_logic	One-cycle register read request.
reg_data_in	in	std_logic_vector(DATA_WIDTH - 1 downto 0)	Register write data.
reg_data_out	out	std_logic_vector(DATA_WIDTH - 1 downto 0)	Register read data.
reg_wr_rdy	out	std_logic	Write-side ready indication.
reg_rd_rdy	out	std_logic	Read-side ready indication.
reg_wr_valid	out	std_logic	Write response valid pulse.
reg_rd_valid	out	std_logic	Read response valid pulse.
reg_error	out	std_logic	Address or transaction error flag for the current response.

Register Interfaces

Static register maps are rendered below for this module.

Interface	Directions	Signals	Representative ports
Register control/status	in, out	13	reg_clk, reg_rstn, reg_wr_addr, reg_rd_addr, reg_wr_en, reg_rd_en, reg_data_in, reg_data_out, +5 more

Register Maps

RadDebugHub

Source: debug/radila/hdl/radila/register_maps/RadDebugHub.map.json

Controls RadILA capture arming, trigger matching, status reporting, and capture-buffer readback through the shared RADIF register interface.

Register	Offset	Access	Reset	Description
id	0x00	ro	0x52414449	Constant ASCII identifier for the RadILA debug hub.
version	0x04	ro	0x00020800	Hardware register-map version and compatibility word.
control	0x08	rw	0x00000000	Issues capture commands and configures optional interrupt and auto-rearm behavior.
status	0x0C	ro	0x00000000	Reports analyzer state and captured sample count.
trig_mask	0x10	rw	0x00000000	Selects which event_i bits participate in hardware trigger comparison.
trig_value	0x14	rw	0x00000000	Expected event value after applying TRIG_MASK.
pretrig	0x18	rw	0x00000000	Reserved pre-trigger depth configuration field retained for host API compatibility.
posttrig	0x1C	rw	0x000000FF	Number of post-trigger samples to capture after the trigger condition is accepted.
data_index	0x20	rw	0x00000000	Capture-buffer read index used by SAMPLE_DATA registers.
sample_data0	0x24	ro	0x00000000	Low 32 bits of the captured sample selected by DATA_INDEX.
sample_now0	0x28	ro	0x00000000	Low 32 bits of the live sample input synchronized into the register clock domain.
event_now	0x2C	ro	0x00000000	Current event metadata synchronized into the register clock domain.
caps	0x30	ro	0x00200008	Static hardware capability word for host discovery.
sample_data1	0x34	ro	0x00000000	Captured sample bits 63 downto 32 when SAMPLE_WIDTH is greater than 32.
sample_data2	0x38	ro	0x00000000	Captured sample bits 95 downto 64 when SAMPLE_WIDTH is greater than 64.
sample_data3	0x3C	ro	0x00000000	Captured sample bits 127 downto 96 when SAMPLE_WIDTH is greater than 96.

id

Offset 0x00 / Access ro / Reset 0x52414449

Constant ASCII identifier for the RadILA debug hub.

Id[15:0]

1514131211109876543210

ID [15:0]

Id[31:16]

31302928272625242322212019181716

ID [31:16]

Name	Register bit(s)	Description
ID	Id[31:0]	Reads as 0x52414449, the ASCII tag RADI.

version

Offset 0x04 / Access ro / Reset 0x00020800

Hardware register-map version and compatibility word.

Version[15:0]

1514131211109876543210

VERSION [15:0]

Version[31:16]

31302928272625242322212019181716

VERSION [31:16]

Name	Register bit(s)	Description
VERSION	Version[31:0]	Encodes the debug hub register contract version used by host tools.

control

Offset 0x08 / Access rw / Reset 0x00000000

Issues capture commands and configures optional interrupt and auto-rearm behavior.

Control[15:0]

1514131211109876543210

RSVD [15:5]

IRQ EN

AUTO REARM

CLEAR

SW TRIG

ARM

Control[31:16]

31302928272625242322212019181716

RSVD [31:16]

Name	Register bit(s)	Description
IRQ EN	Control[4]	When set, irq_o asserts while STATUS.DONE is set.
AUTO REARM	Control[3]	When set, the capture engine automatically returns to the armed state after completing a capture.
CLEAR	Control[2]	Writing 1 clears capture state, sticky done indication, counters, and command framing.
SW TRIG	Control[1]	Writing 1 injects a software trigger into the command stream.
ARM	Control[0]	Writing 1 arms the analyzer and starts capture when the trigger condition is met.

status

Offset 0x0C / Access ro / Reset 0x00000000

Reports analyzer state and captured sample count.

Status[15:0]

1514131211109876543210

RSVD [15:4]

OVERFLOW

DONE

CAPTURING

ARMED

Status[31:16]

31302928272625242322212019181716

COUNT [31:16]

Name	Register bit(s)	Description
COUNT	Status[31:16]	Number of samples captured or retained by the current capture window.
OVERFLOW	Status[3]	Set when capture activity exceeds the configured buffer accounting.
DONE	Status[2]	Set after the configured capture window has completed.
CAPTURING	Status[1]	Set while samples are being written into the capture buffer.
ARMED	Status[0]	Set while the analyzer is armed and waiting for a trigger.

trig_mask

Offset 0x10 / Access rw / Reset 0x00000000

Selects which event_i bits participate in hardware trigger comparison.

TrigMask[15:0]

1514131211109876543210

RSVD [15:8]

TRIG MASK [7:0]

TrigMask[31:16]

31302928272625242322212019181716

RSVD [31:16]

Name	Register bit(s)	Description
TRIG MASK	TrigMask[7:0]	A mask bit of 1 enables comparison for the corresponding event_i bit.

trig_value

Offset 0x14 / Access rw / Reset 0x00000000

Expected event value after applying TRIG_MASK.

TrigValue[15:0]

1514131211109876543210

RSVD [15:8]

TRIG VALUE [7:0]

TrigValue[31:16]

31302928272625242322212019181716

RSVD [31:16]

Name	Register bit(s)	Description
TRIG VALUE	TrigValue[7:0]	The analyzer triggers when event_i masked by TRIG_MASK equals this masked value.

pretrig

Offset 0x18 / Access rw / Reset 0x00000000

Reserved pre-trigger depth configuration field retained for host API compatibility.

Pretrig[15:0]

1514131211109876543210

RSVD [15:10]

PRETRIG [9:0]

Pretrig[31:16]

31302928272625242322212019181716

RSVD [31:16]

Name	Register bit(s)	Description
PRETRIG	Pretrig[9:0]	Reserved for future pre-trigger capture-window selection.

posttrig

Offset 0x1C / Access rw / Reset 0x000000FF

Number of post-trigger samples to capture after the trigger condition is accepted.

Posttrig[15:0]

1514131211109876543210

RSVD [15:10]

POSTTRIG [9:0]

Posttrig[31:16]

31302928272625242322212019181716

RSVD [31:16]

Name	Register bit(s)	Description
POSTTRIG	Posttrig[9:0]	Post-trigger capture count. Values wider than ADDR_WIDTH are ignored by the configured hardware instance.

data_index

Offset 0x20 / Access rw / Reset 0x00000000

Capture-buffer read index used by SAMPLE_DATA registers.

DataIndex[15:0]

1514131211109876543210

RSVD [15:10]

DATA INDEX [9:0]

DataIndex[31:16]

31302928272625242322212019181716

RSVD [31:16]

Name	Register bit(s)	Description
DATA INDEX	DataIndex[9:0]	Selects the capture-buffer sample address returned by SAMPLE_DATA0 through SAMPLE_DATA3.

sample_data0

Offset 0x24 / Access ro / Reset 0x00000000

Low 32 bits of the captured sample selected by DATA_INDEX.

SampleData0[15:0]

1514131211109876543210

SAMPLE DATA0 [15:0]

SampleData0[31:16]

31302928272625242322212019181716

SAMPLE DATA0 [31:16]

Name	Register bit(s)	Description
SAMPLE DATA0	SampleData0[31:0]	Captured sample bits 31 downto 0.

sample_now0

Offset 0x28 / Access ro / Reset 0x00000000

Low 32 bits of the live sample input synchronized into the register clock domain.

SampleNow0[15:0]

1514131211109876543210

SAMPLE NOW0 [15:0]

SampleNow0[31:16]

31302928272625242322212019181716

SAMPLE NOW0 [31:16]

Name	Register bit(s)	Description
SAMPLE NOW0	SampleNow0[31:0]	Live sample_i bits 31 downto 0.

event_now

Offset 0x2C / Access ro / Reset 0x00000000

Current event metadata synchronized into the register clock domain.

EventNow[15:0]

1514131211109876543210

RSVD [15:8]

EVENT NOW [7:0]

EventNow[31:16]

31302928272625242322212019181716

RSVD [31:16]

Name	Register bit(s)	Description
EVENT NOW	EventNow[7:0]	Live event_i value observed by the analyzer.

caps

Offset 0x30 / Access ro / Reset 0x00200008

Static hardware capability word for host discovery.

Caps[15:0]

1514131211109876543210

EVENT WIDTH [15:0]

Caps[31:16]

31302928272625242322212019181716

SAMPLE WIDTH [31:16]

Name	Register bit(s)	Description
SAMPLE WIDTH	Caps[31:16]	Configured width of sample_i in bits.
EVENT WIDTH	Caps[15:0]	Configured width of event_i in bits.

sample_data1

Offset 0x34 / Access ro / Reset 0x00000000

Captured sample bits 63 downto 32 when SAMPLE_WIDTH is greater than 32.

SampleData1[15:0]

1514131211109876543210

SAMPLE DATA1 [15:0]

SampleData1[31:16]

31302928272625242322212019181716

SAMPLE DATA1 [31:16]

Name	Register bit(s)	Description
SAMPLE DATA1	SampleData1[31:0]	Upper captured sample word for wider analyzer instances.

sample_data2

Offset 0x38 / Access ro / Reset 0x00000000

Captured sample bits 95 downto 64 when SAMPLE_WIDTH is greater than 64.

SampleData2[15:0]

1514131211109876543210

SAMPLE DATA2 [15:0]

SampleData2[31:16]

31302928272625242322212019181716

SAMPLE DATA2 [31:16]

Name	Register bit(s)	Description
SAMPLE DATA2	SampleData2[31:0]	Additional captured sample word for wide analyzer instances.

sample_data3

Offset 0x3C / Access ro / Reset 0x00000000

Captured sample bits 127 downto 96 when SAMPLE_WIDTH is greater than 96.

SampleData3[15:0]

1514131211109876543210

SAMPLE DATA3 [15:0]

SampleData3[31:16]

31302928272625242322212019181716

SAMPLE DATA3 [31:16]

Name	Register bit(s)	Description
SAMPLE DATA3	SampleData3[31:0]	Additional captured sample word for wide analyzer instances.

Testbenches

tb_radila_core captured waveform

Source: debug/radila/hdl/radila/testbenches/tb_radila_core.vhd

Self-checking or stimulus-focused testbench for radila core. Exercises representative handshakes, reset behavior, frame boundaries, and numeric corner cases for regression runs.

Artifacts: status, vcd

Captured GHDL Waveform

Source: debug/radila/hdl/radila/testbenches/tb_radila_core.vhd

Horizontal Vertical

sample_clk

reg_clk

sample_rstn

reg_rstn

sample[31:0]

event_v[7:0]

irq

reg_wr_addr[15:0]

reg_rd_addr[15:0]

reg_wr_en

reg_rd_en

reg_data_in[31:0]

reg_data_out[31:0]

reg_wr_rdy

reg_rd_rdy

reg_wr_valid

reg_rd_valid

reg_error

sample_i[31:0]

event_i[7:0]

irq_o

control[31:0]

trig_mask[7:0]

trig_value[7:0]

pretrig[5:0]

posttrig[5:0]

data_index[5:0]

cmd_frame[25:0]

cmd_bit

cmd_pending

cmd_req[2:0]

cmd_data_reg[3:0]

cmd_toggle_reg

cmd_ack_reg

cmd_ack_seen

cmd_data_sample[3:0]

cmd_toggle_sample

cmd_ack_sample

cmd_data_meta1[3:0]

cmd_data_meta2[3:0]

cmd_toggle_meta1

cmd_toggle_meta2

cmd_ack_meta1

cmd_ack_meta2

sample_data[31:0]

sample_now_s[31:0]

event_now_s[7:0]

sample_now_reg[31:0]

event_now_reg[7:0]

armed_s

capturing_s

done_s

overflow_s

count_s[6:0]

status_s[10:0]

status_reg[10:0]

status_meta1[10:0]

status_meta2[10:0]

sample_now_meta1[31:0]

sample_now_meta2[31:0]

event_now_meta1[7:0]

event_now_meta2[7:0]

armed

capturing

done

overflow

count[6:0]

rd_data_r[31:0]

wr_valid_r

rd_valid_r

error_r

axi_clk

axi_rstn

cmd_data_i[3:0]

cmd_toggle_i

cmd_ack_toggle_o

rd_index_i[5:0]

rd_data_o[31:0]

sample_now_o[31:0]

event_now_o[7:0]

armed_o

capturing_o

done_o

overflow_o

count_o[6:0]

wr_ptr[5:0]

sample_cnt[6:0]

post_cnt[6:0]

captured[6:0]

ram_we[0:0]

ram_web_zero[0:0]

wr_addr[5:0]

rd_addr[5:0]

ram_dinb_zero[31:0]

unused_douta[31:0]

trigger_match

Sources

debug/radila/hdl/radila/raddebughub.vhd