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 secoder */
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 */
260 /** XRAN category enum */
268 /** type of beamforming */
269 enum xran_beamforming_type
271 XRAN_BEAM_ID_BASED = 0, /**< beam index based */
272 XRAN_BEAM_WEIGHT, /**< beam forming weights */
273 XRAN_BEAM_ATTRIBUTE, /**< beam index based */
276 /** state of bbdev with xran */
279 XRAN_BBDEV_NOT_USED = -1, /**< BBDEV is disabled */
280 XRAN_BBDEV_MODE_HW_OFF = 0, /**< BBDEV is enabled for SW sim mode */
281 XRAN_BBDEV_MODE_HW_ON = 1, /**< BBDEV is enable for HW */
285 /** callback return information */
292 /** DPDK IO configuration for XRAN layer */
294 uint8_t id; /**< should be (0) for O-DU or (1) O-RU (debug) */
295 char *dpdk_dev[XRAN_VF_MAX]; /**< VFs devices */
296 char *bbdev_dev[1]; /**< BBDev dev name */
297 int32_t bbdev_mode; /**< DPDK for BBDev */
298 int32_t core; /**< reservd */
299 int32_t system_core; /**< reservd */
300 int32_t pkt_proc_core; /**< reservd */
301 int32_t pkt_aux_core; /**< reservd */
302 int32_t timing_core; /**< core used by xRAN */
303 int32_t port[XRAN_VF_MAX]; /**< VFs ports */
306 /** XRAN spec section 3.1.3.1.6 ecpriRtcid / ecpriPcid define */
307 struct xran_eaxcid_config {
308 uint16_t mask_cuPortId; /**< Mask CU PortId */
309 uint16_t mask_bandSectorId; /**< Mask Band */
310 uint16_t mask_ccId; /**< Mask CC */
311 uint16_t mask_ruPortId; /**< Mask RU Port ID */
313 uint8_t bit_cuPortId; /**< bandsectorId + ccId + ruportId */
314 uint8_t bit_bandSectorId; /**< ccId + ruPortId */
315 uint8_t bit_ccId; /**< ruportId */
316 uint8_t bit_ruPortId; /**< 0 */
320 * XRAN Front haul interface initialization settings
322 struct xran_fh_init {
323 struct xran_io_cfg io_cfg;/**< DPDK IO for XRAN */
324 struct xran_eaxcid_config eAxCId_conf; /**< config of ecpriRtcid/ecpriPcid */
326 uint32_t dpdkBasebandFecMode; /**< DPDK Baseband FEC device mode (0-SW, 1-HW) */
327 char *dpdkBasebandDevice; /**< DPDK Baseband device address */
328 char *filePrefix; /**< DPDK prefix */
330 uint32_t mtu; /**< maximum transmission unit (MTU) is the size of the largest protocol data unit (PDU) that can be communicated in a single
331 xRAN network layer transaction. supported 1500 bytes and 9600 bytes (Jumbo Frame) */
332 int8_t *p_o_du_addr; /**< O-DU Ethernet Mac Address */
333 int8_t *p_o_ru_addr; /**< O-RU Ethernet Mac Address */
335 uint16_t totalBfWeights;/**< The total number of beamforming weights on RU for extensions */
337 uint16_t Tadv_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
338 uint16_t T2a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
339 uint16_t T2a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
340 uint16_t T2a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
341 uint16_t T2a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
342 uint16_t T2a_min_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
343 uint16_t T2a_max_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
344 uint16_t Ta3_min; /**< Table 2 7 : xRAN Delay Management Model Parameters */
345 uint16_t Ta3_max; /**< Table 2 7 : xRAN Delay Management Model Parameters */
346 uint16_t T1a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
347 uint16_t T1a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
348 uint16_t T1a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
349 uint16_t T1a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
350 uint16_t T1a_min_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
351 uint16_t T1a_max_up; /**< Table 2 7 : xRAN Delay Management Model Parameters */
352 uint16_t Ta4_min; /**< Table 2 7 : xRAN Delay Management Model Parameters */
353 uint16_t Ta4_max; /**< Table 2 7 : xRAN Delay Management Model Parameters */
355 uint8_t enableCP; /**< enable C-plane */
356 uint8_t prachEnable; /**< enable PRACH */
357 uint8_t srsEnable; /**< enable SRS (Cat B specific) */
358 uint8_t cp_vlan_tag; /**< C-plane vlan tag */
359 uint8_t up_vlan_tag; /**< U-plane vlan tag */
360 int32_t debugStop; /**< enable auto stop */
361 int32_t debugStopCount; /**< enable auto stop after number of Tx packets */
362 int32_t DynamicSectionEna; /**< enable dynamic C-Plane section allocation */
363 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)
364 int32_t GPS_Beta; //beta value as defined in section 9.7.2 of ORAN spec. range -32767 ~ +32767
367 /** Beamforming waights for single stream for each PRBs given number of Antenna elements */
368 struct xran_cp_bf_weight{
369 int16_t nAntElmTRx; /**< num TRX for this allocation */
370 int8_t* p_ext_section; /**< pointer to form extType */
371 int16_t ext_section_sz; /**< extType section size */
373 struct xran_cp_bf_attribute{
376 struct xran_cp_bf_precoding{
380 /** section descriptor for given number of PRBs used on U-plane packet creation */
381 struct xran_section_desc {
382 uint16_t section_id; /**< section id used for this element */
384 int16_t iq_buffer_offset; /**< Offset in bytes for the content of IQs with in main symb buffer */
385 int16_t iq_buffer_len; /**< Length in bytes for the content of IQs with in main symb buffer */
387 uint8_t *pData; /**< optional pointer to data buffer */
388 void *pCtrl; /**< optional poitner to mbuf */
391 /** PRB element structure */
392 struct xran_prb_elm {
393 int16_t nRBStart; /**< start RB of RB allocation */
394 int16_t nRBSize; /**< number of RBs used */
395 int16_t nStartSymb; /**< start symbol ID */
396 int16_t numSymb; /**< number of symbols */
397 int16_t nBeamIndex; /**< beam index for given PRB */
398 int16_t bf_weight_update; /** need to update beam weights or not */
399 int16_t compMethod; /**< compression index for given PRB */
400 int16_t iqWidth; /**< compression bit width for given PRB */
401 int16_t BeamFormingType; /**< index based, weights based or attribute based beam forming*/
403 struct xran_section_desc * p_sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**< section desctiptors to U-plane data given RBs */
404 struct xran_cp_bf_weight bf_weight; /**< beam forming information relevant for given RBs */
407 struct xran_cp_bf_attribute bf_attribute;
408 struct xran_cp_bf_precoding bf_precoding;
412 /** PRB map structure */
413 struct xran_prb_map {
414 uint8_t dir; /**< DL or UL direction */
415 uint8_t xran_port; /**< xran id of given RU [0-(XRAN_PORTS_NUM-1)] */
416 uint16_t band_id; /**< xran band id */
417 uint16_t cc_id; /**< componnent carrier id [0 - (XRAN_MAX_SECTOR_NR-1)] */
418 uint16_t ru_port_id; /**< RU device antenna port id [0 - (XRAN_MAX_ANTENNA_NR-1) */
419 uint16_t tti_id; /**< xRAN slot id [0 - (max tti-1)] */
420 uint8_t start_sym_id; /**< start symbol Id [0-13] */
421 uint32_t nPrbElm; /**< total number of PRB elements for given map [0- (XRAN_MAX_PRBS-1)] */
422 struct xran_prb_elm prbMap[XRAN_MAX_PRBS];
427 /* PRACH config required for XRAN based FH */
428 struct xran_prach_config
431 uint8_t nPrachConfIdx; /**< PRACH Configuration Index*/
432 uint8_t nPrachSubcSpacing;
433 /**< PRACH Sub-carrier spacing
435 For below 6GHz the values indicate 15kHz or 30kHz
436 For above 6GHz the values indicate 60kHz or 120kHz*/
437 uint8_t nPrachZeroCorrConf; /**< PRACH zeroCorrelationZoneConfig */
438 uint8_t nPrachRestrictSet; /**< PRACH restrictedSetConfig */
439 uint16_t nPrachRootSeqIdx; /**< PRACH Root Sequence Index */
440 uint16_t nPrachFreqStart; /**< PRACH prach-frequency-start */
441 int32_t nPrachFreqOffset; /**< PRACH prach-frequency-offset */
442 uint8_t nPrachFilterIdx; /**< PRACH Filter index */
445 /**< SRS configuration required for XRAN based FH */
446 struct xran_srs_config {
447 uint16_t symbMask; /**< symbols used for SRS with in U/S slot [bits 0-13] */
448 uint8_t eAxC_offset; /**< starting value of eAxC for SRS packets */
451 /** XRAN slot configuration */
452 struct xran_slot_config {
453 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 */
457 /** XRAN front haul frame config */
458 struct xran_frame_config {
459 uint8_t nFrameDuplexType; /**< Frame Duplex type: 0 -> FDD, 1 -> TDD */
460 uint8_t nNumerology; /**< Numerology, determine sub carrier spacing, Value: 0->4
461 0: 15khz, 1: 30khz, 2: 60khz
462 3: 120khz, 4: 240khz */
463 uint8_t nTddPeriod; /**< TDD period */
464 struct xran_slot_config sSlotConfig[XRAN_MAX_TDD_PERIODICITY];
465 /**< TDD Slot configuration - If nFrameDuplexType = TDD(1), then this config defines the slot config type for each slot.*/
466 /* The number of slots need to be equal to nTddPeriod */
469 /** XRAN-PHY interface byte order */
470 enum xran_input_byte_order {
471 XRAN_NE_BE_BYTE_ORDER = 0, /**< Network byte order (Big endian), xRAN lib doesn't do swap */
472 XRAN_CPU_LE_BYTE_ORDER /**< CPU byte order (Little endian), xRAN lib does do swap */
475 /** XRAN-PHY interface I and Q order */
476 enum xran_input_i_q_order {
477 XRAN_I_Q_ORDER = 0, /**< I , Q */
478 XRAN_Q_I_ORDER /**< Q , I */
481 /** XRAN front haul IQ compression settings */
482 struct xran_ru_config {
483 enum xran_category xranCat; /**< mode: Catergory A or Category B */
485 uint8_t iqWidth; /**< IQ bit width */
486 uint8_t compMeth; /**< Compression method */
487 uint8_t fftSize; /**< FFT Size */
488 enum xran_input_byte_order byteOrder; /**< Order of bytes in int16_t in buffer. Big or little endian */
489 enum xran_input_i_q_order iqOrder; /**< order of IQs in the buffer */
490 uint16_t xran_max_frame; /**< max frame number supported */
495 * XRAN front haul general configuration */
496 struct xran_fh_config {
497 uint32_t dpdk_port; /**< DPDK port number used for FH */
498 uint32_t sector_id; /**< Band sector ID for FH */
499 uint32_t nCC; /**< number of Component carriers supported on FH */
500 uint32_t neAxc; /**< number of eAxc supported on one CC*/
501 uint32_t neAxcUl; /**< number of eAxc supported on one CC for UL direction */
502 uint32_t nAntElmTRx; /**< Number of antenna elements for TX and RX */
503 uint16_t nDLFftSize; /**< DL FFT size */
504 uint16_t nULFftSize; /**< UL FFT size */
505 uint16_t nDLRBs; /**< DL PRB */
506 uint16_t nULRBs; /**< UL PRB */
507 uint32_t nDLAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
508 uint32_t nULAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
509 uint32_t nDLCenterFreqARFCN; /**< center frerquency for DL in MHz */
510 uint32_t nULCenterFreqARFCN; /**< center frerquency for UL in MHz */
511 xran_fh_tti_callback_fn ttiCb; /**< call back for TTI event */
512 void *ttiCbParam; /**< parameters of call back function */
514 struct xran_prach_config prach_conf; /**< PRACH specific configurations for FH */
515 struct xran_srs_config srs_conf; /**< SRS specific configurations for FH */
516 struct xran_frame_config frame_conf; /**< frame config */
517 struct xran_ru_config ru_conf; /**< config of RU as per XRAN spec */
519 phy_encoder_poll_fn bbdev_enc; /**< call back to poll BBDev encoder */
520 phy_decoder_poll_fn bbdev_dec; /**< call back to poll BBDev decoder */
522 uint32_t log_level; /**< configuration of log level */
527 * XRAN front haul statistic counters according to Table 7 1 : Common Counters for both DL and UL */
528 struct xran_common_counters{
529 uint64_t Rx_on_time; /**< Data was received on time (applies to user data reception window) */
530 uint64_t Rx_early; /**< Data was received too early (applies to user data reception window) */
531 uint64_t Rx_late; /**< Data was received too late (applies to user data reception window) */
532 uint64_t Rx_corrupt; /**< Corrupt/Incorrect header packet */
533 uint64_t Rx_pkt_dupl; /**< Duplicated packet */
534 uint64_t Total_msgs_rcvd; /**< Total messages received (on all links) */
539 * CC instance handle pointer type */
540 typedef void * xran_cc_handle_t;
543 *****************************************************************************
547 * A flat buffer structure. The data pointer, pData, is a virtual address.
548 * The API requires the memory to by physically contiguous. Each flat
549 * buffer segment may contain several equally sized elements.
551 *****************************************************************************/
552 struct xran_flat_buffer
554 uint32_t nElementLenInBytes;
555 /**< The Element length specified in bytes.
556 * This parameter specifies the size of a single element in the buffer.
557 * The total size of the buffer is described as
558 * bufferSize = nElementLenInBytes * nNumberOfElements */
559 uint32_t nNumberOfElements;
560 /**< The number of elements in the physical contiguous memory segment */
561 uint32_t nOffsetInBytes;
562 /**< Offset in bytes to the start of the data in the physical contiguous
566 /**< The data pointer is a virtual address, however the actual data pointed
567 * to is required to be in contiguous physical memory unless the field
568 requiresPhysicallyContiguousMemory in CpaInstanceInfo is false. */
570 /**< pointer to control section coresponding to data buffer */
574 *****************************************************************************
576 * Scatter/Gather buffer list containing an array of Simple buffers.
579 * A Scatter/Gather buffer list structure. It is expected that this buffer
580 * structure will be used where more than one flat buffer can be provided
581 * on a particular API.
583 * IMPORTANT - The memory for the pPrivateMetaData member must be allocated
584 * by the client as contiguous memory. When allocating memory for
585 * pPrivateMetaData a call to cpaCyBufferListGetMetaSize MUST be made to
586 * determine the size of the Meta Data Buffer. The returned size
587 * (in bytes) may then be passed in a memory allocation routine to allocate
588 * the pPrivateMetaData memory.
590 *****************************************************************************/
591 struct xran_buffer_list
593 uint32_t nNumBuffers;
594 /**< Number of pointers */
595 struct xran_flat_buffer *pBuffers;
596 /**< Pointer to an unbounded array containing the number of CpaFlatBuffers
597 * defined by nNumBuffers */
599 /**< This is an opaque field that is not read or modified internally. */
600 void *pPrivateMetaData;
601 /**< Private Meta representation of this buffer List - the memory for this
602 * buffer needs to be allocated by the client as contiguous data.
603 * The amount of memory required is returned with a call to
604 * cpaCyBufferListGetMetaSize. If cpaCyBufferListGetMetaSize returns a size
605 * of zero no memory needs to be allocated, and this parameter can be NULL.
611 * Initialize the XRAN Layer via DPDK.
614 * A non-negative value. If it is greater than 0, the array members
615 * for argv[0] through argv[argc] (non-inclusive) shall contain pointers
618 * An array of strings. The contents of the array, as well as the strings
619 * which are pointed to by the array, may be modified by this function.
623 * Error codes returned via rte_errno
625 int32_t xran_init(int argc, char *argv[], struct xran_fh_init *p_xran_fh_init, char *appName, void ** pHandle);
630 * Function returns handles for number of sectors supported by XRAN layer. Currently function
631 * supports one handle XRAN layer where it supports only one CC
634 * Pointer to XRAN layer handle
635 * @param nNumInstances
636 * total number of instances of CC
637 * @param pSectorInstanceHandles
638 * Pointer to xran_cc_handle_t where to store Handle pointer
643 int32_t xran_sector_get_instances (void * pHandle, uint16_t nNumInstances,
644 xran_cc_handle_t * pSectorInstanceHandles);
649 * Function initialize Memory Management subsystem (mm) in order to handle memory buffers between XRAN layer
653 * Pointer to XRAN layer handle for given CC
655 * memory size of all segments
656 * @param nMemorySegmentSize
657 * size of memory per segment
662 int32_t xran_mm_init (void * pHandle, uint64_t nMemorySize, uint32_t nMemorySegmentSize);
667 * Function allocates buffer memory (bm) used between XRAN layer and PHY. In general case it's DPDK mbuf.
668 * it uses Memory Management system to get memory chunk and define memory pool on top of it.
671 * Pointer to XRAN layer handle for given CC
673 * pointer to buffer pool identification to be returned
674 * @param nNumberOfBuffers
675 * number of buffer to allocate in the pool
677 * buffer size to allocate
682 int32_t xran_bm_init (void * pHandle, uint32_t * pPoolIndex, uint32_t nNumberOfBuffers, uint32_t nBufferSize);
687 * Function allocates buffer used between XRAN layer and PHY. In general case it's DPDK mbuf.
690 * Pointer to XRAN layer handle for given CC
692 * buffer pool identification
694 * Pointer to pointer where to store address of new buffer
696 * Pointer to pointer where to store address of internal private control information
702 int32_t xran_bm_allocate_buffer(void * pHandle, uint32_t nPoolIndex, void **ppData, void **ppCtrl);
707 * Function frees buffer used between XRAN layer and PHY. In general case it's DPDK mbuf
710 * Pointer to XRAN layer handle for given CC
714 * Pointer to internal private control information
719 int32_t xran_bm_free_buffer(void * pHandle, void *pData, void *pCtrl);
724 * Function destroys Memory Management (MM) layer of XRAN library
727 * Pointer to XRAN layer handle for given CC
732 int32_t xran_mm_destroy (void * pHandle);
737 * Function configures TX(DL) and RX(UL) output buffers and callback (UL only) for XRAN layer with
741 * Pointer to XRAN layer handle for given CC
743 * list of memory buffers to use to fetch IQs from PHY to XRAN layer (DL)
744 * @param pSrcCpBuffer
745 * list of memory buffers to use to configure C-plane (DL)
747 * list of memory buffers to use to deliver IQs from XRAN layer to PHY (UL)
748 * @param pDstCpBuffer
749 * list of memory buffers to use to configure C-plane (UL)
750 * @param xran_transport_callback_fn pCallback
751 * Callback function to call with arrival of all packets for given CC for given symbol
752 * @param pCallbackTag
753 * Parameters of Callback function
759 int32_t xran_5g_fronthault_config (void * pHandle,
760 struct xran_buffer_list *pSrcBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
761 struct xran_buffer_list *pSrcCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
762 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
763 struct xran_buffer_list *pDstCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
764 xran_transport_callback_fn pCallback,
770 * Function configures PRACH output buffers and callback for XRAN layer with given handle
773 * Pointer to XRAN layer handle for given CC
775 * list of memory buffers to use to deliver PRACH IQs from xran layer to PHY
776 * @param xran_transport_callback_fn pCallback
777 * Callback function to call with arrival of PRACH packets for given CC
778 * @param pCallbackTag
779 * Parameters of Callback function
785 int32_t xran_5g_prach_req (void * pHandle,
786 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
787 xran_transport_callback_fn pCallback,
793 * Function configures SRS output buffers and callback for XRAN layer with given handle
796 * Pointer to XRAN layer handle for given CC
798 * list of memory buffers to use to deliver SRS IQs from xran layer to PHY
799 * @param xran_transport_callback_fn pCallback
800 * Callback function to call with arrival of SRS packets for given CC
801 * @param pCallbackTag
802 * Parameters of Callback function
808 int32_t xran_5g_srs_req (void * pHandle,
809 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_N_FE_BUF_LEN],
810 xran_transport_callback_fn pCallback,
817 * Function returns XRAN core utilization stats
819 * @param total_time (out)
820 * Pointer to variable to store Total time thread has been running
821 * @param used_time (out)
822 * Pointer to variable to store Total time essential tasks have been running on the thread
823 * @param core_used (out)
824 * Pointer to variable to store Core on which the XRAN thread is running
826 * If set to 1, then internal variables total_time and used_time are cleared
831 uint32_t xran_get_time_stats(uint64_t *total_time, uint64_t *used_time, uint32_t *core_used, uint32_t clear);
836 * Function opens XRAN layer with given handle
839 * Pointer to XRAN layer handle for given CC
840 * @param pointer to struct xran_fh_config pConf
841 * Pointer to XRAN configuration structure with specific settings to use
846 int32_t xran_open(void *pHandle, struct xran_fh_config* pConf);
851 * Function starts XRAN layer with given handle
854 * Pointer to XRAN layer handle for given CC
859 int32_t xran_start(void *pHandle);
864 * Function stops XRAN layer with given handle
867 * Pointer to XRAN layer handle for given CC
872 int32_t xran_stop(void *pHandle);
877 * Function closes XRAN layer with given handle
880 * Pointer to XRAN layer handle for given CC
885 int32_t xran_close(void *pHandle);
890 * Function registers callback to XRAN layer. Function support callbacks aligned on packet arrival.
893 * Pointer to XRAN layer handle for given CC
895 * pointer to callback function
897 * pointer to Callback Function parameters
899 * symbol to be register for
901 * Antenna number to trigger callback for packet arrival
904 * 0 - in case of success
905 * -1 - in case of failure
907 int32_t xran_reg_sym_cb(void *pHandle, xran_callback_sym_fn symCb, void * symCbParam, uint8_t symb, uint8_t ant);
912 * Function registers callback to XRAN layer. Function support callbacks align to OTA time. TTI even, half of slot,
913 * full slot with respect to PTP time.
916 * Pointer to XRAN layer handle for given CC
918 * pointer to callback function
920 * pointer to Callback Function parameters
922 * number of calls to be skipped before first call
923 * @param callback_to_phy_id
924 * call back time identification (see enum callback_to_phy_id)
927 * 0 - in case of success
928 * -1 - in case of failure
930 int32_t xran_reg_physide_cb(void *pHandle, xran_fh_tti_callback_fn Cb, void *cbParam, int skipTtiNum, enum callback_to_phy_id);
935 * Function returns current TTI, Frame, Subframe, Slot Number as seen "Over air" base on PTP time
938 * Pointer to Frame number [0-99]
940 * @param nSubframeIdx
941 * Pointer to Subframe number [0-10]
944 * Pointer to Slot number [0-7]
947 * Pointer to current UTC second
950 * current TTI number [0-7999]
952 int32_t xran_get_slot_idx (uint32_t *nFrameIdx, uint32_t *nSubframeIdx, uint32_t *nSlotIdx, uint64_t *nSecond);
957 * Function retrun XRAN layer common counters for given handle
960 * Pointer to XRAN layer handle for given CC
963 * Pointer to pointer of common counter structure
968 int32_t xran_get_common_counters(void *pXranLayerHandle, struct xran_common_counters *pStats);
974 * Function returns status of operation of FH layer
977 * XRAN_INIT - init state
978 * XRAN_RUNNING - running
979 * XRAN_STOPPED - stopped
981 enum xran_if_state xran_get_if_state(void);
987 * Function allocates memory of given size from heap
993 * ptr - to memory buffer or NULL
995 void* xran_malloc(size_t buf_len);
1001 * Function calculates offset for ptr according to ORAN headers requared
1004 * pointer to be addjusted
1006 * compression method according to enum xran_compression_method
1009 * ptr - pointer to payload given header requared
1011 uint8_t* xran_add_hdr_offset(uint8_t *dst, int16_t compMethod);
1017 #endif /* _XRAN_FH_O_DU_H_*/