fhi_lib/lib/api/xran_fh_o_du.h

   1 /******************************************************************************
   2 *
   3 *   Copyright (c) 2020 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
  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,SFNatSecStart,numSubFramePerSystemFrame, numSlotPerSubFrame)  ((((uint32_t)tti / ((uint32_t)numSubFramePerSystemFrame * (uint32_t)numSlotPerSubFrame)) + SFNatSecStart) & 0x3FF)
 104 /** Macro to calculate Subframe number for given tti */
 105 #define XranGetSubFrameNum(tti, numSlotPerSubFrame, numSubFramePerSystemFrame) (((uint32_t)tti/(uint32_t)numSlotPerSubFrame) % (uint32_t)numSubFramePerSystemFrame)
 106 /** Macro to calculate Slot number */
 107 #define XranGetSlotNum(tti, numSlotPerSfn) ((uint32_t)tti % ((uint32_t)numSlotPerSfn))
 108
 109 #define XRAN_PORTS_NUM               (4)    /**< number of XRAN ports (aka O-RU|O-DU devices) supported */
 110 #define XRAN_ETH_PF_LINKS_NUM        (4)    /**< number of Physical Ethernet links per one O-RU|O-DU */
 111 #define XRAN_N_FE_BUF_LEN            (20)   /**< Number of TTIs (slots) */
 112 #define XRAN_MAX_SECTOR_NR           (16)   /**< Max sectors per XRAN port */
 113 #define XRAN_MAX_ANTENNA_NR          (16)   /**< Max number of extended Antenna-Carriers:
 114                                                 a data flow for a single antenna (or spatial stream) for a single carrier in a single sector */
 115
 116 /* see 10.2     Hierarchy of Radiation Structure in O-RU (assume TX and RX panel are the same dimensions)*/
 117 #define XRAN_MAX_PANEL_NR            (1)   /**< Max number of Panels supported per O-RU */
 118 #define XRAN_MAX_TRX_ANTENNA_ARRAY   (1)   /**< Max number of TX and RX arrays per panel in O-RU */
 119 #define XRAN_MAX_ANT_ARRAY_ELM_NR    (64)  /**< Maximum number of Antenna Array Elemets in Antenna Array in the O-RU */
 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 #define XRAN_NUM_OF_SC_PER_RB  (12) /**< Number of subcarriers per RB */
 129
 130 #define XRAN_MAX_SECTIONS_PER_SLOT   (24)  /**< Max number of different sections in single slot (section may be equal to RB allocation for UE) */
 131 #define XRAN_MIN_SECTIONS_PER_SLOT   (6)   /**< Min number of different sections in single slot (section may be equal to RB allocation for UE) */
 132 #define XRAN_MAX_SECTIONS_PER_SYM    (XRAN_MAX_SECTIONS_PER_SLOT)  /**< Max number of different sections in single slot (section may be equal to RB allocation for UE) */
 133 #define XRAN_MIN_SECTIONS_PER_SYM    (XRAN_MIN_SECTIONS_PER_SLOT)  /**< Min number of different sections in single slot (section may be equal to RB allocation for UE) */
 134
 135 #define XRAN_MAX_FRAGMENT            (1)   /**< Max number of fragmentations in single symbol */
 136 #define XRAN_MAX_SET_BFWS            (64)  /**< Assumed 64Ant, BFP 9bit with 9K jumbo frame */
 137
 138 #define XRAN_MAX_PKT_BURST (448+4) /**< 4x14x8 symbols per ms */
 139 #define XRAN_N_MAX_BUFFER_SEGMENT XRAN_MAX_PKT_BURST /**< Max number of segments per ms */
 140
 141 #define XRAN_STRICT_PARM_CHECK               (1) /**< enable parameter check for C-plane */
 142
 143 /* Slot type definition */
 144 #define XRAN_SLOT_TYPE_INVALID               (0) /**< invalid slot type */
 145 #define XRAN_SLOT_TYPE_DL                    (1) /**< DL slot */
 146 #define XRAN_SLOT_TYPE_UL                    (2) /**< UL slot */
 147 #define XRAN_SLOT_TYPE_SP                    (3) /**< Special slot */
 148 #define XRAN_SLOT_TYPE_FDD                   (4) /**< FDD slot */
 149 #define XRAN_SLOT_TYPE_LAST                  (5) /**< MAX slot */
 150
 151 /* symbol type definition */
 152 #define XRAN_SYMBOL_TYPE_DL                  (0) /**< DL symbol  */
 153 #define XRAN_SYMBOL_TYPE_UL                  (1) /**< UL symbol  */
 154 #define XRAN_SYMBOL_TYPE_GUARD               (2) /**< GUARD symbol */
 155 #define XRAN_SYMBOL_TYPE_FDD                 (3) /**< FDD symbol */
 156
 157 #define XRAN_NUM_OF_SLOT_IN_TDD_LOOP         (80)/**< MAX number of slot for TDD repetition */
 158
 159 //#define _XRAN_DEBUG   /**< Enable debug log */
 160 //#define _XRAN_VERBOSE /**< Enable verbose log */
 161 #define MX_NUM_SAMPLES                       (16)/**< MAX Number of Samples for One Way delay Measurement */
 162
 163 #define XRAN_VF_QUEUE_MAX (XRAN_MAX_ANTENNA_NR*2+XRAN_MAX_ANT_ARRAY_ELM_NR) /**< MAX number of HW queues for given VF */
 164
 165 #ifdef _XRAN_DEBUG
 166     #define xran_log_dbg(fmt, ...)          \
 167         fprintf(stderr,                     \
 168             "DEBUG: %s(%d): " fmt "\n",     \
 169             __FILE__,                       \
 170             __LINE__, ##__VA_ARGS__)
 171 #else
 172     #define xran_log_dbg(fmt, ...)
 173 #endif
 174
 175 #if defined(_XRAN_DEBUG) || defined(_XRAN_VERBOSE)
 176     #define xran_log_wrn(fmt, ...)          \
 177         fprintf(                            \
 178             stderr,                         \
 179             "WARNING: %s(%d): " fmt "\n",   \
 180             __FILE__,                       \
 181             __LINE__, ##__VA_ARGS__)
 182 #else
 183     #define xran_log_dbg(fmt, ...)
 184     #define xran_log_wrn(fmt, ...)
 185 #endif
 186
 187 #define xran_log_err(fmt, ...)          \
 188     fprintf(stderr,                     \
 189         "ERROR: %s(%d): " fmt "\n",     \
 190         __FILE__,                       \
 191         __LINE__, ##__VA_ARGS__)
 192
 193 enum XranFrameDuplexType
 194 {
 195     XRAN_FDD = 0, XRAN_TDD
 196 };
 197
 198 enum xran_if_state
 199 {
 200     XRAN_INIT = 0,
 201     XRAN_RUNNING,
 202     XRAN_STOPPED,
 203     XRAN_OWDM
 204 };
 205
 206 /**
 207  ******************************************************************************
 208  * @ingroup xran
 209  *
 210  * @description
 211  *      Compression Method 6.3.3.13, Table 6-43
 212  *****************************************************************************/
 213 enum xran_compression_method {
 214     XRAN_COMPMETHOD_NONE        = 0,
 215     XRAN_COMPMETHOD_BLKFLOAT    = 1,
 216     XRAN_COMPMETHOD_BLKSCALE    = 2,
 217     XRAN_COMPMETHOD_ULAW        = 3,
 218     XRAN_COMPMETHOD_MODULATION  = 4,
 219     XRAN_COMPMETHOD_MAX
 220 };
 221
 222 /**
 223  ******************************************************************************
 224  * @ingroup xran
 225  *
 226  * @description
 227  *       enum of callback function type ids for TTI
 228  *****************************************************************************/
 229 enum callback_to_phy_id
 230 {
 231     XRAN_CB_TTI = 0, /**< callback on TTI boundary */
 232     XRAN_CB_HALF_SLOT_RX =1, /**< callback on half slot (sym 7) packet arrival*/
 233     XRAN_CB_FULL_SLOT_RX =2, /**< callback on full slot (sym 14) packet arrival */
 234     XRAN_CB_MAX /**< max number of callbacks */
 235 };
 236
 237 /**
 238  ******************************************************************************
 239  * @ingroup xran
 240  *
 241  * @description
 242  *       enum of callback function type ids for sumbol
 243  *****************************************************************************/
 244 enum cb_per_sym_type_id
 245 {
 246     XRAN_CB_SYM_OTA_TIME         = 0, /**< callback on exact SYM OTA time (+-SW jitter)  */
 247     XRAN_CB_SYM_RX_WIN_BEGIN     = 1, /**< callback on exact SYM RX window start time (+-SW jitter) */
 248     XRAN_CB_SYM_RX_WIN_END       = 2, /**< callback on exact SYM RX window stop time (+-SW jitter)  */
 249     XRAN_CB_SYM_TX_WIN_BEGIN     = 3, /**< callback on exact SYM TX window start time (+-SW jitter) */
 250     XRAN_CB_SYM_TX_WIN_END       = 4, /**< callback on exact SYM TX window stop time (+-SW jitter)  */
 251     XRAN_CB_SYM_CP_DL_WIN_BEGIN  = 5, /**< callback on exact SYM DL CP window start time (+-SW jitter)  */
 252     XRAN_CB_SYM_CP_DL_WIN_END    = 6, /**< callback on exact SYM DL CP window stop time (+-SW jitter)  */
 253     XRAN_CB_SYM_CP_UL_WIN_BEGIN  = 7, /**< callback on exact SYM UL CP window start time (+-SW jitter)  */
 254     XRAN_CB_SYM_CP_UL_WIN_END    = 8, /**< callback on exact SYM UL CP window stop time (+-SW jitter)  */
 255     XRAN_CB_SYM_MAX                   /**< max number of types of callbacks */
 256 };
 257
 258 /**  Beamforming type, enumerated as "frequency", "time" or "hybrid"
 259      section 10.4.2     Weight-based dynamic beamforming */
 260 enum xran_weight_based_beamforming_type {
 261     XRAN_BF_T_FREQUENCY = 0,
 262     XRAN_BF_T_TIME      = 1,
 263     XRAN_BF_T_HYBRID    = 2,
 264     XRAN_BF_T_MAX
 265 };
 266
 267 /** contains time related information according to type of event */
 268 struct xran_sense_of_time {
 269     enum cb_per_sym_type_id type_of_event; /**< event type id */
 270     uint32_t tti_counter;  /**< TTI counter with in GPS second */
 271     uint32_t nSymIdx;      /**< Symbol Idx with in Slot [0-13] */
 272     uint32_t nFrameIdx;    /**< ORAN Frame */
 273     uint32_t nSubframeIdx; /**< ORAN Subframe */
 274     uint32_t nSlotIdx;     /**< Slot within subframe */
 275     uint64_t nSecond;      /**< GPS second of this symbol */
 276 };
 277
 278 typedef int32_t xran_status_t; /**< Xran status return value */
 279
 280 /** callback function type for Symbol packet */
 281 typedef int32_t (*xran_callback_sym_fn)(void*, struct xran_sense_of_time* p_sense_of_time);
 282
 283 /** Callback function type for TTI event */
 284 typedef int32_t (*xran_fh_tti_callback_fn)(void*);
 285
 286 /** Callback function type packet arrival from transport layer (ETH or IP) */
 287 typedef void (*xran_transport_callback_fn)(void*, xran_status_t);
 288
 289 /** Callback functions to poll BBdev encoder */
 290 typedef int16_t (*phy_encoder_poll_fn)(void);
 291
 292 /** Callback functions to poll BBdev decoder */
 293 typedef int16_t (*phy_decoder_poll_fn)(void);
 294
 295 /** XRAN port enum */
 296 enum xran_vf_ports
 297 {
 298     XRAN_UP_VF = 0, /**< port type for U-plane */
 299     XRAN_CP_VF,     /**< port type for C-plane */
 300     XRAN_UP_VF1,    /**< port type for U-plane */
 301     XRAN_CP_VF1,    /**< port type for C-plane */
 302     XRAN_UP_VF2,    /**< port type for U-plane */
 303     XRAN_CP_VF2,    /**< port type for C-plane */
 304     XRAN_UP_VF3,    /**< port type for U-plane */
 305     XRAN_CP_VF3,    /**< port type for C-plane */
 306     XRAN_UP_VF4,    /**< port type for U-plane */
 307     XRAN_CP_VF4,    /**< port type for C-plane */
 308     XRAN_UP_VF5,    /**< port type for U-plane */
 309     XRAN_CP_VF5,    /**< port type for C-plane */
 310     XRAN_UP_VF6,    /**< port type for U-plane */
 311     XRAN_CP_VF6,    /**< port type for C-plane */
 312     XRAN_UP_VF7,    /**< port type for U-plane */
 313     XRAN_CP_VF7,    /**< port type for C-plane */
 314     XRAN_VF_MAX
 315 };
 316
 317 /** XRAN Radio Access technology enum */
 318 enum xran_ran_tech
 319 {
 320     XRAN_RAN_5GNR     = 0, /**< 5G NR */
 321     XRAN_RAN_LTE      = 1, /**< LTE   */
 322     XRAN_RAN_MAX
 323 };
 324
 325 /** XRAN user data compression header handling types */
 326 enum xran_comp_hdr_type
 327 {
 328     XRAN_COMP_HDR_TYPE_DYNAMIC   = 0, /**< dynamic data format where U-plane udCompHdr controls compression parameters */
 329     XRAN_COMP_HDR_TYPE_STATIC    = 1, /**< static data format where M-plane defines compression parameters */
 330     XRAN_COMP_HDR_TYPE_MAX
 331 };
 332
 333 /** XRAN category enum */
 334 enum xran_category
 335 {
 336     XRAN_CATEGORY_A     = 0, /**< 5G NR Category A */
 337     XRAN_CATEGORY_B     = 1, /**< 5G NR Category B */
 338     XRAN_CATEGORY_MAX
 339 };
 340
 341 /** type of beamforming */
 342 enum xran_beamforming_type
 343 {
 344     XRAN_BEAM_ID_BASED = 0, /**< beam index based */
 345     XRAN_BEAM_WEIGHT    = 1, /**< beam forming weights */
 346     XRAN_BEAM_ATTRIBUTE = 2, /**< beam index based */
 347     XRAN_BEAM_TYPE_MAX
 348 };
 349
 350 /** state of bbdev with xran */
 351 enum xran_bbdev_init
 352 {
 353     XRAN_BBDEV_NOT_USED    = -1, /**< BBDEV is disabled */
 354     XRAN_BBDEV_MODE_HW_OFF = 0,  /**< BBDEV is enabled for SW sim mode */
 355     XRAN_BBDEV_MODE_HW_ON  = 1,  /**< BBDEV is enable for HW */
 356     XRAN_BBDEV_MODE_HW_SW  =  2, /**< BBDEV for SW and HW is enabled */
 357     XRAN_BBDEV_MODE_MAX
 358 };
 359
 360 /** callback return information */
 361 struct xran_cb_tag {
 362     uint16_t cellId;
 363     uint16_t oXuId;
 364     uint32_t symbol;
 365     uint32_t slotiId;
 366 };
 367
 368 /** Common Data for ecpri one-way delay measurements  */
 369 struct xran_ecpri_del_meas_cmn {
 370     uint16_t initiator_en;      // Initiator 1, Recipient 0
 371     uint16_t numberOfSamples;   // Total number of samples to be collected and averaged
 372     uint32_t filterType;        // Average for number of samples collected 0
 373     uint64_t responseTo;        //  Response Timeout in ns
 374     uint16_t measVf;            //  Vf using the owd transmitter
 375     uint16_t measState;         //  The state of the owd Transmitter: OWDMTX_DIS,OWDMTX_INIT,OWDMTX_IDLE,OWDMTX_ACTIVE,OWDTX_DONE
 376     uint16_t measId;            //  Measurement Id to be used by the transmitter
 377     uint16_t measMethod;        //  Measurement Method i.e. REQUEST, REM_REQ, REQ_WFUP or REM_REQ_WFUP
 378     uint16_t owdm_enable;       //  1: Enabled  0:Disabled
 379     uint16_t owdm_PlLength;     //  Payload Length   44 <= PlLength <= 1400
 380 };
 381
 382 /** Port specific data for ecpri one-way delay measurements */
 383 struct xran_ecpri_del_meas_port {
 384     uint64_t t1;                            // ecpri ts1
 385     uint64_t t2;                            // ecpri ts2
 386     uint64_t tr;                            // ecpri tr
 387     int64_t delta;                          // stores differences based on the msState
 388     uint8_t portid;                         // portid for this owdm
 389     uint8_t runMeas;                        // run One Way Delay measurements for numberOfSamples
 390     uint16_t currentMeasID;                 // Last Measurement ID received, for originator use as base for the Measurement ID being send out
 391     uint16_t msState;                       // Measurement State for Initiator: Idle, Waiting_Response, Waiting_Request, Waiting_Request_with_fup, Waiting_fup, Done
 392                                             // Measurement State for Recipient: Idle, Waiting_Response, Waiting_Follow_up, Done
 393     uint16_t numMeas;                       // Number of Measurements completed (Running number up to common config numberOfSamples
 394     uint16_t txDone;                        // For originator clear after each change of state and set once the transmission is done
 395     uint64_t rspTimerIdx;                   // Timer Index for TimeOut Timer. On timeout abort current measurement and go back to idle state
 396     uint64_t delaySamples[MX_NUM_SAMPLES];  // Storage for collected delay samples i.e. td
 397     uint64_t delayAvg;                      // Contains the average based on the numberOfSamples for the delay, gets computed once we have
 398                                             // completed the collection for all the numberOfSamples prescribed
 399 };
 400
 401 /** DPDK IO configuration for XRAN layer */
 402 struct xran_io_cfg {
 403     uint8_t id; /**< should be (0) for O-DU or (1) O-RU (debug) */
 404     uint8_t num_vfs; /**< number of VFs for C-plane and U-plane (should be even) */
 405     uint16_t num_rxq;             /**< number of RX queues per VF */
 406     char *dpdk_dev[XRAN_VF_MAX]; /**< VFs devices  */
 407     char *bbdev_dev[1];      /**< BBDev dev name */
 408     int32_t bbdev_mode;      /**< DPDK for BBDev */
 409     uint32_t dpdkIoVaMode;   /**< IOVA Mode */
 410     uint32_t dpdkMemorySize; /**< DPDK max memory allocation */
 411     int32_t  core;                /**< reserved */
 412     int32_t  system_core;         /**< reserved */
 413     uint64_t pkt_proc_core;         /**< worker mask 0-63 */
 414     uint64_t pkt_proc_core_64_127;  /**< worker mask 64-127 */
 415     int32_t  pkt_aux_core;        /**< reserved */
 416     int32_t  timing_core;     /**< core used by xRAN */
 417     int32_t  port[XRAN_VF_MAX];  /**< VFs ports */
 418     int32_t  io_sleep;        /**< enable sleep on PMD cores */
 419     uint32_t nEthLinePerPort;     /**< 1, 2, 3 total number of links per O-RU (Fronthaul Ethernet link) */
 420     uint32_t nEthLineSpeed;       /**< 10G,25G,40G,100G speed of Physical connection on O-RU */
 421     int32_t  one_vf_cu_plane;      /**< 1 - C-plane and U-plane use one VF */
 422     struct xran_ecpri_del_meas_cmn eowd_cmn[2];/**<ecpriowdmeasurementscommonsettingsforO-DUandO-RU*/
 423     struct xran_ecpri_del_meas_port eowd_port[2][XRAN_VF_MAX];  /**< ecpri owd measurements per port variables for O-DU and O-RU */
 424 };
 425
 426 /** XRAN spec section 3.1.3.1.6 ecpriRtcid / ecpriPcid define */
 427 struct xran_eaxcid_config {
 428     uint16_t mask_cuPortId;     /**< Mask CU PortId */
 429     uint16_t mask_bandSectorId; /**< Mask Band */
 430     uint16_t mask_ccId;         /**< Mask CC */
 431     uint16_t mask_ruPortId;     /**< Mask RU Port ID */
 432
 433     uint8_t bit_cuPortId;       /**< bandsectorId + ccId + ru_portId */
 434     uint8_t bit_bandSectorId;   /**< ccId + ruPortId */
 435     uint8_t bit_ccId;           /**< ru_portId */
 436     uint8_t bit_ruPortId;       /**< 0 */
 437 };
 438
 439 /**
 440 * XRAN Front haul interface initialization settings
 441 */
 442 struct xran_fh_init {
 443     struct xran_io_cfg io_cfg;/**< DPDK IO for XRAN */
 444     struct xran_eaxcid_config eAxCId_conf; /**< config of ecpriRtcid/ecpriPcid */
 445
 446     uint32_t xran_ports;          /**< Number of O-RU/O-DU connected to this instantiation of ORAN FH layer */
 447     uint32_t dpdkBasebandFecMode; /**< DPDK Baseband FEC device mode (0-SW, 1-HW) */
 448     char *dpdkBasebandDevice;     /**< DPDK Baseband device address */
 449     char *filePrefix;             /**< DPDK prefix */
 450
 451     uint32_t mtu; /**< maximum transmission unit (MTU) is the size of the largest protocol data unit (PDU) that can be communicated in a single
 452                        xRAN network layer transaction. supported 1500 bytes and 9600 bytes (Jumbo Frame) */
 453     int8_t *p_o_du_addr;  /**<  O-DU Ethernet Mac Address */
 454     int8_t *p_o_ru_addr;  /**<  O-RU Ethernet Mac Address */
 455
 456     uint16_t totalBfWeights;/**< The total number of beamforming weights on RU for extensions */
 457 };
 458
 459 struct xran_ext11_bfw_info {
 460         uint16_t    beamId;     /* 15bits, needs to strip MSB */
 461         uint8_t     *pBFWs;     /* external buffer pointer */
 462     };
 463 /** Beamforming waights for single stream for each PRBs  given number of Antenna elements */
 464 struct xran_cp_bf_weight{
 465     int16_t nAntElmTRx;        /**< num TRX for this allocation */
 466     int16_t  ext_section_sz;   /**< extType section size */
 467     int8_t*  p_ext_start;      /**< pointer to start of buffer for full C-plane packet */
 468     int8_t*  p_ext_section;    /**< pointer to form extType */
 469
 470     /* For ext 11 */
 471     uint8_t     bfwCompMeth;    /* Compression Method for BFW */
 472     uint8_t     bfwIqWidth;     /* Bitwidth of BFW */
 473     uint8_t     numSetBFWs;     /* Total number of beam forming weights set (L) */
 474     uint8_t     numBundPrb;     /* This parameter is the number of bundled PRBs per beamforming weights, 0 means to use ext1 */
 475     uint8_t     RAD;
 476     uint8_t     disableBFWs;
 477     int16_t     maxExtBufSize;  /* Maximum space of external buffer */
 478     struct xran_ext11_bfw_info bfw[XRAN_MAX_SET_BFWS];
 479 };
 480 struct xran_cp_bf_attribute{
 481     int16_t weight[4];
 482 };
 483 struct xran_cp_bf_precoding{
 484     int16_t weight[4];
 485 };
 486
 487 /** section descriptor for given number of PRBs used on U-plane packet creation */
 488 struct xran_section_desc {
 489     uint16_t section_id; /**< section id used for this element */
 490     uint16_t num_prbu;
 491     uint16_t start_prbu;
 492     int16_t iq_buffer_offset;    /**< Offset in bytes for the content of IQs with in main symbol buffer */
 493     int16_t iq_buffer_len;       /**< Length in bytes for the content of IQs with in main symbol buffer */
 494
 495     uint8_t *pData;      /**< optional pointer to data buffer */
 496     void    *pCtrl;      /**< optional pointer to mbuf */
 497 };
 498
 499 /** PRB element structure */
 500 struct xran_prb_elm {
 501     int16_t nRBStart;    /**< start RB of RB allocation */
 502     int16_t nRBSize;     /**< number of RBs used */
 503     int16_t nStartSymb;  /**< start symbol ID */
 504     int16_t numSymb;     /**< number of symbols */
 505     int16_t nBeamIndex;  /**< beam index for given PRB */
 506     int16_t bf_weight_update; /** need to update beam weights or not */
 507     int16_t compMethod;  /**< compression index for given PRB */
 508     int16_t iqWidth;     /**< compression bit width for given PRB */
 509     uint16_t ScaleFactor;  /**< scale factor for modulation compression */
 510     int16_t reMask;   /**< 12-bit RE Mask for modulation compression */
 511     int16_t BeamFormingType; /**< index based, weights based or attribute based beam forming*/
 512     int16_t nSecDesc[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**<  number of section descriptors per symbol */
 513
 514     struct xran_section_desc * p_sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT][XRAN_MAX_FRAGMENT]; /**< section desctiptors to U-plane data given RBs */
 515     struct xran_cp_bf_weight   bf_weight; /**< beam forming information relevant for given RBs */
 516
 517     union {
 518         struct xran_cp_bf_attribute bf_attribute;
 519         struct xran_cp_bf_precoding bf_precoding;
 520     };
 521 };
 522
 523 /** PRB map structure */
 524 struct xran_prb_map {
 525     uint8_t   dir;        /**< DL or UL direction */
 526     uint8_t   xran_port;  /**< xran id of given RU [0-(XRAN_PORTS_NUM-1)] */
 527     uint16_t  band_id;    /**< xran band id */
 528     uint16_t  cc_id;      /**< component carrier id [0 - (XRAN_MAX_SECTOR_NR-1)] */
 529     uint16_t  ru_port_id; /**< RU device antenna port id [0 - (XRAN_MAX_ANTENNA_NR-1) */
 530     uint16_t  tti_id;     /**< xRAN slot id [0 - (max tti-1)] */
 531     uint8_t   start_sym_id;     /**< start symbol Id [0-13] */
 532     uint32_t  nPrbElm;    /**< total number of PRB elements for given map [0- (XRAN_MAX_SECTIONS_PER_SLOT-1)] */
 533     struct xran_prb_elm prbMap[1];
 534 };
 535
 536 /* PRACH config required for XRAN based FH */
 537 struct xran_prach_config
 538 {
 539     /* PRACH config*/
 540     uint8_t      nPrachConfIdx;  /**< PRACH Configuration Index*/
 541     uint8_t      nPrachSubcSpacing;
 542     /**< PRACH Sub-carrier spacing
 543     Value:0->1
 544     For below 6GHz the values indicate 15kHz or 30kHz
 545     For above 6GHz the values indicate 60kHz or 120kHz*/
 546     uint8_t      nPrachZeroCorrConf; /**< PRACH zeroCorrelationZoneConfig */
 547     uint8_t      nPrachRestrictSet;  /**< PRACH restrictedSetConfig */
 548     uint16_t     nPrachRootSeqIdx; /**< PRACH Root Sequence Index */
 549     uint16_t     nPrachFreqStart;  /**< PRACH prach-frequency-start  */
 550     int32_t      nPrachFreqOffset; /**< PRACH prach-frequency-offset */
 551     uint8_t      nPrachFilterIdx;  /**< PRACH Filter index */
 552
 553     /* Return values after initialization */
 554     uint8_t    startSymId;
 555     uint8_t    lastSymId;
 556     uint16_t   startPrbc;
 557     uint8_t    numPrbc;
 558     uint16_t   timeOffset;
 559     int32_t    freqOffset;
 560     uint8_t    eAxC_offset;
 561 };
 562
 563 /**< SRS configuration required for XRAN based FH */
 564 struct xran_srs_config {
 565     uint16_t   symbMask;    /**< symbols used for SRS with in U/S slot [bits 0-13] */
 566     uint8_t    eAxC_offset; /**< starting value of eAxC for SRS packets */
 567 };
 568
 569 /** XRAN slot configuration */
 570 struct xran_slot_config {
 571     uint8_t nSymbolType[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**< Defines the Symbol type for all 14 symbols in a slot. 0: DL, 1: UL, 2: Guard */
 572     uint8_t reserved[2];
 573 };
 574
 575 /** XRAN front haul frame config */
 576 struct xran_frame_config {
 577     uint8_t      nFrameDuplexType; /**< Frame Duplex type:  0 -> FDD, 1 -> TDD */
 578     uint8_t      nNumerology; /**< Numerology, determine sub carrier spacing, Value: 0->4
 579                                    0: 15khz,  1: 30khz,  2: 60khz
 580                                    3: 120khz, 4: 240khz */
 581     uint8_t      nTddPeriod;  /**< TDD period */
 582     struct xran_slot_config sSlotConfig[XRAN_MAX_TDD_PERIODICITY];
 583     /**< TDD Slot configuration - If nFrameDuplexType = TDD(1), then this config defines the slot config type for each slot.*/
 584     /* The number of slots need to be equal to nTddPeriod */
 585 };
 586
 587 /** XRAN-PHY interface byte order */
 588 enum xran_input_byte_order {
 589     XRAN_NE_BE_BYTE_ORDER = 0, /**< Network byte order (Big endian), xRAN lib doesn't do swap */
 590     XRAN_CPU_LE_BYTE_ORDER     /**< CPU byte order (Little endian), xRAN lib does do swap */
 591 };
 592
 593 /** XRAN-PHY interface I and Q order */
 594 enum xran_input_i_q_order {
 595     XRAN_I_Q_ORDER = 0,  /**< I , Q */
 596     XRAN_Q_I_ORDER       /**< Q , I */
 597 };
 598
 599 /** XRAN front haul O-RU settings */
 600 struct xran_ru_config {
 601     enum xran_ran_tech      xranTech;      /**< 5GNR or LTE */
 602     enum xran_category      xranCat;       /**< mode: Catergory A or Category B */
 603     enum xran_comp_hdr_type xranCompHdrType;   /**< dynamic or static udCompHdr handling*/
 604     uint8_t                 iqWidth;           /**< IQ bit width */
 605     uint8_t                 compMeth;      /**< Compression method */
 606     uint8_t                 iqWidth_PRACH;           /**< IQ bit width for PRACH */
 607     uint8_t                 compMeth_PRACH;      /**< Compression method for PRACH */
 608     uint8_t                 fftSize;       /**< FFT Size */
 609     enum xran_input_byte_order byteOrder; /**< Order of bytes in int16_t in buffer. Big or little endian */
 610     enum xran_input_i_q_order  iqOrder;   /**< order of IQs in the buffer */
 611     uint16_t xran_max_frame;   /**< max frame number supported */
 612 };
 613
 614 /**
 615  * @ingroup xran
 616  * XRAN front haul general configuration */
 617 struct xran_fh_config {
 618     uint32_t            dpdk_port; /**< DPDK port number used for FH */
 619     uint32_t            sector_id; /**< Band sector ID for FH */
 620     uint32_t            nCC;       /**< number of Component carriers supported on FH */
 621     uint32_t            neAxc;     /**< number of eAxc supported on one CC*/
 622     uint32_t            neAxcUl;     /**< number of eAxc supported on one CC for UL direction */
 623     uint32_t            nAntElmTRx;  /**< Number of antenna elements for TX and RX */
 624     uint16_t            nDLFftSize;  /**< DL FFT size */
 625     uint16_t            nULFftSize;  /**< UL FFT size */
 626     uint16_t            nDLRBs;      /**< DL PRB  */
 627     uint16_t            nULRBs;      /**< UL PRB  */
 628     uint32_t            nDLAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
 629     uint32_t            nULAbsFrePointA; /**< Abs Freq Point A of the Carrier Center Frequency for in KHz Value: 450000->52600000 */
 630     uint32_t            nDLCenterFreqARFCN;   /**< center frequency for DL in MHz */
 631     uint32_t            nULCenterFreqARFCN;   /**< center frequency for UL in MHz */
 632     xran_fh_tti_callback_fn     ttiCb;        /**< call back for TTI event */
 633     void                *ttiCbParam;  /**< parameters of call back function */
 634
 635     uint16_t Tadv_cp_dl;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 636     uint16_t T2a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 637     uint16_t T2a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 638     uint16_t T2a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 639     uint16_t T2a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 640     uint16_t T2a_min_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 641     uint16_t T2a_max_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 642     uint16_t Ta3_min;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 643     uint16_t Ta3_max;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 644     uint16_t T1a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 645     uint16_t T1a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 646     uint16_t T1a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 647     uint16_t T1a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 648     uint16_t T1a_min_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 649     uint16_t T1a_max_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 650     uint16_t Ta4_min;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 651     uint16_t Ta4_max;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 652
 653     uint8_t enableCP;       /**<  enable C-plane */
 654     uint8_t prachEnable;    /**<  enable PRACH   */
 655     uint8_t srsEnable;      /**<  enable SRS (Cat B specific) */
 656     uint8_t puschMaskEnable;/**< enable pusch mask> */
 657     uint8_t puschMaskSlot;  /**< specific which slot pusch channel masked> */
 658     uint8_t cp_vlan_tag;    /**<  C-plane vlan tag */
 659     uint8_t up_vlan_tag;    /**<  U-plane vlan tag */
 660     int32_t debugStop;      /**<  enable auto stop */
 661     int32_t debugStopCount;      /**<  enable auto stop after number of Tx packets */
 662     int32_t DynamicSectionEna; /**<  enable dynamic C-Plane section allocation */
 663     int32_t GPS_Alpha;  // refer to alpha as defined in section 9.7.2 of ORAN spec. this value should be alpha*(1/1.2288ns), range 0 - 1e7 (ns)
 664     int32_t GPS_Beta;   //beta value as defined in section 9.7.2 of ORAN spec. range -32767 ~ +32767
 665
 666     struct xran_prach_config     prach_conf;   /**< PRACH specific configurations for FH */
 667     struct xran_srs_config       srs_conf;     /**< SRS specific configurations for FH */
 668     struct xran_frame_config     frame_conf;   /**< frame config */
 669     struct xran_ru_config        ru_conf;      /**< config of RU as per XRAN spec */
 670
 671     phy_encoder_poll_fn bbdev_enc; /**< call back to poll BBDev encoder */
 672     phy_decoder_poll_fn bbdev_dec; /**< call back to poll BBDev decoder */
 673
 674     uint16_t tx_cp_eAxC2Vf[XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR*2 + XRAN_MAX_ANT_ARRAY_ELM_NR]; /**< mapping of C-Plane (ecpriRtcid) or U-Plane (ecpriPcid) to VF */
 675     uint16_t tx_up_eAxC2Vf[XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR*2 + XRAN_MAX_ANT_ARRAY_ELM_NR]; /**< mapping of C-Plane (ecpriRtcid) or U-Plane (ecpriPcid) to VF */
 676
 677     uint16_t rx_cp_eAxC2Vf[XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR*2 + XRAN_MAX_ANT_ARRAY_ELM_NR]; /**< mapping of C-Plane (ecpriRtcid) or U-Plane (ecpriPcid) to VF */
 678     uint16_t rx_up_eAxC2Vf[XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR*2 + XRAN_MAX_ANT_ARRAY_ELM_NR]; /**< mapping of C-Plane (ecpriRtcid) or U-Plane (ecpriPcid) to VF */
 679
 680     uint32_t log_level; /**< configuration of log level */
 681
 682     uint16_t max_sections_per_slot; /**< M-Plane settings for section */
 683     uint16_t max_sections_per_symbol; /**< M-Plane settings for section */
 684 };
 685
 686 /**
 687  * @ingroup xran
 688  * XRAN front haul statistic counters according to Table 7 1 : Common Counters for both DL and UL */
 689 struct xran_common_counters{
 690     uint64_t Rx_on_time;      /**< Data was received on time (applies to user data reception window) */
 691     uint64_t Rx_early;        /**< Data was received too early (applies to user data reception window) */
 692     uint64_t Rx_late;         /**< Data was received too late (applies to user data reception window) */
 693     uint64_t Rx_corrupt;      /**< Corrupt/Incorrect header packet */
 694     uint64_t Rx_pkt_dupl;     /**< Duplicated packet */
 695     uint64_t Total_msgs_rcvd; /**< Total messages received (on all links) */
 696
 697     /* debug statistis */
 698     uint64_t rx_counter;
 699     uint64_t tx_counter;
 700     uint64_t tx_bytes_counter;
 701     uint64_t rx_bytes_counter;
 702     uint64_t tx_bytes_per_sec;
 703     uint64_t rx_bytes_per_sec;
 704
 705     uint64_t rx_pusch_packets[XRAN_MAX_ANTENNA_NR];
 706     uint64_t rx_prach_packets[XRAN_MAX_ANTENNA_NR];
 707     uint64_t rx_srs_packets;
 708
 709 };
 710
 711 /**
 712  * @ingroup xran
 713  * CC instance handle pointer type */
 714 typedef void * xran_cc_handle_t;
 715
 716 /**
 717  *****************************************************************************
 718  * @ingroup xran
 719  *
 720  * @description
 721  *      A flat buffer structure. The data pointer, pData, is a virtual address.
 722  *      The API requires the memory to by physically contiguous. Each flat
 723  *      buffer segment may contain several equally sized elements.
 724  *
 725  *****************************************************************************/
 726 struct xran_flat_buffer
 727 {
 728     uint32_t nElementLenInBytes; /**< The Element length specified in bytes.
 729      * This parameter specifies the size of a single element in the buffer.
 730      * The total size of the buffer is described as
 731      * bufferSize = nElementLenInBytes * nNumberOfElements */
 732     uint32_t nNumberOfElements;  /**< The number of elements in the physical contiguous memory segment */
 733     uint32_t nOffsetInBytes;     /**< Offset in bytes to the start of the data in the physical contiguous
 734      * memory segment */
 735     uint32_t nIsPhyAddr;
 736     uint8_t *pData;  /**< The data pointer is a virtual address */
 737     void *pCtrl;     /**< pointer to control section coresponding to data buffer */
 738 };
 739
 740 /**
 741  *****************************************************************************
 742  * @ingroup xran
 743  *      Scatter/Gather buffer list containing an array of Simple buffers.
 744  *
 745  * @description
 746  *      A Scatter/Gather buffer list structure. It is expected that this buffer
 747  *      structure will be used where more than one flat buffer can be provided
 748  *      on a particular API.
 749  *
 750  *****************************************************************************/
 751 struct xran_buffer_list
 752 {
 753     uint32_t nNumBuffers; /**< Number of pointers */
 754     struct xran_flat_buffer *pBuffers;
 755     void *pUserData;
 756     void *pPrivateMetaData;
 757 };
 758
 759 /**
 760  * @ingroup xran
 761  * Initialize the XRAN Layer via DPDK.
 762  *
 763  * @param argc
 764  *   A non-negative value.  If it is greater than 0, the array members
 765  *   for argv[0] through argv[argc] (non-inclusive) shall contain pointers
 766  *   to strings.
 767  * @param argv
 768  *   An array of strings.  The contents of the array, as well as the strings
 769  *   which are pointed to by the array, may be modified by this function.
 770  *
 771  * @return
 772  *   0 - on success
 773  *   Error codes returned via rte_errno
 774  */
 775 int32_t xran_init(int argc, char *argv[], struct xran_fh_init *p_xran_fh_init, char *appName, void ** pHandle);
 776
 777 /**
 778  * @ingroup xran
 779  *
 780  *   Function returns handles for number of sectors supported by XRAN layer. Currently function
 781  *   supports one handle XRAN layer where it supports only one CC
 782  *
 783  * @param pHandle
 784  *   Pointer to XRAN layer handle
 785  * @param nNumInstances
 786  *   total number of instances of CC
 787  * @param pSectorInstanceHandles
 788  *   Pointer to xran_cc_handle_t where to store Handle pointer
 789  *
 790  * @return
 791  *   0 - on success
 792  */
 793 int32_t xran_sector_get_instances (uint32_t xran_port, void * pDevHandle, uint16_t nNumInstances,
 794                xran_cc_handle_t * pSectorInstanceHandles);
 795
 796 /**
 797  * @ingroup xran
 798  *
 799  *   Function initialize Memory Management subsystem (mm) in order to handle memory buffers between XRAN layer
 800  *   and PHY.
 801  *
 802  * @param pHandle
 803  *   Pointer to XRAN layer handle for given CC
 804  * @param nMemorySize
 805  *   memory size of all segments
 806  * @param nMemorySegmentSize
 807  *   size of memory per segment
 808  *
 809  * @return
 810  *   0 - on success
 811  */
 812 int32_t xran_mm_init (void * pHandle, uint64_t nMemorySize, uint32_t nMemorySegmentSize);
 813
 814 /**
 815  * @ingroup xran
 816  *
 817  *   Function allocates buffer memory (bm) used between XRAN layer and PHY. In general case it's DPDK mbuf.
 818  *   it uses Memory Management system to get memory chunk and define memory pool on top of it.
 819  *
 820  * @param pHandle
 821  *   Pointer to XRAN layer handle for given CC
 822  * @param nPoolIndex
 823  *   pointer to buffer pool identification to be returned
 824  * @param nNumberOfBuffers
 825  *   number of buffer to allocate in the pool
 826  * @param nBufferSize
 827  *   buffer size to allocate
 828  *
 829  * @return
 830  *   0 - on success
 831  */
 832 int32_t xran_bm_init (void * pHandle, uint32_t * pPoolIndex, uint32_t nNumberOfBuffers, uint32_t nBufferSize);
 833
 834 /**
 835  * @ingroup xran
 836  *
 837  *   Function allocates buffer used between XRAN layer and PHY. In general case it's DPDK mbuf.
 838  *
 839  * @param pHandle
 840  *   Pointer to XRAN layer handle for given CC
 841  * @param nPoolIndex
 842  *   buffer pool identification
 843  * @param ppData
 844  *   Pointer to pointer where to store address of new buffer
 845  * @param ppCtrl
 846  *   Pointer to pointer where to store address of internal private control information
 847  *
 848  *
 849  * @return
 850  *   0 - on success
 851  */
 852 int32_t xran_bm_allocate_buffer(void * pHandle, uint32_t nPoolIndex, void **ppData,  void **ppCtrl);
 853
 854 /**
 855  * @ingroup xran
 856  *
 857  *   Function frees buffer used between XRAN layer and PHY. In general case it's DPDK mbuf
 858  *
 859  * @param pHandle
 860  *   Pointer to XRAN layer handle for given CC
 861  * @param pData
 862  *   Pointer to buffer
 863  * @param pData
 864  *   Pointer to internal private control information
 865  *
 866  * @return
 867  *   0 - on success
 868  */
 869 int32_t xran_bm_free_buffer(void * pHandle, void *pData, void *pCtrl);
 870
 871 /**
 872  * @ingroup xran
 873  *
 874  *   Function destroys Memory Management (MM) layer of XRAN library
 875  *
 876  * @param pHandle
 877  *   Pointer to XRAN layer handle for given CC
 878  *
 879  * @return
 880  *   0 - on success
 881  */
 882 int32_t xran_mm_destroy (void * pHandle);
 883
 884 /**
 885  * @ingroup xran
 886  *
 887  *   Function configures TX(DL) and RX(UL) output buffers and callback (UL only) for XRAN layer with
 888  *   given handle
 889  *
 890  * @param pHandle
 891  *   Pointer to XRAN layer handle for given CC
 892  * @param pSrcBuffer
 893  *   list of memory buffers to use to fetch IQs from PHY to XRAN layer (DL)
 894  * @param pSrcCpBuffer
 895  *   list of memory buffers to use to configure C-plane (DL)
 896  * @param pDstBuffer
 897  *   list of memory buffers to use to deliver IQs from XRAN layer to PHY (UL)
 898  * @param pDstCpBuffer
 899  *   list of memory buffers to use to configure C-plane (UL)
 900  * @param xran_transport_callback_fn pCallback
 901  *   Callback function to call with arrival of all packets for given CC for given symbol
 902  * @param pCallbackTag
 903  *   Parameters of Callback function
 904  *
 905  * @return
 906  *   0  - on success
 907  *   -1 - on error
 908  */
 909  int32_t xran_5g_fronthault_config (void * pHandle,
 910                     struct xran_buffer_list *pSrcBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 911                     struct xran_buffer_list *pSrcCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 912                     struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 913                     struct xran_buffer_list *pDstCpBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 914                     xran_transport_callback_fn pCallback,
 915                     void *pCallbackTag);
 916
 917 /**
 918  * @ingroup xran
 919  *
 920  *   Function configures PRACH output buffers and callback for XRAN layer with given handle
 921  *
 922  * @param pHandle
 923  *   Pointer to XRAN layer handle for given CC
 924  * @param pDstBuffer
 925  *   list of memory buffers to use to deliver PRACH IQs from xran layer to PHY
 926  * @param xran_transport_callback_fn pCallback
 927  *   Callback function to call with arrival of PRACH packets for given CC
 928  * @param pCallbackTag
 929  *   Parameters of Callback function
 930  *
 931  * @return
 932  *   0  - on success
 933  *   -1 - on error
 934  */
 935 int32_t xran_5g_prach_req (void *  pHandle,
 936                 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 937                 struct xran_buffer_list *pDstBufferDecomp[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 938                 xran_transport_callback_fn pCallback,
 939                 void *pCallbackTag);
 940
 941 /**
 942  * @ingroup xran
 943  *
 944  *   Function configures SRS output buffers and callback for XRAN layer with given handle
 945  *
 946  * @param pHandle
 947  *   Pointer to XRAN layer handle for given CC
 948  * @param pDstBuffer
 949  *   list of memory buffers to use to deliver SRS IQs from xran layer to PHY
 950  * @param xran_transport_callback_fn pCallback
 951  *   Callback function to call with arrival of SRS packets for given CC
 952  * @param pCallbackTag
 953  *   Parameters of Callback function
 954  *
 955  * @return
 956  *   0  - on success
 957  *   -1 - on error
 958  */
 959 int32_t xran_5g_srs_req (void *  pHandle,
 960                 struct xran_buffer_list *pDstBuffer[XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_N_FE_BUF_LEN],
 961                 struct xran_buffer_list *pDstCpBuffer[XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_N_FE_BUF_LEN],
 962                 xran_transport_callback_fn pCallback,
 963                 void *pCallbackTag);
 964
 965
 966 /**
 967  * @ingroup xran
 968  *
 969  *   Function returns XRAN core utilization stats
 970  *
 971  * @param total_time (out)
 972  *   Pointer to variable to store Total time thread has been running
 973  * @param used_time (out)
 974  *   Pointer to variable to store Total time essential tasks have been running on the thread
 975  * @param core_used (out)
 976  *   Pointer to variable to store Core on which the XRAN thread is running
 977  * @param clear (in)
 978  *   If set to 1, then internal variables total_time and used_time are cleared
 979  *
 980  * @return
 981  *   0 - on success
 982  */
 983 uint32_t xran_get_time_stats(uint64_t *total_time, uint64_t *used_time, uint32_t *num_core_used, uint32_t *core_used, uint32_t clear);
 984
 985 /**
 986  * @ingroup xran
 987  *
 988  *   Function opens XRAN layer with given handle
 989  *
 990  * @param pHandle
 991  *   Pointer to XRAN layer handle for given CC
 992  * @param pointer to struct xran_fh_config pConf
 993  *   Pointer to XRAN configuration structure with specific settings to use
 994  *
 995  * @return
 996  *   0 - on success
 997  */
 998 int32_t xran_open(void *pHandle, struct xran_fh_config* pConf);
 999
1000 /**
1001  * @ingroup xran
1002  *
1003  *   Function starts XRAN layer with given handle
1004  *
1005  * @param pHandle
1006  *   Pointer to XRAN layer handle for given CC
1007  *
1008  * @return
1009  *   0 - on success
1010  */
1011 int32_t xran_start(void *pHandle);
1012
1013 /**
1014  * @ingroup xran
1015  *
1016  *   Function stops XRAN layer with given handle
1017  *
1018  * @param pHandle
1019  *   Pointer to XRAN layer handle for given CC
1020  *
1021  * @return
1022  *   0 - on success
1023  */
1024 int32_t xran_stop(void *pHandle);
1025
1026 /**
1027  * @ingroup xran
1028  *
1029  *   Function closes XRAN layer with given handle
1030  *
1031  * @param pHandle
1032  *   Pointer to XRAN layer handle for given CC
1033  *
1034  * @return
1035  *   0 - on success
1036  */
1037 int32_t xran_close(void *pHandle);
1038
1039 /**
1040  * @ingroup xran
1041  *
1042  *   Function registers callback to XRAN layer. Function support callbacks aligned on packet arrival.
1043  *
1044  * @param pHandle
1045  *   Pointer to XRAN layer handle for given CC
1046  * @param symCb
1047  *   pointer to callback function
1048  * @param symCbParam
1049  *   pointer to Callback Function parameters
1050  * @param symb
1051  *   symbol to be register for
1052  * @param cb_per_sym_type_id
1053  *   call back time identification (see enum cb_per_sym_type_id)
1054  *
1055  * @return
1056  *    0 - in case of success
1057  *   -1 - in case of failure
1058  */
1059 int32_t xran_reg_sym_cb(void *pHandle, xran_callback_sym_fn symCb, void * symCbParam, struct xran_sense_of_time* symCbTime,  uint8_t symb, enum cb_per_sym_type_id cb_sym_t_id);
1060
1061
1062 /**
1063  * @ingroup xran
1064  *
1065  *   Function registers callback to XRAN layer. Function support callbacks align to OTA time. TTI even, half of slot,
1066  *   full slot with respect to PTP time.
1067  *
1068  * @param pHandle
1069  *   Pointer to XRAN layer handle for given CC
1070  * @param Cb
1071  *   pointer to callback function
1072  * @param cbParam
1073  *   pointer to Callback Function parameters
1074  * @param skipTtiNum
1075  *   number of calls to be skipped before first call
1076  * @param callback_to_phy_id
1077  *   call back time identification (see enum callback_to_phy_id)
1078  *
1079  * @return
1080  *    0 - in case of success
1081  *   -1 - in case of failure
1082  */
1083 int32_t xran_reg_physide_cb(void *pHandle, xran_fh_tti_callback_fn Cb, void *cbParam, int skipTtiNum, enum callback_to_phy_id);
1084
1085 /**
1086  * @ingroup xran
1087  *
1088  *   Function returns current TTI, Frame, Subframe, Slot Number as seen "Over air" base on PTP time
1089  *
1090  * @param nFrameIdx
1091  *    Pointer to Frame number [0-99]
1092  *
1093  * @param nSubframeIdx
1094  *    Pointer to Subframe number [0-10]
1095  *
1096  * @param nSlotIdx
1097  *    Pointer to Slot number [0-7]
1098  *
1099  * @param nSecond
1100  *    Pointer to current UTC second
1101  *
1102  * @return
1103  *   current TTI number [0-7999]
1104  */
1105 int32_t xran_get_slot_idx (uint32_t PortId, uint32_t *nFrameIdx, uint32_t *nSubframeIdx,  uint32_t *nSlotIdx, uint64_t *nSecond);
1106
1107 /**
1108  * @ingroup xran
1109  *
1110  *   Function returns whether it is a prach slot or not based on given port and slot number
1111  *
1112  * @param PortId
1113  *    xRAN Port Id
1114  *
1115  * @param subframe_id
1116  *    Subframe number [0-9]
1117  *
1118  * @param slot_id
1119  *    Pointer to Slot number [0-7]
1120  *
1121  * @return
1122  *   whether it is a prach slot or not
1123  */
1124 int32_t xran_is_prach_slot(uint8_t PortId, uint32_t subframe_id, uint32_t slot_id);
1125
1126 /**
1127  * @ingroup xran
1128  *
1129  *   Function retrun XRAN layer common counters for given handle
1130  *
1131  * @param pHandle
1132  *   Pointer to XRAN layer handle for given CC
1133  *
1134  * @param pStats
1135  *   Pointer to pointer of common counter structure
1136  *
1137  * @return
1138  *   0 - on success
1139  */
1140 int32_t xran_get_common_counters(void *pXranLayerHandle, struct xran_common_counters *pStats);
1141
1142
1143 /**
1144  * @ingroup xran
1145  *
1146  *   Function returns status of operation of FH layer
1147  *
1148  * @return
1149  *  XRAN_INIT    - init state
1150  *  XRAN_RUNNING - running
1151  *  XRAN_STOPPED - stopped
1152  */
1153 enum xran_if_state xran_get_if_state(void);
1154
1155
1156 /**
1157  * @ingroup xran
1158  *
1159  *   Function allocates memory of given size from heap
1160  *
1161  * @param buf_len
1162  *   buffer size
1163  *
1164  * @return
1165  *   buf_len - size of memory allocation
1166  */
1167 void*    xran_malloc(size_t buf_len);
1168
1169 /**
1170  * @ingroup xran
1171  *
1172  *   Function frees memory of given size from heap
1173  *
1174  * @param buf_len
1175  *   addr - pointer to buffer
1176  *
1177  * @return
1178  *   void
1179  */
1180 void  xran_free(void *addr);
1181
1182 /**
1183  * @ingroup xran
1184  *
1185  *   Function calculates offset for ptr according to ORAN headers requared
1186  *
1187  * @param dst
1188  *   pointer to be addjusted
1189  * @compMethod
1190  *   compression method according to enum xran_compression_method
1191  *
1192  * @return
1193  *   ptr - pointer to payload given header requared
1194  */
1195 uint8_t* xran_add_hdr_offset(uint8_t  *dst, int16_t compMethod);
1196
1197 /**
1198  * @ingroup xran
1199  *
1200  *   Function calculates offset for ptr according to ORAN C-plane headers requared
1201  *
1202  * @param dst
1203  *   pointer to be addjusted
1204  *
1205  * @return
1206  *   ptr - pointer to payload given header requared
1207  */
1208 uint8_t  *xran_add_cp_hdr_offset(uint8_t  *dst);
1209
1210 /**
1211  * @ingroup xran
1212  *
1213  *   Debug function to trigger stop on 1pps (GPS second) boundary
1214  *
1215  * @param value
1216  *   1 - enable stop
1217  *   0 - disable stop
1218  * @param count
1219  *   enable auto stop after number of Tx packets
1220  * @return
1221  *    0 - on success
1222  */
1223 int32_t xran_set_debug_stop(int32_t value, int32_t count);
1224 #ifdef __cplusplus
1225 }
1226 #endif
1227
1228 #endif /* _XRAN_FH_O_DU_H_*/