fhi_lib/lib/api/xran_pkt_cp.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  * @brief This file provides the definition of Control Plane Messages
  21  *      for XRAN Front Haul layer as defined in XRAN-FH.CUS.0-v02.01.
  22  *
  23  * @file xran_pkt_cp.h
  24  * @ingroup group_lte_source_xran
  25  * @author Intel Corporation
  26  *
  27  **/
  28
  29 #ifndef _XRAN_PKT_CP_H_
  30 #define _XRAN_PKT_CP_H_
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36
  37 /**********************************************************************
  38  * Common structures for C/U-plane
  39  **********************************************************************/
  40 /**
  41  * @ingroup xran_cp_pkt
  42  *
  43  * @description
  44  *      user data compression header defined in 5.4.4.10 / 6.3.3.13
  45  */
  46 struct xran_radioapp_udComp_header {
  47     uint8_t     udCompMeth:4;           /**< Compression method, XRAN_COMPMETHOD_xxxx */
  48     uint8_t     udIqWidth:4;            /**< IQ bit width, 1 ~ 16 */
  49     } __attribute__((__packed__));
  50
  51
  52 /**********************************************************************
  53  * Definition of C-Plane Protocol 5.4
  54  **********************************************************************/
  55 /**
  56  * @ingroup xran_cp_pkt
  57  *
  58  * @description
  59  *      Common Radio Application Header for C-Plane
  60  */
  61 struct xran_cp_radioapp_common_header {     /* 6bytes, first 4bytes need the conversion for byte order */
  62     uint32_t    startSymbolId:6;        /**< 5.4.4.7 start symbol identifier */
  63     uint32_t    slotId:6;               /**< 5.4.4.6 slot identifier */
  64     uint32_t    subframeId:4;           /**< 5.4.4.5 subframe identifier */
  65     uint32_t    frameId:8;              /**< 5.4.4.4 frame identifier */
  66     uint32_t    filterIndex:4;          /**< 5.4.4.3 filter index, XRAN_FILTERINDEX_xxxx */
  67     uint32_t    payloadVer:3;           /**< 5.4.4.2 payload version, should be 1 */
  68     uint32_t    dataDirection:1;        /**< 5.4.4.1 data direction (gNB Tx/Rx) */
  69     uint8_t     numOfSections;          /**< 5.4.4.8 number of sections */
  70     uint8_t     sectionType;            /**< 5.4.4.9 section type */
  71     } __attribute__((__packed__));
  72
  73 /**
  74  * @ingroup xran_cp_pkt
  75  *
  76  * @description
  77  *      frame structure defined in 5.4.4.13
  78  */
  79 struct xran_cp_radioapp_frameStructure {
  80     uint8_t     uScs:4;                 /**< sub-carrier spacing, XRAN_SCS_xxx */
  81     uint8_t     fftSize:4;              /**< FFT size,  XRAN_FFTSIZE_xxx */
  82     } __attribute__((__packed__));
  83
  84 /**
  85  * @ingroup xran_cp_pkt
  86  *
  87  * @description
  88  *      Section headers definition for C-Plane.
  89  *      Section type 6 and 7 are not present since those have different fields.
  90  */
  91 struct xran_cp_radioapp_section_header {    /* 8bytes, need the conversion for byte order */
  92     union {
  93         struct {
  94             uint32_t    reserved:16;
  95             uint32_t    numSymbol:4;    /**< 5.4.5.7 number of symbols */
  96             uint32_t    reMask:12;      /**< 5.4.5.5 resource element mask */
  97             } s0;
  98         struct {
  99             uint32_t     beamId:15;     /**< 5.4.5.9 beam identifier */
 100             uint32_t     ef:1;          /**< 5.4.5.8 extension flag */
 101             uint32_t     numSymbol:4;   /**< 5.4.5.7 number of symbols */
 102             uint32_t     reMask:12;     /**< 5.4.5.5 resource element mask */
 103             } s1;
 104         struct {
 105             uint32_t    beamId:15;      /**< 5.4.5.9 beam identifier */
 106             uint32_t    ef:1;           /**< 5.4.5.8 extension flag */
 107             uint32_t    numSymbol:4;    /**< 5.4.5.7 number of symbols */
 108             uint32_t    reMask:12;      /**< 5.4.5.5 resource element mask */
 109             } s3;
 110         struct {
 111             uint32_t    ueId:15;        /**< 5.4.5.10 UE identifier */
 112             uint32_t    ef:1;           /**< 5.4.5.8 extension flag */
 113             uint32_t    numSymbol:4;    /**< 5.4.5.7 number of symbols */
 114             uint32_t    reMask:12;      /**< 5.4.5.5 resource element mask */
 115             } s5;
 116         } u;
 117
 118     uint32_t    numPrbc:8;              /**< 5.4.5.6 number of contiguous PRBs per control section  0000 0000b = all PRBs */
 119     uint32_t    startPrbc:10;           /**< 5.4.5.4 starting PRB of control section */
 120     uint32_t    symInc:1;               /**< 5.4.5.3 symbol number increment command XRAN_SYMBOLNUMBER_xxxx */
 121     uint32_t    rb:1;                   /**< 5.4.5.2 resource block indicator, XRAN_RBIND_xxx */
 122     uint32_t    sectionId:12;           /**< 5.4.5.1 section identifier */
 123     } __attribute__((__packed__));
 124
 125
 126 struct xran_cp_radioapp_section_ext_hdr {
 127     /* 12 bytes, need to convert byte order for two parts respectively
 128      *  - 2 and 8 bytes, reserved1 would be OK if it is zero
 129      */
 130     uint16_t     extLen:8;          /**< 5.4.6.3 extension length, in 32bits words */
 131     uint16_t     extType:7;         /**< 5.4.6.1 extension type */
 132     uint16_t     ef:1;              /**< 5.4.6.2 extension flag */
 133     } __attribute__((__packed__));
 134
 135 /**
 136  * @ingroup xran_cp_pkt
 137  *
 138  * @description
 139  *      Beamforming Weights Extension Type(ExtType 1) defined in 5.4.7.1
 140  *      The structure is reordered for byte order conversion.
 141  */
 142 struct xran_cp_radioapp_section_ext1 {
 143     /* variable length, need to be careful to convert byte order
 144      *   - does not need to convert first 3 bytes */
 145     uint8_t     extType:7;          /**< 5.4.6.1 extension type */
 146     uint8_t     ef:1;               /**< 5.4.6.2 extension flag */
 147     uint8_t     extLen;             /**< 5.4.6.3 extension length, in 32bits words */
 148     /* bfwCompHdr */
 149     uint8_t     bfwCompMeth:4;      /**< 5.4.7.1.1 Beamforming weight Compression method */
 150     uint8_t     bfwIqWidth:4;       /**< 5.4.7.1.1 Beamforming weight IQ bit width */
 151
 152     /*
 153      *
 154      *
 155      * bfwCompParam
 156      * (bfwI,  bfwQ)+
 157      *    ......
 158      * zero padding for 4-byte alignment
 159      */
 160     } __attribute__((__packed__));
 161
 162 /**
 163  * @ingroup xran_cp_pkt
 164  *
 165  * @description
 166  *      Beamforming Attributes Extension Type(ExtType 2) defined in 5.4.7.2
 167  *      The structure is reordered for byte order conversion.
 168  */
 169 struct xran_cp_radioapp_section_ext2 {
 170     /* variable length, need to be careful to convert byte order
 171      *   - first 4 bytes can be converted at once
 172      */
 173     uint32_t    bfZe3ddWidth:3;     /**< 5.4.7.2.1 beamforming zenith beamwidth parameter bitwidth, Table 5-21 */
 174     uint32_t    bfAz3ddWidth:3;     /**< 5.4.7.2.1 beamforming azimuth beamwidth parameter bitwidth, Table 5-20 */
 175     uint32_t    bfaCompResv1:2;
 176     uint32_t    bfZePtWidth:3;      /**< 5.4.7.2.1 beamforming zenith pointing parameter bitwidth, Table 5-19 */
 177     uint32_t    bfAzPtWidth:3;      /**< 5.4.7.2.1 beamforming azimuth pointing parameter bitwidth, Table 5-18 */
 178     uint32_t    bfaCompResv0:2;
 179     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 180     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 181     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 182
 183     /*
 184      * would be better to use bit manipulation directly to add these parameters
 185      *
 186      * bfAzPt: var by bfAzPtWidth
 187      * bfZePt: var by bfZePtWidth
 188      * bfAz3dd: var by bfAz3ddWidth
 189      * bfZe3dd: var by bfZe3ddWidth
 190      * bfAzSI:5 (including zero-padding for unused bits)
 191      * bfZeSI:3
 192      * padding for 4-byte alignment
 193      *
 194      */
 195     } __attribute__((__packed__));
 196
 197 /**
 198  * @ingroup xran_cp_pkt
 199  *
 200  * @description
 201  *      DL Precoding Extension Type(ExtType 3) for first data layer.
 202  *      Defined in 5.4.7.3 Table 5-22.
 203  *      Only be used for LTE TM2-4 and not for other LTE TMs nor NR.
 204  *      The structure is reordered for byte order conversion.
 205  */
 206 struct xran_cp_radioapp_section_ext3_first {
 207     /* 16 bytes, need to convert byte order for two parts - 8/8 bytes */
 208     uint64_t    reserved1:8;
 209     uint64_t    crsSymNum:4;        /**< 5.4.7.3.6 CRS symbol number indication */
 210     uint64_t    reserved0:3;
 211     uint64_t    crsShift:1;         /**< 5.4.7.3.7 CRS shift used for DL transmission */
 212     uint64_t    crsReMask:12;       /**< 5.4.7.3.5 CRS resource element mask */
 213     uint64_t    txScheme:4;         /**< 5.4.7.3.3 transmission scheme */
 214     uint64_t    numLayers:4;        /**< 5.4.7.3.4 number of layers used for DL transmission */
 215     uint64_t    layerId:4;          /**< 5.4.7.3.2 Layer ID for DL transmission */
 216     uint64_t    codebookIndex:8;    /**< 5.4.7.3.1 precoder codebook used for transmission */
 217     uint64_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 218     uint64_t    extType:7;          /**< 5.4.6.1 extension type */
 219     uint64_t    ef:1;               /**< 5.4.6.2 extension flag */
 220
 221     uint64_t    beamIdAP1:16;       /**< 5.4.7.3.8 beam id to be used for antenna port 1 */
 222     uint64_t    beamIdAP2:16;       /**< 5.4.7.3.9 beam id to be used for antenna port 2 */
 223     uint64_t    beamIdAP3:16;       /**< 5.4.7.3.10 beam id to be used for antenna port 3 */
 224     uint64_t    reserved2:16;
 225     } __attribute__((__packed__));
 226
 227 /**
 228  * @ingroup xran_cp_pkt
 229  *
 230  * @description
 231  *      DL Precoding Extension Type(ExtType 3) for non-first data layer.
 232  *      Defined in 5.4.7.3 Table 5-23.
 233  *      Only be used for LTE TM2-4 and not for other LTE TMs nor NR.
 234  *      The structure is reordered for byte order conversion.
 235  */
 236 struct xran_cp_radioapp_section_ext3_non_first {
 237     /* 4 bytes, need to convert byte order at once */
 238     uint32_t    numLayers:4;        /**< 5.4.7.3.4 number of layers used for DL transmission */
 239     uint32_t    layerId:4;          /**< 5.4.7.3.2 Layer ID for DL transmission */
 240     uint32_t    codebookIndex:8;    /**< 5.4.7.3.1 precoder codebook used for transmission */
 241
 242     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 243     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 244     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 245     } __attribute__((__packed__));
 246
 247 /**
 248  * @ingroup xran_cp_pkt
 249  *
 250  * @description
 251  *      Modulation Compression Parameter Extension Type(ExtType 4), 5.4.7.4
 252  *      Only applies to section type 1 and 3.
 253  *      The structure is reordered for byte order conversion.
 254  */
 255 struct xran_cp_radioapp_section_ext4 {
 256     /* 4 bytes, need to convert byte order at once */
 257     uint32_t    modCompScaler:15;   /**< 5.4.7.4.2 modulation compression scaler value */
 258     uint32_t    csf:1;              /**< 5.4.7.4.1 constellation shift flag */
 259
 260     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 261     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 262     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 263     } __attribute__((__packed__));
 264
 265 /**
 266  * @ingroup xran_cp_pkt
 267  *
 268  * @description
 269  *      Modulation Compression Additional Parameter Extension Type(ExtType 5) for one scaler value.
 270  *      Defined in 5.4.7.5 Table 5-26 and Table 5-27.
 271  *      Only applies to section type 1 3, and 5.
 272  *      The structure is reordered for byte order conversion.
 273  */
 274 struct xran_cp_radioapp_section_ext5 {
 275     uint32_t    reserved0:8;
 276     uint32_t    mcScaleOffset2:15;  /**< 5.4.7.5.3 scaling value for modulation compression */
 277     uint32_t    csf2:1;             /**< 5.4.7.5.2 constellation shift flag */
 278     uint32_t    mcScaleReMask2:12;  /**< 5.4.7.5.1 modulation compression power scale RE mask */
 279     uint32_t    mcScaleOffset1:15;  /**< 5.4.7.5.3 scaling value for modulation compression */
 280     uint32_t    csf1:1;             /**< 5.4.7.5.2 constellation shift flag */
 281     uint32_t    mcScaleReMask1:12;  /**< 5.4.7.5.1 modulation compression power scale RE mask */
 282     } __attribute__((__packed__));
 283
 284
 285 /**********************************************************
 286  * Scheduling and Beam-forming Commands 5.4.2
 287  **********************************************************/
 288 /**
 289  * @ingroup xran_cp_pkt
 290  *
 291  * @description
 292  *      Section header definition for type 0
 293  */
 294 struct xran_cp_radioapp_section0_header {   // 12bytes (6+2+1+2+1)
 295     struct xran_cp_radioapp_common_header cmnhdr;
 296     uint16_t    timeOffset;             /**< 5.4.4.12 time offset */
 297
 298     struct xran_cp_radioapp_frameStructure  frameStructure;
 299     uint16_t    cpLength;               /**< 5.4.4.14 cyclic prefix length */
 300     uint8_t     reserved;
 301     } __attribute__((__packed__));
 302
 303 /**
 304  * @ingroup xran_cp_pkt
 305  *
 306  * @description
 307  *      Section definition for type 0: Unused RB or Symbols in DL or UL (Table 5-2)
 308  *      Not supported in this release
 309  */
 310 struct xran_cp_radioapp_section0 {          // 8bytes (4+4)
 311     struct xran_cp_radioapp_section_header hdr;
 312     } __attribute__((__packed__));
 313
 314 /**
 315  * @ingroup xran_cp_pkt
 316  *
 317  * @description
 318  *      Section header definition for type 1
 319  */
 320 struct xran_cp_radioapp_section1_header {   // 8bytes (6+1+1)
 321     struct xran_cp_radioapp_common_header cmnhdr;
 322     struct xran_radioapp_udComp_header udComp;
 323     uint8_t     reserved;
 324     } __attribute__((__packed__));
 325
 326 /**
 327  * @ingroup xran_cp_pkt
 328  *
 329  * @description
 330  *      Section definition for type 1: Most DL/UL Radio Channels (Table 5-3)
 331  */
 332 struct xran_cp_radioapp_section1 {          // 8bytes (4+4)
 333     struct xran_cp_radioapp_section_header hdr;
 334
 335     // section extensions               // 5.4.6 & 5.4.7
 336     //  .........
 337     } __attribute__((__packed__));
 338
 339 /**
 340  * @ingroup xran_cp_pkt
 341  *
 342  * @description
 343  *      Section header definition for type 3
 344  */
 345 struct xran_cp_radioapp_section3_header {   // 12bytes (6+2+1+2+1)
 346     struct xran_cp_radioapp_common_header cmnhdr;
 347     uint16_t    timeOffset;             /**< 5.4.4.12 time offset */
 348
 349     struct xran_cp_radioapp_frameStructure  frameStructure;
 350     uint16_t    cpLength;               /**< 5.4.4.14 cyclic prefix length */
 351     struct xran_radioapp_udComp_header udComp;
 352     } __attribute__((__packed__));
 353
 354 /**
 355  * @ingroup xran_cp_pkt
 356  *
 357  * @description
 358  *      Section definition for type 3: PRACH and Mixed-numerology Channels (Table 5-4)
 359  */
 360 struct xran_cp_radioapp_section3 {          // 12bytes (4+4+4)
 361     struct xran_cp_radioapp_section_header hdr;
 362     uint32_t    freqOffset:24;          /**< 5.4.5.11 frequency offset */
 363     uint32_t    reserved:8;
 364
 365     // section extensions               // 5.4.6 & 5.4.7
 366     //  .........
 367     } __attribute__((__packed__));
 368
 369 /**
 370  * @ingroup xran_cp_pkt
 371  *
 372  * @description
 373  *      Section header definition for type 5
 374  */
 375 struct xran_cp_radioapp_section5_header {   // 8bytes (6+1+1)
 376     struct xran_cp_radioapp_common_header cmnhdr;
 377     struct xran_radioapp_udComp_header udComp;
 378     uint8_t     reserved;
 379     } __attribute__((__packed__));
 380
 381 /**
 382  * @ingroup xran_cp_pkt
 383  *
 384  * @description
 385  *      Section definition for type 5: UE scheduling information (Table 5-5)
 386  *      Not supported in this release
 387  */
 388 struct xran_cp_radioapp_section5 {
 389     struct xran_cp_radioapp_section_header hdr;
 390
 391     // section extensions               // 5.4.6 & 5.4.7
 392     //  .........
 393     } __attribute__((__packed__));
 394
 395 /**
 396  * @ingroup xran_cp_pkt
 397  *
 398  * @description
 399  *      Section header definition for type 6
 400  */
 401 struct xran_cp_radioapp_section6_header {   // 8bytes (6+1+1)
 402     struct xran_cp_radioapp_common_header cmnhdr;
 403     uint8_t     numberOfUEs;            /**< 5.4.4.11 number of UEs */
 404     uint8_t     reserved;
 405     } __attribute__((__packed__));
 406
 407 /**
 408  * @ingroup xran_cp_pkt
 409  *
 410  * @description
 411  *      Section definition for type 6: Channel Information (Table 5-6)
 412  *      Not supported in this release
 413  */
 414 struct xran_cp_radioapp_section6 {
 415     uint32_t    regularizationFactor:16;/**< 5.4.5.12 regularization Factor */
 416     uint32_t    ueId:15;                /**< 5.4.5.10 UE identifier */
 417     uint32_t    ef:1;                   /**< 5.4.5.8 extension flag */
 418     uint8_t     startPrbch:2;           /**< 5.4.5.4 starting PRB of control section */
 419     uint8_t     symInc:1;               /**< 5.4.5.3 symbol number increment command XRAN_SYMBOLNUMBER_xxxx */
 420     uint8_t     rb:1;                   /**< 5.4.5.2 resource block indicator, XRAN_RBIND_xxx */
 421     uint8_t     reserved:4;
 422     uint8_t     startPrbcl:8;           /**< 5.4.5.4 starting PRB of control section */
 423     uint8_t     numPrbc:8;              /**< 5.4.5.6 number of contiguous PRBs per control section */
 424
 425     // ciIQsamples start from here      // 5.4.5.13 channel information I and Q values
 426     //  .........
 427     //
 428     // section extensions               // 5.4.6 & 5.4.7
 429     //  .........
 430     } __attribute__((__packed__));
 431
 432 /**
 433  * @ingroup xran_cp_pkt
 434  *
 435  * @description
 436  *      Section header definition for type 7: LAA
 437  *      Not supported in this release
 438  */
 439 struct xran_cp_radioapp_section7_header {
 440     struct xran_cp_radioapp_common_header cmnhdr;
 441     uint16_t    reserved;
 442     uint8_t     laaMsgLen:4;            /**< 5.4.5.15 LAA message length */
 443     uint8_t     laaMsgType:4;           /**< 5.4.5.14 LAA message type */
 444
 445     // Payload start from here          // 5.4.5.16 ~ 5.4.5.32
 446     } __attribute__((__packed__));
 447
 448 #ifdef __cplusplus
 449 }
 450 #endif
 451
 452 #endif  /* _XRAN_PKT_CP_H_ */