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