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 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>
55 #define XRAN_STATUS_SUCCESS (0)
58 * Success status value. */
59 #define XRAN_STATUS_FAIL (-1)
62 * Fail status value. */
64 #define XRAN_STATUS_RETRY (-2)
67 * Retry status value. */
69 #define XRAN_STATUS_RESOURCE (-3)
72 * The resource that has been requested is unavailable. Refer
73 * to relevant sections of the API for specifics on what the suggested
74 * course of action is. */
76 #define XRAN_STATUS_INVALID_PARAM (-4)
79 * Invalid parameter has been passed in. */
80 #define XRAN_STATUS_FATAL (-5)
83 * A serious error has occurred. Recommended course of action
84 * is to shutdown and restart the component. */
86 #define XRAN_STATUS_UNSUPPORTED (-6)
89 * The function is not supported, at least not with the specific
90 * parameters supplied. This may be because a particular
91 * capability is not supported by the current implementation. */
93 #define XRAN_STATUS_INVALID_PACKET (-7)
96 * Recevied packet does not have correct format. */
98 /** Macro to calculate TTI number from symbol index used by timing thread */
99 #define XranGetTtiNum(symIdx, numSymPerTti) (((uint32_t)symIdx / (uint32_t)numSymPerTti))
100 /** Macro to calculate Symbol number for given slot from symbol index */
101 #define XranGetSymNum(symIdx, numSymPerTti) (((uint32_t)symIdx % (uint32_t)numSymPerTti))
102 /** Macro to calculate Frame number for given tti */
103 #define XranGetFrameNum(tti,SFNatSecStart,numSubFramePerSystemFrame, numSlotPerSubFrame) ((((uint32_t)tti / ((uint32_t)numSubFramePerSystemFrame * (uint32_t)numSlotPerSubFrame)) + SFNatSecStart) & 0x3FF)
104 /** Macro to calculate Subframe number for given tti */
105 #define XranGetSubFrameNum(tti, numSlotPerSubFrame, numSubFramePerSystemFrame) (((uint32_t)tti/(uint32_t)numSlotPerSubFrame) % (uint32_t)numSubFramePerSystemFrame)
106 /** Macro to calculate Slot number */
107 #define XranGetSlotNum(tti, numSlotPerSfn) ((uint32_t)tti % ((uint32_t)numSlotPerSfn))
109 #define XRAN_PORTS_NUM (4) /**< number of XRAN ports (aka O-RU|O-DU devices) supported */
110 #define XRAN_ETH_PF_LINKS_NUM (4) /**< number of Physical Ethernet links per one O-RU|O-DU */
111 #define XRAN_N_FE_BUF_LEN (20) /**< Number of TTIs (slots) */
112 #define XRAN_MAX_SECTOR_NR (16) /**< Max sectors per XRAN port */
113 #define XRAN_MAX_ANTENNA_NR (16) /**< Max number of extended Antenna-Carriers:
114 a data flow for a single antenna (or spatial stream) for a single carrier in a single sector */
116 /* see 10.2 Hierarchy of Radiation Structure in O-RU (assume TX and RX panel are the same dimensions)*/
117 #define XRAN_MAX_PANEL_NR (1) /**< Max number of Panels supported per O-RU */
118 #define XRAN_MAX_TRX_ANTENNA_ARRAY (1) /**< Max number of TX and RX arrays per panel in O-RU */
119 #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 */
128 #define XRAN_NUM_OF_SC_PER_RB (12) /**< Number of subcarriers per RB */
130 #define XRAN_MAX_SECTIONS_PER_SLOT (24) /**< Max number of different sections in single slot (section may be equal to RB allocation for UE) */
131 #define XRAN_MIN_SECTIONS_PER_SLOT (6) /**< Min number of different sections in single slot (section may be equal to RB allocation for UE) */
132 #define XRAN_MAX_SECTIONS_PER_SYM (XRAN_MAX_SECTIONS_PER_SLOT) /**< Max number of different sections in single slot (section may be equal to RB allocation for UE) */
133 #define XRAN_MIN_SECTIONS_PER_SYM (XRAN_MIN_SECTIONS_PER_SLOT) /**< Min number of different sections in single slot (section may be equal to RB allocation for UE) */
135 #define XRAN_MAX_FRAGMENT (1) /**< Max number of fragmentations in single symbol */
136 #define XRAN_MAX_SET_BFWS (64) /**< Assumed 64Ant, BFP 9bit with 9K jumbo frame */
138 #define XRAN_MAX_PKT_BURST (448+4) /**< 4x14x8 symbols per ms */
139 #define XRAN_N_MAX_BUFFER_SEGMENT XRAN_MAX_PKT_BURST /**< Max number of segments per ms */
141 #define XRAN_STRICT_PARM_CHECK (1) /**< enable parameter check for C-plane */
143 /* Slot type definition */
144 #define XRAN_SLOT_TYPE_INVALID (0) /**< invalid slot type */
145 #define XRAN_SLOT_TYPE_DL (1) /**< DL slot */
146 #define XRAN_SLOT_TYPE_UL (2) /**< UL slot */
147 #define XRAN_SLOT_TYPE_SP (3) /**< Special slot */
148 #define XRAN_SLOT_TYPE_FDD (4) /**< FDD slot */
149 #define XRAN_SLOT_TYPE_LAST (5) /**< MAX slot */
151 /* symbol type definition */
152 #define XRAN_SYMBOL_TYPE_DL (0) /**< DL symbol */
153 #define XRAN_SYMBOL_TYPE_UL (1) /**< UL symbol */
154 #define XRAN_SYMBOL_TYPE_GUARD (2) /**< GUARD symbol */
155 #define XRAN_SYMBOL_TYPE_FDD (3) /**< FDD symbol */
157 #define XRAN_NUM_OF_SLOT_IN_TDD_LOOP (80)/**< MAX number of slot for TDD repetition */
159 //#define _XRAN_DEBUG /**< Enable debug log */
160 //#define _XRAN_VERBOSE /**< Enable verbose log */
161 #define MX_NUM_SAMPLES (16)/**< MAX Number of Samples for One Way delay Measurement */
163 #define XRAN_VF_QUEUE_MAX (XRAN_MAX_ANTENNA_NR*2+XRAN_MAX_ANT_ARRAY_ELM_NR) /**< MAX number of HW queues for given VF */
166 #define xran_log_dbg(fmt, ...) \
168 "DEBUG: %s(%d): " fmt "\n", \
170 __LINE__, ##__VA_ARGS__)
172 #define xran_log_dbg(fmt, ...)
175 #if defined(_XRAN_DEBUG) || defined(_XRAN_VERBOSE)
176 #define xran_log_wrn(fmt, ...) \
179 "WARNING: %s(%d): " fmt "\n", \
181 __LINE__, ##__VA_ARGS__)
183 #define xran_log_dbg(fmt, ...)
184 #define xran_log_wrn(fmt, ...)
187 #define xran_log_err(fmt, ...) \
189 "ERROR: %s(%d): " fmt "\n", \
191 __LINE__, ##__VA_ARGS__)
193 enum XranFrameDuplexType
195 XRAN_FDD = 0, XRAN_TDD
207 ******************************************************************************
211 * Compression Method 6.3.3.13, Table 6-43
212 *****************************************************************************/
213 enum xran_compression_method {
214 XRAN_COMPMETHOD_NONE = 0,
215 XRAN_COMPMETHOD_BLKFLOAT = 1,
216 XRAN_COMPMETHOD_BLKSCALE = 2,
217 XRAN_COMPMETHOD_ULAW = 3,
218 XRAN_COMPMETHOD_MODULATION = 4,
223 ******************************************************************************
227 * enum of callback function type ids for TTI
228 *****************************************************************************/
229 enum callback_to_phy_id
231 XRAN_CB_TTI = 0, /**< callback on TTI boundary */
232 XRAN_CB_HALF_SLOT_RX =1, /**< callback on half slot (sym 7) packet arrival*/
233 XRAN_CB_FULL_SLOT_RX =2, /**< callback on full slot (sym 14) packet arrival */
234 XRAN_CB_MAX /**< max number of callbacks */
238 ******************************************************************************
242 * enum of callback function type ids for sumbol
243 *****************************************************************************/
244 enum cb_per_sym_type_id
246 XRAN_CB_SYM_OTA_TIME = 0, /**< callback on exact SYM OTA time (+-SW jitter) */
247 XRAN_CB_SYM_RX_WIN_BEGIN = 1, /**< callback on exact SYM RX window start time (+-SW jitter) */
248 XRAN_CB_SYM_RX_WIN_END = 2, /**< callback on exact SYM RX window stop time (+-SW jitter) */
249 XRAN_CB_SYM_TX_WIN_BEGIN = 3, /**< callback on exact SYM TX window start time (+-SW jitter) */
250 XRAN_CB_SYM_TX_WIN_END = 4, /**< callback on exact SYM TX window stop time (+-SW jitter) */
251 XRAN_CB_SYM_CP_DL_WIN_BEGIN = 5, /**< callback on exact SYM DL CP window start time (+-SW jitter) */
252 XRAN_CB_SYM_CP_DL_WIN_END = 6, /**< callback on exact SYM DL CP window stop time (+-SW jitter) */
253 XRAN_CB_SYM_CP_UL_WIN_BEGIN = 7, /**< callback on exact SYM UL CP window start time (+-SW jitter) */
254 XRAN_CB_SYM_CP_UL_WIN_END = 8, /**< callback on exact SYM UL CP window stop time (+-SW jitter) */
255 XRAN_CB_SYM_MAX /**< max number of types of callbacks */
258 /** Beamforming type, enumerated as "frequency", "time" or "hybrid"
259 section 10.4.2 Weight-based dynamic beamforming */
260 enum xran_weight_based_beamforming_type {
261 XRAN_BF_T_FREQUENCY = 0,
263 XRAN_BF_T_HYBRID = 2,
267 /** contains time related information according to type of event */
268 struct xran_sense_of_time {
269 enum cb_per_sym_type_id type_of_event; /**< event type id */
270 uint32_t tti_counter; /**< TTI counter with in GPS second */
271 uint32_t nSymIdx; /**< Symbol Idx with in Slot [0-13] */
272 uint32_t nFrameIdx; /**< ORAN Frame */
273 uint32_t nSubframeIdx; /**< ORAN Subframe */
274 uint32_t nSlotIdx; /**< Slot within subframe */
275 uint64_t nSecond; /**< GPS second of this symbol */
278 typedef int32_t xran_status_t; /**< Xran status return value */
280 /** callback function type for Symbol packet */
281 typedef int32_t (*xran_callback_sym_fn)(void*, struct xran_sense_of_time* p_sense_of_time);
283 /** Callback function type for TTI event */
284 typedef int32_t (*xran_fh_tti_callback_fn)(void*);
286 /** Callback function type packet arrival from transport layer (ETH or IP) */
287 typedef void (*xran_transport_callback_fn)(void*, xran_status_t);
289 /** Callback functions to poll BBdev encoder */
290 typedef int16_t (*phy_encoder_poll_fn)(void);
292 /** Callback functions to poll BBdev decoder */
293 typedef int16_t (*phy_decoder_poll_fn)(void);
295 /** XRAN port enum */
298 XRAN_UP_VF = 0, /**< port type for U-plane */
299 XRAN_CP_VF, /**< port type for C-plane */
300 XRAN_UP_VF1, /**< port type for U-plane */
301 XRAN_CP_VF1, /**< port type for C-plane */
302 XRAN_UP_VF2, /**< port type for U-plane */
303 XRAN_CP_VF2, /**< port type for C-plane */
304 XRAN_UP_VF3, /**< port type for U-plane */
305 XRAN_CP_VF3, /**< port type for C-plane */
306 XRAN_UP_VF4, /**< port type for U-plane */
307 XRAN_CP_VF4, /**< port type for C-plane */
308 XRAN_UP_VF5, /**< port type for U-plane */
309 XRAN_CP_VF5, /**< port type for C-plane */
310 XRAN_UP_VF6, /**< port type for U-plane */
311 XRAN_CP_VF6, /**< port type for C-plane */
312 XRAN_UP_VF7, /**< port type for U-plane */
313 XRAN_CP_VF7, /**< port type for C-plane */
317 /** XRAN Radio Access technology enum */
320 XRAN_RAN_5GNR = 0, /**< 5G NR */
321 XRAN_RAN_LTE = 1, /**< LTE */
325 /** XRAN user data compression header handling types */
326 enum xran_comp_hdr_type
328 XRAN_COMP_HDR_TYPE_DYNAMIC = 0, /**< dynamic data format where U-plane udCompHdr controls compression parameters */
329 XRAN_COMP_HDR_TYPE_STATIC = 1, /**< static data format where M-plane defines compression parameters */
330 XRAN_COMP_HDR_TYPE_MAX
333 /** XRAN category enum */
336 XRAN_CATEGORY_A = 0, /**< 5G NR Category A */
337 XRAN_CATEGORY_B = 1, /**< 5G NR Category B */
341 /** type of beamforming */
342 enum xran_beamforming_type
344 XRAN_BEAM_ID_BASED = 0, /**< beam index based */
345 XRAN_BEAM_WEIGHT = 1, /**< beam forming weights */
346 XRAN_BEAM_ATTRIBUTE = 2, /**< beam index based */
350 /** state of bbdev with xran */
353 XRAN_BBDEV_NOT_USED = -1, /**< BBDEV is disabled */
354 XRAN_BBDEV_MODE_HW_OFF = 0, /**< BBDEV is enabled for SW sim mode */
355 XRAN_BBDEV_MODE_HW_ON = 1, /**< BBDEV is enable for HW */
356 XRAN_BBDEV_MODE_HW_SW = 2, /**< BBDEV for SW and HW is enabled */
360 /** callback return information */
368 /** Common Data for ecpri one-way delay measurements */
369 struct xran_ecpri_del_meas_cmn {
370 uint16_t initiator_en; // Initiator 1, Recipient 0
371 uint16_t numberOfSamples; // Total number of samples to be collected and averaged
372 uint32_t filterType; // Average for number of samples collected 0
373 uint64_t responseTo; // Response Timeout in ns
374 uint16_t measVf; // Vf using the owd transmitter
375 uint16_t measState; // The state of the owd Transmitter: OWDMTX_DIS,OWDMTX_INIT,OWDMTX_IDLE,OWDMTX_ACTIVE,OWDTX_DONE
376 uint16_t measId; // Measurement Id to be used by the transmitter
377 uint16_t measMethod; // Measurement Method i.e. REQUEST, REM_REQ, REQ_WFUP or REM_REQ_WFUP
378 uint16_t owdm_enable; // 1: Enabled 0:Disabled
379 uint16_t owdm_PlLength; // Payload Length 44 <= PlLength <= 1400
382 /** Port specific data for ecpri one-way delay measurements */
383 struct xran_ecpri_del_meas_port {
384 uint64_t t1; // ecpri ts1
385 uint64_t t2; // ecpri ts2
386 uint64_t tr; // ecpri tr
387 int64_t delta; // stores differences based on the msState
388 uint8_t portid; // portid for this owdm
389 uint8_t runMeas; // run One Way Delay measurements for numberOfSamples
390 uint16_t currentMeasID; // Last Measurement ID received, for originator use as base for the Measurement ID being send out
391 uint16_t msState; // Measurement State for Initiator: Idle, Waiting_Response, Waiting_Request, Waiting_Request_with_fup, Waiting_fup, Done
392 // Measurement State for Recipient: Idle, Waiting_Response, Waiting_Follow_up, Done
393 uint16_t numMeas; // Number of Measurements completed (Running number up to common config numberOfSamples
394 uint16_t txDone; // For originator clear after each change of state and set once the transmission is done
395 uint64_t rspTimerIdx; // Timer Index for TimeOut Timer. On timeout abort current measurement and go back to idle state
396 uint64_t delaySamples[MX_NUM_SAMPLES]; // Storage for collected delay samples i.e. td
397 uint64_t delayAvg; // Contains the average based on the numberOfSamples for the delay, gets computed once we have
398 // completed the collection for all the numberOfSamples prescribed
401 /** DPDK IO configuration for XRAN layer */
403 uint8_t id; /**< should be (0) for O-DU or (1) O-RU (debug) */
404 uint8_t num_vfs; /**< number of VFs for C-plane and U-plane (should be even) */
405 uint16_t num_rxq; /**< number of RX queues per VF */
406 char *dpdk_dev[XRAN_VF_MAX]; /**< VFs devices */
407 char *bbdev_dev[1]; /**< BBDev dev name */
408 int32_t bbdev_mode; /**< DPDK for BBDev */
409 uint32_t dpdkIoVaMode; /**< IOVA Mode */
410 uint32_t dpdkMemorySize; /**< DPDK max memory allocation */
411 int32_t core; /**< reserved */
412 int32_t system_core; /**< reserved */
413 uint64_t pkt_proc_core; /**< worker mask 0-63 */
414 uint64_t pkt_proc_core_64_127; /**< worker mask 64-127 */
415 int32_t pkt_aux_core; /**< reserved */
416 int32_t timing_core; /**< core used by xRAN */
417 int32_t port[XRAN_VF_MAX]; /**< VFs ports */
418 int32_t io_sleep; /**< enable sleep on PMD cores */
419 uint32_t nEthLinePerPort; /**< 1, 2, 3 total number of links per O-RU (Fronthaul Ethernet link) */
420 uint32_t nEthLineSpeed; /**< 10G,25G,40G,100G speed of Physical connection on O-RU */
421 int32_t one_vf_cu_plane; /**< 1 - C-plane and U-plane use one VF */
422 struct xran_ecpri_del_meas_cmn eowd_cmn[2];/**<ecpriowdmeasurementscommonsettingsforO-DUandO-RU*/
423 struct xran_ecpri_del_meas_port eowd_port[2][XRAN_VF_MAX]; /**< ecpri owd measurements per port variables for O-DU and O-RU */
426 /** XRAN spec section 3.1.3.1.6 ecpriRtcid / ecpriPcid define */
427 struct xran_eaxcid_config {
428 uint16_t mask_cuPortId; /**< Mask CU PortId */
429 uint16_t mask_bandSectorId; /**< Mask Band */
430 uint16_t mask_ccId; /**< Mask CC */
431 uint16_t mask_ruPortId; /**< Mask RU Port ID */
433 uint8_t bit_cuPortId; /**< bandsectorId + ccId + ru_portId */
434 uint8_t bit_bandSectorId; /**< ccId + ruPortId */
435 uint8_t bit_ccId; /**< ru_portId */
436 uint8_t bit_ruPortId; /**< 0 */
440 * XRAN Front haul interface initialization settings
442 struct xran_fh_init {
443 struct xran_io_cfg io_cfg;/**< DPDK IO for XRAN */
444 struct xran_eaxcid_config eAxCId_conf; /**< config of ecpriRtcid/ecpriPcid */
446 uint32_t xran_ports; /**< Number of O-RU/O-DU connected to this instantiation of ORAN FH layer */
447 uint32_t dpdkBasebandFecMode; /**< DPDK Baseband FEC device mode (0-SW, 1-HW) */
448 char *dpdkBasebandDevice; /**< DPDK Baseband device address */
449 char *filePrefix; /**< DPDK prefix */
451 uint32_t mtu; /**< maximum transmission unit (MTU) is the size of the largest protocol data unit (PDU) that can be communicated in a single
452 xRAN network layer transaction. supported 1500 bytes and 9600 bytes (Jumbo Frame) */
453 int8_t *p_o_du_addr; /**< O-DU Ethernet Mac Address */
454 int8_t *p_o_ru_addr; /**< O-RU Ethernet Mac Address */
456 uint16_t totalBfWeights;/**< The total number of beamforming weights on RU for extensions */
459 struct xran_ext11_bfw_info {
460 uint16_t beamId; /* 15bits, needs to strip MSB */
461 uint8_t *pBFWs; /* external buffer pointer */
463 /** Beamforming waights for single stream for each PRBs given number of Antenna elements */
464 struct xran_cp_bf_weight{
465 int16_t nAntElmTRx; /**< num TRX for this allocation */
466 int16_t ext_section_sz; /**< extType section size */
467 int8_t* p_ext_start; /**< pointer to start of buffer for full C-plane packet */
468 int8_t* p_ext_section; /**< pointer to form extType */
471 uint8_t bfwCompMeth; /* Compression Method for BFW */
472 uint8_t bfwIqWidth; /* Bitwidth of BFW */
473 uint8_t numSetBFWs; /* Total number of beam forming weights set (L) */
474 uint8_t numBundPrb; /* This parameter is the number of bundled PRBs per beamforming weights, 0 means to use ext1 */
477 int16_t maxExtBufSize; /* Maximum space of external buffer */
478 struct xran_ext11_bfw_info bfw[XRAN_MAX_SET_BFWS];
480 struct xran_cp_bf_attribute{
483 struct xran_cp_bf_precoding{
487 /** section descriptor for given number of PRBs used on U-plane packet creation */
488 struct xran_section_desc {
489 uint16_t section_id; /**< section id used for this element */
492 int16_t iq_buffer_offset; /**< Offset in bytes for the content of IQs with in main symbol buffer */
493 int16_t iq_buffer_len; /**< Length in bytes for the content of IQs with in main symbol buffer */
495 uint8_t *pData; /**< optional pointer to data buffer */
496 void *pCtrl; /**< optional pointer to mbuf */
499 /** PRB element structure */
500 struct xran_prb_elm {
501 int16_t nRBStart; /**< start RB of RB allocation */
502 int16_t nRBSize; /**< number of RBs used */
503 int16_t nStartSymb; /**< start symbol ID */
504 int16_t numSymb; /**< number of symbols */
505 int16_t nBeamIndex; /**< beam index for given PRB */
506 int16_t bf_weight_update; /** need to update beam weights or not */
507 int16_t compMethod; /**< compression index for given PRB */
508 int16_t iqWidth; /**< compression bit width for given PRB */
509 uint16_t ScaleFactor; /**< scale factor for modulation compression */
510 int16_t reMask; /**< 12-bit RE Mask for modulation compression */
511 int16_t BeamFormingType; /**< index based, weights based or attribute based beam forming*/
512 int16_t nSecDesc[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**< number of section descriptors per symbol */
514 struct xran_section_desc * p_sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT][XRAN_MAX_FRAGMENT]; /**< section desctiptors to U-plane data given RBs */
515 struct xran_cp_bf_weight bf_weight; /**< beam forming information relevant for given RBs */
518 struct xran_cp_bf_attribute bf_attribute;
519 struct xran_cp_bf_precoding bf_precoding;
523 /** PRB map structure */
524 struct xran_prb_map {
525 uint8_t dir; /**< DL or UL direction */
526 uint8_t xran_port; /**< xran id of given RU [0-(XRAN_PORTS_NUM-1)] */
527 uint16_t band_id; /**< xran band id */
528 uint16_t cc_id; /**< component carrier id [0 - (XRAN_MAX_SECTOR_NR-1)] */
529 uint16_t ru_port_id; /**< RU device antenna port id [0 - (XRAN_MAX_ANTENNA_NR-1) */
530 uint16_t tti_id; /**< xRAN slot id [0 - (max tti-1)] */
531 uint8_t start_sym_id; /**< start symbol Id [0-13] */
532 uint32_t nPrbElm; /**< total number of PRB elements for given map [0- (XRAN_MAX_SECTIONS_PER_SLOT-1)] */
533 struct xran_prb_elm prbMap[1];
536 /* PRACH config required for XRAN based FH */
537 struct xran_prach_config
540 uint8_t nPrachConfIdx; /**< PRACH Configuration Index*/
541 uint8_t nPrachSubcSpacing;
542 /**< PRACH Sub-carrier spacing
544 For below 6GHz the values indicate 15kHz or 30kHz
545 For above 6GHz the values indicate 60kHz or 120kHz*/
546 uint8_t nPrachZeroCorrConf; /**< PRACH zeroCorrelationZoneConfig */
547 uint8_t nPrachRestrictSet; /**< PRACH restrictedSetConfig */
548 uint16_t nPrachRootSeqIdx; /**< PRACH Root Sequence Index */
549 uint16_t nPrachFreqStart; /**< PRACH prach-frequency-start */
550 int32_t nPrachFreqOffset; /**< PRACH prach-frequency-offset */
551 uint8_t nPrachFilterIdx; /**< PRACH Filter index */
553 /* Return values after initialization */
563 /**< SRS configuration required for XRAN based FH */
564 struct xran_srs_config {
565 uint16_t symbMask; /**< symbols used for SRS with in U/S slot [bits 0-13] */
566 uint8_t eAxC_offset; /**< starting value of eAxC for SRS packets */
569 /** XRAN slot configuration */
570 struct xran_slot_config {
571 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 */
575 /** XRAN front haul frame config */
576 struct xran_frame_config {
577 uint8_t nFrameDuplexType; /**< Frame Duplex type: 0 -> FDD, 1 -> TDD */
578 uint8_t nNumerology; /**< Numerology, determine sub carrier spacing, Value: 0->4
579 0: 15khz, 1: 30khz, 2: 60khz
580 3: 120khz, 4: 240khz */
581 uint8_t nTddPeriod; /**< TDD period */
582 struct xran_slot_config sSlotConfig[XRAN_MAX_TDD_PERIODICITY];
583 /**< TDD Slot configuration - If nFrameDuplexType = TDD(1), then this config defines the slot config type for each slot.*/
584 /* The number of slots need to be equal to nTddPeriod */
587 /** XRAN-PHY interface byte order */
588 enum xran_input_byte_order {
589 XRAN_NE_BE_BYTE_ORDER = 0, /**< Network byte order (Big endian), xRAN lib doesn't do swap */
590 XRAN_CPU_LE_BYTE_ORDER /**< CPU byte order (Little endian), xRAN lib does do swap */
593 /** XRAN-PHY interface I and Q order */
594 enum xran_input_i_q_order {
595 XRAN_I_Q_ORDER = 0, /**< I , Q */
596 XRAN_Q_I_ORDER /**< Q , I */
599 /** XRAN front haul O-RU settings */
600 struct xran_ru_config {
601 enum xran_ran_tech xranTech; /**< 5GNR or LTE */
602 enum xran_category xranCat; /**< mode: Catergory A or Category B */
603 enum xran_comp_hdr_type xranCompHdrType; /**< dynamic or static udCompHdr handling*/
604 uint8_t iqWidth; /**< IQ bit width */
605 uint8_t compMeth; /**< Compression method */
606 uint8_t iqWidth_PRACH; /**< IQ bit width for PRACH */
607 uint8_t compMeth_PRACH; /**< Compression method for PRACH */
608 uint8_t fftSize; /**< FFT Size */
609 enum xran_input_byte_order byteOrder; /**< Order of bytes in int16_t in buffer. Big or little endian */
610 enum xran_input_i_q_order iqOrder; /**< order of IQs in the buffer */
611 uint16_t xran_max_frame; /**< max frame number supported */
616 * XRAN front haul general configuration */
617 struct xran_fh_config {
618 uint32_t dpdk_port; /**< DPDK port number used for FH */
619 uint32_t sector_id; /**< Band sector ID for FH */
620 uint32_t nCC; /**< number of Component carriers supported on FH */
621 uint32_t neAxc; /**< number of eAxc supported on one CC*/
622 uint32_t neAxcUl; /**< number of eAxc supported on one CC for UL direction */
623 uint32_t nAntElmTRx; /**< Number of antenna elements for TX and RX */
624 uint16_t nDLFftSize; /**< DL FFT size */
625 uint16_t nULFftSize; /**< UL FFT size */
626 uint16_t nDLRBs; /**< DL PRB */
627 uint16_t nULRBs; /**< UL PRB */
628 uint32_t nDLAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
629 uint32_t nULAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
630 uint32_t nDLCenterFreqARFCN; /**< center frequency for DL in MHz */
631 uint32_t nULCenterFreqARFCN; /**< center frequency for UL in MHz */
632 xran_fh_tti_callback_fn ttiCb; /**< call back for TTI event */
633 void *ttiCbParam; /**< parameters of call back function */
635 uint16_t Tadv_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
636 uint16_t T2a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
637 uint16_t T2a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
638 uint16_t T2a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
639 uint16_t T2a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
640 uint16_t T2a_min_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
641 uint16_t T2a_max_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
642 uint16_t Ta3_min; /**< Table 2 7 : xRAN Delay Management Model Parameters */
643 uint16_t Ta3_max; /**< Table 2 7 : xRAN Delay Management Model Parameters */
644 uint16_t T1a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
645 uint16_t T1a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
646 uint16_t T1a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
647 uint16_t T1a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
648 uint16_t T1a_min_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
649 uint16_t T1a_max_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
650 uint16_t Ta4_min; /**< Table 2 7 : xRAN Delay Management Model Parameters */
651 uint16_t Ta4_max; /**< Table 2 7 : xRAN Delay Management Model Parameters */
653 uint8_t enableCP; /**< enable C-plane */
654 uint8_t prachEnable; /**< enable PRACH */
655 uint8_t srsEnable; /**< enable SRS (Cat B specific) */
656 uint8_t puschMaskEnable;/**< enable pusch mask> */
657 uint8_t puschMaskSlot; /**< specific which slot pusch channel masked> */
658 uint8_t cp_vlan_tag; /**< C-plane vlan tag */
659 uint8_t up_vlan_tag; /**< U-plane vlan tag */
660 int32_t debugStop; /**< enable auto stop */
661 int32_t debugStopCount; /**< enable auto stop after number of Tx packets */
662 int32_t DynamicSectionEna; /**< enable dynamic C-Plane section allocation */
663 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)
664 int32_t GPS_Beta; //beta value as defined in section 9.7.2 of ORAN spec. range -32767 ~ +32767
666 struct xran_prach_config prach_conf; /**< PRACH specific configurations for FH */
667 struct xran_srs_config srs_conf; /**< SRS specific configurations for FH */
668 struct xran_frame_config frame_conf; /**< frame config */
669 struct xran_ru_config ru_conf; /**< config of RU as per XRAN spec */
671 phy_encoder_poll_fn bbdev_enc; /**< call back to poll BBDev encoder */
672 phy_decoder_poll_fn bbdev_dec; /**< call back to poll BBDev decoder */
674 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 */
675 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 */
677 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 */
678 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 */
680 uint32_t log_level; /**< configuration of log level */
682 uint16_t max_sections_per_slot; /**< M-Plane settings for section */
683 uint16_t max_sections_per_symbol; /**< M-Plane settings for section */
688 * XRAN front haul statistic counters according to Table 7 1 : Common Counters for both DL and UL */
689 struct xran_common_counters{
690 uint64_t Rx_on_time; /**< Data was received on time (applies to user data reception window) */
691 uint64_t Rx_early; /**< Data was received too early (applies to user data reception window) */
692 uint64_t Rx_late; /**< Data was received too late (applies to user data reception window) */
693 uint64_t Rx_corrupt; /**< Corrupt/Incorrect header packet */
694 uint64_t Rx_pkt_dupl; /**< Duplicated packet */
695 uint64_t Total_msgs_rcvd; /**< Total messages received (on all links) */
697 /* debug statistis */
700 uint64_t tx_bytes_counter;
701 uint64_t rx_bytes_counter;
702 uint64_t tx_bytes_per_sec;
703 uint64_t rx_bytes_per_sec;
705 uint64_t rx_pusch_packets[XRAN_MAX_ANTENNA_NR];
706 uint64_t rx_prach_packets[XRAN_MAX_ANTENNA_NR];
707 uint64_t rx_srs_packets;
713 * CC instance handle pointer type */
714 typedef void * xran_cc_handle_t;
717 *****************************************************************************
721 * A flat buffer structure. The data pointer, pData, is a virtual address.
722 * The API requires the memory to by physically contiguous. Each flat
723 * buffer segment may contain several equally sized elements.
725 *****************************************************************************/
726 struct xran_flat_buffer
728 uint32_t nElementLenInBytes; /**< The Element length specified in bytes.
729 * This parameter specifies the size of a single element in the buffer.
730 * The total size of the buffer is described as
731 * bufferSize = nElementLenInBytes * nNumberOfElements */
732 uint32_t nNumberOfElements; /**< The number of elements in the physical contiguous memory segment */
733 uint32_t nOffsetInBytes; /**< Offset in bytes to the start of the data in the physical contiguous
736 uint8_t *pData; /**< The data pointer is a virtual address */
737 void *pCtrl; /**< pointer to control section coresponding to data buffer */
741 *****************************************************************************
743 * Scatter/Gather buffer list containing an array of Simple buffers.
746 * A Scatter/Gather buffer list structure. It is expected that this buffer
747 * structure will be used where more than one flat buffer can be provided
748 * on a particular API.
750 *****************************************************************************/
751 struct xran_buffer_list
753 uint32_t nNumBuffers; /**< Number of pointers */
754 struct xran_flat_buffer *pBuffers;
756 void *pPrivateMetaData;
761 * Initialize the XRAN Layer via DPDK.
764 * A non-negative value. If it is greater than 0, the array members
765 * for argv[0] through argv[argc] (non-inclusive) shall contain pointers
768 * An array of strings. The contents of the array, as well as the strings
769 * which are pointed to by the array, may be modified by this function.
773 * Error codes returned via rte_errno
775 int32_t xran_init(int argc, char *argv[], struct xran_fh_init *p_xran_fh_init, char *appName, void ** pHandle);
780 * Function returns handles for number of sectors supported by XRAN layer. Currently function
781 * supports one handle XRAN layer where it supports only one CC
784 * Pointer to XRAN layer handle
785 * @param nNumInstances
786 * total number of instances of CC
787 * @param pSectorInstanceHandles
788 * Pointer to xran_cc_handle_t where to store Handle pointer
793 int32_t xran_sector_get_instances (uint32_t xran_port, void * pDevHandle, uint16_t nNumInstances,
794 xran_cc_handle_t * pSectorInstanceHandles);
799 * Function initialize Memory Management subsystem (mm) in order to handle memory buffers between XRAN layer
803 * Pointer to XRAN layer handle for given CC
805 * memory size of all segments
806 * @param nMemorySegmentSize
807 * size of memory per segment
812 int32_t xran_mm_init (void * pHandle, uint64_t nMemorySize, uint32_t nMemorySegmentSize);
817 * Function allocates buffer memory (bm) used between XRAN layer and PHY. In general case it's DPDK mbuf.
818 * it uses Memory Management system to get memory chunk and define memory pool on top of it.
821 * Pointer to XRAN layer handle for given CC
823 * pointer to buffer pool identification to be returned
824 * @param nNumberOfBuffers
825 * number of buffer to allocate in the pool
827 * buffer size to allocate
832 int32_t xran_bm_init (void * pHandle, uint32_t * pPoolIndex, uint32_t nNumberOfBuffers, uint32_t nBufferSize);
837 * Function allocates buffer used between XRAN layer and PHY. In general case it's DPDK mbuf.
840 * Pointer to XRAN layer handle for given CC
842 * buffer pool identification
844 * Pointer to pointer where to store address of new buffer
846 * Pointer to pointer where to store address of internal private control information
852 int32_t xran_bm_allocate_buffer(void * pHandle, uint32_t nPoolIndex, void **ppData, void **ppCtrl);
857 * Function frees buffer used between XRAN layer and PHY. In general case it's DPDK mbuf
860 * Pointer to XRAN layer handle for given CC
864 * Pointer to internal private control information
869 int32_t xran_bm_free_buffer(void * pHandle, void *pData, void *pCtrl);
874 * Function destroys Memory Management (MM) layer of XRAN library
877 * Pointer to XRAN layer handle for given CC
882 int32_t xran_mm_destroy (void * pHandle);
887 * Function configures TX(DL) and RX(UL) output buffers and callback (UL only) for XRAN layer with
891 * Pointer to XRAN layer handle for given CC
893 * list of memory buffers to use to fetch IQs from PHY to XRAN layer (DL)
894 * @param pSrcCpBuffer
895 * list of memory buffers to use to configure C-plane (DL)
897 * list of memory buffers to use to deliver IQs from XRAN layer to PHY (UL)
898 * @param pDstCpBuffer
899 * list of memory buffers to use to configure C-plane (UL)
900 * @param xran_transport_callback_fn pCallback
901 * Callback function to call with arrival of all packets for given CC for given symbol
902 * @param pCallbackTag
903 * Parameters of Callback function
909 int32_t xran_5g_fronthault_config (void * pHandle,
910 struct xran_buffer_list *pSrcBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
911 struct xran_buffer_list *pSrcCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
912 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
913 struct xran_buffer_list *pDstCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
914 xran_transport_callback_fn pCallback,
920 * Function configures PRACH output buffers and callback for XRAN layer with given handle
923 * Pointer to XRAN layer handle for given CC
925 * list of memory buffers to use to deliver PRACH IQs from xran layer to PHY
926 * @param xran_transport_callback_fn pCallback
927 * Callback function to call with arrival of PRACH packets for given CC
928 * @param pCallbackTag
929 * Parameters of Callback function
935 int32_t xran_5g_prach_req (void * pHandle,
936 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
937 struct xran_buffer_list *pDstBufferDecomp[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
938 xran_transport_callback_fn pCallback,
944 * Function configures SRS output buffers and callback for XRAN layer with given handle
947 * Pointer to XRAN layer handle for given CC
949 * list of memory buffers to use to deliver SRS IQs from xran layer to PHY
950 * @param xran_transport_callback_fn pCallback
951 * Callback function to call with arrival of SRS packets for given CC
952 * @param pCallbackTag
953 * Parameters of Callback function
959 int32_t xran_5g_srs_req (void * pHandle,
960 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_N_FE_BUF_LEN],
961 struct xran_buffer_list *pDstCpBuffer[XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_N_FE_BUF_LEN],
962 xran_transport_callback_fn pCallback,
969 * Function returns XRAN core utilization stats
971 * @param total_time (out)
972 * Pointer to variable to store Total time thread has been running
973 * @param used_time (out)
974 * Pointer to variable to store Total time essential tasks have been running on the thread
975 * @param core_used (out)
976 * Pointer to variable to store Core on which the XRAN thread is running
978 * If set to 1, then internal variables total_time and used_time are cleared
983 uint32_t xran_get_time_stats(uint64_t *total_time, uint64_t *used_time, uint32_t *num_core_used, uint32_t *core_used, uint32_t clear);
988 * Function opens XRAN layer with given handle
991 * Pointer to XRAN layer handle for given CC
992 * @param pointer to struct xran_fh_config pConf
993 * Pointer to XRAN configuration structure with specific settings to use
998 int32_t xran_open(void *pHandle, struct xran_fh_config* pConf);
1003 * Function starts XRAN layer with given handle
1006 * Pointer to XRAN layer handle for given CC
1011 int32_t xran_start(void *pHandle);
1016 * Function stops XRAN layer with given handle
1019 * Pointer to XRAN layer handle for given CC
1024 int32_t xran_stop(void *pHandle);
1029 * Function closes XRAN layer with given handle
1032 * Pointer to XRAN layer handle for given CC
1037 int32_t xran_close(void *pHandle);
1042 * Function registers callback to XRAN layer. Function support callbacks aligned on packet arrival.
1045 * Pointer to XRAN layer handle for given CC
1047 * pointer to callback function
1049 * pointer to Callback Function parameters
1051 * symbol to be register for
1052 * @param cb_per_sym_type_id
1053 * call back time identification (see enum cb_per_sym_type_id)
1056 * 0 - in case of success
1057 * -1 - in case of failure
1059 int32_t xran_reg_sym_cb(void *pHandle, xran_callback_sym_fn symCb, void * symCbParam, struct xran_sense_of_time* symCbTime, uint8_t symb, enum cb_per_sym_type_id cb_sym_t_id);
1065 * Function registers callback to XRAN layer. Function support callbacks align to OTA time. TTI even, half of slot,
1066 * full slot with respect to PTP time.
1069 * Pointer to XRAN layer handle for given CC
1071 * pointer to callback function
1073 * pointer to Callback Function parameters
1075 * number of calls to be skipped before first call
1076 * @param callback_to_phy_id
1077 * call back time identification (see enum callback_to_phy_id)
1080 * 0 - in case of success
1081 * -1 - in case of failure
1083 int32_t xran_reg_physide_cb(void *pHandle, xran_fh_tti_callback_fn Cb, void *cbParam, int skipTtiNum, enum callback_to_phy_id);
1088 * Function returns current TTI, Frame, Subframe, Slot Number as seen "Over air" base on PTP time
1091 * Pointer to Frame number [0-99]
1093 * @param nSubframeIdx
1094 * Pointer to Subframe number [0-10]
1097 * Pointer to Slot number [0-7]
1100 * Pointer to current UTC second
1103 * current TTI number [0-7999]
1105 int32_t xran_get_slot_idx (uint32_t PortId, uint32_t *nFrameIdx, uint32_t *nSubframeIdx, uint32_t *nSlotIdx, uint64_t *nSecond);
1110 * Function returns whether it is a prach slot or not based on given port and slot number
1115 * @param subframe_id
1116 * Subframe number [0-9]
1119 * Pointer to Slot number [0-7]
1122 * whether it is a prach slot or not
1124 int32_t xran_is_prach_slot(uint8_t PortId, uint32_t subframe_id, uint32_t slot_id);
1129 * Function retrun XRAN layer common counters for given handle
1132 * Pointer to XRAN layer handle for given CC
1135 * Pointer to pointer of common counter structure
1140 int32_t xran_get_common_counters(void *pXranLayerHandle, struct xran_common_counters *pStats);
1146 * Function returns status of operation of FH layer
1149 * XRAN_INIT - init state
1150 * XRAN_RUNNING - running
1151 * XRAN_STOPPED - stopped
1153 enum xran_if_state xran_get_if_state(void);
1159 * Function allocates memory of given size from heap
1165 * buf_len - size of memory allocation
1167 void* xran_malloc(size_t buf_len);
1172 * Function frees memory of given size from heap
1175 * addr - pointer to buffer
1180 void xran_free(void *addr);
1185 * Function calculates offset for ptr according to ORAN headers requared
1188 * pointer to be addjusted
1190 * compression method according to enum xran_compression_method
1193 * ptr - pointer to payload given header requared
1195 uint8_t* xran_add_hdr_offset(uint8_t *dst, int16_t compMethod);
1200 * Function calculates offset for ptr according to ORAN C-plane headers requared
1203 * pointer to be addjusted
1206 * ptr - pointer to payload given header requared
1208 uint8_t *xran_add_cp_hdr_offset(uint8_t *dst);
1213 * Debug function to trigger stop on 1pps (GPS second) boundary
1219 * enable auto stop after number of Tx packets
1223 int32_t xran_set_debug_stop(int32_t value, int32_t count);
1228 #endif /* _XRAN_FH_O_DU_H_*/