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 /**
 127  * @ingroup xran_cp_pkt
 128  *
 129  * @description
 130  *      Beamforming Weights Extension Type(ExtType 1) defined in 5.4.7.1
 131  *      The structure is reordered for byte order conversion.
 132  */
 133 struct xran_cp_radioapp_section_ext1 {
 134     /* variable length, need to be careful to convert byte order
 135      *   - does not need to convert first 3 bytes */
 136     uint8_t     extType:7;          /**< 5.4.6.1 extension type */
 137     uint8_t     ef:1;               /**< 5.4.6.2 extension flag */
 138     uint8_t     extLen;             /**< 5.4.6.3 extension length, in 32bits words */
 139     uint8_t     bfwCompMeth:4;      /**< 5.4.7.1.1 Beamforming weight Compression method */
 140     uint8_t     bfwIqWidth:4;       /**< 5.4.7.1.1 Beamforming weight IQ bit width */
 141
 142     /*
 143      * would be better to use bit manipulation directly to add these parameters
 144      *
 145      * bfwCompParam
 146      * (bfwI,  bfwQ)+
 147      *    ......
 148      * padding for 4-byte alignment
 149      */
 150     } __attribute__((__packed__));
 151
 152 /**
 153  * @ingroup xran_cp_pkt
 154  *
 155  * @description
 156  *      Beamforming Attributes Extension Type(ExtType 2) defined in 5.4.7.2
 157  *      The structure is reordered for byte order conversion.
 158  */
 159 struct xran_cp_radioapp_section_ext2 {
 160     /* variable length, need to be careful to convert byte order
 161      *   - first 4 bytes can be converted at once
 162      */
 163     uint32_t    bfZe3ddWidth:3;     /**< 5.4.7.2.1 beamforming zenith beamwidth parameter bitwidth, Table 5-21 */
 164     uint32_t    bfAz3ddWidth:3;     /**< 5.4.7.2.1 beamforming azimuth beamwidth parameter bitwidth, Table 5-20 */
 165     uint32_t    bfaCompResv1:2;
 166     uint32_t    bfZePtWidth:3;      /**< 5.4.7.2.1 beamforming zenith pointing parameter bitwidth, Table 5-19 */
 167     uint32_t    bfAzPtWidth:3;      /**< 5.4.7.2.1 beamforming azimuth pointing parameter bitwidth, Table 5-18 */
 168     uint32_t    bfaCompResv0:2;
 169     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 170     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 171     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 172
 173     /*
 174      * would be better to use bit manipulation directly to add these parameters
 175      *
 176      * bfAzPt: var by bfAzPtWidth
 177      * bfZePt: var by bfZePtWidth
 178      * bfAz3dd: var by bfAz3ddWidth
 179      * bfZe3dd: var by bfZe3ddWidth
 180      * bfAzSI:5 (including zero-padding for unused bits)
 181      * bfZeSI:3
 182      * padding for 4-byte alignment
 183      *
 184      */
 185     } __attribute__((__packed__));
 186
 187 /**
 188  * @ingroup xran_cp_pkt
 189  *
 190  * @description
 191  *      DL Precoding Extension Type(ExtType 3) for first data layer.
 192  *      Defined in 5.4.7.3 Table 5-22.
 193  *      Only be used for LTE TM2-4 and not for other LTE TMs nor NR.
 194  *      The structure is reordered for byte order conversion. Not supported.
 195  */
 196 struct xran_cp_radioapp_section_ext3_first {
 197     /* 16 bytes, need to convert byte order for two parts
 198      *   - 8 / 8 bytes
 199      */
 200     uint32_t    reserved1:8;
 201     uint32_t    crsSymNum:4;        /**< 5.4.7.3.6 CRS symbol number indication */
 202     uint32_t    reserved0:3;
 203     uint32_t    crsShift:1;         /**< 5.4.7.3.7 CRS shift used for DL transmission */
 204     uint32_t    crsReMask:12;       /**< 5.4.7.3.5 CRS resource element mask */
 205     uint32_t    txScheme:4;         /**< 5.4.7.3.3 transmission scheme */
 206     uint32_t    numLayers:4;        /**< 5.4.7.3.4 number of layers used for DL transmission */
 207     uint32_t    layerId:4;          /**< 5.4.7.3.2 Layer ID for DL transmission */
 208     uint32_t    codebookIndex:8;    /**< 5.4.7.3.1 precoder codebook used for transmission */
 209     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 210     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 211     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 212
 213     uint16_t    beamIdAP3;          /**< 5.4.7.3.10 beam id to be used for antenna port 3 */
 214     uint16_t    beamIdAP2;          /**< 5.4.7.3.9 beam id to be used for antenna port 2 */
 215     uint16_t    beamIdAP1;          /**< 5.4.7.3.8 beam id to be used for antenna port 1 */
 216     uint16_t    reserved2;
 217     } __attribute__((__packed__));
 218
 219 /**
 220  * @ingroup xran_cp_pkt
 221  *
 222  * @description
 223  *      DL Precoding Extension Type(ExtType 3) for non-first data layer.
 224  *      Defined in 5.4.7.3 Table 5-23.
 225  *      Only be used for LTE TM2-4 and not for other LTE TMs nor NR.
 226  *      The structure is reordered for byte order conversion. Not supported.
 227  */
 228 struct xran_cp_radioapp_section_ext3_non_first {
 229     /* 4 bytes, need to convert byte order at once */
 230     uint32_t    numLayers:4;        /**< 5.4.7.3.4 number of layers used for DL transmission */
 231     uint32_t    layerId:4;          /**< 5.4.7.3.2 Layer ID for DL transmission */
 232     uint32_t    codebookIndex:8;    /**< 5.4.7.3.1 precoder codebook used for transmission */
 233
 234     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 235     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 236     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 237     } __attribute__((__packed__));
 238
 239 /**
 240  * @ingroup xran_cp_pkt
 241  *
 242  * @description
 243  *      Modulation Compression Parameter Extension Type(ExtType 4), 5.4.7.4
 244  *      Only applies to section type 1 and 3.
 245  *      The structure is reordered for byte order conversion.
 246  */
 247 struct xran_cp_radioapp_section_ext4 {
 248     /* 4 bytes, need to convert byte order at once */
 249     uint32_t    modCompScaler:15;   /**< 5.4.7.4.2 modulation compression scaler value */
 250     uint32_t    csf:1;              /**< 5.4.7.4.1 constellation shift flag */
 251
 252     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 253     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 254     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 255     } __attribute__((__packed__));
 256
 257 /**
 258  * @ingroup xran_cp_pkt
 259  *
 260  * @description
 261  *      Modulation Compression Additional Parameter Extension Type(ExtType 5) for one scaler value.
 262  *      Defined in 5.4.7.5 Table 5-26
 263  *      Only applies to section type 1 3, and 5.
 264  *      The structure is reordered for byte order conversion.
 265  */
 266 struct xran_cp_radioapp_section_ext5_1 {
 267     /* 8 bytes, need to convert byte order at once */
 268     uint32_t    reserved:20;
 269     uint32_t    mcScaleOffset:15;   /**< 5.4.7.5.3 scaling value for modulation compression */
 270     uint32_t    csf:1;              /**< 5.4.7.5.2 constellation shift flag */
 271     uint32_t    mcScaleReMask:12;   /**< 5.4.7.5.1 modulation compression power scale RE mask */
 272
 273     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 274     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 275     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 276     } __attribute__((__packed__));
 277
 278 /**
 279  * @ingroup xran_cp_pkt
 280  *
 281  * @description
 282  *      Modulation Compression Additional Parameter Extension Type(ExtType 5) for two scaler values.
 283  *      Defined in 5.4.7.5 Table 5-27
 284  *      Only applies to section type 1 3, and 5.
 285  *      The structure is reordered for byte order conversion.
 286  */
 287 struct xran_cp_radioapp_section_ext5_2 {
 288     /* 12 bytes, need to convert byte order for two parts respectively
 289      *  - 2 and 8 bytes, reserved1 would be OK if it is zero
 290      */
 291     uint16_t     extLen:8;          /**< 5.4.6.3 extension length, in 32bits words */
 292     uint16_t     extType:7;         /**< 5.4.6.1 extension type */
 293     uint16_t     ef:1;              /**< 5.4.6.2 extension flag */
 294
 295     uint32_t    reserved0:8;
 296     uint32_t    mcScaleOffset2:15;  /**< 5.4.7.5.3 scaling value for modulation compression */
 297     uint32_t    csf2:1;             /**< 5.4.7.5.2 constellation shift flag */
 298     uint32_t    mcScaleReMask2:12;  /**< 5.4.7.5.1 modulation compression power scale RE mask */
 299     uint32_t    mcScaleOffset1:15;  /**< 5.4.7.5.3 scaling value for modulation compression */
 300     uint32_t    csf1:1;             /**< 5.4.7.5.2 constellation shift flag */
 301     uint32_t    mcScaleReMask1:12;  /**< 5.4.7.5.1 modulation compression power scale RE mask */
 302
 303     uint16_t    reserved1;
 304     } __attribute__((__packed__));
 305
 306 /**********************************************************
 307  * Scheduling and Beam-forming Commands 5.4.2
 308  **********************************************************/
 309 /**
 310  * @ingroup xran_cp_pkt
 311  *
 312  * @description
 313  *      Section header definition for type 0
 314  */
 315 struct xran_cp_radioapp_section0_header {   // 12bytes (6+2+1+2+1)
 316     struct xran_cp_radioapp_common_header cmnhdr;
 317     uint16_t    timeOffset;             /**< 5.4.4.12 time offset */
 318
 319     struct xran_cp_radioapp_frameStructure  frameStructure;
 320     uint16_t    cpLength;               /**< 5.4.4.14 cyclic prefix length */
 321     uint8_t     reserved;
 322     } __attribute__((__packed__));
 323
 324 /**
 325  * @ingroup xran_cp_pkt
 326  *
 327  * @description
 328  *      Section definition for type 0: Unused RB or Symbols in DL or UL (Table 5-2)
 329  *      Not supported in this release
 330  */
 331 struct xran_cp_radioapp_section0 {          // 8bytes (4+4)
 332     struct xran_cp_radioapp_section_header hdr;
 333     } __attribute__((__packed__));
 334
 335 /**
 336  * @ingroup xran_cp_pkt
 337  *
 338  * @description
 339  *      Section header definition for type 1
 340  */
 341 struct xran_cp_radioapp_section1_header {   // 8bytes (6+1+1)
 342     struct xran_cp_radioapp_common_header cmnhdr;
 343     struct xran_radioapp_udComp_header udComp;
 344     uint8_t     reserved;
 345     } __attribute__((__packed__));
 346
 347 /**
 348  * @ingroup xran_cp_pkt
 349  *
 350  * @description
 351  *      Section definition for type 1: Most DL/UL Radio Channels (Table 5-3)
 352  */
 353 struct xran_cp_radioapp_section1 {          // 8bytes (4+4)
 354     struct xran_cp_radioapp_section_header hdr;
 355
 356     // section extensions               // 5.4.6 & 5.4.7
 357     //  .........
 358     } __attribute__((__packed__));
 359
 360 /**
 361  * @ingroup xran_cp_pkt
 362  *
 363  * @description
 364  *      Section header definition for type 3
 365  */
 366 struct xran_cp_radioapp_section3_header {   // 12bytes (6+2+1+2+1)
 367     struct xran_cp_radioapp_common_header cmnhdr;
 368     uint16_t    timeOffset;             /**< 5.4.4.12 time offset */
 369
 370     struct xran_cp_radioapp_frameStructure  frameStructure;
 371     uint16_t    cpLength;               /**< 5.4.4.14 cyclic prefix length */
 372     struct xran_radioapp_udComp_header udComp;
 373     } __attribute__((__packed__));
 374
 375 /**
 376  * @ingroup xran_cp_pkt
 377  *
 378  * @description
 379  *      Section definition for type 3: PRACH and Mixed-numerology Channels (Table 5-4)
 380  */
 381 struct xran_cp_radioapp_section3 {          // 12bytes (4+4+4)
 382     struct xran_cp_radioapp_section_header hdr;
 383     uint32_t    freqOffset:24;          /**< 5.4.5.11 frequency offset */
 384     uint32_t    reserved:8;
 385
 386     // section extensions               // 5.4.6 & 5.4.7
 387     //  .........
 388     } __attribute__((__packed__));
 389
 390 /**
 391  * @ingroup xran_cp_pkt
 392  *
 393  * @description
 394  *      Section header definition for type 5
 395  */
 396 struct xran_cp_radioapp_section5_header {   // 8bytes (6+1+1)
 397     struct xran_cp_radioapp_common_header cmnhdr;
 398     struct xran_radioapp_udComp_header udComp;
 399     uint8_t     reserved;
 400     } __attribute__((__packed__));
 401
 402 /**
 403  * @ingroup xran_cp_pkt
 404  *
 405  * @description
 406  *      Section definition for type 5: UE scheduling information (Table 5-5)
 407  *      Not supported in this release
 408  */
 409 struct xran_cp_radioapp_section5 {
 410     struct xran_cp_radioapp_section_header hdr;
 411
 412     // section extensions               // 5.4.6 & 5.4.7
 413     //  .........
 414     } __attribute__((__packed__));
 415
 416 /**
 417  * @ingroup xran_cp_pkt
 418  *
 419  * @description
 420  *      Section header definition for type 6
 421  */
 422 struct xran_cp_radioapp_section6_header {   // 8bytes (6+1+1)
 423     struct xran_cp_radioapp_common_header cmnhdr;
 424     uint8_t     numberOfUEs;            /**< 5.4.4.11 number of UEs */
 425     uint8_t     reserved;
 426     } __attribute__((__packed__));
 427
 428 /**
 429  * @ingroup xran_cp_pkt
 430  *
 431  * @description
 432  *      Section definition for type 5: Channel Information (Table 5-6)
 433  *      Not supported in this release
 434  */
 435 struct xran_cp_radioapp_section6 {
 436     uint32_t    regularizationFactor:16;/**< 5.4.5.12 regularization Factor */
 437     uint32_t    ueId:15;                /**< 5.4.5.10 UE identifier */
 438     uint32_t    ef:1;                   /**< 5.4.5.8 extension flag */
 439     uint8_t     startPrbch:2;           /**< 5.4.5.4 starting PRB of control section */
 440     uint8_t     symInc:1;               /**< 5.4.5.3 symbol number increment command XRAN_SYMBOLNUMBER_xxxx */
 441     uint8_t     rb:1;                   /**< 5.4.5.2 resource block indicator, XRAN_RBIND_xxx */
 442     uint8_t     reserved:4;
 443     uint8_t     startPrbcl:8;           /**< 5.4.5.4 starting PRB of control section */
 444     uint8_t     numPrbc:8;              /**< 5.4.5.6 number of contiguous PRBs per control section */
 445
 446     // ciIQsamples start from here      // 5.4.5.13 channel information I and Q values
 447     //  .........
 448     //
 449     // section extensions               // 5.4.6 & 5.4.7
 450     //  .........
 451     } __attribute__((__packed__));
 452
 453 /**
 454  * @ingroup xran_cp_pkt
 455  *
 456  * @description
 457  *      Section header definition for type 7: LAA
 458  *      Not supported in this release
 459  */
 460 struct xran_cp_radioapp_section7_header {
 461     struct xran_cp_radioapp_common_header cmnhdr;
 462     uint16_t    reserved;
 463     uint8_t     laaMsgLen:4;            /**< 5.4.5.15 LAA message length */
 464     uint8_t     laaMsgType:4;           /**< 5.4.5.14 LAA message type */
 465
 466     // Payload start from here          // 5.4.5.16 ~ 5.4.5.32
 467     } __attribute__((__packed__));
 468
 469 #ifdef __cplusplus
 470 }
 471 #endif
 472
 473 #endif  /* _XRAN_PKT_CP_H_ */