> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/holoscan/sensor-bridge/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sensor-bridge/_mcp/server.
## Top Level Module
The top level module of the Holoscan Sensor Bridge IP is "HOLOLINK\_top".
## User Configurability
The Holoscan Sensor Bridge (HSB) IP is designed to be easily configurable to various use
case of the IP, such as number of sensors and Ethernet ports. It’s also designed to be
compatible with multiple FPGA vendors. The following describes the configurations
available to user.
### Macro Definitions
The Holoscan Sensor Bridge definitions file, “HOLOLINK\_def.svh”, defines the following
macros.
The macros can be configured to user’s application of the Holoscan Sensor Bridge IP. The
default macro value is the configuration that has been tested and verified.
Table 1
| **Macro** | **Tested Values** | **Description** |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| HIF\_CLK\_FREQ | 156250000 (for DATAPATH\_WIDTH=64)
201416016 (for DATAPATH\_WIDTH=512) | Clock frequency of the Host Interface. Unit is in Hz |
| APB\_CLK\_FREQ | 19531250 (for DATAPATH\_WIDTH=64)
100000000 (for DATAPATH\_WIDTH=512) | Clock frequency of the APB Interface. Unit is in Hz |
| PTP\_CLK\_FREQ | 100446545 | Clock frequency of the PTP Interface. Unit is in Hz. Range 95MHz to 105MHz |
| UUID\[127:0] | 128'h889B7CE3\_65A5\_4247\_8B05\_4FF1904C3359 for Lattice LF-SNSR-ETH-EVN
128'hED6A9292\_DEBF\_40AC\_B603\_A24E025309C1 for Microchip MPF200-ETH-SENSOR-BRIDGE
128'hF1627640\_B4DC\_48AF\_A360\_C65B09B3D230 for Leopard Imaging VB1940 Eagle Camera
128'h9957A9AC\_36B5\_4518\_83EC\_5D514AECB750 for TauroTech DA326 | Universally Unique Identifier are used to identify the board to fetch and remote flash the correct bitfile. |
| ENUM\_EEPROM | Defined or undefined | When defined, read the contents of the Enumeration packet from external non-volatile memory. If undefined, use the macros defined below\.. |
| EEPROM\_REG\_ADDR\_BITS | 8 or 16 | Valid when ENUM\_EEPROM is defined. Number for register address bits used in the EEPROM. |
| DATAPATH\_WIDTH | 8, 16, 32, 64, 128, 256, 512, 1024 | Width of the Sensor AXI Stream TDATA in bits. This number must be byte-aligned. Meaning, it must be a number divisible by 8. |
| DATAKEEP\_WIDTH | DATAPATH\_WIDTH/8 | Width of the Sensor AXI Stream TKEEP.This should not be changed. |
| DATAUSER\_WIDTH | 1-2 | Width of the Sensor AXI Stream TUSER signal. |
| SENSOR\_RX\_IF\_INST | undefined, 1-32 | Number of Sensor RX Interface. |
| SIF\_RX\_WIDTH\[SENSOR\_RX\_IF\_INST-1:0] | 8, 16, 32, 64, 128, 256, 512, 1024 | Valid when SENSOR\_RX\_IF\_INST is defined. Each Sensor RX interface width can be individually defined. Max value should be DATAPATH\_WIDTH. |
| SIF\_RX\_DATA\_GEN | undefined, defined | Valid when SENSOR\_RX\_IF\_INST is defined. Instantiates a Data Generator module to test Sensor to Host data path. |
| SIF\_RX\_PACKETIZER\_EN\[SENSOR\_RX\_IF\_INST-1:0] | 0, 1 | Valid when SENSOR\_RX\_IF\_INST is defined. Each Sensor RX interface Packetizer can be individually enabled. |
| SIF\_RX\_VP\_COUNT\[SENSOR\_RX\_IF\_INST-1:0] | DO NOT TOUCH | Valid when SENSOR\_RX\_IF\_INST and SIF\_RX\_PACKETIZER\_EN is defined. TBD. Do not change. |
| SIF\_RX\_SORT\_RESOLUTION\[SENSOR\_RX\_IF\_INST-1:0] | DO NOT TOUCH | Valid when SENSOR\_RX\_IF\_INST and SIF\_RX\_PACKETIZER\_EN is defined. TBD. Do not change. |
| SIF\_RX\_VP\_SIZE\[SENSOR\_RX\_IF\_INST-1:0] | DO NOT TOUCH | Valid when SENSOR\_RX\_IF\_INST and SIF\_RX\_PACKETIZER\_EN is defined. TBD. Do not change. |
| SIF\_RX\_NUM\_CYCLES\[SENSOR\_RX\_IF\_INST-1:0] | DO NOT TOUCH | Valid when SENSOR\_RX\_IF\_INST and SIF\_RX\_PACKETIZER\_EN is defined. TBD. Do not change. |
| SENSOR\_TX\_IF\_INST | undefined, 1-32 | Number of Sensor TX Interface. |
| SIF\_TX\_WIDTH\[SENSOR\_TX\_IF\_INST-1:0] | 8, 64, 512 | Valid when SENSOR\_TX\_IF\_INST is defined. Each Sensor TX interface width can be individually defined. Max value should be DATAPATH\_WIDTH. |
| SIF\_TX\_BUF\_SIZE\[SENSOR\_TX\_IF\_INST-1:0] | 1024, 2048, 4096 | Valid when SENSOR\_TX\_IF\_INST is defined. Set the Sensor TX Buffer Size. |
| HOST\_WIDTH | 8, 16, 32, 64, 128, 256, 512 | Width of the Host AXI Stream TDATA in bits. This number must be byte-aligned. Meaning, it must be a number divisible by 8. |
| HOSTKEEP\_WIDTH | HOST\_WIDTH/8 | Width of the Host AXI Stream TKEEP.This should not be changed. |
| HOSTUSER\_WIDTH | 1 | Width of the Host AXI Stream TUSER signal. |
| HOST\_IF\_INST | 1-32 | Number of Host interfaces. |
| HOST\_MTU | 1500, 4096 | Size of Ethernet packet in bytes. |
| SPI\_INST | undefined, 1-8 | Number of SPI interfaces. |
| I2C\_INST | undefined, 1-8 | Number of I2C interfaces. |
| UART\_INST | undefined, 1 | Number of UART interfaces. |
| GPIO\_INST | 1-255 | Number of GPIO Input & Output bits. |
| GPIO\_RESET\_VALUE\[GPIO\_INST-1:0] | 0 | Reset value of GPIO bits. |
| REG\_INST | 1-8 | Number of user register. |
| N\_INIT\_REG | undefined, Integer value | Number of initialization registers. |
### Build Revision
Parameter `BUILD_REV[47:0]` can be passed down to the "HOLOLINK\_top" module to uniquely
identify the FPGA build revision.
### Sensor Interface Configuration
In applications where the HSB IP connects multiple sensors with varying bandwidths, the
IP can be configured on a per-sensor-interface basis to optimize resource utilization.
The `DATAPATH_WIDTH` parameter defines the AXI Stream vector width for all sensor
interfaces to simplify integration and should be set to match the widest sensor. The
`SIF_RX_WIDTH` and `SIF_TX_WIDTH` parameters can be configured individually to specify
narrower data widths for each sensor interface.
For example, if the first sensor interface has a width of 64 bits and the second has 32
bits: Set `DATAPATH_WIDTH` to 64 and set `SIF_RX_WIDTH` to `{32, 64}`. For second sensor
interface, only the \[31:0] of the AXI Stream TDATA and \[3:0] of the AXI Stream TKEEP are
used and the remaining signals should be tied to 0. The LSB \[3:0] of AXI Stream TKEEP is
still required to be set to all 1'b1.
Furthermore, the Packetizer function, which is needed when streaming camera to Thor, can
be enabled for each sensor interface. For example, if the first sensor needs the
Packetizer function but the second sensor does not, set `SIF_RX_PACKETIZER_EN` parameter
to `{0,1}`.
HSB IP supports Virtual Port mapping. For more information, refer to
[Sensor Interface to Virtual Port Mapping](/holoscan/sensor-bridge/fpga-ip/dataplane#sensor-interface-to-virtual-port-mapping)
### BOOTP Packet
The HSB IP transmits a broadcast BOOTP Request packet (adhering to RFC-951) on each Host
interface. BOOTP Request packets are used to enumerate the HSB to host and to change the
IP address from default in case of multiple board enumeration. Default IP address of HSB
IP is "192.168.0.2" for Host interface 0 and "192.168.0.3" for Host interface 1 and so
on. BOOTP Request packets are sent once a second. If PTP internal to the HSB IP is used,
BOOTP packet is sent every pulse-per-second (PPS) which is internally generated in the
"i\_ptp\_clk" domain. If `EXT_PTP` macro is defined, then PPS is internally generated when
the LSB of "i\_ptp\_sec" input port toggles.
The Vendor Field of the BOOTP packet is used to communicate enumeration info and status
of HSB to the host. The BOOTP Vendor field is laid out in below table:
Table 2
| **Byte Number** | **Description** | **Value** |
| --------------- | --------------------------------- | ------------------------------------------------------------------------------ |
| \[0] | Vendor Tag | 0xE0 |
| \[1] | Tag Length | 0x38 |
| \[5:2] | ASCII "NVDA" | 0x4144564E, in Big Endian format |
| \[6] | Ethernet Port Number | 0x0 for Port 0 , 0x1 for Port 1 |
| \[7] | Enumeration Version | 0x2 |
| \[9:8] | Reserved | Reserved. Set to 0. |
| \[25:10] | UUID | UUID defined in HOLOLINK\_def.svh. Big Endian format |
| \[29:26] | Reserved | Reserved. |
| \[36:30] | Board Serial Number | BOARD\_SN fetched from EEPROM or from HSB IP input port. Little Endian format. |
| \[38:37] | Holoscan Sensor Bridge IP Version | *0x2606* for *Holoscan SDK v2.7.0* release. Little Endian format. |
| \[44:39] | Reserved | Reserved. |
| \[54:45] | PTP Timestamp | PTP Timestamp. Seconds and Nanoseconds in PTP v2 format. Big Endian format. |
| \[56:55] | Packet Sequence Number | Packet Sequence Number. Increments per BOOTP packet sent. Big Endian format. |
| \[57] | Status | 0x1 when PTP is enabled in HSB and a SYNC PTP packet has been received. |
| \[63:58] | Reserved | Reserved. Set to 0. |
Each of the macros used for enumeration packet is further explained below.
UUID: This macro defines the unique identifier for the board. Holoscan uses this value
to identify which board it is interfacing and fetch the correct bitfile for remote
flash. For newly developed boards, users can generate and assign a new UUID. This macro
must be defined and is not optionally stored in the non-volatile memory.
ENUM\_EEPROM: When this macro is defined, enumeration fields, the MAC address and Board
Serial Number, are retrieved from an on-board, non-volatile memory upon boot-up. The
enumeration fields are retrieved over I2C port 0 with EEPROM 7-bit address 0x50.
Mass production of boards with Holoscan Sensor Bridge IP requires an external EEPROM to
store unique MAC address and board serial numbers. When using evaluation platforms for
test and bring-up, enumeration fields, MAC address and Board Serial Number, can be
passed to HSB IP via input port.
When retrieving from EEPROM, the MAC address and board serial number must be placed in
these EEPROM register address.
| EEPROM address (decimal) | MAC bits |
| ------------------------ | ---------------- |
| 68 | MAC\[47:40] |
| 69 | MAC\[39:32] |
| 70 | MAC\[31:24] |
| 71 | MAC\[23:16] |
| 72 | MAC\[15:8] |
| 73 | MAC\[7:0] |
| 74 | Board SN\[55:48] |
| 75 | Board SN\[47:40] |
| 76 | Board SN\[39:32] |
| 77 | Board SN\[31:24] |
| 78 | Board SN\[23:16] |
| 79 | Board SN\[15:8] |
| 80 | Board SN\[7:0] |
## System Initialization
The Holoscan Sensor Bridge IP provides system initialization function to write to
registers upon power up. This function is used to initialize the Ethernet block to
establish ethernet connection between the FPGA and the host, and can be used for any
other user function in the top level design.
The list of registers to be initialized is defined in “HOLOLINK\_def.svh” as “init\_reg”
array. The “init\_reg” is an unpacked array, sized \[N\_INIT\_REG] \[63:0], where the
N\_INIT\_REG macro defines the number of registers to be initialized and the 64-bit vector
is used to define the 32-bit address of register at \[63:32] and the 32-bit write data at
\[31:0].
To give an example of one of the init\_reg array entry:
```
{32'h1000_0020, 32'h0000_00FF} //init_reg[0]
```
Will write to the User REG\_INST\_0 block address offset 0x0000\_0020 the data 0x0000\_00FF.
Once system initialization is complete, the “o\_init\_done” port will be asserted high in
“i\_apb\_clk” domain. User can use this signal to gate their logic if it’s dependent on
ethernet block initialization.