hololink::module::LinuxReceiverInterfaceV1

Provide device-side support for LinuxReceiver.

The device transmits a data channel’s frames to a host socket as a stream of UDP datagrams. This receiver reassembles that stream into whole frames and delivers each one into CUDA memory the application supplies, along with a LinuxReceiverFrameInfoV1 describing it. One receiver serves one data channel; RoceReceiverInterfaceV1 is the counterpart for channels the NIC receives without the host reading packets.

Fetch it with the EnumerationMetadata describing the channel, after fetching that channel’s LinuxDataChannelInterfaceV1.

The application drives the receiver:

• start() prepares the receiver over a socket the channel has already prepared, and over the CUDA buffer frames are delivered into. The values the channel programs the device with are readable once it returns, so this precedes LinuxDataChannelInterfaceV1::attach_receiver().
• blocking_monitor() runs the receiver and returns when close() is called, so it gets a thread of its own.
• get_next_frame() hands over frames as they complete; frames_ready() and set_frame_ready() tell an application when one is waiting.
• close() ends the run, and start() may then run the receiver again.

#include <hololink/module/linux_receiver.hpp>

Inherits from: hololink::module::ConfigurableService< LinuxReceiverInterfaceV1 > (public)

Methods

start

virtual hololink_module_status_t hololink::module::LinuxReceiverInterfaceV1::start(
    int data_socket,
    uint64_t cu_buffer,
    size_t cu_buffer_size,
    size_t cu_frame_size,
    size_t cu_page_size,
    unsigned pages,
    unsigned queue_size
)

Prepare the receiver to run over a socket and a CUDA buffer.

Frames are delivered into cu_buffer, one frame at a time. The device writes each frame to one of pages pages, cu_page_size bytes apart, so a page holds a frame’s data, the padding that aligns it, and the metadata block that follows it.

get_qp_number(), get_rkey(), local_port(), frame_size(), page_size() and pages() report what the device is programmed with once this returns, so an application calls this before LinuxDataChannelInterfaceV1::attach_receiver(). Calling it again after close() runs the receiver a second time.

Returns: HOLOLINK_MODULE_OK or an error status.

Parameters

close

virtual void hololink::module::LinuxReceiverInterfaceV1::close()

End the run, returning blocking_monitor() to its caller.

Callable from any thread, including while blocking_monitor() runs.

blocking_monitor

virtual void hololink::module::LinuxReceiverInterfaceV1::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.

get_next_frame

virtual bool hololink::module::LinuxReceiverInterfaceV1::get_next_frame(
    unsigned timeout_ms,
    LinuxReceiverFrameInfoV1 &info,
    void *cuda_stream
)

Take the next completed frame.

Waits up to timeout_ms for a frame, then delivers it into the CUDA buffer start() was given and describes it in info. The copy runs on cuda_stream, so work already queued on that stream precedes it and work queued afterwards sees the frame.

Returns: True when a frame was delivered; false when the timeout elapsed first.

Parameters

frames_ready

virtual bool hololink::module::LinuxReceiverInterfaceV1::frames_ready()

Whether a frame is waiting to be taken.

Returns: True when get_next_frame() has a frame to hand over; false when it would wait for one.

set_frame_ready

virtual void hololink::module::LinuxReceiverInterfaceV1::set_frame_ready(
    std::function<void()> 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.

Parameters

get_qp_number

virtual uint32_t hololink::module::LinuxReceiverInterfaceV1::get_qp_number()

The connection number the device stamps into this channel’s packets.

Returns: The number, once start() has run.

get_rkey

virtual uint32_t hololink::module::LinuxReceiverInterfaceV1::get_rkey()

The key the device presents when it writes a frame.

Returns: The key, once start() has run.

local_port

virtual uint32_t hololink::module::LinuxReceiverInterfaceV1::local_port()

The UDP port the device transmits this channel’s frames to.

The port the socket given to start() is bound to.

Returns: The port, once start() has run.

frame_size

virtual size_t hololink::module::LinuxReceiverInterfaceV1::frame_size()

Bytes of frame data the device sends per frame.

Returns: The cu_frame_size start() was given.

page_size

virtual size_t hololink::module::LinuxReceiverInterfaceV1::page_size()

Bytes from one page to the next.

Returns: The cu_page_size start() was given.

pages

virtual unsigned hololink::module::LinuxReceiverInterfaceV1::pages()

Pages the device cycles through.

Returns: The pages start() was given.

configure

virtual void hololink::module::ConfigurableService<LinuxReceiverInterfaceV1>::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

std::shared_ptr<Module> hololink::module::ServiceBase::module() const

The Module that this service was published from.

The service holds no strong reference to its Module, so this does not extend the Module’s lifetime.

Returns: The owning Module, or an empty pointer if the service has not been published or its Module no longer exists.

Static methods

get_service

static std::shared_ptr<LinuxReceiverInterfaceV1> hololink::module::ConfigurableService<LinuxReceiverInterfaceV1>::get_service(
    const EnumerationMetadata &metadata,
    bool allow_null = false
)

for_each_type_id

static bool hololink::module::Service<LinuxReceiverInterfaceV1>::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.