1 /******************************************************************************
3 * Copyright (c) 2020 Intel.
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
17 *******************************************************************************/
20 * @brief This file provides the definitions for Control Plane Messages APIs.
23 * @ingroup group_lte_source_xran
24 * @author Intel Corporation
28 #ifndef _XRAN_CP_API_H_
29 #define _XRAN_CP_API_H_
35 #include "xran_fh_o_du.h"
36 #include "xran_pkt_cp.h"
37 #include "xran_transport.h"
39 #define XRAN_MAX_SECTIONDB_CTX 2
41 #define XRAN_MAX_NUM_EXTENSIONS XRAN_MAX_PRBS /* Maximum number of extensions in a section [up to 1 ext section per RB]*/
42 #define XRAN_MAX_NUM_UE 16 /* Maximum number of UEs/Lyaers */
43 #define XRAN_MAX_NUM_ANT_BF 64 /* Maximum number of beamforming antenna,
44 * could be defined as XRAN_MAX_ANTENNA_NR */
45 /* Maximum total number of beamforming weights (5.4.7.1.2) */
46 #define XRAN_MAX_BFW_N (XRAN_MAX_NUM_ANT_BF*XRAN_MAX_NUM_UE)
47 #define XRAN_MAX_MODCOMP_ADDPARMS 6 /* max should be even number */
49 #define XRAN_SECTIONEXT_ALIGN 4 /* alignment size in byte for section extension */
52 /** Control Plane section types, defined in 5.4 Table 5.1 */
53 enum xran_cp_sectiontype {
54 XRAN_CP_SECTIONTYPE_0 = 0, /**< Unused RB or Symbols in DL or UL, not supported */
55 XRAN_CP_SECTIONTYPE_1 = 1, /**< Most DL/UL Radio Channels */
56 XRAN_CP_SECTIONTYPE_3 = 3, /**< PRACH and Mixed-numerology Channels */
57 XRAN_CP_SECTIONTYPE_5 = 5, /**< UE scheduling information, not supported */
58 XRAN_CP_SECTIONTYPE_6 = 6, /**< Channel Information, not supported */
59 XRAN_CP_SECTIONTYPE_7 = 7, /**< LAA, not supported */
60 XRAN_CP_SECTIONTYPE_MAX
63 /** Filter index, defined in 5.4.4.3 */
64 enum xran_cp_filterindex {
65 XRAN_FILTERINDEX_STANDARD = 0, /**< UL filter for standard channel */
66 XRAN_FILTERINDEX_PRACH_012 = 1, /**< UL filter for PRACH preamble format 0, 1, 2 */
67 XRAN_FILTERINDEX_PRACH_3 = 2, /**< UL filter for PRACH preamble format 3 */
68 XRAN_FILTERINDEX_PRACH_ABC = 3, /**< UL filter for PRACH preamble format A1~3, B1~4, C0, C2 */
69 XRAN_FILTERINDEX_NPRACH = 4, /**< UL filter for NPRACH */
70 XRAN_FILTERINDEX_LTE4 = 5, /**< UL filter for PRACH preamble format LTE-4 */
74 /** Maximum Slot Index, defined in 5.4.4.6 */
75 #define XRAN_SLOTID_MAX 16
77 /** FFT size in frame structure, defined in 5.4.4.13 Table 5.9 */
78 enum xran_cp_fftsize {
79 XRAN_FFTSIZE_128 = 7, /* 128 */
80 XRAN_FFTSIZE_256 = 8, /* 256 */
81 XRAN_FFTSIZE_512 = 9, /* 512 */
82 XRAN_FFTSIZE_1024 = 10, /* 1024 */
83 XRAN_FFTSIZE_2048 = 11, /* 2048 */
84 XRAN_FFTSIZE_4096 = 12, /* 4096 */
85 XRAN_FFTSIZE_1536 = 13, /* 1536 */
89 /** Sub-carrier spacing, defined in 5.4.4.13 Table 5.10 */
90 enum xran_cp_subcarrierspacing { /*3GPP u, SCS, Nslot, Slot len */
91 XRAN_SCS_15KHZ = 0, /* 0, 15kHz, 1, 1ms */
92 XRAN_SCS_30KHZ = 1, /* 1, 30kHz, 2, 500us */
93 XRAN_SCS_60KHZ = 2, /* 2, 60kHz, 4, 250us */
94 XRAN_SCS_120KHZ = 3, /* 3, 120kHz, 8, 125us */
95 XRAN_SCS_240KHZ = 4, /* 4, 240kHz, 16, 62.5us */
96 XRAN_SCS_1P25KHZ = 12, /* NA, 1.25kHz, 1, 1ms */
97 XRAN_SCS_3P75KHZ = 13, /* NA, 3.75kHz, 1, 1ms */
98 XRAN_SCS_5KHZ = 14, /* NA, 5kHz, 1, 1ms */
99 XRAN_SCS_7P5KHZ = 15, /* NA, 7.5kHz, 1, 1ms */
103 /** Resource block indicator, defined in 5.4.5.2 */
104 enum xran_cp_rbindicator {
105 XRAN_RBIND_EVERY = 0, /**< every RB used */
106 XRAN_RBIND_EVERYOTHER = 1, /**< every other RB used */
110 /** Symbol number increment command, defined in 5.4.5.3 */
111 enum xran_cp_symbolnuminc {
112 XRAN_SYMBOLNUMBER_NOTINC = 0, /**< do not increment the current symbol number */
113 XRAN_SYMBOLNUMBER_INC = 1, /**< increment the current symbol number and use that */
114 XRAN_SYMBOLNUMBER_INC_MAX
117 /** Macro to convert the number of PRBs as defined in 5.4.5.6 */
118 #define XRAN_CONVERT_NUMPRBC(x) ((x) > 255 ? 0 : (x))
120 #define XRAN_CONVERT_IQWIDTH(x) ((x) > 15 ? 0 : (x))
122 /** Minimum number of symbols, defined in 5.4.5.7 */
123 #define XRAN_SYMBOLNUMBER_MIN 1
124 /** Maximum number of symbols, defined in 5.4.5.7 */
125 #define XRAN_SYMBOLNUMBER_MAX 14
127 /* LAA message type 5.4.5.14 Table 5.11, not supported */
128 #define XRAN_LAAMSGTYPE_LBT_PDSCH_REQ 0
129 #define XRAN_LAAMSGTYPE_LBT_DRS_REQ 1
130 #define XRAN_LAAMSGTYPE_LBT_PDSCH_RSP 2
131 #define XRAN_LAAMSGTYPE_LBT_DRS_RSP 3
132 #define XRAN_LAAMSGTYPE_LBT_BUFFER_ERROR 4
133 #define XRAN_LAAMSGTYPE_LBT_CWCONFIG_REQ 5
134 #define XRAN_LAAMSGTYPE_LBT_CWCONFIG_RSP 6
136 #define XRAN_LBTMODE_FULL 0
137 #define XRAN_LBTMODE_PARTIAL25 1
138 #define XRAN_LBTMODE_PARTIAL34 2
139 #define XRAN_LBTMODE_FULLSTOP 3
142 #define XRAN_EF_F_LAST 0
143 #define XRAN_EF_F_ANOTHER_ONE 1
145 /** Control Plane section extension commands, defined in 5.4.6 Table 5.13 */
146 enum xran_cp_sectionextcmd {
147 XRAN_CP_SECTIONEXTCMD_0 = 0, /**< Reserved, for future use */
148 XRAN_CP_SECTIONEXTCMD_1 = 1, /**< Beamforming weights */
149 XRAN_CP_SECTIONEXTCMD_2 = 2, /**< Beamforming attributes */
150 XRAN_CP_SECTIONEXTCMD_3 = 3, /**< DL Precoding configuration parameters and indications, not supported */
151 XRAN_CP_SECTIONEXTCMD_4 = 4, /**< Modulation compression parameter */
152 XRAN_CP_SECTIONEXTCMD_5 = 5, /**< Modulation compression additional scaling parameters */
153 XRAN_CP_SECTIONEXTCMD_6 = 6, /**< Non-contiguous PRB allocation */
154 XRAN_CP_SECTIONEXTCMD_7 = 7, /**< Multiple-eAxC designation */
155 XRAN_CP_SECTIONEXTCMD_8 = 8, /**< MMSE parameters */
156 XRAN_CP_SECTIONEXTCMD_9 = 9, /**< Dynamic Spectrum Sharing parameters */
157 XRAN_CP_SECTIONEXTCMD_10 = 10, /**< Multiple ports grouping */
158 XRAN_CP_SECTIONEXTCMD_11 = 11, /**< Flexible BF weights */
159 XRAN_CP_SECTIONEXTCMD_MAX /* 12~127 reserved for future use */
162 /** Macro to convert bfwIqWidth defined in 5.4.7.1.1, Table 5-15 */
163 #define XRAN_CONVERT_BFWIQWIDTH(x) ((x) > 15 ? 0 : (x))
165 /** Beamforming Weights Compression Method 5.4.7.1.1, Table 5-16 */
166 enum xran_cp_bfw_compression_method {
167 XRAN_BFWCOMPMETHOD_NONE = 0, /**< Uncopressed I/Q value */
168 XRAN_BFWCOMPMETHOD_BLKFLOAT = 1, /**< I/Q mantissa value */
169 XRAN_BFWCOMPMETHOD_BLKSCALE = 2, /**< I/Q scaled value */
170 XRAN_BFWCOMPMETHOD_ULAW = 3, /**< compressed I/Q value */
171 XRAN_BFWCOMPMETHOD_BEAMSPACE = 4, /**< beamspace I/Q coefficient */
172 XRAN_BFWCOMPMETHOD_MAX /* reserved for future methods */
175 /** Beamforming Attributes Bitwidth 5.4.7.2.1 */
176 enum xran_cp_bfa_bitwidth {
177 XRAN_BFABITWIDTH_NO = 0, /**< the filed is no applicable or the default value shall be used */
178 XRAN_BFABITWIDTH_2BIT = 1, /**< the filed is 2-bit bitwidth */
179 XRAN_BFABITWIDTH_3BIT = 2, /**< the filed is 3-bit bitwidth */
180 XRAN_BFABITWIDTH_4BIT = 3, /**< the filed is 4-bit bitwidth */
181 XRAN_BFABITWIDTH_5BIT = 4, /**< the filed is 5-bit bitwidth */
182 XRAN_BFABITWIDTH_6BIT = 5, /**< the filed is 6-bit bitwidth */
183 XRAN_BFABITWIDTH_7BIT = 6, /**< the filed is 7-bit bitwidth */
184 XRAN_BFABITWIDTH_8BIT = 7, /**< the filed is 8-bit bitwidth */
187 /** Layer ID for DL transmission in TM1-TM4 5.4.7.3.2 */
188 #define XRAN_LAYERID_0 0 /**< Layer 0 */
189 #define XRAN_LAYERID_1 1 /**< Layer 1 */
190 #define XRAN_LAYERID_2 2 /**< Layer 2 */
191 #define XRAN_LAYERID_3 3 /**< Layer 3 */
192 #define XRAN_LAYERID_TXD 0xf /**< TxD */
194 /** LTE Transmission Scheme for section extension type 3 5.4.7.3.3 */
195 #define XRAN_TXS_SMUXCDD 0 /**< Spatial Multiplexing (CDD) */
196 #define XRAN_TXS_SMUXNOCDD 1 /**< Spatial Multiplexing (no CDD) */
197 #define XRAN_TXS_TXDIV 2 /**< Transmit diversity */
199 /** Resource Block Group Size 5.4.7.6.1 */
200 enum xran_cp_rbgsize {
201 XRAN_RBGSIZE_1RB = 1, /**< 1 RB */
202 XRAN_RBGSIZE_2RB = 2, /**< 2 RBs */
203 XRAN_RBGSIZE_3RB = 3, /**< 3 RBs */
204 XRAN_RBGSIZE_4RB = 4, /**< 4 RBs */
205 XRAN_RBGSIZE_6RB = 5, /**< 6 RBs */
206 XRAN_RBGSIZE_8RB = 6, /**< 8 RBs */
207 XRAN_RBGSIZE_16RB = 7, /**< 16 RBs */
210 /** Technology for Dynamic Spectrum Sharing operation 5,4,7.9.1 */
211 #define XRAN_DSSTECH_LTE 0 /**< LTE support */
212 #define XRAN_DSSTECH_NR 1 /**< NR support */
214 /** The type of beam grouping 5.4.7.10.1 */
215 #define XRAN_BEAMGT_COMMON 0 /** common beam */
216 #define XRAN_BEAMGT_MATRIXIND 1 /** beam matrix indication */
217 #define XRAN_BEAMGT_VECTORLIST 2 /** beam vector listing */
219 #define XRAN_MAX_NUMPORTC_EXT10 64 /* defined in 5.4.7.10.2 */
222 * This structure contains the information to generate the section body of C-Plane message */
223 struct xran_section_info {
224 uint8_t type; /* type of this section */
225 /* section type bit- */
226 /* 0 1 3 5 6 7 length */
227 uint8_t startSymId; /* X X X X X X 4bits */
228 uint8_t numSymbol; /* X X X X 4bits */
229 uint8_t symInc; /* X X X X X 1bit */
230 uint16_t id; /* X X X X X 12bits */
231 uint16_t reMask; /* X X X X 12bits */
232 uint16_t startPrbc; /* X X X X X 10bits */
233 uint16_t numPrbc; /* X X X X X 8bits */ /* will be converted to zero if >255 */
234 uint8_t rb; /* X X X X X 1bit */
235 uint8_t compMeth; /* X X X 4bits */
236 uint8_t iqWidth; /* X X X 4bits */
237 uint8_t ef; /* X X X X 1bit */
238 int32_t freqOffset; /* X 24bits */
239 uint16_t beamId; /* X X 15bits */
240 uint16_t ueId; /* X X 15bits */
241 uint16_t regFactor; /* X 16bits */
244 struct xran_section_desc sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT];
248 struct xran_sectionext1_info {
249 uint16_t rbNumber; /**< number RBs to ext1 chain */
250 uint16_t bfwNumber; /**< number of bf weights in this section */
253 int16_t *p_bfwIQ; /**< pointer to formed section extention */
254 int16_t bfwIQ_sz; /**< size of buffer with section extention information */
258 uint8_t compBitWidthShift;
259 uint8_t activeBeamspaceCoeffMask[XRAN_MAX_BFW_N]; /* ceil(N/8)*8, should be multiple of 8 */
263 struct xran_sectionext2_info {
264 uint8_t bfAzPtWidth; /* beamforming zenith beamwidth parameter */
266 uint8_t bfZePtWidth; /* beamforming azimuth beamwidth parameter */
268 uint8_t bfAz3ddWidth; /* beamforming zenith pointing parameter */
270 uint8_t bfZe3ddWidth; /* beamforming azimuth pointing parameter */
277 struct xran_sectionext3_info {
285 uint16_t numAntPort; /* number of antenna port - 2 or 4 */
291 struct xran_sectionext4_info {
294 uint16_t modCompScaler;
297 struct xran_sectionext5_info {
301 uint16_t mcScaleReMask;
302 uint16_t mcScaleOffset;
303 } mc[XRAN_MAX_MODCOMP_ADDPARMS];
306 struct xran_sectionext6_info {
313 struct xran_sectionext7_info {
317 struct xran_sectionext8_info {
318 uint16_t regularizationFactor;
321 struct xran_sectionext9_info {
325 struct xran_sectionext10_info {
328 uint16_t beamID[XRAN_MAX_NUMPORTC_EXT10];
331 struct xran_sectionext11_info {
336 uint8_t numSetBFWs; /* Total number of beam forming weights set (L) */
341 int32_t totalBfwIQLen;
342 int32_t maxExtBufSize; /* Maximum space of external buffer */
343 uint8_t *pExtBuf; /* pointer to start of external buffer */
344 void *pExtBufShinfo; /* Pointer to rte_mbuf_ext_shared_info */
347 union xran_ext_bfwcompparam_info {
349 // uint8_t blockScaler; /* Not supported */
350 // uint8_t compBitWidthShift; /* Not supported */
351 // uint8_t *pActBeamspaceCoeffMask; /* Not supported */
353 struct xran_ext11_prbbundle_info {
354 union xran_ext_bfwcompparam_info bfwCompParam;
355 uint16_t beamId; /* 15bits, needs to strip MSB */
356 uint16_t BFWSize; /* actual size of bfws in bytes */
357 uint8_t *pBFWs; /* external buffer pointer */
359 struct xran_sectionext11_recv_info {
364 uint8_t numSetBFWs; /* Total number of beam forming weights set (L) */
369 int32_t totalBfwIQLen;
370 int32_t maxExtBufSize; /* Maximum space of external buffer */
371 uint8_t *pExtBuf; /* pointer to start of external buffer */
372 void *pExtBufShinfo; /* Pointer to rte_mbuf_ext_shared_info */
375 struct xran_ext11_prbbundle_info bundInfo[XRAN_MAX_SET_BFWS];
378 struct xran_sectionext_info {
385 * This structure contains the information to generate the section header of C-Plane message */
386 struct xran_cp_header_params {
393 /* section type bit- */
394 /* 0 1 3 5 6 7 length */
395 uint8_t fftSize; /* X X 4bits */
396 uint8_t scs; /* X X 4bits */
397 uint8_t iqWidth; /* X X X 4bits */
398 uint8_t compMeth; /* X X X 4bits */
399 uint8_t numUEs; /* X 8bits */
400 uint16_t timeOffset; /* X X 16bits */
401 uint16_t cpLength; /* X X 16bits */
404 /** The structure for the generation of section extension */
405 struct xran_section_ext_gen_info {
406 uint16_t type; /**< the type of section extension */
407 uint16_t len; /**< length of extension data */
408 void *data; /**< pointer to extension data */
412 * This structure to hold the information to generate the sections of C-Plane message */
413 struct xran_section_gen_info {
414 struct xran_section_info info; /**< The information for section */
416 uint32_t exDataSize; /**< The number of Extensions or type 6/7 data */
417 /** the array to store section extension */
418 struct xran_section_ext_gen_info exData[XRAN_MAX_NUM_EXTENSIONS];
422 * This structure to hold the information to generate a C-Plane message */
423 struct xran_cp_gen_params {
424 uint8_t dir; /**< UL or DL */
425 uint8_t sectionType; /**< each section must have same type with this */
426 uint16_t numSections; /**< the number of sections to generate */
428 struct xran_cp_header_params hdr;
429 /**< The information for C-Plane message header */
430 struct xran_section_gen_info *sections;
431 /**< Array of the section information */
434 /** The structure to store received section extension */
435 struct xran_section_ext_recv_info {
436 uint16_t type; /**< the type of section extension */
439 struct xran_sectionext1_info ext1;
440 struct xran_sectionext2_info ext2;
441 struct xran_sectionext3_info ext3;
442 struct xran_sectionext4_info ext4;
443 struct xran_sectionext5_info ext5;
444 struct xran_sectionext6_info ext6;
445 struct xran_sectionext10_info ext10;
446 struct xran_sectionext11_recv_info ext11;
451 * This structure to hold the information of received sections of C-Plane message */
452 struct xran_section_recv_info {
453 struct xran_section_info info; /**< The information for received section */
456 /** the array to store section extension */
457 struct xran_section_ext_recv_info exts[XRAN_MAX_NUM_EXTENSIONS];
461 * This structure to store received C-Plane message */
462 struct xran_cp_recv_params {
463 uint8_t dir; /**< UL or DL */
464 uint8_t sectionType; /**< each section must have same type with this */
465 uint16_t numSections; /**< the number of sections received */
467 struct xran_cp_header_params hdr;
468 /**< The information for C-Plane message header */
469 struct xran_section_recv_info *sections;
470 /**< Array of the section information */
474 * This structure to hold the information of RB allocation from PHY
475 * to send data for allocated RBs only. */
476 struct xran_cp_rbmap_list {
477 uint16_t grp_id; /**< group id for this entry, reserved for future use */
479 uint8_t sym_start; /**< Start symbol ID */
480 uint8_t sym_num; /**< Number of symbols */
482 uint16_t rb_start; /**< Start RB position */
483 uint16_t rb_num; /**< Number of RBs */
485 int16_t iq_buff_offset; /**< Offset within Sym for start of IQs */
486 int16_t iq_buff_len; /**< length IQs */
488 uint16_t beam_id; /**< Bean Index */
489 uint8_t iqWidth; /**< I and Q width in bits */
490 uint8_t comp_meth; /**< Compression method */
494 typedef struct tagSECTION_DB_TYPE {
495 struct xran_sectioninfo_db* p_sectiondb_elm[XRAN_MAX_SECTIONDB_CTX][XRAN_DIR_MAX][XRAN_COMPONENT_CARRIERS_MAX][XRAN_MAX_ANTENNA_NR * 2 + XRAN_MAX_ANT_ARRAY_ELM_NR];
496 } SECTION_DB_TYPE, * PSECTION_DB_TYPE;
498 uint16_t xran_get_cplength(int32_t cpLength);
499 int32_t xran_get_freqoffset(int32_t freqOffset, int32_t scs);
501 int32_t xran_prepare_ctrl_pkt(struct rte_mbuf *mbuf,
502 struct xran_cp_gen_params *params,
503 uint8_t CC_ID, uint8_t Ant_ID,
506 int32_t xran_parse_cp_pkt(struct rte_mbuf *mbuf,
507 struct xran_cp_recv_params *result,
508 struct xran_recv_packet_info *pkt_info);
510 int32_t xran_cp_init_sectiondb(void *pHandle);
511 int32_t xran_cp_free_sectiondb(void *pHandle);
512 int32_t xran_cp_add_section_info(void *pHandle,
513 uint8_t dir, uint8_t cc_id, uint8_t ruport_id,
514 uint8_t ctx_id, struct xran_section_info *info);
515 int32_t xran_cp_add_multisection_info(void *pHandle,
516 uint8_t cc_id, uint8_t ruport_id, uint8_t ctx_id,
517 struct xran_cp_gen_params *gen_info);
518 struct xran_section_info *xran_cp_find_section_info(void *pHandle,
519 uint8_t dir, uint8_t cc_id, uint8_t ruport_id,
520 uint8_t ctx_id, uint16_t section_id);
521 struct xran_section_info *xran_cp_iterate_section_info(void *pHandle,
522 uint8_t dir, uint8_t cc_id, uint8_t ruport_id,
523 uint8_t ctx_id, uint32_t *next);
525 int32_t xran_cp_getsize_section_info(void *pHandle, uint8_t dir, uint8_t cc_id, uint8_t ruport_id, uint8_t ctx_id);
526 int32_t xran_cp_reset_section_info(void *pHandle, uint8_t dir, uint8_t cc_id, uint8_t ruport_id, uint8_t ctx_id);
527 int32_t xran_cp_populate_section_ext_1(int8_t *p_ext1_dst, /**< destination buffer */
528 uint16_t ext1_dst_len, /**< dest buffer size */
529 int16_t *p_bfw_iq_src, /**< source buffer of IQs */
530 uint16_t rbNumber, /**< number RBs to ext1 chain */
531 uint16_t bfwNumber, /**< number of bf weights in this set of sections */
532 uint8_t bfwiqWidth, /**< bit size of IQs */
533 uint8_t bfwCompMeth); /**< compression method */
534 struct rte_mbuf *xran_attach_cp_ext_buf(uint16_t vf_id, int8_t* p_ext_buff_start, int8_t* p_ext_buff, uint16_t ext_buff_len,
535 struct rte_mbuf_ext_shared_info * p_share_data);
536 int32_t xran_cp_attach_ext_buf(struct rte_mbuf *mbuf, uint8_t *extbuf_start, uint16_t extbuf_len,
537 struct rte_mbuf_ext_shared_info *shinfo);
538 int32_t xran_cp_prepare_ext11_bfws(uint8_t numSetBFW, uint8_t numBFW,
539 uint8_t iqWidth, uint8_t compMeth,
540 uint8_t *dst, int16_t dst_maxlen,
541 struct xran_ext11_bfw_info bfwInfo[]);
542 int32_t xran_cp_estimate_max_set_bfws(uint8_t numBFWs, uint8_t iqWidth,
543 uint8_t compMeth, uint16_t mtu);
549 #endif /* _XRAN_CP_API_H_ */