fhi_lib/lib/api/xran_fh_lls_cu.h

   1 /******************************************************************************
   2 *
   3 *   Copyright (c) 2019 Intel.
   4 *
   5 *   Licensed under the Apache License, Version 2.0 (the "License");
   6 *   you may not use this file except in compliance with the License.
   7 *   You may obtain a copy of the License at
   8 *
   9 *       http://www.apache.org/licenses/LICENSE-2.0
  10 *
  11 *   Unless required by applicable law or agreed to in writing, software
  12 *   distributed under the License is distributed on an "AS IS" BASIS,
  13 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 *   See the License for the specific language governing permissions and
  15 *   limitations under the License.
  16 *
  17 *******************************************************************************/
  18
  19
  20 /**
  21  * @brief This file provides public interface to XRAN Front Haul layer implementation as defined in the
  22  *      XRAN-FH.CUS.0-v02.00 spec. Implementation is specific to lls-CU node
  23  *      for 5G NR Radio Access technology
  24  *
  25  * @file xran_fh_lls_cu.h
  26  * @ingroup group_lte_source_xran
  27  * @author Intel Corporation
  28  *
  29  **/
  30
  31 #ifndef _XRAN_FH_LLS_CU_H_
  32 #define _XRAN_FH_LLS_CU_H_
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #include <stdio.h>
  39 #include <stdlib.h>
  40 #include <string.h>
  41 #include <stdint.h>
  42 #include <inttypes.h>
  43 #include <sys/types.h>
  44 #include <sys/queue.h>
  45 #include <netinet/in.h>
  46 #include <setjmp.h>
  47 #include <stdarg.h>
  48 #include <ctype.h>
  49 #include <errno.h>
  50 #include <getopt.h>
  51 #include <unistd.h>
  52
  53 #define XRAN_STATUS_SUCCESS (0)
  54 /**<
  55  *  @ingroup xran
  56  *   Success status value. */
  57 #define XRAN_STATUS_FAIL (-1)
  58 /**<
  59  *  @ingroup xran
  60  *   Fail status value. */
  61
  62 #define XRAN_STATUS_RETRY (-2)
  63 /**<
  64  *  @ingroup xran
  65  *  Retry status value. */
  66
  67 #define XRAN_STATUS_RESOURCE (-3)
  68 /**<
  69  *  @ingroup xran
  70  *  The resource that has been requested is unavailable. Refer
  71  *  to relevant sections of the API for specifics on what the suggested
  72  *  course of action is. */
  73
  74 #define XRAN_STATUS_INVALID_PARAM (-4)
  75 /**<
  76  *  @ingroup xran
  77  *  Invalid parameter has been passed in. */
  78 #define XRAN_STATUS_FATAL (-5)
  79 /**<
  80  *  @ingroup xran
  81  *  A serious error has occurred. Recommended course of action
  82  *  is to shutdown and restart the component. */
  83
  84 #define XRAN_STATUS_UNSUPPORTED (-6)
  85 /**<
  86  *  @ingroup xran
  87  *  The function is not supported, at least not with the specific
  88  *  parameters supplied.  This may be because a particular
  89  *  capability is not supported by the current implementation. */
  90
  91 /** Macro to calculate TTI number [0:7999] from symbol index [0: 112000-1] used by timing thread */
  92 #define XranGetTtiNum(symIdx, numSymPerTti) (((uint32_t)symIdx / (uint32_t)numSymPerTti))
  93 /** Macro to calculate Symbol number [0:7] for given slot from symbol index [0: 112000-1] */
  94 #define XranGetSymNum(symIdx, numSymPerTti) (((uint32_t)symIdx % (uint32_t)numSymPerTti))
  95 /** Macro to calculate Frame number [0:99] for given tti [0: 7999] */
  96 #define XranGetFrameNum(tti,numSubFramePerSystemFrame, numSlotPerSubFrame)  ((uint32_t)tti / ((uint32_t)numSubFramePerSystemFrame * (uint32_t)numSlotPerSubFrame))
  97 /** Macro to calculate Subframe number [0:9] for given tti [0: 7999] */
  98 #define XranGetSubFrameNum(tti, numSlotPerSubFrame, numSubFramePerSystemFrame) (((uint32_t)tti/(uint32_t)numSlotPerSubFrame) % (uint32_t)numSubFramePerSystemFrame)
  99 /** Macro to calculate Slot number [0:7] for given tti [0: 7999] */
 100 #define XranGetSlotNum(tti, numSlotPerSfn) ((uint32_t)tti % ((uint32_t)numSlotPerSfn))
 101
 102 #define XRAN_PORTS_NUM      (1) /**< number of XRAN ports supported */
 103 #define XRAN_N_FE_BUF_LEN   (80)/** Number of TTIs (slots) */
 104 #define XRAN_MAX_SECTOR_NR  (4) /**< Max sectors per XRAN port */
 105 #define XRAN_MAX_ANTENNA_NR (4) /**< Max antenna per port */
 106 #define XRAN_NUM_OF_SYMBOL_PER_SLOT          ( 14 ) /**< Number of symbols per slot */
 107
 108 #define XRAN_MAX_CELLS_PER_PORT      (4) /**< Max cells mapped to XRAN port */
 109 #define XRAN_COMPONENT_CARRIERS_MAX  XRAN_MAX_SECTOR_NR /**< number of CCs */
 110 #define XRAN_NUM_OF_ANT_RADIO        16  /**< Max Number of Antennas supported for all CC on single XRAN port */
 111
 112 #define XRAN_MAX_PKT_BURST (448+4) /**< 4x14x8 symbols per ms */
 113 #define XRAN_N_MAX_BUFFER_SEGMENT XRAN_MAX_PKT_BURST /**< Max number of segments per ms */
 114
 115 #define XRAN_STRICT_PARM_CHECK      (1) /**< enable parameter check for C-plane */
 116
 117 //#define _XRAN_DEBUG   /**< Enable debug log */
 118 //#define _XRAN_VERBOSE /**< Enable verbose log */
 119
 120 #ifdef _XRAN_DEBUG
 121     #define xran_log_dbg(fmt, ...)          \
 122         fprintf(stderr,                     \
 123             "DEBUG: %s(%d): " fmt "\n",     \
 124             __FILE__,                       \
 125             __LINE__, ##__VA_ARGS__)
 126 #else
 127     #define xran_log_dbg(fmt, ...)
 128 #endif
 129
 130 #if defined(_XRAN_DEBUG) || defined(_XRAN_VERBOSE)
 131     #define xran_log_wrn(fmt, ...)          \
 132         fprintf(                            \
 133             stderr,                         \
 134             "WARNING: %s(%d): " fmt "\n",   \
 135             __FILE__,                       \
 136             __LINE__, ##__VA_ARGS__)
 137 #else
 138     #define xran_log_dbg(fmt, ...)
 139     #define xran_log_wrn(fmt, ...)
 140 #endif
 141
 142 #define xran_log_err(fmt, ...)          \
 143     fprintf(stderr,                     \
 144         "ERROR: %s(%d): " fmt "\n",     \
 145         __FILE__,                       \
 146         __LINE__, ##__VA_ARGS__)
 147
 148 /**
 149  ******************************************************************************
 150  * @ingroup xran
 151  *
 152  * @description
 153  *      Compression Method 6.3.3.13, Table 6-43
 154  *****************************************************************************/
 155 enum xran_compression_method {
 156     XRAN_COMPMETHOD_NONE        = 0,
 157     XRAN_COMPMETHOD_BLKFLOAT    = 1,
 158     XRAN_COMPMETHOD_BLKSCALE    = 2,
 159     XRAN_COMPMETHOD_ULAW        = 3,
 160     XRAN_COMPMETHOD_MODULATION  = 4,
 161     XRAN_COMPMETHOD_MAX
 162     };
 163
 164 /**
 165  ******************************************************************************
 166  * @ingroup xran
 167  *
 168  * @description
 169  *      Callback function type for symbol packet enum
 170  *****************************************************************************/
 171 enum callback_to_phy_id
 172 {
 173     XRAN_CB_TTI = 0, /**< callback on TTI boundary */
 174     XRAN_CB_HALF_SLOT_RX =1, /**< callback on half slot (sym 7) packet arrival*/
 175     XRAN_CB_FULL_SLOT_RX =2, /**< callback on full slot (sym 14) packet arrival */
 176     XRAN_CB_MAX /**< max number of callbacks */
 177 };
 178
 179 typedef int32_t XranStatusInt32; /**< Xran status return value */
 180
 181 /** callback function type for Symbol packet */
 182 typedef void (*XRANFHSYMPROCCB)(void*);
 183
 184 /** Callback function type for TTI event */
 185 typedef int (*XRANFHTTIPROCCB)(void* );
 186
 187 /** Callback function type packet arrival from transport layer (ETH or IP) */
 188 typedef void (*XranTransportBlockCallbackFn)(void*, int32_t);
 189
 190 /**
 191 * Component Carrier Initialization
 192 */
 193 typedef struct tagXRANCCINIT
 194 {
 195     uint32_t RadioMode; /**< XRAN mode Cat A or Cat B on given CC */
 196     uint32_t nTxAnt;    /**< Number of TX antennas */
 197     uint32_t nRxAnt;    /**< Number of RX antennas */
 198     uint32_t radiobw;   /**< bandwidth id */
 199     uint32_t dpdk_port; /**< networking layer port id */
 200     char *dpdk_pcie_eth_dev; /**< pcie device for this cc */
 201     char *ru_mac_str;       /**< mac address of RU */
 202     uint32_t ulAgc;     /**< state of UL AGC (ON/OFF) */
 203     uint32_t numCell;   /**< Number of Cells per port per CC */
 204     uint32_t phyInsId[XRAN_MAX_CELLS_PER_PORT]; /**< Mapping of Cell ID to CC */
 205     uint32_t dpdkRxCore; /**< DPDK RX Core */
 206     uint32_t dpdkTxCore; /**< DPDK TX Core */
 207 }XRANCCINIT, *PXRANCCINIT;
 208
 209 /** XRAN port enum */
 210 enum xran_vf_ports
 211 {
 212     XRAN_UP_VF = 0, /**< port type for U-plane */
 213     XRAN_CP_VF,     /**< port type for C-plane */
 214     XRAN_VF_MAX
 215 };
 216
 217 /** DPDK IO configuration for XRAN layer */
 218 typedef struct tagXRAN_IO_LOOP_CFG
 219 {
 220     uint8_t id;
 221     char *dpdk_dev[XRAN_VF_MAX];
 222     int core;
 223     int system_core;    /* Needed as DPDK will change your starting core. */
 224     int pkt_proc_core;  /* Needed for packet processing thread. */
 225     int pkt_aux_core;   /* Needed for debug purposes. */
 226     int timing_core;    /* Needed for getting precise time */
 227     int port[XRAN_VF_MAX];  /* This is auto-detected, no need to set. */
 228 }XRAN_IO_LOOP_CFG, *PXRAN_IO_LOOP_CFG;
 229
 230 /** XRAN spec section 3.1.3.1.6 ecpriRtcid / ecpriPcid define */
 231 typedef struct tagXRANEAXCIDCONFIG
 232 {
 233     uint16_t mask_cuPortId;     /**< Mask CU PortId */
 234     uint16_t mask_bandSectorId; /**< Mask Band */
 235     uint16_t mask_ccId;         /**< Mask CC */
 236     uint16_t mask_ruPortId;     /**< Mask RU Port ID */
 237
 238     uint8_t bit_cuPortId;       /**< bandsectorId + ccId + ruportId */
 239     uint8_t bit_bandSectorId;   /**< ccId + ruPortId */
 240     uint8_t bit_ccId;           /**<  ruportId */
 241     uint8_t bit_ruPortId;       /**<  0 */
 242 }XRANEAXCIDCONFIG, *PXRANEAXCIDCONFIG;
 243
 244 /**
 245 * XRAN Front haul interface initialization settings
 246 */
 247 typedef struct tagXRANFHINIT
 248 {
 249     uint32_t llscuId;    /**< lls-cu ID */
 250     uint32_t nSec;       /**< number of sectors, shall be 1 */
 251     XRANCCINIT ccCfg[XRAN_COMPONENT_CARRIERS_MAX]; /**< configuration of each CCs */
 252     XRANEAXCIDCONFIG eAxCId_conf; /**< config of ecpriRtcid/ecpriPcid */
 253     uint32_t radio_iface;         /**< enable/disable radio */
 254     uint32_t dpdkMasterCore;      /**< master core of DPDK */
 255     uint32_t dpdkMemorySize;      /**< huge pages allocation for DPDK */
 256     uint32_t dpdkIrqMode;         /**< DPDK IRQ or PMD mode */
 257     uint32_t dpdkBasebandFecMode; /**< DPDK Baseband FEC device mode (0-SW, 1-HW) */
 258     char *dpdkBasebandDevice;     /**< DPDK Baseband device address */
 259     uint32_t singleThreadTxRx;
 260     uint32_t bbuPoolCores;  /**< DPDK cores for BBU pool */
 261     uint32_t radioEnabled;  /**< reserved */
 262     uint32_t powerSaveEn;   /**< reserved */
 263     char *filePrefix;       /**< DPDK prefix */
 264     XRAN_IO_LOOP_CFG io_cfg;/**< DPDK IO for XRAN */
 265     uint8_t xranMode;       /**< mode: lls-CU or RU */
 266     int8_t *p_lls_cu_addr;  /**<  lls-CU Ethernet Mac Address */
 267     int8_t *p_ru_addr;      /**<  RU Ethernet Mac Address */
 268     uint32_t ttiPeriod;     /**< TTI period */
 269
 270     uint16_t Tadv_cp_dl;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 271     uint16_t T2a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 272     uint16_t T2a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 273     uint16_t T2a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 274     uint16_t T2a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 275     uint16_t T2a_min_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 276     uint16_t T2a_max_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 277     uint16_t Ta3_min;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 278     uint16_t Ta3_max;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 279     uint16_t T1a_min_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 280     uint16_t T1a_max_cp_dl; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 281     uint16_t T1a_min_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 282     uint16_t T1a_max_cp_ul; /**< Table 2 7 : xRAN Delay Management Model Parameters */
 283     uint16_t T1a_min_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 284     uint16_t T1a_max_up;    /**< Table 2 7 : xRAN Delay Management Model Parameters */
 285     uint16_t Ta4_min;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 286     uint16_t Ta4_max;       /**< Table 2 7 : xRAN Delay Management Model Parameters */
 287
 288     uint8_t enableCP;    /**<  enable C-plane */
 289     uint8_t cp_vlan_tag; /**<  C-plane vlan tag */
 290     uint8_t up_vlan_tag; /**<  U-plane vlan tag */
 291     int32_t debugStop;   /**<  enable auto stop */
 292 } XRANFHINIT, *PXRANFHINIT;
 293
 294 /** XRAN Playback format */
 295 typedef enum {
 296     XRAN_RADIO_PLAYBACK_TIME_DOMAIN = 0,
 297     XRAN_RADIO_PLAYBACK_FREQ_DOMAIN = 1
 298 } XranPlaybackFormatEnum;
 299
 300 /* PRACH config required for XRAN based FH */
 301 typedef struct tagXRANPRACHCONFIG
 302 {
 303     /**** word 5 *****/
 304     /* PRACH config*/
 305     /** PRACH Configuration Index*/
 306     uint8_t      nPrachConfIdx;
 307     /** PRACH Sub-carrier spacing
 308     Value:0->1
 309     For below 6GHz the values indicate 15kHz or 30kHz
 310     For above 6GHz the values indicate 60kHz or 120kHz*/
 311     /*PRACH zeroCorrelationZoneConfig */
 312     uint8_t      nPrachSubcSpacing;
 313     /** PRACH zeroCorrelationZoneConfig */
 314     uint8_t      nPrachZeroCorrConf;
 315     /** PRACH restrictedSetConfig */
 316     uint8_t      nPrachRestrictSet;
 317
 318     /**** word 6 *****/
 319     /** PRACH Root Sequence Index */
 320     uint16_t     nPrachRootSeqIdx;
 321     /** PRACH prach-frequency-start  */
 322     uint16_t     nPrachFreqStart;
 323
 324     /** PRACH prach-frequency-offset */
 325     int32_t     nPrachFreqOffset;
 326     /** PRACH Filter index */
 327     uint8_t     nPrachFilterIdx;
 328 }XRANPRACHCONFIG, *PXRANPRACHCONFIG;
 329
 330 /** XRAN front haul playback configuration (not supported in 19.03) */
 331 typedef struct tagXRANFHPLAYBACK
 332 {
 333     XranPlaybackFormatEnum TxPlayFormatType; /**< type of play back files [Time|Freq] */
 334
 335     unsigned long TxPlayBufAddr[XRAN_NUM_OF_ANT_RADIO]; /**< pointer to buffers to play */
 336     uint32_t TxPlayBufSize; /**< Buffer size */
 337
 338     char*      TxPlayFileName[XRAN_NUM_OF_ANT_RADIO]; /**< files to play */
 339     uint32_t   TxPlayFileSize; /**< expected the same size for all Ant */
 340
 341 }XRANPLAYBACKCONFIG,*PXRANPLAYBACKCONFIG;
 342
 343 /** XRAN front haul logging configuration (not supported in 19.03) */
 344 typedef struct tagXRANFHLOGCONF
 345 {
 346     /* logging */
 347     unsigned long TxLogBufAddr;
 348     uint32_t TxLogBufSize;
 349
 350     unsigned long TxLogIfftInAddr;
 351     uint32_t  TxLogIfftInSize;
 352
 353     unsigned long TxLogIfft1200InAddr;
 354     uint32_t  TxLogIfft1200InSize;
 355
 356     unsigned long RxLogFftOutAddr;
 357     uint32_t  RxLogFftOutSize;
 358
 359     unsigned long RxLogFftOutExpAddr;
 360     uint32_t  RxLogFftOutExpSize;
 361
 362     unsigned long RxLogFftOutGainAddr;
 363     uint32_t  RxLogFftOutGainSize;
 364
 365     unsigned long RxLogBufAddr;
 366     uint32_t  RxLogBufSize;
 367
 368     unsigned long RxLogAlawBufAddr;
 369     uint32_t  RxLogAlawBufSize;
 370
 371     unsigned long RxLogPrachBufAddr;
 372     uint32_t  RxLogPrachBufSize;
 373
 374     uint32_t  cfg_dl_iq_buf_enabled;
 375     uint32_t  cfg_ul_iq_buf_enabled;
 376
 377 }XRANFHLOGCONF, *PXRANFHLOGCONF;
 378
 379 /** XRAN front haul frame config */
 380 typedef struct tagXRANFRAMECONFIG
 381 {
 382     /** Frame Duplex type:  0 -> FDD, 1 -> TDD */
 383     uint8_t      nFrameDuplexType;
 384     /** Numerology, determine sub carrier spacing, Value: 0->4
 385        0: 15khz,  1: 30khz,  2: 60khz
 386        3: 120khz, 4: 240khz */
 387     uint8_t      nNumerology;
 388     /** TDD period */
 389     uint8_t      nTddPeriod;
 390 }XRANFRAMECONFIG, *PXRANFRAMECONFIG;
 391
 392 /** XRAN front haul BBU pooling config */
 393 typedef struct tagXRANBBUPOOLCONFIG
 394 {
 395     uint32_t isBbuPool; /**< FH running with BBU pool */
 396 }XRANBBUPOOLCONFIG, *PXRANBBUPOOLCONFIG;
 397
 398 /** XRAN front haul IQ compression settings */
 399 typedef struct tagXRANRUCONFIG
 400 {
 401     uint8_t iqWidth;        /**< IQ bit width */
 402     uint8_t compMeth;       /**< Compression method */
 403     uint8_t fftSize;        /**< FFT Size */
 404 }XRANRUCONFIG, *PXRANRUCONFIG;
 405
 406 /** XRAN front haul Phase compensation settings */
 407 typedef struct
 408 {
 409     uint32_t nSecNum;
 410     uint32_t nPhaseCompFlag;
 411     uint32_t nDlArfcn[XRAN_MAX_SECTOR_NR];
 412     uint32_t nUlArfcn[XRAN_MAX_SECTOR_NR];
 413 }XRANPHASECompConfig;
 414
 415 /**
 416  * @ingroup xran
 417  *XRAN front haul general configuration */
 418 typedef struct tagXRANFHCONFIG
 419 {
 420     uint32_t            dpdk_port; /**< DPDK port number used for FH */
 421     uint32_t            sector_id; /**< Band sector ID for FH */
 422     uint32_t            nCC;       /**< number of Component carriers supported on FH */
 423     uint32_t            neAxc;     /**< number of eAxc supported on FH */
 424     XRANPLAYBACKCONFIG  playback_conf;/**< configuration of playback of IQs supported with FH */
 425     XRANFHLOGCONF       log_conf;     /**< config of logging functionality supported by FH */
 426     XRANFHTTIPROCCB     ttiCb;        /**< call back for TTI event */
 427     void                *ttiCbParam;  /**< parameters of call back function */
 428     XRANPRACHCONFIG     prach_conf;   /**< PRACH specific configurations for FH */
 429     XRANFRAMECONFIG     frame_conf;   /**< frame config */
 430     XRANBBUPOOLCONFIG   bbu_conf;     /**< BBU pool config */
 431     XRANRUCONFIG        ru_conf;      /**< config of RU as per XRAN spec */
 432     XRANPHASECompConfig phase_compensation; /**< phase compensation settings */
 433 }XRANFHCONFIG, *PXRANFHCONFIG;
 434
 435
 436 /**
 437  * @ingroup xran
 438  * CC instance handle pointer type */
 439 typedef void * XranCcInstanceHandleVoidP;
 440
 441 /**
 442  *****************************************************************************
 443  * @ingroup xran
 444  *
 445  * @description
 446  *      A flat buffer structure. The data pointer, pData, is a virtual address.
 447  *      The API requires the memory to by physically contiguous. Each flat
 448  *      buffer segment may contain several equally sized elements.
 449  *
 450  *****************************************************************************/
 451 typedef struct XRANFlatBuffer
 452 {
 453     uint32_t nElementLenInBytes;
 454     /**< The Element length specified in bytes.
 455      * This parameter specifies the size of a single element in the buffer.
 456      * The total size of the buffer is described as
 457      * bufferSize = nElementLenInBytes * nNumberOfElements */
 458     uint32_t nNumberOfElements;
 459     /**< The number of elements in the physical contiguous memory segment */
 460     uint32_t nOffsetInBytes;
 461     /**< Offset in bytes to the start of the data in the physical contiguous
 462      * memory segment */
 463     uint32_t nIsPhyAddr;
 464     uint8_t *pData;
 465     /**< The data pointer is a virtual address, however the actual data pointed
 466      * to is required to be in contiguous physical memory unless the field
 467      requiresPhysicallyContiguousMemory in CpaInstanceInfo is false. */
 468 } XRANFlatBufferStruct;
 469
 470 /**
 471  *****************************************************************************
 472  * @ingroup xran
 473  *      Scatter/Gather buffer list containing an array of Simple buffers.
 474  *
 475  * @description
 476  *      A Scatter/Gather buffer list structure. It is expected that this buffer
 477  *      structure will be used where more than one flat buffer can be provided
 478  *      on a particular API.
 479  *
 480  *      IMPORTANT - The memory for the pPrivateMetaData member must be allocated
 481  *      by the client as contiguous memory.  When allocating memory for
 482  *      pPrivateMetaData a call to cpaCyBufferListGetMetaSize MUST be made to
 483  *      determine the size of the Meta Data Buffer.  The returned size
 484  *      (in bytes) may then be passed in a memory allocation routine to allocate
 485  *      the pPrivateMetaData memory.
 486  *
 487  *****************************************************************************/
 488 typedef struct XRANBufferList
 489 {
 490     uint32_t nNumBuffers;
 491     /**< Number of pointers */
 492     XRANFlatBufferStruct *pBuffers;
 493     /**< Pointer to an unbounded array containing the number of CpaFlatBuffers
 494      * defined by nNumBuffers */
 495     void *pUserData;
 496     /**< This is an opaque field that is not read or modified internally. */
 497     void *pPrivateMetaData;
 498     /**< Private Meta representation of this buffer List - the memory for this
 499      * buffer needs to be allocated by the client as contiguous data.
 500      * The amount of memory required is returned with a call to
 501      * cpaCyBufferListGetMetaSize. If cpaCyBufferListGetMetaSize returns a size
 502      * of zero no memory needs to be allocated, and this parameter can be NULL.
 503      */
 504 } XRANBufferListStruct;
 505
 506 /**
 507  * @ingroup xran
 508  * Initialize the XRAN Layer via DPDK.
 509  *
 510  * @param argc
 511  *   A non-negative value.  If it is greater than 0, the array members
 512  *   for argv[0] through argv[argc] (non-inclusive) shall contain pointers
 513  *   to strings.
 514  * @param argv
 515  *   An array of strings.  The contents of the array, as well as the strings
 516  *   which are pointed to by the array, may be modified by this function.
 517  *
 518  * @return
 519  *   0 - on success
 520  *   Error codes returned via rte_errno
 521  */
 522 int32_t xran_init(int argc, char *argv[], PXRANFHINIT p_xran_fh_init, char *appName, void ** pHandle);
 523
 524 /**
 525  * @ingroup xran
 526  *
 527  *   Function returns handles for number of sectors supported by XRAN layer. Currently function
 528  *   supports one handle XRAN layer where it supports only one CC
 529  *
 530  * @param pHandle
 531  *   Pointer to XRAN layer handle
 532  * @param nNumInstances
 533  *   total number of instances of CC
 534  * @param pSectorInstanceHandles
 535  *   Pointer to XranCcInstanceHandleVoidP where to store Handle pointer
 536  *
 537  * @return
 538  *   0 - on success
 539  */
 540 int32_t xran_sector_get_instances (void * pHandle, uint16_t nNumInstances,
 541                XranCcInstanceHandleVoidP * pSectorInstanceHandles);
 542
 543 /**
 544  * @ingroup xran
 545  *
 546  *   Function initialize Memory Management subsystem (mm) in order to handle memory buffers between XRAN layer
 547  *   and PHY.
 548  *
 549  * @param pHandle
 550  *   Pointer to XRAN layer handle for given CC
 551  * @param nMemorySize
 552  *   memory size of all segments
 553  * @param nMemorySegmentSize
 554  *   size of memory per segment
 555  *
 556  * @return
 557  *   0 - on success
 558  */
 559 int32_t xran_mm_init (void * pHandle, uint64_t nMemorySize, uint32_t nMemorySegmentSize);
 560
 561 /**
 562  * @ingroup xran
 563  *
 564  *   Function allocates buffer memory (bm) used between XRAN layer and PHY. In general case it's DPDK mbuf.
 565  *   it uses Memory Management system to get memory chunk and define memory pool on top of it.
 566  *
 567  * @param pHandle
 568  *   Pointer to XRAN layer handle for given CC
 569  * @param nPoolIndex
 570  *   pointer to buffer pool identification to be returned
 571  * @param nNumberOfBuffers
 572  *   number of buffer to allocate in the pool
 573  * @param nBufferSize
 574  *   buffer size to allocate
 575  *
 576  * @return
 577  *   0 - on success
 578  */
 579 int32_t xran_bm_init (void * pHandle, uint32_t * pPoolIndex, uint32_t nNumberOfBuffers, uint32_t nBufferSize);
 580
 581 /**
 582  * @ingroup xran
 583  *
 584  *   Function allocates buffer used between XRAN layer and PHY. In general case it's DPDK mbuf.
 585  *
 586  * @param pHandle
 587  *   Pointer to XRAN layer handle for given CC
 588  * @param nPoolIndex
 589  *   buffer pool identification
 590  * @param ppVirtAddr
 591  *   Pointer to pointer where to store address of new buffer
 592  *
 593  * @return
 594  *   0 - on success
 595  */
 596 int32_t xran_bm_allocate_buffer(void * pHandle, uint32_t nPoolIndex, void **ppVirtAddr);
 597
 598 /**
 599  * @ingroup xran
 600  *
 601  *   Function frees buffer used between XRAN layer and PHY. In general case it's DPDK mbuf
 602  *
 603  * @param pHandle
 604  *   Pointer to XRAN layer handle for given CC
 605  * @param pVirtAddr
 606  *   Pointer to buffer
 607  *
 608  * @return
 609  *   0 - on success
 610  */
 611 int32_t xran_bm_free_buffer(void * pHandle, void *pVirtAddr);
 612
 613 /**
 614  * @ingroup xran
 615  *
 616  *   Function destroys Memory Management (MM) layer of XRAN library
 617  *
 618  * @param pHandle
 619  *   Pointer to XRAN layer handle for given CC
 620  *
 621  * @return
 622  *   0 - on success
 623  */
 624 int32_t xran_mm_destroy (void * pHandle);
 625
 626 /**
 627  * @ingroup xran
 628  *
 629  *   Function configures TX(DL) and RX(UL) output buffers and callback (UL only) for XRAN layer with
 630  *   given handle
 631  *
 632  * @param pHandle
 633  *   Pointer to XRAN layer handle for given CC
 634  * @param pSrcBuffer
 635  *   list of memory buffers to use to fetch IQs from PHY to XRAN layer (DL)
 636  * @param pDstBuffer
 637  *   list of memory buffers to use to deliver IQs from XRAN layer to PHY (UL)
 638  * @param XranTransportBlockCallbackFn pCallback
 639  *   Callback function to call with arrival of all packets for given CC for given symbol
 640  * @param pCallbackTag
 641  *   Parameters of Callback function
 642  *
 643  * @return
 644  *   0  - on success
 645  *   -1 - on error
 646  */
 647 int32_t xran_5g_fronthault_config (void * pHandle,
 648                 XRANBufferListStruct *pSrcBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 649                 XRANBufferListStruct *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 650                 XranTransportBlockCallbackFn pCallback,
 651                 void *pCallbackTag);
 652
 653 /**
 654  * @ingroup xran
 655  *
 656  *   Function configures PRACH output buffers and callback for XRAN layer with given handle
 657  *
 658  * @param pHandle
 659  *   Pointer to XRAN layer handle for given CC
 660  * @param pDstBuffer
 661  *   list of memory buffers to use to deliver PRACH IQs from xran layer to PHY
 662  * @param XranTransportBlockCallbackFn pCallback
 663  *   Callback function to call with arrival of PRACH packets for given CC
 664  * @param pCallbackTag
 665  *   Parameters of Callback function
 666  *
 667  * @return
 668  *   0  - on success
 669  *   -1 - on error
 670  */
 671 int32_t xran_5g_prach_req (void *  pHandle,
 672                 XRANBufferListStruct *pDstBuffer[XRAN_MAX_ANTENNA_NR][XRAN_N_FE_BUF_LEN],
 673                 XranTransportBlockCallbackFn pCallback,
 674                 void *pCallbackTag);
 675 /**
 676  * @ingroup xran
 677  *
 678  *   Function configures phase compensation for RU via XRAN layer with given handle
 679  *
 680  * @param pHandle
 681  *   Pointer to XRAN layer handle for given CC
 682  * @param nTxPhaseCps
 683  *   TX(DL) phase compensation settings
 684  * @param nTxPhaseCps
 685  *   RX(UL) phase compensation settings
 686  * @param nSectorId
 687  *   Sector id to use with given settings
 688  *
 689  * @return
 690  *   0 - on success
 691  */
 692 int32_t xran_5g_pre_compenstor_cfg(void* pHandle,
 693                 uint32_t nTxPhaseCps,
 694                 uint32_t nRxPhaseCps,
 695                 uint8_t nSectorId);
 696
 697 /**
 698  * @ingroup xran
 699  *
 700  *   Function opens XRAN layer with given handle
 701  *
 702  * @param pHandle
 703  *   Pointer to XRAN layer handle for given CC
 704  * @param PXRANFHCONFIG pConf
 705  *   Pointer to XRAN configuration structure with specific settings to use
 706  *
 707  * @return
 708  *   0 - on success
 709  */
 710 int32_t xran_open(void *pHandle, PXRANFHCONFIG pConf);
 711
 712 /**
 713  * @ingroup xran
 714  *
 715  *   Function starts XRAN layer with given handle
 716  *
 717  * @param pHandle
 718  *   Pointer to XRAN layer handle for given CC
 719  *
 720  * @return
 721  *   0 - on success
 722  */
 723 int32_t xran_start(void *pHandle);
 724
 725 /**
 726  * @ingroup xran
 727  *
 728  *   Function stops XRAN layer with given handle
 729  *
 730  * @param pHandle
 731  *   Pointer to XRAN layer handle for given CC
 732  *
 733  * @return
 734  *   0 - on success
 735  */
 736 int32_t xran_stop(void *pHandle);
 737
 738 /**
 739  * @ingroup xran
 740  *
 741  *   Function closes XRAN layer with given handle
 742  *
 743  * @param pHandle
 744  *   Pointer to XRAN layer handle for given CC
 745  *
 746  * @return
 747  *   0 - on success
 748  */
 749 int32_t xran_close(void *pHandle);
 750
 751 /**
 752  * @ingroup xran
 753  *
 754  *   Function registers callback to XRAN layer. Function support callbacks aligned on packet arrival.
 755  *
 756  * @param pHandle
 757  *   Pointer to XRAN layer handle for given CC
 758  * @param symCb
 759  *   pointer to callback function
 760  * @param symCb
 761  *   pointer to Callback Function parameters
 762  * @param symb
 763  *   symbol to be register for
 764  * @param ant
 765  *   Antenna number to trigger callback for packet arrival
 766  *
 767  * @return
 768  *    0 - in case of success
 769  *   -1 - in case of failure
 770  */
 771 int32_t xran_reg_sym_cb(void *pHandle, XRANFHSYMPROCCB symCb, void * symCbParam, uint8_t symb, uint8_t ant);
 772
 773 /**
 774  * @ingroup xran
 775  *
 776  *   Function registers callback to XRAN layer. Function support callbacks align to OTA time. TTI even, half of slot,
 777  *   full slot with respect to PTP time.
 778  *
 779  * @param pHandle
 780  *   Pointer to XRAN layer handle for given CC
 781  * @param Cb
 782  *   pointer to callback function
 783  * @param cbParam
 784  *   pointer to Callback Function parameters
 785  * @param skipTtiNum
 786  *   number of calls to be skipped before first call
 787  * @param callback_to_phy_id
 788  *   call back time identification (see enum callback_to_phy_id)
 789  *
 790  * @return
 791  *    0 - in case of success
 792  *   -1 - in case of failure
 793  */
 794 int32_t xran_reg_physide_cb(void *pHandle, XRANFHTTIPROCCB Cb, void *cbParam, int skipTtiNum, enum callback_to_phy_id);
 795
 796 /**
 797  * @ingroup xran
 798  *
 799  *   Function returns current TTI, Frame, Subframe, Slot Number as seen "Over air" base on PTP time
 800  *
 801  * @param nFrameIdx
 802  *    Pointer to Frame number [0-99]
 803  *
 804  * @param nSubframeIdx
 805  *    Pointer to Subframe number [0-10]
 806  *
 807  * @param nSlotIdx
 808  *    Pointer to Slot number [0-7]
 809  *
 810  * @param nSecond
 811  *    Pointer to current UTC second
 812  *
 813  * @return
 814  *   current TTI number [0-7999]
 815  */
 816 int32_t xran_get_slot_idx (uint32_t *nFrameIdx, uint32_t *nSubframeIdx,  uint32_t *nSlotIdx, uint64_t *nSecond);
 817
 818 #ifdef __cplusplus
 819 }
 820 #endif
 821
 822 #endif /* _XRAN_FH_LLS_CU_H_*/