1 /******************************************************************************
3 * Copyright (c) 2019 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 public interface to xRAN Front Haul layer implementation as defined in the
21 * ORAN-WG4.CUS.0-v01.00 spec. Implementation specific to
22 * Lower Layer Split Central Unit (O-DU): a logical node that includes the eNB/gNB functions as
23 * listed in section 2.1 split option 7-2x, excepting those functions allocated exclusively to the O-RU.
24 * The O-DU controls the operation of O-RUs for 5G NR Radio Access technology
26 * @file xran_fh_o_du.h
27 * @ingroup group_lte_source_xran
28 * @author Intel Corporation
32 #ifndef _XRAN_FH_O_DU_H_
33 #define _XRAN_FH_O_DU_H_
44 #include <sys/types.h>
45 #include <sys/queue.h>
46 #include <netinet/in.h>
54 #define XRAN_STATUS_SUCCESS (0)
57 * Success status value. */
58 #define XRAN_STATUS_FAIL (-1)
61 * Fail status value. */
63 #define XRAN_STATUS_RETRY (-2)
66 * Retry status value. */
68 #define XRAN_STATUS_RESOURCE (-3)
71 * The resource that has been requested is unavailable. Refer
72 * to relevant sections of the API for specifics on what the suggested
73 * course of action is. */
75 #define XRAN_STATUS_INVALID_PARAM (-4)
78 * Invalid parameter has been passed in. */
79 #define XRAN_STATUS_FATAL (-5)
82 * A serious error has occurred. Recommended course of action
83 * is to shutdown and restart the component. */
85 #define XRAN_STATUS_UNSUPPORTED (-6)
88 * The function is not supported, at least not with the specific
89 * parameters supplied. This may be because a particular
90 * capability is not supported by the current implementation. */
92 #define XRAN_STATUS_INVALID_PACKET (-7)
95 * Recevied packet does not have correct format. */
97 /** Macro to calculate TTI number from symbol index used by timing thread */
98 #define XranGetTtiNum(symIdx, numSymPerTti) (((uint32_t)symIdx / (uint32_t)numSymPerTti))
99 /** Macro to calculate Symbol number for given slot from symbol index */
100 #define XranGetSymNum(symIdx, numSymPerTti) (((uint32_t)symIdx % (uint32_t)numSymPerTti))
101 /** Macro to calculate Frame number for given tti */
102 #define XranGetFrameNum(tti,SFNatSecStart,numSubFramePerSystemFrame, numSlotPerSubFrame) ((((uint32_t)tti / ((uint32_t)numSubFramePerSystemFrame * (uint32_t)numSlotPerSubFrame)) + SFNatSecStart) & 0x3FF)
103 /** Macro to calculate Subframe number for given tti */
104 #define XranGetSubFrameNum(tti, numSlotPerSubFrame, numSubFramePerSystemFrame) (((uint32_t)tti/(uint32_t)numSlotPerSubFrame) % (uint32_t)numSubFramePerSystemFrame)
105 /** Macro to calculate Slot number */
106 #define XranGetSlotNum(tti, numSlotPerSfn) ((uint32_t)tti % ((uint32_t)numSlotPerSfn))
108 #define XRAN_PORTS_NUM (1) /**< number of XRAN ports (aka O-RU devices) supported */
109 #define XRAN_N_FE_BUF_LEN (40) /**< Number of TTIs (slots) */
110 #define XRAN_MAX_SECTOR_NR (12) /**< Max sectors per XRAN port */
111 #define XRAN_MAX_ANTENNA_NR (16) /**< Max number of extended Antenna-Carriers:
112 a data flow for a single antenna (or spatial stream) for a single carrier in a single sector */
114 /* see 10.2 Hierarchy of Radiation Structure in O-RU (assume TX and RX pannel are the same dimensions)*/
115 #define XRAN_MAX_PANEL_NR (1) /**< Max number of Panels supported per O-RU */
116 #define XRAN_MAX_TRX_ANTENNA_ARRAY (1) /**< Max number of TX and RX arrays per panel in O-RU */
117 #define XRAN_MAX_ANT_ARRAY_ELM_NR (64) /**< Maximum number of Antenna Array Elemets in Antenna Array in the O-RU */
121 #define XRAN_NUM_OF_SYMBOL_PER_SLOT (14) /**< Number of symbols per slot */
122 #define XRAN_MAX_NUM_OF_SRS_SYMBOL_PER_SLOT XRAN_NUM_OF_SYMBOL_PER_SLOT /**< Max Number of SRS symbols per slot */
123 #define XRAN_MAX_TDD_PERIODICITY (80) /**< Max TDD pattern period */
124 #define XRAN_MAX_CELLS_PER_PORT (XRAN_MAX_SECTOR_NR) /**< Max cells mapped to XRAN port */
125 #define XRAN_COMPONENT_CARRIERS_MAX (XRAN_MAX_SECTOR_NR) /**< number of CCs */
126 #define XRAN_NUM_OF_ANT_RADIO (XRAN_MAX_SECTOR_NR*XRAN_MAX_ANTENNA_NR) /**< Max Number of Antennas supported for all CC on single XRAN port */
127 #define XRAN_MAX_PRBS (275) /**< Max of PRBs per CC per antanna for 5G NR */
129 #define XRAN_MAX_SECTIONS_PER_SYM (16) /**< Max number of different sections in single symbol (section is equal to RB allocation for UE) */
131 #define XRAN_MAX_PKT_BURST (448+4) /**< 4x14x8 symbols per ms */
132 #define XRAN_N_MAX_BUFFER_SEGMENT XRAN_MAX_PKT_BURST /**< Max number of segments per ms */
134 #define XRAN_STRICT_PARM_CHECK (1) /**< enable parameter check for C-plane */
136 /* Slot type definition */
137 #define XRAN_SLOT_TYPE_INVALID (0) /**< invalid slot type */
138 #define XRAN_SLOT_TYPE_DL (1) /**< DL slot */
139 #define XRAN_SLOT_TYPE_UL (2) /**< UL slot */
140 #define XRAN_SLOT_TYPE_SP (3) /**< Special slot */
141 #define XRAN_SLOT_TYPE_FDD (4) /**< FDD slot */
142 #define XRAN_SLOT_TYPE_LAST (5) /**< MAX slot */
144 /* symbol type definition */
145 #define XRAN_SYMBOL_TYPE_DL (0) /**< DL symbol */
146 #define XRAN_SYMBOL_TYPE_UL (1) /**< UL symbol */
147 #define XRAN_SYMBOL_TYPE_GUARD (2) /**< GUARD symbol */
148 #define XRAN_SYMBOL_TYPE_FDD (3) /**< FDD symbol */
150 #define XRAN_NUM_OF_SLOT_IN_TDD_LOOP (80)/**< MAX number of slot for TDD repetition */
152 //#define _XRAN_DEBUG /**< Enable debug log */
153 //#define _XRAN_VERBOSE /**< Enable verbose log */
156 #define xran_log_dbg(fmt, ...) \
158 "DEBUG: %s(%d): " fmt "\n", \
160 __LINE__, ##__VA_ARGS__)
162 #define xran_log_dbg(fmt, ...)
165 #if defined(_XRAN_DEBUG) || defined(_XRAN_VERBOSE)
166 #define xran_log_wrn(fmt, ...) \
169 "WARNING: %s(%d): " fmt "\n", \
171 __LINE__, ##__VA_ARGS__)
173 #define xran_log_dbg(fmt, ...)
174 #define xran_log_wrn(fmt, ...)
177 #define xran_log_err(fmt, ...) \
179 "ERROR: %s(%d): " fmt "\n", \
181 __LINE__, ##__VA_ARGS__)
183 enum XranFrameDuplexType
185 XRAN_FDD = 0, XRAN_TDD
196 ******************************************************************************
200 * Compression Method 6.3.3.13, Table 6-43
201 *****************************************************************************/
202 enum xran_compression_method {
203 XRAN_COMPMETHOD_NONE = 0,
204 XRAN_COMPMETHOD_BLKFLOAT = 1,
205 XRAN_COMPMETHOD_BLKSCALE = 2,
206 XRAN_COMPMETHOD_ULAW = 3,
207 XRAN_COMPMETHOD_MODULATION = 4,
212 ******************************************************************************
216 * Callback function type for symbol packet enum
217 *****************************************************************************/
218 enum callback_to_phy_id
220 XRAN_CB_TTI = 0, /**< callback on TTI boundary */
221 XRAN_CB_HALF_SLOT_RX =1, /**< callback on half slot (sym 7) packet arrival*/
222 XRAN_CB_FULL_SLOT_RX =2, /**< callback on full slot (sym 14) packet arrival */
223 XRAN_CB_MAX /**< max number of callbacks */
226 /** Beamforming type, enumerated as "frequency", "time" or "hybrid"
227 section 10.4.2 Weight-based dynamic beamforming */
228 enum xran_weight_based_beamforming_type {
229 XRAN_BF_T_FREQUENCY = 0,
231 XRAN_BF_T_HYBRID = 2,
235 typedef int32_t xran_status_t; /**< Xran status return value */
237 /** callback function type for Symbol packet */
238 typedef void (*xran_callback_sym_fn)(void*);
240 /** Callback function type for TTI event */
241 typedef int (*xran_fh_tti_callback_fn)(void*);
243 /** Callback function type packet arrival from transport layer (ETH or IP) */
244 typedef void (*xran_transport_callback_fn)(void*, xran_status_t);
246 /** Callback functions to poll BBdev encoder */
247 typedef int16_t (*phy_encoder_poll_fn)(void);
249 /** Callback functions to poll BBdev decoder */
250 typedef int16_t (*phy_decoder_poll_fn)(void);
252 /** XRAN port enum */
255 XRAN_UP_VF = 0, /**< port type for U-plane */
256 XRAN_CP_VF, /**< port type for C-plane */
257 XRAN_UP_VF1, /**< port type for U-plane */
258 XRAN_CP_VF1, /**< port type for C-plane */
259 XRAN_UP_VF2, /**< port type for U-plane */
260 XRAN_CP_VF2, /**< port type for C-plane */
261 XRAN_UP_VF3, /**< port type for U-plane */
262 XRAN_CP_VF3, /**< port type for C-plane */
263 XRAN_UP_VF4, /**< port type for U-plane */
264 XRAN_CP_VF4, /**< port type for C-plane */
265 XRAN_UP_VF5, /**< port type for U-plane */
266 XRAN_CP_VF5, /**< port type for C-plane */
267 XRAN_UP_VF6, /**< port type for U-plane */
268 XRAN_CP_VF6, /**< port type for C-plane */
269 XRAN_UP_VF7, /**< port type for U-plane */
270 XRAN_CP_VF7, /**< port type for C-plane */
274 /** XRAN Radio Access technology enum */
277 XRAN_RAN_5GNR = 0, /**< 5G NR */
278 XRAN_RAN_LTE = 1, /**< LTE */
282 /** XRAN user data compression header handling types */
283 enum xran_comp_hdr_type
285 XRAN_COMP_HDR_TYPE_DYNAMIC = 0, /**< dynamic data format where U-plane udCompHdr controls compression parameters */
286 XRAN_COMP_HDR_TYPE_STATIC = 1, /**< static data format where M-plane defines compression parameters */
287 XRAN_COMP_HDR_TYPE_MAX
290 /** XRAN category enum */
293 XRAN_CATEGORY_A = 0, /**< 5G NR Category A */
294 XRAN_CATEGORY_B = 1, /**< 5G NR Category B */
298 /** type of beamforming */
299 enum xran_beamforming_type
301 XRAN_BEAM_ID_BASED = 0, /**< beam index based */
302 XRAN_BEAM_WEIGHT, /**< beam forming weights */
303 XRAN_BEAM_ATTRIBUTE, /**< beam index based */
306 /** state of bbdev with xran */
309 XRAN_BBDEV_NOT_USED = -1, /**< BBDEV is disabled */
310 XRAN_BBDEV_MODE_HW_OFF = 0, /**< BBDEV is enabled for SW sim mode */
311 XRAN_BBDEV_MODE_HW_ON = 1, /**< BBDEV is enable for HW */
315 /** callback return information */
322 /** DPDK IO configuration for XRAN layer */
324 uint8_t id; /**< should be (0) for O-DU or (1) O-RU (debug) */
325 uint8_t num_vfs; /**< number of VFs for C-plane and U-plane (should be even) */
326 char *dpdk_dev[XRAN_VF_MAX]; /**< VFs devices */
327 char *bbdev_dev[1]; /**< BBDev dev name */
328 int32_t bbdev_mode; /**< DPDK for BBDev */
329 uint32_t dpdkIoVaMode; /**< IOVA Mode */
330 uint32_t dpdkMemorySize; /**< DPDK max memory allocation */
331 int32_t core; /**< reservd */
332 int32_t system_core; /**< reservd */
333 uint64_t pkt_proc_core; /**< worker mask */
334 int32_t pkt_aux_core; /**< reservd */
335 int32_t timing_core; /**< core used by xRAN */
336 int32_t port[XRAN_VF_MAX]; /**< VFs ports */
337 int32_t io_sleep; /**< enable sleep on PMD cores */
340 /** XRAN spec section 3.1.3.1.6 ecpriRtcid / ecpriPcid define */
341 struct xran_eaxcid_config {
342 uint16_t mask_cuPortId; /**< Mask CU PortId */
343 uint16_t mask_bandSectorId; /**< Mask Band */
344 uint16_t mask_ccId; /**< Mask CC */
345 uint16_t mask_ruPortId; /**< Mask RU Port ID */
347 uint8_t bit_cuPortId; /**< bandsectorId + ccId + ruportId */
348 uint8_t bit_bandSectorId; /**< ccId + ruPortId */
349 uint8_t bit_ccId; /**< ruportId */
350 uint8_t bit_ruPortId; /**< 0 */
354 * XRAN Front haul interface initialization settings
356 struct xran_fh_init {
357 struct xran_io_cfg io_cfg;/**< DPDK IO for XRAN */
358 struct xran_eaxcid_config eAxCId_conf; /**< config of ecpriRtcid/ecpriPcid */
360 uint32_t dpdkBasebandFecMode; /**< DPDK Baseband FEC device mode (0-SW, 1-HW) */
361 char *dpdkBasebandDevice; /**< DPDK Baseband device address */
362 char *filePrefix; /**< DPDK prefix */
364 uint32_t mtu; /**< maximum transmission unit (MTU) is the size of the largest protocol data unit (PDU) that can be communicated in a single
365 xRAN network layer transaction. supported 1500 bytes and 9600 bytes (Jumbo Frame) */
366 int8_t *p_o_du_addr; /**< O-DU Ethernet Mac Address */
367 int8_t *p_o_ru_addr; /**< O-RU Ethernet Mac Address */
369 uint16_t totalBfWeights;/**< The total number of beamforming weights on RU for extensions */
371 uint16_t Tadv_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
372 uint16_t T2a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
373 uint16_t T2a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
374 uint16_t T2a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
375 uint16_t T2a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
376 uint16_t T2a_min_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
377 uint16_t T2a_max_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
378 uint16_t Ta3_min; /**< Table 2 7 : xRAN Delay Management Model Parameters */
379 uint16_t Ta3_max; /**< Table 2 7 : xRAN Delay Management Model Parameters */
380 uint16_t T1a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
381 uint16_t T1a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
382 uint16_t T1a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
383 uint16_t T1a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
384 uint16_t T1a_min_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
385 uint16_t T1a_max_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
386 uint16_t Ta4_min; /**< Table 2 7 : xRAN Delay Management Model Parameters */
387 uint16_t Ta4_max; /**< Table 2 7 : xRAN Delay Management Model Parameters */
389 uint8_t enableCP; /**< enable C-plane */
390 uint8_t prachEnable; /**< enable PRACH */
391 uint8_t srsEnable; /**< enable SRS (Cat B specific) */
392 uint8_t cp_vlan_tag; /**< C-plane vlan tag */
393 uint8_t up_vlan_tag; /**< U-plane vlan tag */
394 int32_t debugStop; /**< enable auto stop */
395 int32_t debugStopCount; /**< enable auto stop after number of Tx packets */
396 int32_t DynamicSectionEna; /**< enable dynamic C-Plane section allocation */
397 int32_t GPS_Alpha; // refer to alpha as defined in section 9.7.2 of ORAN spec. this value should be alpha*(1/1.2288ns), range 0 - 1e7 (ns)
398 int32_t GPS_Beta; //beta value as defined in section 9.7.2 of ORAN spec. range -32767 ~ +32767
401 /** Beamforming waights for single stream for each PRBs given number of Antenna elements */
402 struct xran_cp_bf_weight{
403 int16_t nAntElmTRx; /**< num TRX for this allocation */
404 int8_t* p_ext_start; /**< pointer to start of buffer for full C-plane packet */
405 int8_t* p_ext_section; /**< pointer to form extType */
406 int16_t ext_section_sz; /**< extType section size */
408 struct xran_cp_bf_attribute{
411 struct xran_cp_bf_precoding{
415 /** section descriptor for given number of PRBs used on U-plane packet creation */
416 struct xran_section_desc {
417 uint16_t section_id; /**< section id used for this element */
419 int16_t iq_buffer_offset; /**< Offset in bytes for the content of IQs with in main symb buffer */
420 int16_t iq_buffer_len; /**< Length in bytes for the content of IQs with in main symb buffer */
422 uint8_t *pData; /**< optional pointer to data buffer */
423 void *pCtrl; /**< optional poitner to mbuf */
426 /** PRB element structure */
427 struct xran_prb_elm {
428 int16_t nRBStart; /**< start RB of RB allocation */
429 int16_t nRBSize; /**< number of RBs used */
430 int16_t nStartSymb; /**< start symbol ID */
431 int16_t numSymb; /**< number of symbols */
432 int16_t nBeamIndex; /**< beam index for given PRB */
433 int16_t bf_weight_update; /** need to update beam weights or not */
434 int16_t compMethod; /**< compression index for given PRB */
435 int16_t iqWidth; /**< compression bit width for given PRB */
436 int16_t BeamFormingType; /**< index based, weights based or attribute based beam forming*/
438 struct xran_section_desc * p_sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**< section desctiptors to U-plane data given RBs */
439 struct xran_cp_bf_weight bf_weight; /**< beam forming information relevant for given RBs */
442 struct xran_cp_bf_attribute bf_attribute;
443 struct xran_cp_bf_precoding bf_precoding;
447 /** PRB map structure */
448 struct xran_prb_map {
449 uint8_t dir; /**< DL or UL direction */
450 uint8_t xran_port; /**< xran id of given RU [0-(XRAN_PORTS_NUM-1)] */
451 uint16_t band_id; /**< xran band id */
452 uint16_t cc_id; /**< componnent carrier id [0 - (XRAN_MAX_SECTOR_NR-1)] */
453 uint16_t ru_port_id; /**< RU device antenna port id [0 - (XRAN_MAX_ANTENNA_NR-1) */
454 uint16_t tti_id; /**< xRAN slot id [0 - (max tti-1)] */
455 uint8_t start_sym_id; /**< start symbol Id [0-13] */
456 uint32_t nPrbElm; /**< total number of PRB elements for given map [0- (XRAN_MAX_PRBS-1)] */
457 struct xran_prb_elm prbMap[XRAN_MAX_PRBS];
462 /* PRACH config required for XRAN based FH */
463 struct xran_prach_config
466 uint8_t nPrachConfIdx; /**< PRACH Configuration Index*/
467 uint8_t nPrachSubcSpacing;
468 /**< PRACH Sub-carrier spacing
470 For below 6GHz the values indicate 15kHz or 30kHz
471 For above 6GHz the values indicate 60kHz or 120kHz*/
472 uint8_t nPrachZeroCorrConf; /**< PRACH zeroCorrelationZoneConfig */
473 uint8_t nPrachRestrictSet; /**< PRACH restrictedSetConfig */
474 uint16_t nPrachRootSeqIdx; /**< PRACH Root Sequence Index */
475 uint16_t nPrachFreqStart; /**< PRACH prach-frequency-start */
476 int32_t nPrachFreqOffset; /**< PRACH prach-frequency-offset */
477 uint8_t nPrachFilterIdx; /**< PRACH Filter index */
480 /**< SRS configuration required for XRAN based FH */
481 struct xran_srs_config {
482 uint16_t symbMask; /**< symbols used for SRS with in U/S slot [bits 0-13] */
483 uint8_t eAxC_offset; /**< starting value of eAxC for SRS packets */
486 /** XRAN slot configuration */
487 struct xran_slot_config {
488 uint8_t nSymbolType[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**< Defines the Symbol type for all 14 symbols in a slot. 0: DL, 1: UL, 2: Guard */
492 /** XRAN front haul frame config */
493 struct xran_frame_config {
494 uint8_t nFrameDuplexType; /**< Frame Duplex type: 0 -> FDD, 1 -> TDD */
495 uint8_t nNumerology; /**< Numerology, determine sub carrier spacing, Value: 0->4
496 0: 15khz, 1: 30khz, 2: 60khz
497 3: 120khz, 4: 240khz */
498 uint8_t nTddPeriod; /**< TDD period */
499 struct xran_slot_config sSlotConfig[XRAN_MAX_TDD_PERIODICITY];
500 /**< TDD Slot configuration - If nFrameDuplexType = TDD(1), then this config defines the slot config type for each slot.*/
501 /* The number of slots need to be equal to nTddPeriod */
504 /** XRAN-PHY interface byte order */
505 enum xran_input_byte_order {
506 XRAN_NE_BE_BYTE_ORDER = 0, /**< Network byte order (Big endian), xRAN lib doesn't do swap */
507 XRAN_CPU_LE_BYTE_ORDER /**< CPU byte order (Little endian), xRAN lib does do swap */
510 /** XRAN-PHY interface I and Q order */
511 enum xran_input_i_q_order {
512 XRAN_I_Q_ORDER = 0, /**< I , Q */
513 XRAN_Q_I_ORDER /**< Q , I */
516 /** XRAN front haul O-RU settings */
517 struct xran_ru_config {
518 enum xran_ran_tech xranTech; /**< 5GNR or LTE */
519 enum xran_category xranCat; /**< mode: Catergory A or Category B */
520 enum xran_comp_hdr_type xranCompHdrType; /**< dynamic or static udCompHdr handling*/
521 uint8_t iqWidth; /**< IQ bit width */
522 uint8_t compMeth; /**< Compression method */
523 uint8_t fftSize; /**< FFT Size */
524 enum xran_input_byte_order byteOrder; /**< Order of bytes in int16_t in buffer. Big or little endian */
525 enum xran_input_i_q_order iqOrder; /**< order of IQs in the buffer */
526 uint16_t xran_max_frame; /**< max frame number supported */
531 * XRAN front haul general configuration */
532 struct xran_fh_config {
533 uint32_t dpdk_port; /**< DPDK port number used for FH */
534 uint32_t sector_id; /**< Band sector ID for FH */
535 uint32_t nCC; /**< number of Component carriers supported on FH */
536 uint32_t neAxc; /**< number of eAxc supported on one CC*/
537 uint32_t neAxcUl; /**< number of eAxc supported on one CC for UL direction */
538 uint32_t nAntElmTRx; /**< Number of antenna elements for TX and RX */
539 uint16_t nDLFftSize; /**< DL FFT size */
540 uint16_t nULFftSize; /**< UL FFT size */
541 uint16_t nDLRBs; /**< DL PRB */
542 uint16_t nULRBs; /**< UL PRB */
543 uint32_t nDLAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
544 uint32_t nULAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
545 uint32_t nDLCenterFreqARFCN; /**< center frerquency for DL in MHz */
546 uint32_t nULCenterFreqARFCN; /**< center frerquency for UL in MHz */
547 xran_fh_tti_callback_fn ttiCb; /**< call back for TTI event */
548 void *ttiCbParam; /**< parameters of call back function */
550 struct xran_prach_config prach_conf; /**< PRACH specific configurations for FH */
551 struct xran_srs_config srs_conf; /**< SRS specific configurations for FH */
552 struct xran_frame_config frame_conf; /**< frame config */
553 struct xran_ru_config ru_conf; /**< config of RU as per XRAN spec */
555 phy_encoder_poll_fn bbdev_enc; /**< call back to poll BBDev encoder */
556 phy_decoder_poll_fn bbdev_dec; /**< call back to poll BBDev decoder */
558 uint16_t tx_cp_eAxC2Vf[XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR*2 + XRAN_MAX_ANT_ARRAY_ELM_NR]; /**< mapping of C-Plane (ecpriRtcid) or U-Plane (ecpriPcid) to VF */
559 uint16_t tx_up_eAxC2Vf[XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR*2 + XRAN_MAX_ANT_ARRAY_ELM_NR]; /**< mapping of C-Plane (ecpriRtcid) or U-Plane (ecpriPcid) to VF */
561 uint16_t rx_cp_eAxC2Vf[XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR*2 + XRAN_MAX_ANT_ARRAY_ELM_NR]; /**< mapping of C-Plane (ecpriRtcid) or U-Plane (ecpriPcid) to VF */
562 uint16_t rx_up_eAxC2Vf[XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR*2 + XRAN_MAX_ANT_ARRAY_ELM_NR]; /**< mapping of C-Plane (ecpriRtcid) or U-Plane (ecpriPcid) to VF */
564 uint32_t log_level; /**< configuration of log level */
569 * XRAN front haul statistic counters according to Table 7 1 : Common Counters for both DL and UL */
570 struct xran_common_counters{
571 uint64_t Rx_on_time; /**< Data was received on time (applies to user data reception window) */
572 uint64_t Rx_early; /**< Data was received too early (applies to user data reception window) */
573 uint64_t Rx_late; /**< Data was received too late (applies to user data reception window) */
574 uint64_t Rx_corrupt; /**< Corrupt/Incorrect header packet */
575 uint64_t Rx_pkt_dupl; /**< Duplicated packet */
576 uint64_t Total_msgs_rcvd; /**< Total messages received (on all links) */
578 /* debug statistis */
581 uint64_t tx_bytes_counter;
582 uint64_t rx_bytes_counter;
583 uint64_t tx_bytes_per_sec;
584 uint64_t rx_bytes_per_sec;
586 uint64_t rx_pusch_packets[XRAN_MAX_ANTENNA_NR];
587 uint64_t rx_prach_packets[XRAN_MAX_ANTENNA_NR];
588 uint64_t rx_srs_packets;
593 * CC instance handle pointer type */
594 typedef void * xran_cc_handle_t;
597 *****************************************************************************
601 * A flat buffer structure. The data pointer, pData, is a virtual address.
602 * The API requires the memory to by physically contiguous. Each flat
603 * buffer segment may contain several equally sized elements.
605 *****************************************************************************/
606 struct xran_flat_buffer
608 uint32_t nElementLenInBytes;
609 /**< The Element length specified in bytes.
610 * This parameter specifies the size of a single element in the buffer.
611 * The total size of the buffer is described as
612 * bufferSize = nElementLenInBytes * nNumberOfElements */
613 uint32_t nNumberOfElements;
614 /**< The number of elements in the physical contiguous memory segment */
615 uint32_t nOffsetInBytes;
616 /**< Offset in bytes to the start of the data in the physical contiguous
620 /**< The data pointer is a virtual address, however the actual data pointed
621 * to is required to be in contiguous physical memory unless the field
622 requiresPhysicallyContiguousMemory in CpaInstanceInfo is false. */
624 /**< pointer to control section coresponding to data buffer */
628 *****************************************************************************
630 * Scatter/Gather buffer list containing an array of Simple buffers.
633 * A Scatter/Gather buffer list structure. It is expected that this buffer
634 * structure will be used where more than one flat buffer can be provided
635 * on a particular API.
637 * IMPORTANT - The memory for the pPrivateMetaData member must be allocated
638 * by the client as contiguous memory. When allocating memory for
639 * pPrivateMetaData a call to cpaCyBufferListGetMetaSize MUST be made to
640 * determine the size of the Meta Data Buffer. The returned size
641 * (in bytes) may then be passed in a memory allocation routine to allocate
642 * the pPrivateMetaData memory.
644 *****************************************************************************/
645 struct xran_buffer_list
647 uint32_t nNumBuffers;
648 /**< Number of pointers */
649 struct xran_flat_buffer *pBuffers;
650 /**< Pointer to an unbounded array containing the number of CpaFlatBuffers
651 * defined by nNumBuffers */
653 /**< This is an opaque field that is not read or modified internally. */
654 void *pPrivateMetaData;
655 /**< Private Meta representation of this buffer List - the memory for this
656 * buffer needs to be allocated by the client as contiguous data.
657 * The amount of memory required is returned with a call to
658 * cpaCyBufferListGetMetaSize. If cpaCyBufferListGetMetaSize returns a size
659 * of zero no memory needs to be allocated, and this parameter can be NULL.
665 * Initialize the XRAN Layer via DPDK.
668 * A non-negative value. If it is greater than 0, the array members
669 * for argv[0] through argv[argc] (non-inclusive) shall contain pointers
672 * An array of strings. The contents of the array, as well as the strings
673 * which are pointed to by the array, may be modified by this function.
677 * Error codes returned via rte_errno
679 int32_t xran_init(int argc, char *argv[], struct xran_fh_init *p_xran_fh_init, char *appName, void ** pHandle);
684 * Function returns handles for number of sectors supported by XRAN layer. Currently function
685 * supports one handle XRAN layer where it supports only one CC
688 * Pointer to XRAN layer handle
689 * @param nNumInstances
690 * total number of instances of CC
691 * @param pSectorInstanceHandles
692 * Pointer to xran_cc_handle_t where to store Handle pointer
697 int32_t xran_sector_get_instances (void * pHandle, uint16_t nNumInstances,
698 xran_cc_handle_t * pSectorInstanceHandles);
703 * Function initialize Memory Management subsystem (mm) in order to handle memory buffers between XRAN layer
707 * Pointer to XRAN layer handle for given CC
709 * memory size of all segments
710 * @param nMemorySegmentSize
711 * size of memory per segment
716 int32_t xran_mm_init (void * pHandle, uint64_t nMemorySize, uint32_t nMemorySegmentSize);
721 * Function allocates buffer memory (bm) used between XRAN layer and PHY. In general case it's DPDK mbuf.
722 * it uses Memory Management system to get memory chunk and define memory pool on top of it.
725 * Pointer to XRAN layer handle for given CC
727 * pointer to buffer pool identification to be returned
728 * @param nNumberOfBuffers
729 * number of buffer to allocate in the pool
731 * buffer size to allocate
736 int32_t xran_bm_init (void * pHandle, uint32_t * pPoolIndex, uint32_t nNumberOfBuffers, uint32_t nBufferSize);
741 * Function allocates buffer used between XRAN layer and PHY. In general case it's DPDK mbuf.
744 * Pointer to XRAN layer handle for given CC
746 * buffer pool identification
748 * Pointer to pointer where to store address of new buffer
750 * Pointer to pointer where to store address of internal private control information
756 int32_t xran_bm_allocate_buffer(void * pHandle, uint32_t nPoolIndex, void **ppData, void **ppCtrl);
761 * Function frees buffer used between XRAN layer and PHY. In general case it's DPDK mbuf
764 * Pointer to XRAN layer handle for given CC
768 * Pointer to internal private control information
773 int32_t xran_bm_free_buffer(void * pHandle, void *pData, void *pCtrl);
778 * Function destroys Memory Management (MM) layer of XRAN library
781 * Pointer to XRAN layer handle for given CC
786 int32_t xran_mm_destroy (void * pHandle);
791 * Function configures TX(DL) and RX(UL) output buffers and callback (UL only) for XRAN layer with
795 * Pointer to XRAN layer handle for given CC
797 * list of memory buffers to use to fetch IQs from PHY to XRAN layer (DL)
798 * @param pSrcCpBuffer
799 * list of memory buffers to use to configure C-plane (DL)
801 * list of memory buffers to use to deliver IQs from XRAN layer to PHY (UL)
802 * @param pDstCpBuffer
803 * list of memory buffers to use to configure C-plane (UL)
804 * @param xran_transport_callback_fn pCallback
805 * Callback function to call with arrival of all packets for given CC for given symbol
806 * @param pCallbackTag
807 * Parameters of Callback function
813 int32_t xran_5g_fronthault_config (void * pHandle,
814 struct xran_buffer_list *pSrcBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
815 struct xran_buffer_list *pSrcCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
816 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
817 struct xran_buffer_list *pDstCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
818 xran_transport_callback_fn pCallback,
824 * Function configures PRACH output buffers and callback for XRAN layer with given handle
827 * Pointer to XRAN layer handle for given CC
829 * list of memory buffers to use to deliver PRACH IQs from xran layer to PHY
830 * @param xran_transport_callback_fn pCallback
831 * Callback function to call with arrival of PRACH packets for given CC
832 * @param pCallbackTag
833 * Parameters of Callback function
839 int32_t xran_5g_prach_req (void * pHandle,
840 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
841 xran_transport_callback_fn pCallback,
847 * Function configures SRS output buffers and callback for XRAN layer with given handle
850 * Pointer to XRAN layer handle for given CC
852 * list of memory buffers to use to deliver SRS IQs from xran layer to PHY
853 * @param xran_transport_callback_fn pCallback
854 * Callback function to call with arrival of SRS packets for given CC
855 * @param pCallbackTag
856 * Parameters of Callback function
862 int32_t xran_5g_srs_req (void * pHandle,
863 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_N_FE_BUF_LEN],
864 xran_transport_callback_fn pCallback,
871 * Function returns XRAN core utilization stats
873 * @param total_time (out)
874 * Pointer to variable to store Total time thread has been running
875 * @param used_time (out)
876 * Pointer to variable to store Total time essential tasks have been running on the thread
877 * @param core_used (out)
878 * Pointer to variable to store Core on which the XRAN thread is running
880 * If set to 1, then internal variables total_time and used_time are cleared
885 uint32_t xran_get_time_stats(uint64_t *total_time, uint64_t *used_time, uint32_t *core_used, uint32_t clear);
890 * Function opens XRAN layer with given handle
893 * Pointer to XRAN layer handle for given CC
894 * @param pointer to struct xran_fh_config pConf
895 * Pointer to XRAN configuration structure with specific settings to use
900 int32_t xran_open(void *pHandle, struct xran_fh_config* pConf);
905 * Function starts XRAN layer with given handle
908 * Pointer to XRAN layer handle for given CC
913 int32_t xran_start(void *pHandle);
918 * Function stops XRAN layer with given handle
921 * Pointer to XRAN layer handle for given CC
926 int32_t xran_stop(void *pHandle);
931 * Function closes XRAN layer with given handle
934 * Pointer to XRAN layer handle for given CC
939 int32_t xran_close(void *pHandle);
944 * Function registers callback to XRAN layer. Function support callbacks aligned on packet arrival.
947 * Pointer to XRAN layer handle for given CC
949 * pointer to callback function
951 * pointer to Callback Function parameters
953 * symbol to be register for
955 * Antenna number to trigger callback for packet arrival
958 * 0 - in case of success
959 * -1 - in case of failure
961 int32_t xran_reg_sym_cb(void *pHandle, xran_callback_sym_fn symCb, void * symCbParam, uint8_t symb, uint8_t ant);
966 * Function registers callback to XRAN layer. Function support callbacks align to OTA time. TTI even, half of slot,
967 * full slot with respect to PTP time.
970 * Pointer to XRAN layer handle for given CC
972 * pointer to callback function
974 * pointer to Callback Function parameters
976 * number of calls to be skipped before first call
977 * @param callback_to_phy_id
978 * call back time identification (see enum callback_to_phy_id)
981 * 0 - in case of success
982 * -1 - in case of failure
984 int32_t xran_reg_physide_cb(void *pHandle, xran_fh_tti_callback_fn Cb, void *cbParam, int skipTtiNum, enum callback_to_phy_id);
989 * Function returns current TTI, Frame, Subframe, Slot Number as seen "Over air" base on PTP time
992 * Pointer to Frame number [0-99]
994 * @param nSubframeIdx
995 * Pointer to Subframe number [0-10]
998 * Pointer to Slot number [0-7]
1001 * Pointer to current UTC second
1004 * current TTI number [0-7999]
1006 int32_t xran_get_slot_idx (uint32_t *nFrameIdx, uint32_t *nSubframeIdx, uint32_t *nSlotIdx, uint64_t *nSecond);
1011 * Function retrun XRAN layer common counters for given handle
1014 * Pointer to XRAN layer handle for given CC
1017 * Pointer to pointer of common counter structure
1022 int32_t xran_get_common_counters(void *pXranLayerHandle, struct xran_common_counters *pStats);
1028 * Function returns status of operation of FH layer
1031 * XRAN_INIT - init state
1032 * XRAN_RUNNING - running
1033 * XRAN_STOPPED - stopped
1035 enum xran_if_state xran_get_if_state(void);
1041 * Function allocates memory of given size from heap
1047 * buf_len - size of memory allocation
1049 void* xran_malloc(size_t buf_len);
1054 * Function frees memory of given size from heap
1057 * addr - pointer to buffer
1062 void xran_free(void *addr);
1067 * Function calculates offset for ptr according to ORAN headers requared
1070 * pointer to be addjusted
1072 * compression method according to enum xran_compression_method
1075 * ptr - pointer to payload given header requared
1077 uint8_t* xran_add_hdr_offset(uint8_t *dst, int16_t compMethod);
1082 * Function calculates offset for ptr according to ORAN C-plane headers requared
1085 * pointer to be addjusted
1088 * ptr - pointer to payload given header requared
1090 uint8_t *xran_add_cp_hdr_offset(uint8_t *dst);
1096 #endif /* _XRAN_FH_O_DU_H_*/