cuMAC-CP API Messages#

This section provides a description of the cuMAC-CP API message formats. It defines the PHY API message header, the message bodies and the error codes associated with the cuMAC-CP API.

The cuMAC-CP API messages include 2 kinds: configuration procedure messages and slot procedure messages. Both kinds of messages start with the generic header as below table

Field

Type

Description

message_count

uint8_t

Number of messages included in PHY API message

handle_id

uint8_t

An opaque handle (purpose not defined, however, usages may include a PHY ID or Carrier ID)

type_id

uint16_t

Message type ID

body_len

uint32_t

Length of message body (bytes)

All the message IDs are listed as below.

Message

Value

Message Body Definition

CONFIG.request

0x02

CONFIG.response

0x03

START.request

0x04

STOP.request

0x05

STOP.response

0x06

ERROR.indication

0x07

TODO

START.response

0x08

RESERVED

0x09-0x7F

SCH_TTI.request

0x82

TTI_END

0x83

SCH_TTI.response

0x8F

TTI_ERR.indication

0x90

TODO

RESERVED

0x91-0xFF

Configuration Procedure Messages#

Configuration procedure messages are followed by configuration message bodies.

CONFIG.request#

The CONFIG.request message body is defined in cuMAC per cell message definition.

Field

Type

Description

nMaxCell

uint8_t

A constant integer for the maximum number of cells in the cell group.

Value: 0 -> 255

nMaxActUePerCell

uint16_t

A constant integer for the maximum number of active UEs per cell.

Value: 0 -> 65535

nMaxSchUePerCell

uint8_t

A constant integer for the maximum number of UEs that can be scheduled per TTI per cell.

Value: 0 -> 255

nMaxPrg

uint16_t

A constant integer for the maximum number of PRGs for allocation in each cell

Value: 0 -> 65535

nPrbPerPrg

uint8_t

A constant integer for the number of PRBs per PRG (PRB group)

Value: 0 -> 255

nMaxBsAnt

uint8_t

A constant integer for the maximum number of BS antenna ports.

Value: 0 -> 255

nMaxUeAnt

uint8_t

A constant integer for the maximum number of UE antenna ports.

Value: 0 -> 255

scSpacing

uint32_t

Subcarrier spacing of the carrier.

Value: 15000, 30000, 60000, 120000 (Hz)

allocType

uint8_t

Indicator for type-0 or type-1 PRG allocation.

Value:

0: type-0 allocation

1: type-1 allocation

precoderType

uint8_t

Indicator for the precoder type.

Value:

0: No precoding

1: SVD precoding

receiverType

uint8_t

Indicator for the receiver type.

Value:

0: MMSE receiver

1: MMSE-IRC receiver

colMajChanAccess

uint8_t

Indicator for whether the estimated narrow-band SRS channel matrices are stored in column-major order or in row-major order.

Value:

0: row-major

1: column-major

betaCoeff

float

Coefficient for adjusting the cell-edge UEs’ performance in multi-cell scheduling.

Value: non-negative real number. The default value is 1.0, representing pure proportional-fairness scheduling.

sinValThr

float

Singular value threshold for layer selection.

Value: in (0, 1). Default value is 0.1

corrThr

float

Channel vector correlation value threshold for layer selection.

Value: in (0, 1). Default value is 0.5

prioWeightStep

uint16_t

Step size for UE priority weight increment per TTI if UE does not get scheduled. For priority-based UE selection.

Value: 0 -> 65535. Default is 100

CONFIG.response#

The message body is as below.

Field

Type

Description

error_code

uint8_t

0: no error. Other: TBD

START.request#

The message body is as below.

Field

Type

Description

start_param

uint8_t

Reserved, not used yet.

START.response#

The message body is as below.

Field

Type

Description

error_code

uint8_t

0: no error. Other: TBD

Slot procedure messages#

Slot procedures have an additional SFN/SLOT header as below table, then followed by slot message bodies.

Name

Type

Description

sfn

uint16_t

SFN number

slot

uint16_t

SLOT number

SCH_TTI.request#

Field

Type

Description

taskBitMask

uint32_t

Indicate which cuMAC tasks to be scheduled. Each bit represents 1 task type:

0x01: multiCellUeSelection

0x02: multiCellScheduler

0x04: multiCellLayerSel

0x08: mcsSelectionLUT

Value: 0x1, 0x3, 0x7, 0xF

cellID

uint16_t

Cell ID.

Value: 0 -> 65535

ULDLSch

uint8_t

Indication for UL/DL scheduling.

Value:

0: UL scheduling

1: DL scheduling

nActiveUe

uint16_t

Total number of active UEs in the cell.

Value: 0 -> 65535

nSrsUe

uint16_t

The number of UEs in the cell that have refreshed SRS channel estimates.

Value: 0 -> 65535

nPrbGrp

uint16_t

The number of PRGs that can be allocated for the current TTI, excluding the PRGs reserved for HARQ re-transmissions.

Value: 0 -> nMaxPrg

nBsAnt

uint8_t

Number of BS antenna ports.

Value: 0 -> nMaxBsAnt

nUeAnt

uint8_t

Number of UE antenna ports.

Value: 0 -> nMaxUeAnt

sigmaSqrd

float

Noise variance.

Value: noise variance value in watts

offsets

struct

Buffer offset for each data:

0xFFFFFFFF: buffer not used (Invalid).

Other: buffer offset based on nvipc data_buf

The data buffers are populated in NVIPC DATA buffer. The “offsets” structure defines the buffer offsets of all the buffers.

Note: not all buffers are used. The offsets of not used buffers should be set to 0xFFFFFFFF. For each task type, the required buffers are listed in the following tables.

Offset name

Offset Type

Buffer description

CRNTI

uint32_t

C-RNTIs of all active UEs in the cell

srsCRNTI

uint32_t

C-RNTIs of the UEs that have refreshed SRS channel estimates in the cell.

prgMsk

uint32_t

Bit map for the availability of each PRG for allocation

postEqSinr

uint32_t

Array of the per-PRG per-layer post-equalizer SINRs of all active UEs in the cell

wbSinr

uint32_t

Array of wideband per-layer post-equalizer SINRs of all active UEs in the cell

estH_fr

uint32_t

For FP32. Array of the subband (per-PRG) SRS channel estimate coefficients for all active UEs in the cell

estH_fr_half

uint32_t

For FP16. Array of the subband (per-PRG) SRS channel estimate coefficients for all active UEs in the cell

prdMat

uint32_t

Array of the precoder/beamforming weights for all active UEs in the cell

detMat

uint32_t

Array of the detector/beamforming weights for all active UEs in the cell

sinVal

uint32_t

Array of the per-UE, per-PRG, per-layer singular values obtained from the SVD of the channel matrix

avgRatesActUe

uint32_t

Array of the long-term average data rates of all active UEs in the cell

prioWeightActUe

uint32_t

For priority-based UE selection. Priority weights of all active UEs in the cell

tbErrLastActUe

uint32_t

TB decoding error indicators of all active UEs in the cell

newDataActUe

uint32_t

Indicators of initial transmission/retransmission for all active UEs in the cell

allocSolLastTxActUe

uint32_t

The PRG allocation solution for the last transmissions of all active UEs in the cell

mcsSelSolLastTxActUe

uint32_t

MCS selection solution for the last transmissions of all active UEs in the cell

layerSelSolLastTxActUe

uint32_t

Layer selection solution for the last transmissions of all active UEs in the cell

The data buffer details are described below.

Field

Type

Description

CRNTI

uint16_t[nActiveUe]

C-RNTIs of all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

CRNTI[uIdx] is the uIdx-th active UE’s C-RNTI.

srsCRNTI

uint16_t[nSrsUe]

C-RNTIs of the UEs that have refreshed SRS channel estimates in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nSrsUe-1 as the index of the UE with refreshed SRS in the cell.

srsCRNTI[uIdx] is the uIdx-th UE’s C-RNTI.

prgMsk

uint8_t[nPrbGrp]

Bit map indicating the availability of each PRG for allocation.

Value of each element:

Denote prgIdx = 0, 1, …, nPrbGrp-1 as the PRG index

prgMsk[prgIdx] is the availability indicator for the prgIdx-th PRG.

0 - unavailable, 1 - available

postEqSinr

float[nActiveUe* nPrbGrp*nUeAnt]

Array of the per-PRG per-layer post-equalizer SINRs of all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

Denote prgIdx = 0, 1, …, nPrbGrp-1 as the PRG index.

Denote layerIdx = 0, 1, …, nUeAnt-1 as the layer index.

post EqSinr[uIdx*nPrbGrp*nUeAnt + prgIdx*nUeAnt + layerIdx] is the uIdx-th active UE’s post-equalizer SINR on the prgIdx-th PRG and the layerIdx-th layer.

wbSinr

float[nActiveUe*nUeAnt]

Array of wideband per-layer post-equalizer SINRs of all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

Denote layerIdx = 0, 1, …, nUeAnt-1 as the layer index.

wbSinr[uIdx*nUeAnt + layerIdx] is the uIdx-th active UE’s wideband post-equalizer SINR on the layerIdx-th layer.

For FP32:

estH_fr

For FP16:

estH_fr_half

For FP32:

cuComplex[nSrsUe*nPrbGrp* nBsAnt*nUeAnt]

For FP16:

__nv_bfloat162[nSrsUe* nPrbGrp*nBsAnt*nUeAnt]

Array of the refreshed subband (per-PRG) SRS channel estimates in the cell.

Value of each element:

Denote prgIdx = 0, 1, …, nPrbGrp-1 as the PRG index.

Denote uIdx = 0, 1, …, nSrsUe-1 as the index of the UE with refreshed SRS in the cell.

Denote bsAntIdx = 0, 1, …, nBsAnt-1 as the BS antenna port index

Denote ueAntIdx = 0, 1, …, nUeAnt as the UE antenna port index

estH_fr[p rgIdx*nSrsUe*nBsAnt*nUeAnt + uIdx*nBsAnt*nUeAnt + bsAntIdx*nUeAnt + ueAntIdx] is the complex channel coefficient for the uIdx-th UE on the prgIdx-th PRG, the bsAntIdx-th BS antenna port and the ueAntIdx-th UE antenna port.

(The above applies to the FP16 version as well)

prdMat

For DL:

cuComplex[nSrsUe*nPrbGrp* nBsAnt*nBsAnt]

For UL:

cuComplex[nSrsUe*nPrbGrp* nUeAnt*nUeAnt]

Array of the precoder/beamforming weights for the UEs that have refreshed SRS channel estimates in the cell.

Value of each element:

(for DL)

Denote uIdx = 0, 1, …, nSrsUe-1 as the index of the UE with refreshed SRS in the cell.

Denote prgIdx = 0, 1, …, nPrbGrp-1 as the PRG index.

Denote inPortIdx = 0, 1, …, nBsAnt-1 as the precoder input port index

Denote outPortIdx = 0, 1, …, nBsAnt-1 as the precoder output port index

prdMat[ uIdx*nPrbGrp*nBsAnt*nBsAnt + prgIdx* nBsAnt*nBsAnt + inPortIdx*nBsAnt + outPortIdx] is the precoder/beamforming weight of the uIdx-th UE on the prgIdx-th PRG and between the inPortIdx-th input port and the outPortIdx-th output port.

(for UL, replace nBsAnt by nUeAnt in above description)

detMat

For DL:

cuComplex[nSrsUe* nPrbGrp*nUeAnt*nUeAnt]

For UL:

cuComplex[nSrsUe* nPrbGrp*nBsAnt*nBsAnt]

Array of the detector/beamforming weights for the UEs that have refreshed SRS channel estimates in the cell.

Value of each element:

(for DL)

Denote uIdx = 0, 1, …, nSrsUe-1 as the index of the UE with refreshed SRS in the cell.

Denote prgIdx = 0, 1, …, nPrbGrp-1 as the PRG index.

Denote inPortIdx = 0, 1, …, nUeAnt-1 as the detector input port index.

Denote outPortIdx = 0, 1, …, nUeAnt-1 as the detector output port index.

detMat[ uIdx*nPrbGrp*nUeAnt*nUeAnt + prgIdx*nUeAnt*nUeAnt + inPortIdx*nUeAnt + outPortIdx] is the detector weight of the uIdx-th UE on the prgIdx-th PRG and between the inPortIdx-th input port and the outPortIdx-th output port.

(for UL, replace nUeAnt by nBsAnt in above description)

sinVal

float[nSrsUe*nPrbGrp*nUeAnt]

Array of the per-UE, per-PRG, per-layer singular values obtained from the SVD of the refreshed SRS channel matrices.

Value of each element:

Denote uIdx = 0, 1, …, nSrsUe-1 as the index of the UE with refreshed SRS in the cell.

Denote prgIdx = 0, 1, …, nPrbGrp-1 as the PRG index.

Denote layerIdx = 0, 1, …, nUeAnt-1 as the layer index.

sinVal[uIdx*nPrbGrp*nUeAnt + prgIdx*nUeAnt + layerIdx] is the uIdx-th UE’s layerIdx-th largest singular value on the prgIdx-th PRG.

For each UE and on each PRG, the singular values are stored in descending order.

avgRatesActUe

float[nActiveUe]

Array of the long-term average data rates of all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

avgRatesActUe[uIdx] is the long-term average throughput of the uIdx-th active UE in the cell.

prioWeightActUe

uint16_t[nActiveUe]

For priority-based UE selection. Priority weights of all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

prioWeightActUe[uIdx] is the uIdx-th active UE’s priority weight.

0xFFFF indicates an invalid element.

tbErrLastActUe

int8_t[nActiveUe]

TB decoding error indicators of all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

tbErrLastActUe[uIdx] is the uIdx-th active UE’s TB decoding error indicator:

-1 - the last transmission is not a new transmission (is a re-transmission)

0 - decoded correctly

1 - decoding error

** Note that if the last transmission of a UE is not a new transmission, tbErrLastActUe of that UE should be set to -1.

newDataActUe

int8_t[nActiveUe]

Indicators of initial transmission/retransmission for all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

newDataActUe[uIdx] is the indicator of initial transmission/retransmission for the uIdx-th active UE in the cell.

0 – retransmission

1 - new data/initial transmission

-1 indicates an invalid element

allocSolLastTxActUe

For type-0 PRG allocation:

int16_t[nPrbGrp]

For type-1 PRG allocation:

int16_t[2*nActiveUe]

The PRG allocation solution for the last transmissions of all active UEs in the cell.

Value of each element:

For type-0 PRG allocation:

Denote prgIdx = 0, 1, …, nPrbGrp-1 as the PRG index.

allocSolLastTxActUe[prgIdx] indicates the active UE index (0, 1, …, nActiveUe-1) that the prgIdx-th PRG is allocated to.

-1 indicates that a given PRG is not allocated to any UE.

For type-1 PRG allocation:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

allocSolLastTxActUe[2*uIdx] is the starting PRG index of the uIdx-th active UE.

allocSolLastTxActUe[2*uIdx + 1] is the ending PRG index of the uIdx-th active UE.

-1 indicates that a given UE is not being allocated to any PRG.

mcsSelSolLastTxActUe

int16_t[nActiveUe]

MCS selection solution for the last transmissions of all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

mcsSelSolLastTxActUe[uIdx] indicates the MCS level for the uIdx-th active UE in the cell.

Range of each element:

0, 1, …, 27 (Currently only support Table 5.1.3.1-2: MCS index table 2, 3GPP TS 38.214).

-1 indicates an element is invalid.

layerSelSolLastTxActUe

uint8_t[nActiveUe]

Layer selection solution for the last transmissions of all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

layerSelSolLastTxActUe[uIdx] indicates the number of layers selected for the uIdx-th active UE in the cell.

Range of each element: 0, 1, …, nUeAnt-1

The selected layers have singular values descending from the largest one.

The following are required data buffers for each cuMAC task type, which is defined by taskBitMask.

Task Type

cuMAC module name

Required data for L2 to pass to cuMAC-CP

0x01

multiCellUeSelection

prgMsk, wbSinr, avgRatesActUe.

0x02

multiCellScheduler

All TaskType=0x01 buffers and postEqSinr, sinVal, estH_fr, detMat, prdMat.

0x04

multiCellLayerSel

All TaskType=0x02 buffers.

0x08

mcsSelectionLUT

All TaskType=0x04 buffers and tbErrLastActUe.

TTI_END#

Name

Type

Description

end_param

uint8_t

Reserved, not used yet.

SCH_TTI.response#

This message is used to return scheduling results to L2. The results are populated in NVIPC DATA buffer,

Name

Type

Description

offsets

struct

Buffer offset for each data:

0xFFFFFFFF: buffer not used (Invalid).

Other: buffer offset based on nvipc data_buf

The data buffers are populated in NVIPC DATA buffer. The “offsets” structure defines the buffer offsets of all the buffers.

Note: not all buffers are used. The offset of not used buffers should be set to 0xFFFFFFFF.

Offset Name

Offset Type

Buffer description

setSchdUePerCellTTI

uint32_t

Set of IDs of the selected UEs for the cell

allocSol

uint32_t

PRB group allocation solution for all active UEs in the cell

layerSelSol

uint32_t

Layer selection solution for all active UEs in the cell

mcsSelSol

uint32_t

MCS selection solution for all active UEs in the cell

The data buffers details are as below.

Field

Type

Description

setSchdUePerCellTTI

uint16_t [nMaxSchUePerCell]

Set of IDs of the selected UEs for the cell.

Value of each element:

Denote i = 0, 1, …, nMaxSchUePerCell-1 as the i-th selected UE for the cell.

setSchdUePerCellTTI[i] is within {0, 1, …, nActiveUe-1} and represents the active UE index of the i-th selected UE.

allocSol

For type-0 PRG allocation:

int16_t[nPrbGrp]

For type-1 PRG allocation:

int16_t[2*nActiveUe]

PRB group allocation solution for all active UEs in the cell.

Value of each element:

For type-0 PRG allocation:

Denote prgIdx = 0, 1, …, nPrbGrp-1 as the PRG index.

allocSol[prgIdx] indicates the active UE index (0, 1, …, nActiveUe-1) that the prgIdx-th PRG is allocated to.

-1 indicates that a given PRG is not allocated to any UE.

For type-1 PRG allocation:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

allocSol[2*uIdx] is the starting PRG index of the uIdx-th active UE.

allocSol[2*uIdx + 1] is the ending PRG index of the uIdx-th active UE.

-1 indicates that a given UE is not being allocated to any PRG.

mcsSelSol

int16_t[nActiveUe]

MCS selection solution for all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

mcsSelSol[uIdx] indicates the MCS level for the uIdx-th active UE in the cell.

Range of each element:

0, 1, …, 27 (Currently only support Table 5.1.3.1-2: MCS index table 2, 3GPP TS 38.214).

-1 indicates an element is invalid.

layerSelSol

uint8_t[nActiveUe]

Layer selection solution for all active UEs in the cell.

Value of each element:

Denote uIdx = 0, 1, …, nActiveUe-1 as the active UE index in the cell.

layerSelSol[uIdx] indicates the number of layers selected for the uIdx-th active UE in the cell.

Range of each element: 0, 1, …, nUeAnt-1

The selected layers have singular values descending from the largest one.

TTI_ERR.indication#

Name

Type

Description

msg_id

in t32_t

SFN number

error_code

in t32_t

0: no error. Other: TBD

reason_code

in t32_t

0: no error. Other: TBD