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 |