fhi_lib/lib/api/xran_cp_api.h

   1 /******************************************************************************\r
   2 *\r
   3 *   Copyright (c) 2019 Intel.\r
   4 *\r
   5 *   Licensed under the Apache License, Version 2.0 (the "License");\r
   6 *   you may not use this file except in compliance with the License.\r
   7 *   You may obtain a copy of the License at\r
   8 *\r
   9 *       http://www.apache.org/licenses/LICENSE-2.0\r
  10 *\r
  11 *   Unless required by applicable law or agreed to in writing, software\r
  12 *   distributed under the License is distributed on an "AS IS" BASIS,\r
  13 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  14 *   See the License for the specific language governing permissions and\r
  15 *   limitations under the License.\r
  16 *\r
  17 *******************************************************************************/\r
  18 \r
  19 /**\r
  20  * @brief This file provides the definitions for Control Plane Messages APIs.\r
  21  *\r
  22  * @file xran_cp_api.h\r
  23  * @ingroup group_lte_source_xran\r
  24  * @author Intel Corporation\r
  25  *\r
  26  **/\r
  27 \r
  28 #ifndef _XRAN_CP_API_H_\r
  29 #define _XRAN_CP_API_H_\r
  30 \r
  31 #ifdef __cplusplus\r
  32 extern "C" {\r
  33 #endif\r
  34 \r
  35 \r
  36 #include "xran_fh_o_du.h"\r
  37 #include "xran_pkt_cp.h"\r
  38 #include "xran_transport.h"\r
  39 \r
  40 #define XRAN_MAX_SECTIONDB_CTX              2\r
  41 \r
  42 #define XRAN_MAX_NUM_EXTENSIONS     XRAN_MAX_PRBS /* Maximum number of extensions in a section [up to 1 ext section per RB]*/\r
  43 #define XRAN_MAX_NUM_UE             16      /* Maximum number of UEs/Lyaers */\r
  44 #define XRAN_MAX_NUM_ANT_BF         64      /* Maximum number of beamforming antenna,\r
  45                                              * could be defined as XRAN_MAX_ANTENNA_NR */\r
  46 /* Maximum total number of beamforming weights (5.4.7.1.2) */\r
  47 #define XRAN_MAX_BFW_N              (XRAN_MAX_NUM_ANT_BF*XRAN_MAX_NUM_UE)\r
  48 #define XRAN_MAX_MODCOMP_ADDPARMS   6       /* max should be even number */\r
  49 \r
  50 #define XRAN_SECTIONEXT_ALIGN       4       /* alignment size in byte for section extension */\r
  51 \r
  52 \r
  53 /** Control Plane section types, defined in 5.4 Table 5.1 */\r
  54 enum xran_cp_sectiontype {\r
  55     XRAN_CP_SECTIONTYPE_0   = 0,    /**< Unused RB or Symbols in DL or UL, not supported */\r
  56     XRAN_CP_SECTIONTYPE_1   = 1,    /**< Most DL/UL Radio Channels */\r
  57     XRAN_CP_SECTIONTYPE_3   = 3,    /**< PRACH and Mixed-numerology Channels */\r
  58     XRAN_CP_SECTIONTYPE_5   = 5,    /**< UE scheduling information, not supported  */\r
  59     XRAN_CP_SECTIONTYPE_6   = 6,    /**< Channel Information, not supported */\r
  60     XRAN_CP_SECTIONTYPE_7   = 7,    /**< LAA, not supported */\r
  61     XRAN_CP_SECTIONTYPE_MAX\r
  62     };\r
  63 \r
  64 /** Filter index, defined in 5.4.4.3 */\r
  65 enum xran_cp_filterindex {\r
  66     XRAN_FILTERINDEX_STANDARD   = 0,    /**< UL filter for standard channel */\r
  67     XRAN_FILTERINDEX_PRACH_012  = 1,    /**< UL filter for PRACH preamble format 0, 1, 2 */\r
  68     XRAN_FILTERINDEX_PRACH_3    = 2,    /**< UL filter for PRACH preamble format 3 */\r
  69     XRAN_FILTERINDEX_PRACH_ABC  = 3,    /**< UL filter for PRACH preamble format A1~3, B1~4, C0, C2 */\r
  70     XRAN_FILTERINDEX_NPRACH     = 4,    /**< UL filter for NPRACH */\r
  71     XRAN_FILTERINDEX_MAX\r
  72     };\r
  73 \r
  74 /** Maximum Slot Index, defined in 5.4.4.6 */\r
  75 #define XRAN_SLOTID_MAX                     16\r
  76 \r
  77 /** FFT size in frame structure, defined in 5.4.4.13 Table 5.9 */\r
  78 enum xran_cp_fftsize {\r
  79     XRAN_FFTSIZE_128    = 7,       /* 128 */\r
  80     XRAN_FFTSIZE_256    = 8,       /* 256 */\r
  81     XRAN_FFTSIZE_512    = 9,       /* 512 */\r
  82     XRAN_FFTSIZE_1024   = 10,      /* 1024 */\r
  83     XRAN_FFTSIZE_2048   = 11,      /* 2048 */\r
  84     XRAN_FFTSIZE_4096   = 12,      /* 4096 */\r
  85     XRAN_FFTSIZE_1536   = 13,      /* 1536 */\r
  86     XRAN_FFTSIZE_MAX\r
  87     };\r
  88 \r
  89 /** Sub-carrier spacing, defined in 5.4.4.13 Table 5.10 */\r
  90 enum xran_cp_subcarrierspacing {   /*3GPP u,  SCS, Nslot, Slot len */\r
  91     XRAN_SCS_15KHZ      = 0,       /*  0,   15kHz,  1, 1ms */\r
  92     XRAN_SCS_30KHZ      = 1,       /*  1,   30kHz,  2, 500us */\r
  93     XRAN_SCS_60KHZ      = 2,       /*  2,   60kHz,  4, 250us */\r
  94     XRAN_SCS_120KHZ     = 3,       /*  3,  120kHz,  8, 125us */\r
  95     XRAN_SCS_240KHZ     = 4,       /*  4,  240kHz, 16, 62.5us */\r
  96     XRAN_SCS_1P25KHZ    = 12,      /* NA, 1.25kHz,  1, 1ms */\r
  97     XRAN_SCS_3P75KHZ    = 13,      /* NA, 3.75kHz,  1, 1ms */\r
  98     XRAN_SCS_5KHZ       = 14,      /* NA,    5kHz,  1, 1ms */\r
  99     XRAN_SCS_7P5KHZ     = 15,      /* NA,  7.5kHz,  1, 1ms */\r
 100     XRAN_SCS_MAX\r
 101     };\r
 102 \r
 103 /** Resource block indicator, defined in 5.4.5.2 */\r
 104 enum xran_cp_rbindicator {\r
 105     XRAN_RBIND_EVERY        = 0,    /**< every RB used */\r
 106     XRAN_RBIND_EVERYOTHER   = 1,    /**< every other RB used */\r
 107     XRAN_RBIND_MAX\r
 108     };\r
 109 \r
 110 /** Symbol number increment command, defined in 5.4.5.3 */\r
 111 enum xran_cp_symbolnuminc {\r
 112     XRAN_SYMBOLNUMBER_NOTINC    = 0,      /**< do not increment the current symbol number */\r
 113     XRAN_SYMBOLNUMBER_INC       = 1,      /**< increment the current symbol number and use that */\r
 114     XRAN_SYMBOLNUMBER_INC_MAX\r
 115     };\r
 116 \r
 117 /** Macro to convert the number of PRBs as defined in 5.4.5.6 */\r
 118 #define XRAN_CONVERT_NUMPRBC(x)             ((x) > 255 ? 0 : (x))\r
 119 \r
 120 #define XRAN_CONVERT_IQWIDTH(x)             ((x) > 15 ? 0 : (x))\r
 121 \r
 122 /** Minimum number of symbols, defined in 5.4.5.7 */\r
 123 #define XRAN_SYMBOLNUMBER_MIN               1\r
 124 /** Maximum number of symbols, defined in  5.4.5.7 */\r
 125 #define XRAN_SYMBOLNUMBER_MAX               14\r
 126 \r
 127 /* LAA message type 5.4.5.14 Table 5.11, not supported */\r
 128 #define XRAN_LAAMSGTYPE_LBT_PDSCH_REQ       0\r
 129 #define XRAN_LAAMSGTYPE_LBT_DRS_REQ         1\r
 130 #define XRAN_LAAMSGTYPE_LBT_PDSCH_RSP       2\r
 131 #define XRAN_LAAMSGTYPE_LBT_DRS_RSP         3\r
 132 #define XRAN_LAAMSGTYPE_LBT_BUFFER_ERROR    4\r
 133 #define XRAN_LAAMSGTYPE_LBT_CWCONFIG_REQ    5\r
 134 #define XRAN_LAAMSGTYPE_LBT_CWCONFIG_RSP    6\r
 135 \r
 136 #define XRAN_LBTMODE_FULL                   0\r
 137 #define XRAN_LBTMODE_PARTIAL25              1\r
 138 #define XRAN_LBTMODE_PARTIAL34              2\r
 139 #define XRAN_LBTMODE_FULLSTOP               3\r
 140 \r
 141 #define XRAN_EF_F_LAST                      0\r
 142 #define XRAN_EF_F_ANOTHER_ONE               1\r
 143 \r
 144 \r
 145 \r
 146 /** Control Plane section extension commands, defined in 5.4.6 Table 5.13 */\r
 147 enum xran_cp_sectionextcmd {\r
 148     XRAN_CP_SECTIONEXTCMD_0 = 0,    /**< Reserved, for future use */\r
 149     XRAN_CP_SECTIONEXTCMD_1 = 1,    /**< Beamforming weights */\r
 150     XRAN_CP_SECTIONEXTCMD_2 = 2,    /**< Beamforming attributes */\r
 151     XRAN_CP_SECTIONEXTCMD_3 = 3,    /**< DL Precoding configuration parameters and indications, not supported */\r
 152     XRAN_CP_SECTIONEXTCMD_4 = 4,    /**< Modulation compression parameter */\r
 153     XRAN_CP_SECTIONEXTCMD_5 = 5,    /**< Modulation compression additional scaling parameters */\r
 154     XRAN_CP_SECTIONEXTCMD_MAX       /* 6~127 reserved for future use */\r
 155     };\r
 156 \r
 157 /** Macro to convert bfwIqWidth defined in 5.4.7.1.1, Table 5-15 */\r
 158 #define XRAN_CONVERT_BFWIQWIDTH(x)          ((x) > 15 ? 0 : (x))\r
 159 \r
 160 /** Beamforming Weights Compression Method 5.4.7.1.1, Table 5-16 */\r
 161 enum xran_cp_bfw_compression_method {\r
 162     XRAN_BFWCOMPMETHOD_NONE         = 0,    /**< Uncopressed I/Q value */\r
 163     XRAN_BFWCOMPMETHOD_BLKFLOAT     = 1,    /**< I/Q mantissa value */\r
 164     XRAN_BFWCOMPMETHOD_BLKSCALE     = 2,    /**< I/Q scaled value */\r
 165     XRAN_BFWCOMPMETHOD_ULAW         = 3,    /**< compressed I/Q value */\r
 166     XRAN_BFWCOMPMETHOD_BEAMSPACE    = 4,    /**< beamspace I/Q coefficient */\r
 167     XRAN_BFWCOMPMETHOD_MAX                  /* reserved for future methods */\r
 168     };\r
 169 \r
 170 /** Beamforming Attributes Bitwidth 5.4.7.2.1 */\r
 171 enum xran_cp_bfa_bitwidth {\r
 172     XRAN_BFABITWIDTH_NO             = 0,    /**< the filed is no applicable or the default value shall be used */\r
 173     XRAN_BFABITWIDTH_2BIT           = 1,    /**< the filed is 2-bit bitwidth */\r
 174     XRAN_BFABITWIDTH_3BIT           = 2,    /**< the filed is 3-bit bitwidth */\r
 175     XRAN_BFABITWIDTH_4BIT           = 3,    /**< the filed is 4-bit bitwidth */\r
 176     XRAN_BFABITWIDTH_5BIT           = 4,    /**< the filed is 5-bit bitwidth */\r
 177     XRAN_BFABITWIDTH_6BIT           = 5,    /**< the filed is 6-bit bitwidth */\r
 178     XRAN_BFABITWIDTH_7BIT           = 6,    /**< the filed is 7-bit bitwidth */\r
 179     XRAN_BFABITWIDTH_8BIT           = 7,    /**< the filed is 8-bit bitwidth */\r
 180     };\r
 181 \r
 182 /**\r
 183  * This structure contains the information to generate the section body of C-Plane message */\r
 184 struct xran_section_info {\r
 185     uint8_t     type;       /* type of this section  */\r
 186                             /* section type   bit-    */\r
 187                             /*  0 1 3 5 6 7    length */\r
 188     uint8_t     startSymId; /*  X X X X X X    4bits */\r
 189     uint8_t     numSymbol;  /*  X X X X        4bits */\r
 190     uint8_t     symInc;     /*  X X X X X      1bit  */\r
 191     uint16_t    id;         /*  X X X X X     12bits */\r
 192     uint16_t    reMask;     /*  X X X X       12bits */\r
 193     uint16_t    startPrbc;  /*  X X X X X     10bits */\r
 194     uint16_t    numPrbc;    /*  X X X X X      8bits */ /* will be converted to zero if >255 */\r
 195     uint8_t     rb;         /*  X X X X X      1bit  */\r
 196     uint8_t     compMeth;   /*    X X X        4bits */\r
 197     uint8_t     iqWidth;    /*    X X X        4bits */\r
 198     uint8_t     ef;         /*    X X X X      1bit  */\r
 199     int32_t     freqOffset; /*      X         24bits */\r
 200     uint16_t    beamId;     /*    X X         15bits */\r
 201     uint16_t    ueId;       /*        X X     15bits */\r
 202     uint16_t    regFactor;  /*          X     16bits */\r
 203     uint16_t    pad0;\r
 204     /** for U-plane */\r
 205     struct xran_section_desc sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT];\r
 206 };\r
 207 \r
 208 \r
 209 struct xran_sectionext1_info {\r
 210     uint16_t    rbNumber;                   /**< number RBs to ext1 chain */\r
 211     uint16_t    bfwNumber;                  /**< number of bf weights in this section */\r
 212     uint8_t     bfwiqWidth;\r
 213     uint8_t     bfwCompMeth;\r
 214     int16_t     *p_bfwIQ;                   /**< pointer to formed section extention */\r
 215     int16_t     bfwIQ_sz;                   /**< size of buffer with section extention information */\r
 216     union {\r
 217         uint8_t     exponent;\r
 218         uint8_t     blockScaler;\r
 219         uint8_t     compBitWidthShift;\r
 220         uint8_t     activeBeamspaceCoeffMask[XRAN_MAX_BFW_N];   /* ceil(N/8)*8, should be multiple of 8 */\r
 221         } bfwCompParam;\r
 222     };\r
 223 \r
 224 struct xran_sectionext2_info {\r
 225     uint8_t     bfAzPtWidth;    /* beamforming zenith beamwidth parameter */\r
 226     uint8_t     bfAzPt;\r
 227     uint8_t     bfZePtWidth;    /* beamforming azimuth beamwidth parameter */\r
 228     uint8_t     bfZePt;\r
 229     uint8_t     bfAz3ddWidth;   /* beamforming zenith pointing parameter */\r
 230     uint8_t     bfAz3dd;\r
 231     uint8_t     bfZe3ddWidth;   /* beamforming azimuth pointing parameter */\r
 232     uint8_t     bfZe3dd;\r
 233 \r
 234     uint8_t     bfAzSI;\r
 235     uint8_t     bfZeSI;\r
 236     };\r
 237 \r
 238 struct xran_sectionext3_info {  /* NOT SUPPORTED */\r
 239     uint8_t     codebookIdx;\r
 240     uint8_t     layerId;\r
 241     uint8_t     numLayers;\r
 242     uint8_t     txScheme;\r
 243     uint16_t    crsReMask;\r
 244     uint8_t     crsShift;\r
 245     uint8_t     crsSymNum;\r
 246     uint16_t    beamIdAP1;\r
 247     uint16_t    beamIdAP2;\r
 248     uint16_t    beamIdAP3;\r
 249     };\r
 250 \r
 251 struct xran_sectionext4_info {\r
 252     uint8_t     csf;\r
 253     uint8_t     pad0;\r
 254     uint16_t    modCompScaler;\r
 255     };\r
 256 \r
 257 struct xran_sectionext5_info {\r
 258     uint8_t     num_sets;\r
 259     struct {\r
 260         uint16_t    csf;\r
 261         uint16_t    mcScaleReMask;\r
 262         uint16_t    mcScaleOffset;\r
 263         } mc[XRAN_MAX_MODCOMP_ADDPARMS];\r
 264     };\r
 265 \r
 266 struct xran_sectionext_info {\r
 267     uint16_t    type;\r
 268     uint16_t    len;\r
 269     void        *data;\r
 270     };\r
 271 \r
 272 \r
 273 /**\r
 274  * This structure contains the information to generate the section header of C-Plane message */\r
 275 struct xran_cp_header_params {\r
 276     // common parameters\r
 277     uint8_t     filterIdx;\r
 278     uint8_t     frameId;\r
 279     uint8_t     subframeId;\r
 280     uint8_t     slotId;\r
 281     uint8_t     startSymId;\r
 282                             /* section type   bit-    */\r
 283                             /*  0 1 3 5 6 7    length */\r
 284     uint8_t     fftSize;    /*  X   X          4bits */\r
 285     uint8_t     scs;        /*  X   X          4bits */\r
 286     uint8_t     iqWidth;    /*    X X X        4bits */\r
 287     uint8_t     compMeth;   /*    X X X        4bits */\r
 288     uint8_t     numUEs;     /*          X      8bits */\r
 289     uint16_t    timeOffset; /*  X   X         16bits */\r
 290     uint16_t    cpLength;   /*  X   X         16bits */\r
 291     };\r
 292 \r
 293 /**\r
 294  * This structure to hold the information to generate the sections of C-Plane message */\r
 295 struct xran_section_gen_info {\r
 296     struct xran_section_info info;  /**< The information for section */\r
 297 \r
 298     uint32_t    exDataSize;         /**< The number of Extensions or type 6/7 data */\r
 299     /** the array to store section extension */\r
 300     struct {\r
 301         uint16_t    type;           /**< the type of section extension */\r
 302         uint16_t    len;            /**< length of extension data */\r
 303         void        *data;          /**< pointer to extension data */\r
 304         } exData[XRAN_MAX_NUM_EXTENSIONS];\r
 305     struct xran_sectionext1_info m_ext1[XRAN_MAX_NUM_EXTENSIONS];\r
 306     struct xran_sectionext2_info m_ext2[XRAN_MAX_NUM_EXTENSIONS];\r
 307     struct xran_sectionext3_info m_ext3[XRAN_MAX_NUM_EXTENSIONS];\r
 308     struct xran_sectionext4_info m_ext4[XRAN_MAX_NUM_EXTENSIONS];\r
 309     struct xran_sectionext5_info m_ext5[XRAN_MAX_NUM_EXTENSIONS];\r
 310 };\r
 311 \r
 312 \r
 313 /**\r
 314  * This structure to hold the information to generate a C-Plane message */\r
 315 struct xran_cp_gen_params {\r
 316     uint8_t     dir;            /**< UL or DL */\r
 317     uint8_t     sectionType;    /**< each section must have same type with this */\r
 318     uint16_t    numSections;    /**< the number of sections to generate */\r
 319 \r
 320     struct xran_cp_header_params hdr;\r
 321     /**< The information for C-Plane message header */\r
 322     struct xran_section_gen_info *sections;\r
 323     /**< Array of the section information */\r
 324     };\r
 325 \r
 326 /**\r
 327  * This structure to hold the information of RB allocation from PHY\r
 328  * to send data for allocated RBs only. */\r
 329 struct xran_cp_rbmap_list {\r
 330     uint16_t    grp_id;     /**< group id for this entry, reserved for future use */\r
 331 \r
 332     uint8_t     sym_start;  /**< Start symbol ID */\r
 333     uint8_t     sym_num;    /**< Number of symbols */\r
 334 \r
 335     uint16_t    rb_start;   /**< Start RB position */\r
 336     uint16_t    rb_num;     /**< Number of RBs */\r
 337 \r
 338     int16_t     iq_buff_offset; /**< Offset within Sym for start of IQs */\r
 339     int16_t     iq_buff_len;    /**< length IQs */\r
 340 \r
 341     uint16_t    beam_id;    /**< Bean Index */\r
 342     uint8_t     iqWidth;    /**< I and Q width in bits */\r
 343     uint8_t     comp_meth;  /**< Compression method */\r
 344     uint8_t     pad0;\r
 345     };\r
 346 \r
 347 \r
 348 uint16_t xran_get_cplength(int cpLength);\r
 349 int32_t xran_get_freqoffset(int freqOffset, int scs);\r
 350 \r
 351 int xran_prepare_ctrl_pkt(struct rte_mbuf *mbuf,\r
 352                         struct xran_cp_gen_params *params,\r
 353                         uint8_t CC_ID, uint8_t Ant_ID,\r
 354                         uint8_t seq_id);\r
 355 \r
 356 int xran_parse_cp_pkt(struct rte_mbuf *mbuf,\r
 357                     struct xran_cp_gen_params *result,\r
 358                     struct xran_recv_packet_info *pkt_info);\r
 359 \r
 360 int xran_cp_init_sectiondb(void *pHandle);\r
 361 int xran_cp_free_sectiondb(void *pHandle);\r
 362 int xran_cp_add_section_info(void *pHandle,\r
 363         uint8_t dir, uint8_t cc_id, uint8_t ruport_id,\r
 364         uint8_t ctx_id, struct xran_section_info *info);\r
 365 int xran_cp_add_multisection_info(void *pHandle,\r
 366         uint8_t cc_id, uint8_t ruport_id, uint8_t ctx_id,\r
 367         struct xran_cp_gen_params *gen_info);\r
 368 struct xran_section_info *xran_cp_find_section_info(void *pHandle,\r
 369         uint8_t dir, uint8_t cc_id, uint8_t ruport_id,\r
 370         uint8_t ctx_id, uint16_t section_id);\r
 371 struct xran_section_info *xran_cp_iterate_section_info(void *pHandle,\r
 372         uint8_t dir, uint8_t cc_id, uint8_t ruport_id,\r
 373         uint8_t ctx_id, uint32_t *next);\r
 374 int xran_cp_getsize_section_info(void *pHandle, uint8_t dir, uint8_t cc_id, uint8_t ruport_id, uint8_t ctx_id);\r
 375 int xran_cp_reset_section_info(void *pHandle, uint8_t dir, uint8_t cc_id, uint8_t ruport_id, uint8_t ctx_id);\r
 376 int32_t xran_cp_populate_section_ext_1(int8_t  *p_ext1_dst,    /**< destination buffer */\r
 377                                        uint16_t  ext1_dst_len, /**< dest buffer size */\r
 378                                        int16_t  *p_bfw_iq_src, /**< source buffer of IQs */\r
 379                                        uint16_t  rbNumber,     /**< number RBs to ext1 chain */\r
 380                                        uint16_t  bfwNumber,    /**< number of bf weights in this set of sections */\r
 381                                        uint8_t   bfwiqWidth,   /**< bit size of IQs */\r
 382                                        uint8_t   bfwCompMeth); /**< compression method */\r
 383 #ifdef __cplusplus\r
 384 }\r
 385 #endif\r
 386 \r
 387 #endif /* _XRAN_CP_API_H_ */\r