> This page is for version 3.0 (Latest) (default). > For other versions, use one of these documentation indexes: > - 3.0 (Latest) (default): https://docs.nvidia.com/holoscan/sensor-bridge/3-0/llms.txt > - 2.7: https://docs.nvidia.com/holoscan/sensor-bridge/2-7/llms.txt > - Archives: https://docs.nvidia.com/holoscan/sensor-bridge/archives/llms.txt > 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. # hololink::module::RoceReceiverInterfaceV1 > Controller that manages data reception via RoCE packets. Controller that manages data reception via RoCE packets. This is usually driven by e.g. RoceReceiverOp and serves to set up the host for RDMA data reception, configure the HSB device for compatible data transmission, and provides a routine that observes received data indications and queues those up for application reception. ```cpp showLineNumbers={false} #include ``` **Inherits from:** `hololink::module::ConfigurableService< RoceReceiverInterfaceV1 >` (public) --- ## Methods ### start \[#start] ```cpp showLineNumbers={false} virtual hololink_module_status_t hololink::module::RoceReceiverInterfaceV1::start( const std::string &ibv_name, unsigned ibv_port, uint64_t cu_buffer, size_t cu_buffer_size, size_t cu_frame_size, size_t cu_page_size, unsigned pages, size_t metadata_offset, const std::string &peer_ip, unsigned queue_size ) ``` Configure the receiver and network adapter for RDMA. Frames are delivered into `cu_buffer`, which is a single contiguous region with enough space to accommodate the total number of frames indicated by the [`pages`](#pages) parameter; each frame is `cu_page_size` bytes apart; `cu_page_size` needs to include space for received frame metadata (and its alignment). **Returns:** HOLOLINK_MODULE_OK or an error status. **Throws:** `std::runtime_error` if the receiver cannot be brought up, for example the named device is not found or `peer_ip` is not a valid address. **Parameters** **`ibv_name`** `const std::string &` Name of the InfiniBand verbs device of the network adapter that receives the frames, e.g. "roceP5p3s0f0". --- **`ibv_port`** `unsigned` Port of that device to use. --- **`cu_buffer`** `uint64_t` CUDA memory frames are delivered into, as a CUdeviceptr. --- **`cu_buffer_size`** `size_t` Bytes available at `cu_buffer`. --- **`cu_frame_size`** `size_t` Bytes of frame data expected for each received data frame: the HSB device is programmed to trigger an end-of-frame when this many bytes are received; but an earlier TLAST signal will trigger end-of-frame at an earlier point. --- **`cu_page_size`** `size_t` Bytes from one page to the next. --- **`pages`** `unsigned` Pages the device cycles through. --- **`metadata_offset`** `size_t` Offset, in bytes from the start of a page, of the metadata block the device writes after the frame data. --- **`peer_ip`** `const std::string &` IPv4 address of the device, in dotted-decimal form. The receiver accepts data only from this address. --- **`queue_size`** `unsigned` Completed frames the receiver holds while the application is busy with an earlier one. When a frame completes with this many already waiting, the oldest waiting frame is discarded (see RoceReceiverFrameInfoV1::dropped). --- ### close \[#close] ```cpp showLineNumbers={false} virtual void hololink::module::RoceReceiverInterfaceV1::close() ``` End the run, returning blocking_monitor() to its caller. Callable from any thread, including while blocking_monitor() runs. Does nothing if the receiver was never started. ### blocking_monitor \[#blockingmonitor] ```cpp showLineNumbers={false} virtual void hololink::module::RoceReceiverInterfaceV1::blocking_monitor() ``` Run the receiver until close() is called. Frames arrive only while this runs, so it gets a thread of its own, and that thread carries the CUDA context the receiver was started with. Clients typically execute this in its own thread. **Throws:** `std::runtime_error` if start() has not been called. ### get_next_frame \[#getnextframe] ```cpp showLineNumbers={false} virtual bool hololink::module::RoceReceiverInterfaceV1::get_next_frame( unsigned timeout_ms, RoceReceiverFrameInfoV1 &info ) ``` Take the next completed frame. Waits up to `timeout_ms` for a frame. On successful reception of a frame, `info` is updated with various metadata about the data, which is present at the indicated address within the `cu_buffer` passed to [`start`](#start). Frames are returned in the order they are received. **Returns:** True when a frame was taken; false when the timeout elapsed first. **Throws:** `std::runtime_error` if start() has not been called. **Parameters** **`timeout_ms`** `unsigned` How long to wait for a frame, in milliseconds. --- **`info`** `RoceReceiverFrameInfoV1 &` Describes the frame that was taken. --- ### frames_ready \[#framesready] ```cpp showLineNumbers={false} virtual bool hololink::module::RoceReceiverInterfaceV1::frames_ready() ``` **Returns:** False when get_next_frame() will block waiting for a new frame to arrive. ### set_frame_ready \[#setframeready] ```cpp showLineNumbers={false} virtual void hololink::module::RoceReceiverInterfaceV1::set_frame_ready( std::function callback ) ``` Register a callback run each time a frame becomes available. An application that cannot afford to wait in get_next_frame() is told from here that a frame is waiting, and takes it when it is ready to. The callback runs on the thread running blocking_monitor(). Register it before that starts; pass an empty std::function to stop being called. It stays registered across calls to start(). **Parameters** **`callback`** `std::function` Run once per frame that becomes available. --- ### get_qp_number \[#getqpnumber] ```cpp showLineNumbers={false} virtual uint32_t hololink::module::RoceReceiverInterfaceV1::get_qp_number() ``` The number of the queue pair that receives this channel's frames. The channel programs this into the device so it sends to the right queue pair. **Returns:** The number. Only meaningful once start() has run. **Throws:** `std::runtime_error` if start() has not been called. ### get_rkey \[#getrkey] ```cpp showLineNumbers={false} virtual uint32_t hololink::module::RoceReceiverInterfaceV1::get_rkey() ``` The key the device presents when it writes a frame into the receiver's memory. **Returns:** The key. Only meaningful once start() has run. **Throws:** `std::runtime_error` if start() has not been called. ### external_frame_memory \[#externalframememory] ```cpp showLineNumbers={false} virtual uint64_t hololink::module::RoceReceiverInterfaceV1::external_frame_memory() ``` The address, in the device's view of the receiver's memory, where the first page begins. The device addresses page `n` at this value plus `n` times page_size(). This is not a CUDA address. **Returns:** The address. Only meaningful once start() has run. **Throws:** `std::runtime_error` if start() has not been called. ### frame_size \[#framesize] ```cpp showLineNumbers={false} virtual size_t hololink::module::RoceReceiverInterfaceV1::frame_size() ``` Bytes of frame data the device sends per frame. **Returns:** The `cu_frame_size` start() was given. ### page_size \[#pagesize] ```cpp showLineNumbers={false} virtual size_t hololink::module::RoceReceiverInterfaceV1::page_size() ``` Bytes from one page to the next. **Returns:** The `cu_page_size` start() was given. ### pages \[#pages] ```cpp showLineNumbers={false} virtual unsigned hololink::module::RoceReceiverInterfaceV1::pages() ``` Pages the device cycles through. **Returns:** The [`pages`](#pages) start() was given. ### configure \[#configure] ```cpp showLineNumbers={false} virtual void hololink::module::ConfigurableService::configure( const EnumerationMetadata & ) ``` Use `metadata` contents to initialize this instance. This routine is guaranteed to be called the first time a call to get_service(metadata) is called on a specific service instance. ### module \[#module] ```cpp showLineNumbers={false} std::shared_ptr hololink::module::ServiceBase::module() const ``` The [Module](module) that this service was published from. The service holds no strong reference to its [Module](module), so this does not extend the [Module](module)'s lifetime. **Returns:** The owning [Module](module), or an empty pointer if the service has not been published or its [Module](module) no longer exists. --- ## Static methods ### get_service \[#getservice] #### Fetch a service ```cpp showLineNumbers={false} static std::shared_ptr hololink::module::ConfigurableService::get_service( const EnumerationMetadata &metadata, bool allow_null = false ) ``` Fetch a service, configured by [EnumerationMetadata](enumerationmetadata). [Module](module) usually caches service objects; so when a specific service instance isn't found, it will be constructed with the current values in [EnumerationMetadata](enumerationmetadata). Later calls to get_service are likely to return that cached instance, ignoring changes to any enumeration metadata that aren't specifically related to service addressing. **Returns:** A shared pointer to the requested service (\). **Throws:** `std::runtime_error` when allow_null==false and the service lookup (or construction) fails. **Parameters** **`metadata`** `const EnumerationMetadata &` Addressing and configuration for the service. --- **`allow_null`** `bool` — default: false Use `true` to return nullptr when the service cannot be resolved; the default `false` value raises a std::runtime_error. --- #### Overload 2 inline ```cpp showLineNumbers={false} static std::shared_ptr hololink::module::Service::get_service( std::shared_ptr module, const char *instance_id, bool allow_null = false ) ``` Type-safe way to fetch a std::shared_ptr to an instance of \ from a [Module](module). Note that [Module](module) usually caches instances, it's likely that calls to get_service with the same locator_id will return pointers to the same implementation object. **Returns:** A shared pointer to the service instance. **Parameters** **`module`** `std::shared_ptr` Is the shared object that owns the instance we wish to fetch --- **`instance_id`** `const char *` Names the specific object, usually expressed as a set of "name=value;..." pairs, as defined by the implementations themselves. This name is normally fetched by calling `Derived::locator_id(enumeration_metadata)`. --- **`allow_null`** `bool` — default: false The default value of `false` causes this routine to throw a std::runtime_error if the service cannot be found within the module; this would be expected to terminate the calling program. If the application wants to handle the error, pass in `true` here and get_service will return `nullptr` when this module doesn't provide the requested service. --- ### for_each_type_id \[#foreachtypeid] ```cpp showLineNumbers={false} static bool hololink::module::Service::for_each_type_id( Callback &&cb ) ``` Iterate over every type_id supported by this instance. The callback signature is `bool(const char*)` — returning false halts the walk; true continues. Iteration is depth-first, so you'll see the most specific implementation types first.