Driver

PUSCH pipeline manager with device memory handling and multi-cell slot coordination.

Overview

The Driver manages PUSCH pipeline lifecycle and coordinates multi-cell processing:

• Pipeline Creation - Creates PUSCH pipelines with TensorRT engines (Stream or Graph execution modes)

• Device Memory Management - Allocates CUDA device memory for pipeline inputs/outputs

• Slot Response Tracking - Tracks which cells have responded per slot using atomic operations

• Pipeline Launch - Launches PUSCH pipeline execution when all cells are ready

• UL Indication Callbacks - Notifies when pipeline execution completes

API Reference

using ran::driver::UlIndicationCallback = std::function<void(std::size_t slot)>

UL Indication Callback

Callback function type for sending UL indications from Driver to the pipeline owner. Called after pipeline execution completes.

Param slot:

[in] Slot number that was processed

ran::driver::DECLARE_LOG_COMPONENT(

DriverComponent,

Driver,

PuschPipelineContext,

)

Driver logging components

ran::driver::DECLARE_LOG_EVENT(

DriverEvent,

CreatePuschPipeline,

SlotResponseReceived,

ResetSlotStatus,

LaunchPipelines,

UlIndication,

AllocatePuschInputMemory,

GetPipelineResource,

ReleasePipelineResource,

GetHostBuffers,

ReleaseHostBuffers,

SaveHostBuffersIndex,

SavePipelineIndex,

GetSlotResources,

ClearSlotResources,

PrepareInputData,

)

Driver event logging identifiers

static inline pusch::PuschDynamicParams ran::driver::prepare_mock_pusch_dynamic_params(

)

class Driver

#include <driver.hpp>

Pipeline Driver

Manages device memory allocation for external inputs to PUSCH pipelines. Handles allocation, deallocation, and data transfer for pipeline processing.

Features:

• CUDA device memory management

• RAII-based resource handling

• Support for multiple pipelines

• External input/output buffer management

• Slot response tracking across multiple cells

Public Functions

Driver()

~Driver() = default

Destructor

Driver(const Driver&) = delete

Driver &operator=(const Driver&) = delete

Driver(Driver&&) = delete

Driver &operator=(Driver&&) = delete

void create_pusch_pipeline(

const ran::common::PhyParams &phy_params,

const std::string &execution_mode,

UlIndicationCallback ul_indication_callback,

std::span<const framework::pipeline::PortInfo> order_kernel_outputs,

)

Create PUSCH pipeline based on physical layer parameters

Parameters:

• phy_params – [in] Physical layer parameters

• execution_mode – [in] Pipeline execution mode (“Stream” or “Graph”)

• ul_indication_callback – [in] Callback function for sending UL indications

• order_kernel_outputs – [in] Order Kernel output addresses from Fronthaul (captured after warmup)

bool process_slot_response(

std::size_t slot,

std::uint16_t cell_id,

std::uint32_t active_cell_bitmap,

)

Process slot response from a cell

Updates the slot_ready array with the cell’s response. If all active cells have responded for this slot, marks the slot as completed.

Parameters:

• slot – [in] Slot number (0 to ran::common::NUM_SLOTS_PER_SF-1)

• cell_id – [in] Cell ID that sent the response

• active_cell_bitmap – [in] Bitmap of currently active cells

Returns:

true if all active cells have responded for this slot, false otherwise

void reset_slot_status(std::size_t slot)

Reset slot ready status for a specific slot

Parameters:

slot – [in] Slot number (0 to ran::common::NUM_SLOTS_PER_SF-1)

void launch_pipelines(std::size_t slot)

Launch pipeline processing for a completed slot

Parameters:

slot – [in] Slot number (0 to ran::common::NUM_SLOTS_PER_SF-1)

Public Members

PuschPipelineContext pusch_pipeline_context

PUSCH pipeline context.

std::array<SlotReadyStatus, ran::common::NUM_SLOTS_PER_SF> slot_ready = {}

Slot readiness tracking.

struct PuschHostBuffers

#include <pusch_pipeline_context.hpp>

PUSCH Host Buffers

Encapsulates both input and output host-side buffers for PUSCH processing. Provides unified management of related input/output data structures.

Public Functions

PuschHostBuffers() = default

Default constructor

inline void reset()

Reset both input and output buffers

PuschHostBuffers(const PuschHostBuffers&) = delete

Copy constructor (deleted)

PuschHostBuffers &operator=(const PuschHostBuffers&) = delete

Copy assignment (deleted)

PuschHostBuffers(PuschHostBuffers&&) = delete

Move constructor (deleted)

PuschHostBuffers &operator=(PuschHostBuffers&&) = delete

Move assignment (deleted)

~PuschHostBuffers() = default

Destructor (default)

Public Members

PuschHostInput inputs

Host input buffers.

PuschHostOutput outputs

Host output buffers.

struct PuschHostInput

#include <pusch_pipeline_context.hpp>

PUSCH Host Input Wrapper

Encapsulates host-side input data with RAII cleanup.

Public Functions

inline PuschHostInput()

Default constructor - initializes vectors with proper sizes

inline void reset()

Reset all index counters to 0

PuschHostInput(const PuschHostInput&) = delete

Copy constructor (deleted)

PuschHostInput &operator=(const PuschHostInput&) = delete

Copy assignment (deleted)

PuschHostInput(PuschHostInput&&) = delete

Move constructor (deleted)

PuschHostInput &operator=(PuschHostInput&&) = delete

Move assignment (deleted)

~PuschHostInput() = default

Destructor (default)

Public Members

pusch::PuschInput pusch_inputs = {}

Host-side input data.

struct PuschHostOutput

#include <pusch_pipeline_context.hpp>

PUSCH Host Output Wrapper

Encapsulates host-side output data with RAII cleanup for pinned memory.

Public Functions

inline PuschHostOutput()

Constructor - allocates pinned memory for transport block payloads

inline ~PuschHostOutput() noexcept

inline void reset()

Reset output buffer state

PuschHostOutput(const PuschHostOutput&) = delete

Copy constructor (deleted)

PuschHostOutput &operator=(const PuschHostOutput&) = delete

Copy assignment (deleted)

PuschHostOutput(PuschHostOutput&&) = delete

Move constructor (deleted)

PuschHostOutput &operator=(PuschHostOutput&&) = delete

Move assignment (deleted)

Public Members

pusch::PuschOutput pusch_outputs = {}

Host-side output data.

Public Static Attributes

static constexpr std::uint32_t TB_PAYLOAD_BUFFER_SIZE = (ran::common::MAX_NUM_UE_GRPS * ran::common::MAX_NUM_UES_PER_UE_GRP * ran::common::PUSCH_MAX_TB_SIZE_BYTES * ran::common::NUM_CELLS_SUPPORTED)

Maximum buffer size for transport block payloads.

class PuschPipelineContext

#include <pusch_pipeline_context.hpp>

PUSCH Pipeline Context

Manages multiple PUSCH pipeline instances with their associated resources.

Public Functions

PuschPipelineContext()

Constructor

~PuschPipelineContext() = default

Destructor

PuschPipelineContext(const PuschPipelineContext&) = delete

PuschPipelineContext &operator=(const PuschPipelineContext&) = delete

PuschPipelineContext(PuschPipelineContext&&) = delete

PuschPipelineContext &operator=(PuschPipelineContext&&) = delete

void create_pusch_pipeline(

const ran::common::PhyParams &phy_params,

framework::pipeline::ExecutionMode execution_mode,

std::span<const framework::pipeline::PortInfo> order_kernel_outputs,

)

Create PUSCH pipeline

Parameters:

• phy_params – [in] Physical layer parameters

• execution_mode – [in] Execution mode (Graph or Stream)

• order_kernel_outputs – [in] Output buffers from Order Kernel pipeline (PUSCH IQ data)

std::optional<std::pair<std::size_t, PuschPipelineResources*>> get_pipeline_resource(

)

Atomically allocate and get an available pipeline resource from the pool

Returns:

Optional pair of (resource_index, resource_pointer) if available, std::nullopt if all resources are in use

bool release_pipeline_resource(std::size_t resource_index)

Release a previously allocated pipeline resource

Parameters:

resource_index – [in] Index of the resource to release

Returns:

true if successfully released, false if index was invalid or already free

std::optional<std::pair<std::size_t, PuschHostBuffers*>> get_host_buffers(

)

Atomically allocate and get an available host input from the pool

Returns:

Optional pair of (resource_index, resource_pointer) if available, std::nullopt if all resources are in use

bool release_host_buffers(std::size_t resource_index)

Release a previously allocated host buffers

Parameters:

resource_index – [in] Index of the resource to release

Returns:

true if successfully released, false if index was invalid or already free

PuschHostInput &get_host_input_by_index(std::size_t resource_index)

Get host input by index

Parameters:

resource_index – [in] Index of the host input (0 to ran::common::MAX_PUSCH_PIPELINES-1)

Throws:

std::out_of_range – if index is invalid

Returns:

Reference to PuschHostInput

PuschHostOutput &get_host_output_by_index(

std::size_t resource_index,

)

Get host output by index

Parameters:

resource_index – [in] Index of the host output (0 to ran::common::MAX_PUSCH_PIPELINES-1)

Throws:

std::out_of_range – if index is invalid

Returns:

Reference to PuschHostOutput

cudaStream_t get_stream_by_index(std::size_t pipeline_index) const

Get CUDA stream by pipeline index

Parameters:

pipeline_index – [in] Index of the pipeline (0 to ran::common::MAX_PUSCH_PIPELINES-1)

Throws:

std::out_of_range – if index is invalid

Returns:

CUDA stream associated with the pipeline

const std::vector<framework::pipeline::PortInfo> &get_external_outputs_by_index(

std::size_t pipeline_index,

) const

Get external outputs by pipeline index

Parameters:

pipeline_index – [in] Index of the pipeline (0 to ran::common::MAX_PUSCH_PIPELINES-1)

Throws:

std::out_of_range – if index is invalid

Returns:

Reference to external outputs vector

std::size_t get_available_pipeline_count() const

Get number of available (free) pipeline resources

Returns:

Number of free pipeline resources

std::size_t get_available_host_buffers_count() const

Get number of available (free) host buffers

Returns:

Number of free host buffers

void save_host_buffers_index(

std::size_t slot,

std::size_t host_buffers_index,

)

Save host buffers index for a specific slot

Parameters:

• slot – [in] Slot number (0 to ran::common::NUM_SLOTS_PER_SF-1)

• host_buffers_index – [in] Host buffers resource index

void save_pipeline_index(

std::size_t slot,

std::size_t pipeline_index,

)

Save pipeline index for a specific slot

Parameters:

• slot – [in] Slot number (0 to ran::common::NUM_SLOTS_PER_SF-1)

• pipeline_index – [in] Pipeline resource index

const PuschSlotResources &get_slot_resources(std::size_t slot) const

Get resource indices for a specific slot

Parameters:

slot – [in] Slot number (0 to ran::common::NUM_SLOTS_PER_SF-1)

Returns:

Reference to slot resources

void clear_slot_resources(std::size_t slot)

Clear resource indices for a specific slot

Parameters:

slot – [in] Slot number (0 to ran::common::NUM_SLOTS_PER_SF-1)

Public Static Functions

static bool prepare_input_data(

uint16_t sfn,

uint16_t cell_id,

const scf_fapi_pusch_pdu_t &pusch_pdu,

pusch::PuschInput &pusch_input,

const ran::common::PhyParams &phy_params,

)

Prepare PUSCH input data from FAPI PDU

Converts FAPI PUSCH PDU to PuschInput format and validates parameters.

Parameters:

• sfn – [in] System Frame Number

• cell_id – [in] Cell ID

• pusch_pdu – [in] FAPI PUSCH PDU containing input parameters

• pusch_input – [inout] PuschInput structure to populate

• phy_params – [in] Physical layer parameters for validation

Returns:

true if successful, false if validation fails

static pusch::PuschDynamicParams prepare_pusch_dynamic_params(

const pusch::PuschInput &pusch_input,

)

Prepare PUSCH dynamic parameters from input data

Parameters:

pusch_input – [in] PUSCH input data containing UE parameters

Returns:

Prepared dynamic parameters for pipeline execution

struct PuschPipelineResources

#include <pusch_pipeline_context.hpp>

PUSCH Pipeline Resource Bundle

Encapsulates pipeline, external inputs, and CUDA stream. Ensures proper RAII cleanup.

Public Functions

inline PuschPipelineResources()

Constructor - creates and initializes the CUDA stream

~PuschPipelineResources() noexcept

Destructor - cleans up all resources

PuschPipelineResources(const PuschPipelineResources&) = delete

Copy constructor (deleted)

PuschPipelineResources &operator=(

const PuschPipelineResources&,

) = delete

Copy assignment (deleted)

PuschPipelineResources(PuschPipelineResources&&) = delete

Move constructor (deleted)

PuschPipelineResources &operator=(PuschPipelineResources&&) = delete

Move assignment (deleted)

Public Members

std::unique_ptr<pusch::PuschPipeline> pipeline

PUSCH pipeline instance.

std::vector<framework::pipeline::PortInfo> external_inputs

External input ports (borrowed, non-owning)

cudaStream_t stream = {}

CUDA stream for this pipeline.

std::vector<framework::pipeline::PortInfo> external_outputs

External output ports.

struct PuschSlotResources

#include <pusch_pipeline_context.hpp>

PUSCH Resource Indices per Slot

Tracks which pipeline and host input resources are allocated for a specific slot. Uses -1 as sentinel value for “not set”. Uses atomic operations for lock-free access.

Public Functions

inline bool has_resources() const

Check if both resources are allocated

Returns:

true if both pipeline and host input are allocated (not -1)

inline void clear()

Clear all resource indices

Public Members

std::atomic<std::ptrdiff_t> pipeline_index = {-1}

Pipeline resource index (lock-free)

std::atomic<std::ptrdiff_t> host_buffers_index = {-1}

Host buffers resource index (lock-free)

struct SlotReadyStatus

#include <driver.hpp>

Slot Readiness Tracking

Tracks which cells have sent slot responses for a given slot. Uses atomic operations for lock-free access.

Public Members

std::atomic<std::uint32_t> slot_rsp_rcvd{0}

Bitmap of cells that have responded (lock-free)

std::atomic<bool> is_completed{false}

True when all active cells have responded (lock-free)