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 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 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 buffers details are detailed 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 |