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. Not supported.
 205  */
 206 struct xran_cp_radioapp_section_ext3_first {
 207     /* 16 bytes, need to convert byte order for two parts
 208      *   - 8 / 8 bytes
 209      */
 210     uint32_t    reserved1:8;
 211     uint32_t    crsSymNum:4;        /**< 5.4.7.3.6 CRS symbol number indication */
 212     uint32_t    reserved0:3;
 213     uint32_t    crsShift:1;         /**< 5.4.7.3.7 CRS shift used for DL transmission */
 214     uint32_t    crsReMask:12;       /**< 5.4.7.3.5 CRS resource element mask */
 215     uint32_t    txScheme:4;         /**< 5.4.7.3.3 transmission scheme */
 216     uint32_t    numLayers:4;        /**< 5.4.7.3.4 number of layers used for DL transmission */
 217     uint32_t    layerId:4;          /**< 5.4.7.3.2 Layer ID for DL transmission */
 218     uint32_t    codebookIndex:8;    /**< 5.4.7.3.1 precoder codebook used for transmission */
 219     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 220     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 221     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 222
 223     uint16_t    beamIdAP3;          /**< 5.4.7.3.10 beam id to be used for antenna port 3 */
 224     uint16_t    beamIdAP2;          /**< 5.4.7.3.9 beam id to be used for antenna port 2 */
 225     uint16_t    beamIdAP1;          /**< 5.4.7.3.8 beam id to be used for antenna port 1 */
 226     uint16_t    reserved2;
 227     } __attribute__((__packed__));
 228
 229 /**
 230  * @ingroup xran_cp_pkt
 231  *
 232  * @description
 233  *      DL Precoding Extension Type(ExtType 3) for non-first data layer.
 234  *      Defined in 5.4.7.3 Table 5-23.
 235  *      Only be used for LTE TM2-4 and not for other LTE TMs nor NR.
 236  *      The structure is reordered for byte order conversion. Not supported.
 237  */
 238 struct xran_cp_radioapp_section_ext3_non_first {
 239     /* 4 bytes, need to convert byte order at once */
 240     uint32_t    numLayers:4;        /**< 5.4.7.3.4 number of layers used for DL transmission */
 241     uint32_t    layerId:4;          /**< 5.4.7.3.2 Layer ID for DL transmission */
 242     uint32_t    codebookIndex:8;    /**< 5.4.7.3.1 precoder codebook used for transmission */
 243
 244     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 245     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 246     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 247     } __attribute__((__packed__));
 248
 249 /**
 250  * @ingroup xran_cp_pkt
 251  *
 252  * @description
 253  *      Modulation Compression Parameter Extension Type(ExtType 4), 5.4.7.4
 254  *      Only applies to section type 1 and 3.
 255  *      The structure is reordered for byte order conversion.
 256  */
 257 struct xran_cp_radioapp_section_ext4 {
 258     /* 4 bytes, need to convert byte order at once */
 259     uint32_t    modCompScaler:15;   /**< 5.4.7.4.2 modulation compression scaler value */
 260     uint32_t    csf:1;              /**< 5.4.7.4.1 constellation shift flag */
 261
 262     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 263     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 264     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 265     } __attribute__((__packed__));
 266
 267 #if 0
 268 /**
 269  * @ingroup xran_cp_pkt
 270  *
 271  * @description
 272  *      Modulation Compression Additional Parameter Extension Type(ExtType 5) for one scaler value.
 273  *      Defined in 5.4.7.5 Table 5-26
 274  *      Only applies to section type 1 3, and 5.
 275  *      The structure is reordered for byte order conversion.
 276  */
 277 struct xran_cp_radioapp_section_ext5_1 {
 278     /* 8 bytes, need to convert byte order at once */
 279     uint32_t    reserved:20;
 280     uint32_t    mcScaleOffset:15;   /**< 5.4.7.5.3 scaling value for modulation compression */
 281     uint32_t    csf:1;              /**< 5.4.7.5.2 constellation shift flag */
 282     uint32_t    mcScaleReMask:12;   /**< 5.4.7.5.1 modulation compression power scale RE mask */
 283
 284     uint32_t    extLen:8;           /**< 5.4.6.3 extension length, in 32bits words */
 285     uint32_t    extType:7;          /**< 5.4.6.1 extension type */
 286     uint32_t    ef:1;               /**< 5.4.6.2 extension flag */
 287     } __attribute__((__packed__));
 288
 289 /**
 290  * @ingroup xran_cp_pkt
 291  *
 292  * @description
 293  *      Modulation Compression Additional Parameter Extension Type(ExtType 5) for two scaler values.
 294  *      Defined in 5.4.7.5 Table 5-27
 295  *      Only applies to section type 1 3, and 5.
 296  *      The structure is reordered for byte order conversion.
 297  */
 298 struct xran_cp_radioapp_section_ext5_2 {
 299     /* 12 bytes, need to convert byte order for two parts respectively
 300      *  - 2 and 8 bytes, reserved1 would be OK if it is zero
 301      */
 302     uint16_t     extLen:8;          /**< 5.4.6.3 extension length, in 32bits words */
 303     uint16_t     extType:7;         /**< 5.4.6.1 extension type */
 304     uint16_t     ef:1;              /**< 5.4.6.2 extension flag */
 305
 306     uint32_t    reserved0:8;
 307     uint32_t    mcScaleOffset2:15;  /**< 5.4.7.5.3 scaling value for modulation compression */
 308     uint32_t    csf2:1;             /**< 5.4.7.5.2 constellation shift flag */
 309     uint32_t    mcScaleReMask2:12;  /**< 5.4.7.5.1 modulation compression power scale RE mask */
 310     uint32_t    mcScaleOffset1:15;  /**< 5.4.7.5.3 scaling value for modulation compression */
 311     uint32_t    csf1:1;             /**< 5.4.7.5.2 constellation shift flag */
 312     uint32_t    mcScaleReMask1:12;  /**< 5.4.7.5.1 modulation compression power scale RE mask */
 313
 314     uint16_t    reserved1;
 315     } __attribute__((__packed__));
 316 #endif
 317
 318 struct xran_cp_radioapp_section_ext5 {
 319     uint32_t    reserved0:8;
 320     uint32_t    mcScaleOffset2:15;  /**< 5.4.7.5.3 scaling value for modulation compression */
 321     uint32_t    csf2:1;             /**< 5.4.7.5.2 constellation shift flag */
 322     uint32_t    mcScaleReMask2:12;  /**< 5.4.7.5.1 modulation compression power scale RE mask */
 323     uint32_t    mcScaleOffset1:15;  /**< 5.4.7.5.3 scaling value for modulation compression */
 324     uint32_t    csf1:1;             /**< 5.4.7.5.2 constellation shift flag */
 325     uint32_t    mcScaleReMask1:12;  /**< 5.4.7.5.1 modulation compression power scale RE mask */
 326     } __attribute__((__packed__));
 327
 328 /**********************************************************
 329  * Scheduling and Beam-forming Commands 5.4.2
 330  **********************************************************/
 331 /**
 332  * @ingroup xran_cp_pkt
 333  *
 334  * @description
 335  *      Section header definition for type 0
 336  */
 337 struct xran_cp_radioapp_section0_header {   // 12bytes (6+2+1+2+1)
 338     struct xran_cp_radioapp_common_header cmnhdr;
 339     uint16_t    timeOffset;             /**< 5.4.4.12 time offset */
 340
 341     struct xran_cp_radioapp_frameStructure  frameStructure;
 342     uint16_t    cpLength;               /**< 5.4.4.14 cyclic prefix length */
 343     uint8_t     reserved;
 344     } __attribute__((__packed__));
 345
 346 /**
 347  * @ingroup xran_cp_pkt
 348  *
 349  * @description
 350  *      Section definition for type 0: Unused RB or Symbols in DL or UL (Table 5-2)
 351  *      Not supported in this release
 352  */
 353 struct xran_cp_radioapp_section0 {          // 8bytes (4+4)
 354     struct xran_cp_radioapp_section_header hdr;
 355     } __attribute__((__packed__));
 356
 357 /**
 358  * @ingroup xran_cp_pkt
 359  *
 360  * @description
 361  *      Section header definition for type 1
 362  */
 363 struct xran_cp_radioapp_section1_header {   // 8bytes (6+1+1)
 364     struct xran_cp_radioapp_common_header cmnhdr;
 365     struct xran_radioapp_udComp_header udComp;
 366     uint8_t     reserved;
 367     } __attribute__((__packed__));
 368
 369 /**
 370  * @ingroup xran_cp_pkt
 371  *
 372  * @description
 373  *      Section definition for type 1: Most DL/UL Radio Channels (Table 5-3)
 374  */
 375 struct xran_cp_radioapp_section1 {          // 8bytes (4+4)
 376     struct xran_cp_radioapp_section_header hdr;
 377
 378     // section extensions               // 5.4.6 & 5.4.7
 379     //  .........
 380     } __attribute__((__packed__));
 381
 382 /**
 383  * @ingroup xran_cp_pkt
 384  *
 385  * @description
 386  *      Section header definition for type 3
 387  */
 388 struct xran_cp_radioapp_section3_header {   // 12bytes (6+2+1+2+1)
 389     struct xran_cp_radioapp_common_header cmnhdr;
 390     uint16_t    timeOffset;             /**< 5.4.4.12 time offset */
 391
 392     struct xran_cp_radioapp_frameStructure  frameStructure;
 393     uint16_t    cpLength;               /**< 5.4.4.14 cyclic prefix length */
 394     struct xran_radioapp_udComp_header udComp;
 395     } __attribute__((__packed__));
 396
 397 /**
 398  * @ingroup xran_cp_pkt
 399  *
 400  * @description
 401  *      Section definition for type 3: PRACH and Mixed-numerology Channels (Table 5-4)
 402  */
 403 struct xran_cp_radioapp_section3 {          // 12bytes (4+4+4)
 404     struct xran_cp_radioapp_section_header hdr;
 405     uint32_t    freqOffset:24;          /**< 5.4.5.11 frequency offset */
 406     uint32_t    reserved:8;
 407
 408     // section extensions               // 5.4.6 & 5.4.7
 409     //  .........
 410     } __attribute__((__packed__));
 411
 412 /**
 413  * @ingroup xran_cp_pkt
 414  *
 415  * @description
 416  *      Section header definition for type 5
 417  */
 418 struct xran_cp_radioapp_section5_header {   // 8bytes (6+1+1)
 419     struct xran_cp_radioapp_common_header cmnhdr;
 420     struct xran_radioapp_udComp_header udComp;
 421     uint8_t     reserved;
 422     } __attribute__((__packed__));
 423
 424 /**
 425  * @ingroup xran_cp_pkt
 426  *
 427  * @description
 428  *      Section definition for type 5: UE scheduling information (Table 5-5)
 429  *      Not supported in this release
 430  */
 431 struct xran_cp_radioapp_section5 {
 432     struct xran_cp_radioapp_section_header hdr;
 433
 434     // section extensions               // 5.4.6 & 5.4.7
 435     //  .........
 436     } __attribute__((__packed__));
 437
 438 /**
 439  * @ingroup xran_cp_pkt
 440  *
 441  * @description
 442  *      Section header definition for type 6
 443  */
 444 struct xran_cp_radioapp_section6_header {   // 8bytes (6+1+1)
 445     struct xran_cp_radioapp_common_header cmnhdr;
 446     uint8_t     numberOfUEs;            /**< 5.4.4.11 number of UEs */
 447     uint8_t     reserved;
 448     } __attribute__((__packed__));
 449
 450 /**
 451  * @ingroup xran_cp_pkt
 452  *
 453  * @description
 454  *      Section definition for type 5: Channel Information (Table 5-6)
 455  *      Not supported in this release
 456  */
 457 struct xran_cp_radioapp_section6 {
 458     uint32_t    regularizationFactor:16;/**< 5.4.5.12 regularization Factor */
 459     uint32_t    ueId:15;                /**< 5.4.5.10 UE identifier */
 460     uint32_t    ef:1;                   /**< 5.4.5.8 extension flag */
 461     uint8_t     startPrbch:2;           /**< 5.4.5.4 starting PRB of control section */
 462     uint8_t     symInc:1;               /**< 5.4.5.3 symbol number increment command XRAN_SYMBOLNUMBER_xxxx */
 463     uint8_t     rb:1;                   /**< 5.4.5.2 resource block indicator, XRAN_RBIND_xxx */
 464     uint8_t     reserved:4;
 465     uint8_t     startPrbcl:8;           /**< 5.4.5.4 starting PRB of control section */
 466     uint8_t     numPrbc:8;              /**< 5.4.5.6 number of contiguous PRBs per control section */
 467
 468     // ciIQsamples start from here      // 5.4.5.13 channel information I and Q values
 469     //  .........
 470     //
 471     // section extensions               // 5.4.6 & 5.4.7
 472     //  .........
 473     } __attribute__((__packed__));
 474
 475 /**
 476  * @ingroup xran_cp_pkt
 477  *
 478  * @description
 479  *      Section header definition for type 7: LAA
 480  *      Not supported in this release
 481  */
 482 struct xran_cp_radioapp_section7_header {
 483     struct xran_cp_radioapp_common_header cmnhdr;
 484     uint16_t    reserved;
 485     uint8_t     laaMsgLen:4;            /**< 5.4.5.15 LAA message length */
 486     uint8_t     laaMsgType:4;           /**< 5.4.5.14 LAA message type */
 487
 488     // Payload start from here          // 5.4.5.16 ~ 5.4.5.32
 489     } __attribute__((__packed__));
 490
 491 #ifdef __cplusplus
 492 }
 493 #endif
 494
 495 #endif  /* _XRAN_PKT_CP_H_ */