fhi_lib/lib/api/xran_fh_o_du.h

   1 /******************************************************************************
   2 *
   3 *   Copyright (c) 2019 Intel.
   4 *
   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
   8 *
   9 *       http://www.apache.org/licenses/LICENSE-2.0
  10 *
  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.
  16 *
  17 *******************************************************************************/
  18
  19 /**
  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
  25  *
  26  * @file xran_fh_o_du.h
  27  * @ingroup group_lte_source_xran
  28  * @author Intel Corporation
  29  *
  30  **/
  31
  32 #ifndef _XRAN_FH_O_DU_H_
  33 #define _XRAN_FH_O_DU_H_
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 #include <stdio.h>
  40 #include <stdlib.h>
  41 #include <string.h>
  42 #include <stdint.h>
  43 #include <inttypes.h>
  44 #include <sys/types.h>
  45 #include <sys/queue.h>
  46 #include <netinet/in.h>
  47 #include <setjmp.h>
  48 #include <stdarg.h>
  49 #include <ctype.h>
  50 #include <errno.h>
  51 #include <getopt.h>
  52 #include <unistd.h>
  53
  54 #define XRAN_STATUS_SUCCESS (0)
  55 /**<
  56  *  @ingroup xran
  57  *   Success status value. */
  58 #define XRAN_STATUS_FAIL (-1)
  59 /**<
  60  *  @ingroup xran
  61  *   Fail status value. */
  62
  63 #define XRAN_STATUS_RETRY (-2)
  64 /**<
  65  *  @ingroup xran
  66  *  Retry status value. */
  67
  68 #define XRAN_STATUS_RESOURCE (-3)
  69 /**<
  70  *  @ingroup xran
  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. */
  74
  75 #define XRAN_STATUS_INVALID_PARAM (-4)
  76 /**<
  77  *  @ingroup xran
  78  *  Invalid parameter has been passed in. */
  79 #define XRAN_STATUS_FATAL (-5)
  80 /**<
  81  *  @ingroup xran
  82  *  A serious error has occurred. Recommended course of action
  83  *  is to shutdown and restart the component. */
  84
  85 #define XRAN_STATUS_UNSUPPORTED (-6)
  86 /**<
  87  *  @ingroup xran
  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. */
  91
  92 #define XRAN_STATUS_INVALID_PACKET (-7)
  93 /**<
  94  *  @ingroup xran
  95  *  Recevied packet does not have correct format. */
  96
  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))
 107
 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 */
 113
 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 */
 118
 119
 120
 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
 129 #define XRAN_MAX_SECTIONS_PER_SYM    (16)  /**< Max number of different sections in single symbol (section is equal to RB allocation for UE) */
 130
 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 */
 133
 134 #define XRAN_STRICT_PARM_CHECK               (1) /**< enable parameter check for C-plane */
 135
 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 */
 143
 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 */
 149
 150 #define XRAN_NUM_OF_SLOT_IN_TDD_LOOP         (80)/**< MAX number of slot for TDD repetition */
 151
 152 //#define _XRAN_DEBUG   /**< Enable debug log */
 153 //#define _XRAN_VERBOSE /**< Enable verbose log */
 154
 155 #ifdef _XRAN_DEBUG
 156     #define xran_log_dbg(fmt, ...)          \
 157         fprintf(stderr,                     \
 158             "DEBUG: %s(%d): " fmt "\n",     \
 159             __FILE__,                       \
 160             __LINE__, ##__VA_ARGS__)
 161 #else
 162     #define xran_log_dbg(fmt, ...)
 163 #endif
 164
 165 #if defined(_XRAN_DEBUG) || defined(_XRAN_VERBOSE)
 166     #define xran_log_wrn(fmt, ...)          \
 167         fprintf(                            \
 168             stderr,                         \
 169             "WARNING: %s(%d): " fmt "\n",   \
 170             __FILE__,                       \
 171             __LINE__, ##__VA_ARGS__)
 172 #else
 173     #define xran_log_dbg(fmt, ...)
 174     #define xran_log_wrn(fmt, ...)
 175 #endif
 176
 177 #define xran_log_err(fmt, ...)          \
 178     fprintf(stderr,                     \
 179         "ERROR: %s(%d): " fmt "\n",     \
 180         __FILE__,                       \
 181         __LINE__, ##__VA_ARGS__)
 182
 183 enum XranFrameDuplexType
 184 {
 185     XRAN_FDD = 0, XRAN_TDD
 186 };
 187
 188 enum xran_if_state
 189 {
 190     XRAN_INIT = 0,
 191     XRAN_RUNNING,
 192     XRAN_STOPPED
 193 };
 194
 195 /**
 196  ******************************************************************************
 197  * @ingroup xran
 198  *
 199  * @description
 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,
 208     XRAN_COMPMETHOD_MAX
 209 };
 210
 211 /**
 212  ******************************************************************************
 213  * @ingroup xran
 214  *
 215  * @description
 216  *      Callback function type for symbol packet enum
 217  *****************************************************************************/
 218 enum callback_to_phy_id
 219 {
 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 */
 224 };
 225
 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,
 230     XRAN_BF_T_TIME      = 1,
 231     XRAN_BF_T_HYBRID    = 2,
 232     XRAN_BF_T_MAX
 233 };
 234
 235 typedef int32_t xran_status_t; /**< Xran status return value */
 236
 237 /** callback function type for Symbol packet */
 238 typedef void (*xran_callback_sym_fn)(void*);
 239
 240 /** Callback function type for TTI event */
 241 typedef int (*xran_fh_tti_callback_fn)(void*);
 242
 243 /** Callback function type packet arrival from transport layer (ETH or IP) */
 244 typedef void (*xran_transport_callback_fn)(void*, xran_status_t);
 245
 246 /** Callback functions to poll BBdev encoder */
 247 typedef int16_t (*phy_encoder_poll_fn)(void);
 248
 249 /** Callback functions to poll BBdev secoder */
 250 typedef int16_t (*phy_decoder_poll_fn)(void);
 251
 252 /** XRAN port enum */
 253 enum xran_vf_ports
 254 {
 255     XRAN_UP_VF = 0, /**< port type for U-plane */
 256     XRAN_CP_VF,     /**< port type for C-plane */
 257     XRAN_VF_MAX
 258 };
 259
 260 /** XRAN category enum */
 261 enum xran_category
 262 {
 263     XRAN_CATEGORY_A = 0,
 264     XRAN_CATEGORY_B = 1,
 265     XRAN_CATEGORY_MAX
 266 };
 267
 268 /** type of beamforming */
 269 enum xran_beamforming_type
 270 {
 271     XRAN_BEAM_ID_BASED = 0, /**< beam index based */
 272     XRAN_BEAM_WEIGHT,       /**< beam forming weights */
 273     XRAN_BEAM_ATTRIBUTE,    /**< beam index based */
 274 };
 275
 276 /** state of bbdev with xran */
 277 enum xran_bbdev_init
 278 {
 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 */
 282     XRAN_BBDEV_MODE_MAX
 283 };
 284
 285 /** callback return information */
 286 struct xran_cb_tag {
 287     uint16_t cellId;
 288     uint32_t symbol;
 289     uint32_t slotiId;
 290 };
 291
 292 /** DPDK IO configuration for XRAN layer */
 293 struct xran_io_cfg {
 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 */
 304 };
 305
 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 */
 312
 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 */
 317 };
 318
 319 /**
 320 * XRAN Front haul interface initialization settings
 321 */
 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 */
 325
 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 */
 329
 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 */
 334
 335     uint16_t totalBfWeights;/**< The total number of beamforming weights on RU for extensions */
 336
 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 */
 354
 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
 365 };
 366
 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 */
 372 };
 373 struct xran_cp_bf_attribute{
 374     int16_t weight[4];
 375 };
 376 struct xran_cp_bf_precoding{
 377     int16_t weight[4];
 378 };
 379
 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 */
 383
 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 */
 386
 387     uint8_t *pData;      /**< optional pointer to data buffer */
 388     void    *pCtrl;      /**< optional poitner to mbuf */
 389 };
 390
 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*/
 402
 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 */
 405
 406     union {
 407         struct xran_cp_bf_attribute bf_attribute;
 408         struct xran_cp_bf_precoding bf_precoding;
 409     };
 410 };
 411
 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];
 423
 424
 425 };
 426
 427 /* PRACH config required for XRAN based FH */
 428 struct xran_prach_config
 429 {
 430     /* PRACH config*/
 431     uint8_t      nPrachConfIdx;  /**< PRACH Configuration Index*/
 432     uint8_t      nPrachSubcSpacing;
 433     /**< PRACH Sub-carrier spacing
 434     Value:0->1
 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 */
 443 };
 444
 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 */
 449 };
 450
 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 */
 454     uint8_t reserved[2];
 455 };
 456
 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 */
 467 };
 468
 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 */
 473 };
 474
 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 */
 479 };
 480
 481 /** XRAN front haul IQ compression settings */
 482 struct xran_ru_config {
 483     enum xran_category xranCat;   /**< mode: Catergory A or Category B */
 484
 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 */
 491 };
 492
 493 /**
 494  * @ingroup xran
 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 */
 513
 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 */
 518
 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 */
 521
 522     uint32_t log_level; /**< configuration of log level */
 523 };
 524
 525 /**
 526  * @ingroup xran
 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) */
 535 };
 536
 537 /**
 538  * @ingroup xran
 539  * CC instance handle pointer type */
 540 typedef void * xran_cc_handle_t;
 541
 542 /**
 543  *****************************************************************************
 544  * @ingroup xran
 545  *
 546  * @description
 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.
 550  *
 551  *****************************************************************************/
 552 struct xran_flat_buffer
 553 {
 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
 563      * memory segment */
 564     uint32_t nIsPhyAddr;
 565     uint8_t *pData;
 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. */
 569     void *pCtrl;
 570     /**< pointer to control section coresponding to data buffer */
 571 };
 572
 573 /**
 574  *****************************************************************************
 575  * @ingroup xran
 576  *      Scatter/Gather buffer list containing an array of Simple buffers.
 577  *
 578  * @description
 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.
 582  *
 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.
 589  *
 590  *****************************************************************************/
 591 struct xran_buffer_list
 592 {
 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 */
 598     void *pUserData;
 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.
 606      */
 607 };
 608
 609 /**
 610  * @ingroup xran
 611  * Initialize the XRAN Layer via DPDK.
 612  *
 613  * @param argc
 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
 616  *   to strings.
 617  * @param argv
 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.
 620  *
 621  * @return
 622  *   0 - on success
 623  *   Error codes returned via rte_errno
 624  */
 625 int32_t xran_init(int argc, char *argv[], struct xran_fh_init *p_xran_fh_init, char *appName, void ** pHandle);
 626
 627 /**
 628  * @ingroup xran
 629  *
 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
 632  *
 633  * @param pHandle
 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
 639  *
 640  * @return
 641  *   0 - on success
 642  */
 643 int32_t xran_sector_get_instances (void * pHandle, uint16_t nNumInstances,
 644                xran_cc_handle_t * pSectorInstanceHandles);
 645
 646 /**
 647  * @ingroup xran
 648  *
 649  *   Function initialize Memory Management subsystem (mm) in order to handle memory buffers between XRAN layer
 650  *   and PHY.
 651  *
 652  * @param pHandle
 653  *   Pointer to XRAN layer handle for given CC
 654  * @param nMemorySize
 655  *   memory size of all segments
 656  * @param nMemorySegmentSize
 657  *   size of memory per segment
 658  *
 659  * @return
 660  *   0 - on success
 661  */
 662 int32_t xran_mm_init (void * pHandle, uint64_t nMemorySize, uint32_t nMemorySegmentSize);
 663
 664 /**
 665  * @ingroup xran
 666  *
 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.
 669  *
 670  * @param pHandle
 671  *   Pointer to XRAN layer handle for given CC
 672  * @param nPoolIndex
 673  *   pointer to buffer pool identification to be returned
 674  * @param nNumberOfBuffers
 675  *   number of buffer to allocate in the pool
 676  * @param nBufferSize
 677  *   buffer size to allocate
 678  *
 679  * @return
 680  *   0 - on success
 681  */
 682 int32_t xran_bm_init (void * pHandle, uint32_t * pPoolIndex, uint32_t nNumberOfBuffers, uint32_t nBufferSize);
 683
 684 /**
 685  * @ingroup xran
 686  *
 687  *   Function allocates buffer used between XRAN layer and PHY. In general case it's DPDK mbuf.
 688  *
 689  * @param pHandle
 690  *   Pointer to XRAN layer handle for given CC
 691  * @param nPoolIndex
 692  *   buffer pool identification
 693  * @param ppData
 694  *   Pointer to pointer where to store address of new buffer
 695  * @param ppCtrl
 696  *   Pointer to pointer where to store address of internal private control information
 697  *
 698  *
 699  * @return
 700  *   0 - on success
 701  */
 702 int32_t xran_bm_allocate_buffer(void * pHandle, uint32_t nPoolIndex, void **ppData,  void **ppCtrl);
 703
 704 /**
 705  * @ingroup xran
 706  *
 707  *   Function frees buffer used between XRAN layer and PHY. In general case it's DPDK mbuf
 708  *
 709  * @param pHandle
 710  *   Pointer to XRAN layer handle for given CC
 711  * @param pData
 712  *   Pointer to buffer
 713  * @param pData
 714  *   Pointer to internal private control information
 715  *
 716  * @return
 717  *   0 - on success
 718  */
 719 int32_t xran_bm_free_buffer(void * pHandle, void *pData, void *pCtrl);
 720
 721 /**
 722  * @ingroup xran
 723  *
 724  *   Function destroys Memory Management (MM) layer of XRAN library
 725  *
 726  * @param pHandle
 727  *   Pointer to XRAN layer handle for given CC
 728  *
 729  * @return
 730  *   0 - on success
 731  */
 732 int32_t xran_mm_destroy (void * pHandle);
 733
 734 /**
 735  * @ingroup xran
 736  *
 737  *   Function configures TX(DL) and RX(UL) output buffers and callback (UL only) for XRAN layer with
 738  *   given handle
 739  *
 740  * @param pHandle
 741  *   Pointer to XRAN layer handle for given CC
 742  * @param pSrcBuffer
 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)
 746  * @param pDstBuffer
 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
 754  *
 755  * @return
 756  *   0  - on success
 757  *   -1 - on error
 758  */
 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,
 765                     void *pCallbackTag);
 766
 767 /**
 768  * @ingroup xran
 769  *
 770  *   Function configures PRACH output buffers and callback for XRAN layer with given handle
 771  *
 772  * @param pHandle
 773  *   Pointer to XRAN layer handle for given CC
 774  * @param pDstBuffer
 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
 780  *
 781  * @return
 782  *   0  - on success
 783  *   -1 - on error
 784  */
 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,
 788                 void *pCallbackTag);
 789
 790 /**
 791  * @ingroup xran
 792  *
 793  *   Function configures SRS output buffers and callback for XRAN layer with given handle
 794  *
 795  * @param pHandle
 796  *   Pointer to XRAN layer handle for given CC
 797  * @param pDstBuffer
 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
 803  *
 804  * @return
 805  *   0  - on success
 806  *   -1 - on error
 807  */
 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,
 811                 void *pCallbackTag);
 812
 813
 814 /**
 815  * @ingroup xran
 816  *
 817  *   Function returns XRAN core utilization stats
 818  *
 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
 825  * @param clear (in)
 826  *   If set to 1, then internal variables total_time and used_time are cleared
 827  *
 828  * @return
 829  *   0 - on success
 830  */
 831 uint32_t xran_get_time_stats(uint64_t *total_time, uint64_t *used_time, uint32_t *core_used, uint32_t clear);
 832
 833 /**
 834  * @ingroup xran
 835  *
 836  *   Function opens XRAN layer with given handle
 837  *
 838  * @param pHandle
 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
 842  *
 843  * @return
 844  *   0 - on success
 845  */
 846 int32_t xran_open(void *pHandle, struct xran_fh_config* pConf);
 847
 848 /**
 849  * @ingroup xran
 850  *
 851  *   Function starts XRAN layer with given handle
 852  *
 853  * @param pHandle
 854  *   Pointer to XRAN layer handle for given CC
 855  *
 856  * @return
 857  *   0 - on success
 858  */
 859 int32_t xran_start(void *pHandle);
 860
 861 /**
 862  * @ingroup xran
 863  *
 864  *   Function stops XRAN layer with given handle
 865  *
 866  * @param pHandle
 867  *   Pointer to XRAN layer handle for given CC
 868  *
 869  * @return
 870  *   0 - on success
 871  */
 872 int32_t xran_stop(void *pHandle);
 873
 874 /**
 875  * @ingroup xran
 876  *
 877  *   Function closes XRAN layer with given handle
 878  *
 879  * @param pHandle
 880  *   Pointer to XRAN layer handle for given CC
 881  *
 882  * @return
 883  *   0 - on success
 884  */
 885 int32_t xran_close(void *pHandle);
 886
 887 /**
 888  * @ingroup xran
 889  *
 890  *   Function registers callback to XRAN layer. Function support callbacks aligned on packet arrival.
 891  *
 892  * @param pHandle
 893  *   Pointer to XRAN layer handle for given CC
 894  * @param symCb
 895  *   pointer to callback function
 896  * @param symCb
 897  *   pointer to Callback Function parameters
 898  * @param symb
 899  *   symbol to be register for
 900  * @param ant
 901  *   Antenna number to trigger callback for packet arrival
 902  *
 903  * @return
 904  *    0 - in case of success
 905  *   -1 - in case of failure
 906  */
 907 int32_t xran_reg_sym_cb(void *pHandle, xran_callback_sym_fn symCb, void * symCbParam, uint8_t symb, uint8_t ant);
 908
 909 /**
 910  * @ingroup xran
 911  *
 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.
 914  *
 915  * @param pHandle
 916  *   Pointer to XRAN layer handle for given CC
 917  * @param Cb
 918  *   pointer to callback function
 919  * @param cbParam
 920  *   pointer to Callback Function parameters
 921  * @param skipTtiNum
 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)
 925  *
 926  * @return
 927  *    0 - in case of success
 928  *   -1 - in case of failure
 929  */
 930 int32_t xran_reg_physide_cb(void *pHandle, xran_fh_tti_callback_fn Cb, void *cbParam, int skipTtiNum, enum callback_to_phy_id);
 931
 932 /**
 933  * @ingroup xran
 934  *
 935  *   Function returns current TTI, Frame, Subframe, Slot Number as seen "Over air" base on PTP time
 936  *
 937  * @param nFrameIdx
 938  *    Pointer to Frame number [0-99]
 939  *
 940  * @param nSubframeIdx
 941  *    Pointer to Subframe number [0-10]
 942  *
 943  * @param nSlotIdx
 944  *    Pointer to Slot number [0-7]
 945  *
 946  * @param nSecond
 947  *    Pointer to current UTC second
 948  *
 949  * @return
 950  *   current TTI number [0-7999]
 951  */
 952 int32_t xran_get_slot_idx (uint32_t *nFrameIdx, uint32_t *nSubframeIdx,  uint32_t *nSlotIdx, uint64_t *nSecond);
 953
 954 /**
 955  * @ingroup xran
 956  *
 957  *   Function retrun XRAN layer common counters for given handle
 958  *
 959  * @param pHandle
 960  *   Pointer to XRAN layer handle for given CC
 961  *
 962  * @param pStats
 963  *   Pointer to pointer of common counter structure
 964  *
 965  * @return
 966  *   0 - on success
 967  */
 968 int32_t xran_get_common_counters(void *pXranLayerHandle, struct xran_common_counters *pStats);
 969
 970
 971 /**
 972  * @ingroup xran
 973  *
 974  *   Function returns status of operation of FH layer
 975  *
 976  * @return
 977  *  XRAN_INIT    - init state
 978  *  XRAN_RUNNING - running
 979  *  XRAN_STOPPED - stopped
 980  */
 981 enum xran_if_state xran_get_if_state(void);
 982
 983
 984 /**
 985  * @ingroup xran
 986  *
 987  *   Function allocates memory of given size from heap
 988  *
 989  * @param buf_len
 990  *   buffer size
 991  *
 992  * @return
 993  *   ptr - to memory buffer or NULL
 994  */
 995 void*    xran_malloc(size_t buf_len);
 996
 997
 998 /**
 999  * @ingroup xran
1000  *
1001  *   Function calculates offset for ptr according to ORAN headers requared
1002  *
1003  * @param dst
1004  *   pointer to be addjusted
1005  * @compMethod
1006  *   compression method according to enum xran_compression_method
1007  *
1008  * @return
1009  *   ptr - pointer to payload given header requared
1010  */
1011 uint8_t* xran_add_hdr_offset(uint8_t  *dst, int16_t compMethod);
1012
1013 #ifdef __cplusplus
1014 }
1015 #endif
1016
1017 #endif /* _XRAN_FH_O_DU_H_*/