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 /**
  21  * @brief This file provides public interface to xRAN Front Haul layer implementation as defined in the
  22  *      ORAN-WG4.CUS.0-v01.00 spec. Implementation specific to
  23  *      Lower Layer Split Central Unit (O-DU): a logical node that includes the eNB/gNB functions as
  24  *      listed in section 2.1 split option 7-2x, excepting those functions allocated exclusively to the O-RU.
  25  *      The O-DU controls the operation of O-RUs for 5G NR Radio Access technology
  26  *
  27  * @file xran_fh_o_du.h
  28  * @ingroup group_lte_source_xran
  29  * @author Intel Corporation
  30  *
  31  **/
  32
  33 #ifndef _XRAN_FH_O_DU_H_
  34 #define _XRAN_FH_O_DU_H_
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 #include <stdio.h>
  41 #include <stdlib.h>
  42 #include <string.h>
  43 #include <stdint.h>
  44 #include <inttypes.h>
  45 #include <sys/types.h>
  46 #include <sys/queue.h>
  47 #include <netinet/in.h>
  48 #include <setjmp.h>
  49 #include <stdarg.h>
  50 #include <ctype.h>
  51 #include <errno.h>
  52 #include <getopt.h>
  53 #include <unistd.h>
  54
  55 #define XRAN_STATUS_SUCCESS (0)
  56 /**<
  57  *  @ingroup xran
  58  *   Success status value. */
  59 #define XRAN_STATUS_FAIL (-1)
  60 /**<
  61  *  @ingroup xran
  62  *   Fail status value. */
  63
  64 #define XRAN_STATUS_RETRY (-2)
  65 /**<
  66  *  @ingroup xran
  67  *  Retry status value. */
  68
  69 #define XRAN_STATUS_RESOURCE (-3)
  70 /**<
  71  *  @ingroup xran
  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. */
  75
  76 #define XRAN_STATUS_INVALID_PARAM (-4)
  77 /**<
  78  *  @ingroup xran
  79  *  Invalid parameter has been passed in. */
  80 #define XRAN_STATUS_FATAL (-5)
  81 /**<
  82  *  @ingroup xran
  83  *  A serious error has occurred. Recommended course of action
  84  *  is to shutdown and restart the component. */
  85
  86 #define XRAN_STATUS_UNSUPPORTED (-6)
  87 /**<
  88  *  @ingroup xran
  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. */
  92
  93 #define XRAN_STATUS_INVALID_PACKET (-7)
  94 /**<
  95  *  @ingroup xran
  96  *  Recevied packet does not have correct format. */
  97
  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,numSubFramePerSystemFrame, numSlotPerSubFrame)  ((uint32_t)tti / ((uint32_t)numSubFramePerSystemFrame * (uint32_t)numSlotPerSubFrame))
 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))
 108
 109 #define XRAN_PORTS_NUM      (1)  /**< number of XRAN ports (aka O-RU devices) supported */
 110 #define XRAN_N_FE_BUF_LEN   (80) /**< Number of TTIs (slots) */
 111 #define XRAN_MAX_SECTOR_NR  (12) /**< Max sectors per XRAN port */
 112 #define XRAN_MAX_ANTENNA_NR (4)  /**< Max antenna per port */
 113 #define XRAN_NUM_OF_SYMBOL_PER_SLOT  (14) /**< Number of symbols per slot */
 114 #define XRAN_MAX_TDD_PERIODICITY     (80)   /**< Max TDD pattern period */
 115 #define XRAN_MAX_CELLS_PER_PORT      (XRAN_MAX_SECTOR_NR) /**< Max cells mapped to XRAN port */
 116 #define XRAN_COMPONENT_CARRIERS_MAX  (XRAN_MAX_SECTOR_NR) /**< number of CCs */
 117 #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 */
 118 #define XRAN_MAX_PRBS                (275) /**< Max of PRBs per CC per antanna for 5G NR */
 119
 120
 121 #define XRAN_MAX_PKT_BURST (448+4) /**< 4x14x8 symbols per ms */
 122 #define XRAN_N_MAX_BUFFER_SEGMENT XRAN_MAX_PKT_BURST /**< Max number of segments per ms */
 123
 124 #define XRAN_STRICT_PARM_CHECK               (1) /**< enable parameter check for C-plane */
 125
 126 /* Slot type definition */
 127 #define XRAN_SLOT_TYPE_INVALID               (0) /**< invalid slot type */
 128 #define XRAN_SLOT_TYPE_DL                    (1) /**< DL slot */
 129 #define XRAN_SLOT_TYPE_UL                    (2) /**< UL slot */
 130 #define XRAN_SLOT_TYPE_SP                    (3) /**< Special slot */
 131 #define XRAN_SLOT_TYPE_FDD                   (4) /**< FDD slot */
 132 #define XRAN_SLOT_TYPE_LAST                  (5) /**< MAX slot */
 133
 134 /* symbol type definition */
 135 #define XRAN_SYMBOL_TYPE_DL                  (0) /**< DL symbol  */
 136 #define XRAN_SYMBOL_TYPE_UL                  (1) /**< UL symbol  */
 137 #define XRAN_SYMBOL_TYPE_GUARD               (2) /**< GUARD symbol */
 138 #define XRAN_SYMBOL_TYPE_FDD                 (3) /**< FDD symbol */
 139
 140 #define XRAN_NUM_OF_SLOT_IN_TDD_LOOP         (80)/**< MAX number of slot for TDD repetition */
 141
 142 //#define _XRAN_DEBUG   /**< Enable debug log */
 143 //#define _XRAN_VERBOSE /**< Enable verbose log */
 144
 145 #ifdef _XRAN_DEBUG
 146     #define xran_log_dbg(fmt, ...)          \
 147         fprintf(stderr,                     \
 148             "DEBUG: %s(%d): " fmt "\n",     \
 149             __FILE__,                       \
 150             __LINE__, ##__VA_ARGS__)
 151 #else
 152     #define xran_log_dbg(fmt, ...)
 153 #endif
 154
 155 #if defined(_XRAN_DEBUG) || defined(_XRAN_VERBOSE)
 156     #define xran_log_wrn(fmt, ...)          \
 157         fprintf(                            \
 158             stderr,                         \
 159             "WARNING: %s(%d): " fmt "\n",   \
 160             __FILE__,                       \
 161             __LINE__, ##__VA_ARGS__)
 162 #else
 163     #define xran_log_dbg(fmt, ...)
 164     #define xran_log_wrn(fmt, ...)
 165 #endif
 166
 167 #define xran_log_err(fmt, ...)          \
 168     fprintf(stderr,                     \
 169         "ERROR: %s(%d): " fmt "\n",     \
 170         __FILE__,                       \
 171         __LINE__, ##__VA_ARGS__)
 172
 173 enum XranFrameDuplexType
 174 {
 175     XRAN_FDD = 0, XRAN_TDD
 176 };
 177
 178 enum xran_if_state
 179 {
 180     XRAN_INIT = 0,
 181     XRAN_RUNNING,
 182     XRAN_STOPPED
 183 };
 184
 185 /**
 186  ******************************************************************************
 187  * @ingroup xran
 188  *
 189  * @description
 190  *      Compression Method 6.3.3.13, Table 6-43
 191  *****************************************************************************/
 192 enum xran_compression_method {
 193     XRAN_COMPMETHOD_NONE        = 0,
 194     XRAN_COMPMETHOD_BLKFLOAT    = 1,
 195     XRAN_COMPMETHOD_BLKSCALE    = 2,
 196     XRAN_COMPMETHOD_ULAW        = 3,
 197     XRAN_COMPMETHOD_MODULATION  = 4,
 198     XRAN_COMPMETHOD_MAX
 199 };
 200
 201 /**
 202  ******************************************************************************
 203  * @ingroup xran
 204  *
 205  * @description
 206  *      Callback function type for symbol packet enum
 207  *****************************************************************************/
 208 enum callback_to_phy_id
 209 {
 210     XRAN_CB_TTI = 0, /**< callback on TTI boundary */
 211     XRAN_CB_HALF_SLOT_RX =1, /**< callback on half slot (sym 7) packet arrival*/
 212     XRAN_CB_FULL_SLOT_RX =2, /**< callback on full slot (sym 14) packet arrival */
 213     XRAN_CB_MAX /**< max number of callbacks */
 214 };
 215
 216 typedef int32_t xran_status_t; /**< Xran status return value */
 217
 218 /** callback function type for Symbol packet */
 219 typedef void (*xran_callback_sym_fn)(void*);
 220
 221 /** Callback function type for TTI event */
 222 typedef int (*xran_fh_tti_callback_fn)(void*);
 223
 224 /** Callback function type packet arrival from transport layer (ETH or IP) */
 225 typedef void (*xran_transport_callback_fn)(void*, int32_t);
 226
 227 /** Callback functions to poll BBdev encoder */
 228 typedef int16_t (*phy_encoder_poll_fn)(void);
 229
 230 /** Callback functions to poll BBdev secoder */
 231 typedef int16_t (*phy_decoder_poll_fn)(void);
 232
 233
 234 /** XRAN port enum */
 235 enum xran_vf_ports
 236 {
 237     XRAN_UP_VF = 0, /**< port type for U-plane */
 238     XRAN_CP_VF,     /**< port type for C-plane */
 239     XRAN_VF_MAX
 240 };
 241
 242 /** XRAN category enum */
 243 enum xran_category
 244 {
 245     XRAN_CATRGORY_A = 0,
 246     XRAN_CATRGORY_B = 1,
 247     XRAN_CATRGORY_MAX
 248 };
 249
 250 /** type of beamforming */
 251 enum xran_beamforming_type
 252 {
 253     XRAN_BEAM_ID_BASED = 0, /**< beam index based */
 254     XRAN_BEAM_WEIGHT,       /**< beam forming weights */
 255     XRAN_BEAM_ATTRIBUTE,    /**< beam index based */
 256 };
 257
 258 /** state of bbdev with xran */
 259 enum xran_bbdev_init
 260 {
 261     XRAN_BBDEV_NOT_USED    = -1, /**< BBDEV is disabled */
 262     XRAN_BBDEV_MODE_HW_OFF = 0,  /**< BBDEV is enabled for SW sim mode */
 263     XRAN_BBDEV_MODE_HW_ON  = 1,  /**< BBDEV is enable for HW */
 264     XRAN_BBDEV_MODE_MAX
 265 };
 266
 267 /** DPDK IO configuration for XRAN layer */
 268 struct xran_io_cfg {
 269     uint8_t id; /**< should be (0) for O-DU or (1) O-RU (debug) */
 270     char *dpdk_dev[XRAN_VF_MAX]; /**< VFs devices  */
 271     char *bbdev_dev[1];     /**< BBDev dev name */
 272     int32_t bbdev_mode;     /**< DPDK for BBDev */
 273     int32_t core;           /**< reservd */
 274     int32_t system_core;    /**< reservd */
 275     int32_t pkt_proc_core;  /**< reservd */
 276     int32_t pkt_aux_core;   /**< reservd */
 277     int32_t timing_core;    /**< core used by xRAN */
 278     int32_t port[XRAN_VF_MAX];  /**< VFs ports */
 279 };
 280
 281 /** XRAN spec section 3.1.3.1.6 ecpriRtcid / ecpriPcid define */
 282 struct xran_eaxcid_config {
 283     uint16_t mask_cuPortId;     /**< Mask CU PortId */
 284     uint16_t mask_bandSectorId; /**< Mask Band */
 285     uint16_t mask_ccId;         /**< Mask CC */
 286     uint16_t mask_ruPortId;     /**< Mask RU Port ID */
 287
 288     uint8_t bit_cuPortId;       /**< bandsectorId + ccId + ruportId */
 289     uint8_t bit_bandSectorId;   /**< ccId + ruPortId */
 290     uint8_t bit_ccId;           /**< ruportId */
 291     uint8_t bit_ruPortId;       /**< 0 */
 292 };
 293
 294 /**
 295 * XRAN Front haul interface initialization settings
 296 */
 297 struct xran_fh_init {
 298     struct xran_io_cfg io_cfg;/**< DPDK IO for XRAN */
 299     struct xran_eaxcid_config eAxCId_conf; /**< config of ecpriRtcid/ecpriPcid */
 300
 301     uint32_t dpdkBasebandFecMode; /**< DPDK Baseband FEC device mode (0-SW, 1-HW) */
 302     char *dpdkBasebandDevice;     /**< DPDK Baseband device address */
 303     char *filePrefix;             /**< DPDK prefix */
 304
 305     enum xran_category xranCat;   /**< mode: Catergory A or Category B */
 306
 307     uint32_t mtu; /**< maximum transmission unit (MTU) is the size of the largest protocol data unit (PDU) that can be communicated in a single
 308                        xRAN network layer transaction. supported 1500 bytes and 9600 bytes (Jumbo Frame) */
 309     int8_t   *p_o_du_addr;  /**<  O-DU Ethernet Mac Address */
 310     int8_t   *p_o_ru_addr;  /**<  O-RU Ethernet Mac Address */
 311
 312     uint16_t Tadv_cp_dl;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 313     uint16_t T2a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 314     uint16_t T2a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 315     uint16_t T2a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 316     uint16_t T2a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 317     uint16_t T2a_min_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 318     uint16_t T2a_max_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 319     uint16_t Ta3_min;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 320     uint16_t Ta3_max;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 321     uint16_t T1a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 322     uint16_t T1a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 323     uint16_t T1a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 324     uint16_t T1a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 325     uint16_t T1a_min_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 326     uint16_t T1a_max_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 327     uint16_t Ta4_min;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 328     uint16_t Ta4_max;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 329
 330     uint8_t enableCP;       /**<  enable C-plane */
 331     uint8_t prachEnable;    /**<  enable PRACH   */
 332     uint8_t cp_vlan_tag;    /**<  C-plane vlan tag */
 333     uint8_t up_vlan_tag;    /**<  U-plane vlan tag */
 334     int32_t debugStop;      /**<  enable auto stop */
 335     int32_t debugStopCount;      /**<  enable auto stop after number of Tx packets */
 336     int32_t DynamicSectionEna; /**<  enable dynamic C-Plane section allocation */
 337 };
 338
 339 struct xran_cp_bf_weight{
 340     int16_t weight[64];
 341 };
 342 struct xran_cp_bf_attribute{
 343     int16_t weight[4];
 344 };
 345 struct xran_cp_bf_precoding{
 346     int16_t weight[4];
 347 };
 348
 349 /** PRB element structure */
 350 struct xran_prb_elm {
 351     int16_t nRBStart; /**< start RB of RB allocation */
 352     int16_t nRBSize;  /**< number of RBs used */
 353     int16_t nStartSymb; /**< start symbol ID */
 354     int16_t numSymb;  /**< number of symbol */
 355     int16_t nBeamIndex; /**< beam index for given PRB */
 356     int16_t compMethod; /**< compression index for given PRB */
 357     int16_t BeamFormingType;
 358     union {
 359         struct xran_cp_bf_attribute bf_attribute;
 360         struct xran_cp_bf_precoding bf_precoding;
 361     };
 362 };
 363
 364 /** PRB map structure */
 365 struct xran_prb_map {
 366     uint8_t   dir;        /**< DL or UL direction */
 367     uint8_t   xran_port;  /**< xran id of given RU [0-(XRAN_PORTS_NUM-1)] */
 368     uint16_t  band_id;    /**< xran band id */
 369     uint16_t  cc_id;      /**< componnent carrier id [0 - (XRAN_MAX_SECTOR_NR-1)] */
 370     uint16_t  ru_port_id; /**< RU device antenna port id [0 - (XRAN_MAX_ANTENNA_NR-1) */
 371     uint16_t  tti_id;     /**< xRAN slot id [0 - (max tti-1)] */
 372     uint8_t   start_sym_id;     /**< start symbol Id [0-13] */
 373     uint8_t   bf_weight_update;     /**need to update beam weight or not*/
 374     uint32_t  nPrbElm;    /**< total number of PRBs for given map [0- (XRAN_MAX_PRBS-1)] */
 375     struct xran_prb_elm prbMap[XRAN_MAX_PRBS];
 376     struct xran_cp_bf_weight bf_weight;
 377 };
 378
 379 /* PRACH config required for XRAN based FH */
 380 struct xran_prach_config
 381 {
 382     /* PRACH config*/
 383     uint8_t      nPrachConfIdx;  /**< PRACH Configuration Index*/
 384     uint8_t      nPrachSubcSpacing;
 385     /**< PRACH Sub-carrier spacing
 386     Value:0->1
 387     For below 6GHz the values indicate 15kHz or 30kHz
 388     For above 6GHz the values indicate 60kHz or 120kHz*/
 389     uint8_t      nPrachZeroCorrConf; /**< PRACH zeroCorrelationZoneConfig */
 390     uint8_t      nPrachRestrictSet;  /**< PRACH restrictedSetConfig */
 391     uint16_t     nPrachRootSeqIdx; /**< PRACH Root Sequence Index */
 392     uint16_t     nPrachFreqStart;  /**< PRACH prach-frequency-start  */
 393     int32_t      nPrachFreqOffset; /**< PRACH prach-frequency-offset */
 394     uint8_t      nPrachFilterIdx;  /**< PRACH Filter index */
 395 };
 396
 397 /** XRAN slot configuration */
 398 struct xran_slot_config {
 399     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 */
 400     uint8_t reserved[2];
 401 };
 402
 403 /** XRAN front haul frame config */
 404 struct xran_frame_config {
 405     uint8_t      nFrameDuplexType; /**< Frame Duplex type:  0 -> FDD, 1 -> TDD */
 406     uint8_t      nNumerology; /**< Numerology, determine sub carrier spacing, Value: 0->4
 407                                    0: 15khz,  1: 30khz,  2: 60khz
 408                                    3: 120khz, 4: 240khz */
 409     uint8_t      nTddPeriod;  /**< TDD period */
 410     struct xran_slot_config sSlotConfig[XRAN_MAX_TDD_PERIODICITY];
 411     /**< TDD Slot configuration - If nFrameDuplexType = TDD(1), then this config defines the slot config type for each slot.*/
 412     /* The number of slots need to be equal to nTddPeriod */
 413 };
 414
 415 /** XRAN-PHY interface byte order */
 416 enum xran_input_byte_order {
 417     XRAN_NE_BE_BYTE_ORDER = 0, /**< Network byte order (Big endian), xRAN lib doesn't do swap */
 418     XRAN_CPU_LE_BYTE_ORDER     /**< CPU byte order (Little endian), xRAN lib does do swap */
 419 };
 420
 421 /** XRAN-PHY interface I and Q order */
 422 enum xran_input_i_q_order {
 423     XRAN_I_Q_ORDER = 0,  /**< I , Q */
 424     XRAN_Q_I_ORDER       /**< Q , I */
 425 };
 426
 427 /** XRAN front haul IQ compression settings */
 428 struct xran_ru_config {
 429     uint8_t iqWidth;        /**< IQ bit width */
 430     uint8_t compMeth;       /**< Compression method */
 431     uint8_t fftSize;        /**< FFT Size */
 432     enum xran_input_byte_order byteOrder; /**< Order of bytes in int16_t in buffer. Big or little endian */
 433     enum xran_input_i_q_order  iqOrder;   /**< order of IQs in the buffer */
 434 };
 435
 436 /**
 437  * @ingroup xran
 438  * XRAN front haul general configuration */
 439 struct xran_fh_config {
 440     uint32_t            dpdk_port; /**< DPDK port number used for FH */
 441     uint32_t            sector_id; /**< Band sector ID for FH */
 442     uint32_t            nCC;       /**< number of Component carriers supported on FH */
 443     uint32_t            neAxc;     /**< number of eAxc supported on one CC*/
 444     uint16_t            nDLFftSize;  /**< DL FFT size */
 445     uint16_t            nULFftSize;  /**< UL FFT size */
 446     uint16_t            nDLRBs;      /**< DL PRB  */
 447     uint16_t            nULRBs;      /**< UL PRB  */
 448     uint32_t            nDLAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
 449     uint32_t            nULAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
 450     uint32_t            nDLCenterFreqARFCN;   /**< center frerquency for DL in MHz */
 451     uint32_t            nULCenterFreqARFCN;   /**< center frerquency for UL in MHz */
 452     xran_fh_tti_callback_fn     ttiCb;        /**< call back for TTI event */
 453     void                *ttiCbParam;  /**< parameters of call back function */
 454
 455     struct xran_prach_config     prach_conf;   /**< PRACH specific configurations for FH */
 456     struct xran_frame_config     frame_conf;   /**< frame config */
 457     struct xran_ru_config        ru_conf;      /**< config of RU as per XRAN spec */
 458
 459     phy_encoder_poll_fn bbdev_enc; /**< call back to poll BBDev encoder */
 460     phy_decoder_poll_fn bbdev_dec; /**< call back to poll BBDev decoder */
 461
 462     uint32_t log_level; /**< configuration of log level */
 463 };
 464
 465 /**
 466  * @ingroup xran
 467  * XRAN front haul statistic counters according to Table 7 1 : Common Counters for both DL and UL */
 468 struct xran_common_counters{
 469     uint64_t Rx_on_time;      /**< Data was received on time (applies to user data reception window) */
 470     uint64_t Rx_early;        /**< Data was received too early (applies to user data reception window) */
 471     uint64_t Rx_late;         /**< Data was received too late (applies to user data reception window) */
 472     uint64_t Rx_corrupt;      /**< Corrupt/Incorrect header packet */
 473     uint64_t Rx_pkt_dupl;     /**< Duplicated packet */
 474     uint64_t Total_msgs_rcvd; /**< Total messages received (on all links) */
 475 };
 476
 477 /**
 478  * @ingroup xran
 479  * CC instance handle pointer type */
 480 typedef void * xran_cc_handle_t;
 481
 482 /**
 483  *****************************************************************************
 484  * @ingroup xran
 485  *
 486  * @description
 487  *      A flat buffer structure. The data pointer, pData, is a virtual address.
 488  *      The API requires the memory to by physically contiguous. Each flat
 489  *      buffer segment may contain several equally sized elements.
 490  *
 491  *****************************************************************************/
 492 struct xran_flat_buffer
 493 {
 494     uint32_t nElementLenInBytes;
 495     /**< The Element length specified in bytes.
 496      * This parameter specifies the size of a single element in the buffer.
 497      * The total size of the buffer is described as
 498      * bufferSize = nElementLenInBytes * nNumberOfElements */
 499     uint32_t nNumberOfElements;
 500     /**< The number of elements in the physical contiguous memory segment */
 501     uint32_t nOffsetInBytes;
 502     /**< Offset in bytes to the start of the data in the physical contiguous
 503      * memory segment */
 504     uint32_t nIsPhyAddr;
 505     uint8_t *pData;
 506     /**< The data pointer is a virtual address, however the actual data pointed
 507      * to is required to be in contiguous physical memory unless the field
 508      requiresPhysicallyContiguousMemory in CpaInstanceInfo is false. */
 509     void *pCtrl;
 510     /**< pointer to control section coresponding to data buffer */
 511 };
 512
 513 /**
 514  *****************************************************************************
 515  * @ingroup xran
 516  *      Scatter/Gather buffer list containing an array of Simple buffers.
 517  *
 518  * @description
 519  *      A Scatter/Gather buffer list structure. It is expected that this buffer
 520  *      structure will be used where more than one flat buffer can be provided
 521  *      on a particular API.
 522  *
 523  *      IMPORTANT - The memory for the pPrivateMetaData member must be allocated
 524  *      by the client as contiguous memory.  When allocating memory for
 525  *      pPrivateMetaData a call to cpaCyBufferListGetMetaSize MUST be made to
 526  *      determine the size of the Meta Data Buffer.  The returned size
 527  *      (in bytes) may then be passed in a memory allocation routine to allocate
 528  *      the pPrivateMetaData memory.
 529  *
 530  *****************************************************************************/
 531 struct xran_buffer_list
 532 {
 533     uint32_t nNumBuffers;
 534     /**< Number of pointers */
 535     struct xran_flat_buffer *pBuffers;
 536     /**< Pointer to an unbounded array containing the number of CpaFlatBuffers
 537      * defined by nNumBuffers */
 538     void *pUserData;
 539     /**< This is an opaque field that is not read or modified internally. */
 540     void *pPrivateMetaData;
 541     /**< Private Meta representation of this buffer List - the memory for this
 542      * buffer needs to be allocated by the client as contiguous data.
 543      * The amount of memory required is returned with a call to
 544      * cpaCyBufferListGetMetaSize. If cpaCyBufferListGetMetaSize returns a size
 545      * of zero no memory needs to be allocated, and this parameter can be NULL.
 546      */
 547 };
 548
 549 /**
 550  * @ingroup xran
 551  * Initialize the XRAN Layer via DPDK.
 552  *
 553  * @param argc
 554  *   A non-negative value.  If it is greater than 0, the array members
 555  *   for argv[0] through argv[argc] (non-inclusive) shall contain pointers
 556  *   to strings.
 557  * @param argv
 558  *   An array of strings.  The contents of the array, as well as the strings
 559  *   which are pointed to by the array, may be modified by this function.
 560  *
 561  * @return
 562  *   0 - on success
 563  *   Error codes returned via rte_errno
 564  */
 565 int32_t xran_init(int argc, char *argv[], struct xran_fh_init *p_xran_fh_init, char *appName, void ** pHandle);
 566
 567 /**
 568  * @ingroup xran
 569  *
 570  *   Function returns handles for number of sectors supported by XRAN layer. Currently function
 571  *   supports one handle XRAN layer where it supports only one CC
 572  *
 573  * @param pHandle
 574  *   Pointer to XRAN layer handle
 575  * @param nNumInstances
 576  *   total number of instances of CC
 577  * @param pSectorInstanceHandles
 578  *   Pointer to xran_cc_handle_t where to store Handle pointer
 579  *
 580  * @return
 581  *   0 - on success
 582  */
 583 int32_t xran_sector_get_instances (void * pHandle, uint16_t nNumInstances,
 584                xran_cc_handle_t * pSectorInstanceHandles);
 585
 586 /**
 587  * @ingroup xran
 588  *
 589  *   Function initialize Memory Management subsystem (mm) in order to handle memory buffers between XRAN layer
 590  *   and PHY.
 591  *
 592  * @param pHandle
 593  *   Pointer to XRAN layer handle for given CC
 594  * @param nMemorySize
 595  *   memory size of all segments
 596  * @param nMemorySegmentSize
 597  *   size of memory per segment
 598  *
 599  * @return
 600  *   0 - on success
 601  */
 602 int32_t xran_mm_init (void * pHandle, uint64_t nMemorySize, uint32_t nMemorySegmentSize);
 603
 604 /**
 605  * @ingroup xran
 606  *
 607  *   Function allocates buffer memory (bm) used between XRAN layer and PHY. In general case it's DPDK mbuf.
 608  *   it uses Memory Management system to get memory chunk and define memory pool on top of it.
 609  *
 610  * @param pHandle
 611  *   Pointer to XRAN layer handle for given CC
 612  * @param nPoolIndex
 613  *   pointer to buffer pool identification to be returned
 614  * @param nNumberOfBuffers
 615  *   number of buffer to allocate in the pool
 616  * @param nBufferSize
 617  *   buffer size to allocate
 618  *
 619  * @return
 620  *   0 - on success
 621  */
 622 int32_t xran_bm_init (void * pHandle, uint32_t * pPoolIndex, uint32_t nNumberOfBuffers, uint32_t nBufferSize);
 623
 624 /**
 625  * @ingroup xran
 626  *
 627  *   Function allocates buffer used between XRAN layer and PHY. In general case it's DPDK mbuf.
 628  *
 629  * @param pHandle
 630  *   Pointer to XRAN layer handle for given CC
 631  * @param nPoolIndex
 632  *   buffer pool identification
 633  * @param ppData
 634  *   Pointer to pointer where to store address of new buffer
 635  * @param ppCtrl
 636  *   Pointer to pointer where to store address of internal private control information
 637  *
 638  *
 639  * @return
 640  *   0 - on success
 641  */
 642 int32_t xran_bm_allocate_buffer(void * pHandle, uint32_t nPoolIndex, void **ppData,  void **ppCtrl);
 643
 644 /**
 645  * @ingroup xran
 646  *
 647  *   Function frees buffer used between XRAN layer and PHY. In general case it's DPDK mbuf
 648  *
 649  * @param pHandle
 650  *   Pointer to XRAN layer handle for given CC
 651  * @param pData
 652  *   Pointer to buffer
 653  * @param pData
 654  *   Pointer to internal private control information
 655  *
 656  * @return
 657  *   0 - on success
 658  */
 659 int32_t xran_bm_free_buffer(void * pHandle, void *pData, void *pCtrl);
 660
 661 /**
 662  * @ingroup xran
 663  *
 664  *   Function destroys Memory Management (MM) layer of XRAN library
 665  *
 666  * @param pHandle
 667  *   Pointer to XRAN layer handle for given CC
 668  *
 669  * @return
 670  *   0 - on success
 671  */
 672 int32_t xran_mm_destroy (void * pHandle);
 673
 674 /**
 675  * @ingroup xran
 676  *
 677  *   Function configures TX(DL) and RX(UL) output buffers and callback (UL only) for XRAN layer with
 678  *   given handle
 679  *
 680  * @param pHandle
 681  *   Pointer to XRAN layer handle for given CC
 682  * @param pSrcBuffer
 683  *   list of memory buffers to use to fetch IQs from PHY to XRAN layer (DL)
 684  * @param pSrcCpBuffer
 685  *   list of memory buffers to use to configure C-plane (DL)
 686  * @param pDstBuffer
 687  *   list of memory buffers to use to deliver IQs from XRAN layer to PHY (UL)
 688  * @param pDstCpBuffer
 689  *   list of memory buffers to use to configure C-plane (UL)
 690  * @param xran_transport_callback_fn pCallback
 691  *   Callback function to call with arrival of all packets for given CC for given symbol
 692  * @param pCallbackTag
 693  *   Parameters of Callback function
 694  *
 695  * @return
 696  *   0  - on success
 697  *   -1 - on error
 698  */
 699  int32_t xran_5g_fronthault_config (void * pHandle,
 700                     struct xran_buffer_list *pSrcBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 701                     struct xran_buffer_list *pSrcCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 702                     struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 703                     struct xran_buffer_list *pDstCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 704                     xran_transport_callback_fn pCallback,
 705                     void *pCallbackTag);
 706
 707 /**
 708  * @ingroup xran
 709  *
 710  *   Function configures PRACH output buffers and callback for XRAN layer with given handle
 711  *
 712  * @param pHandle
 713  *   Pointer to XRAN layer handle for given CC
 714  * @param pDstBuffer
 715  *   list of memory buffers to use to deliver PRACH IQs from xran layer to PHY
 716  * @param xran_transport_callback_fn pCallback
 717  *   Callback function to call with arrival of PRACH packets for given CC
 718  * @param pCallbackTag
 719  *   Parameters of Callback function
 720  *
 721  * @return
 722  *   0  - on success
 723  *   -1 - on error
 724  */
 725 int32_t xran_5g_prach_req (void *  pHandle,
 726                 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 727                 xran_transport_callback_fn pCallback,
 728                 void *pCallbackTag);
 729
 730 /**
 731  * @ingroup xran
 732  *
 733  *   Function opens XRAN layer with given handle
 734  *
 735  * @param pHandle
 736  *   Pointer to XRAN layer handle for given CC
 737  * @param pointer to struct xran_fh_config pConf
 738  *   Pointer to XRAN configuration structure with specific settings to use
 739  *
 740  * @return
 741  *   0 - on success
 742  */
 743 int32_t xran_open(void *pHandle, struct xran_fh_config* pConf);
 744
 745 /**
 746  * @ingroup xran
 747  *
 748  *   Function starts XRAN layer with given handle
 749  *
 750  * @param pHandle
 751  *   Pointer to XRAN layer handle for given CC
 752  *
 753  * @return
 754  *   0 - on success
 755  */
 756 int32_t xran_start(void *pHandle);
 757
 758 /**
 759  * @ingroup xran
 760  *
 761  *   Function stops XRAN layer with given handle
 762  *
 763  * @param pHandle
 764  *   Pointer to XRAN layer handle for given CC
 765  *
 766  * @return
 767  *   0 - on success
 768  */
 769 int32_t xran_stop(void *pHandle);
 770
 771 /**
 772  * @ingroup xran
 773  *
 774  *   Function closes XRAN layer with given handle
 775  *
 776  * @param pHandle
 777  *   Pointer to XRAN layer handle for given CC
 778  *
 779  * @return
 780  *   0 - on success
 781  */
 782 int32_t xran_close(void *pHandle);
 783
 784 /**
 785  * @ingroup xran
 786  *
 787  *   Function registers callback to XRAN layer. Function support callbacks aligned on packet arrival.
 788  *
 789  * @param pHandle
 790  *   Pointer to XRAN layer handle for given CC
 791  * @param symCb
 792  *   pointer to callback function
 793  * @param symCb
 794  *   pointer to Callback Function parameters
 795  * @param symb
 796  *   symbol to be register for
 797  * @param ant
 798  *   Antenna number to trigger callback for packet arrival
 799  *
 800  * @return
 801  *    0 - in case of success
 802  *   -1 - in case of failure
 803  */
 804 int32_t xran_reg_sym_cb(void *pHandle, xran_callback_sym_fn symCb, void * symCbParam, uint8_t symb, uint8_t ant);
 805
 806 /**
 807  * @ingroup xran
 808  *
 809  *   Function registers callback to XRAN layer. Function support callbacks align to OTA time. TTI even, half of slot,
 810  *   full slot with respect to PTP time.
 811  *
 812  * @param pHandle
 813  *   Pointer to XRAN layer handle for given CC
 814  * @param Cb
 815  *   pointer to callback function
 816  * @param cbParam
 817  *   pointer to Callback Function parameters
 818  * @param skipTtiNum
 819  *   number of calls to be skipped before first call
 820  * @param callback_to_phy_id
 821  *   call back time identification (see enum callback_to_phy_id)
 822  *
 823  * @return
 824  *    0 - in case of success
 825  *   -1 - in case of failure
 826  */
 827 int32_t xran_reg_physide_cb(void *pHandle, xran_fh_tti_callback_fn Cb, void *cbParam, int skipTtiNum, enum callback_to_phy_id);
 828
 829 /**
 830  * @ingroup xran
 831  *
 832  *   Function returns current TTI, Frame, Subframe, Slot Number as seen "Over air" base on PTP time
 833  *
 834  * @param nFrameIdx
 835  *    Pointer to Frame number [0-99]
 836  *
 837  * @param nSubframeIdx
 838  *    Pointer to Subframe number [0-10]
 839  *
 840  * @param nSlotIdx
 841  *    Pointer to Slot number [0-7]
 842  *
 843  * @param nSecond
 844  *    Pointer to current UTC second
 845  *
 846  * @return
 847  *   current TTI number [0-7999]
 848  */
 849 int32_t xran_get_slot_idx (uint32_t *nFrameIdx, uint32_t *nSubframeIdx,  uint32_t *nSlotIdx, uint64_t *nSecond);
 850
 851 /**
 852  * @ingroup xran
 853  *
 854  *   Function retrun XRAN layer common counters for given handle
 855  *
 856  * @param pHandle
 857  *   Pointer to XRAN layer handle for given CC
 858  *
 859  * @param pStats
 860  *   Pointer to pointer of common counter structure
 861  *
 862  * @return
 863  *   0 - on success
 864  */
 865 int32_t xran_get_common_counters(void *pXranLayerHandle, struct xran_common_counters *pStats);
 866
 867 enum xran_if_state xran_get_if_state(void);
 868
 869
 870 #ifdef __cplusplus
 871 }
 872 #endif
 873
 874 #endif /* _XRAN_FH_O_DU_H_*/