fhi_lib/lib/api/xran_pkt.h

   1 /******************************************************************************
   2 *
   3 *   Copyright (c) 2020 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 Definitions and support functions to process XRAN packet
  21  * @file xran_pkt.h
  22  * @ingroup group_source_xran
  23  * @author Intel Corporation
  24  **/
  25
  26 /* ORAN-WG4.CUS.0-v01.00 O-RAN Fronthaul Working Group
  27                          Control, User and Synchronization Plane Specification
  28 */
  29
  30 /*
  31  * Layer common to data and control packets
  32  */
  33
  34 #ifndef _XRAN_PKT_H_
  35 #define _XRAN_PKT_H_
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 #include <rte_common.h>
  42 #include <rte_ether.h>
  43 #include <rte_byteorder.h>
  44
  45 /**
  46  *****************************************************************************
  47  * @file xran_pkt.h
  48  *
  49  * @defgroup xran_common_pkt XRAN Packet definitions and functions
  50  * @ingroup xran
  51  *
  52  * @description
  53  *      Definitions and support functions to process XRAN packet
  54  *****************************************************************************/
  55
  56 #define ECPRI_MAX_PAYLOAD_SIZE 65535 /**< Max packet size taken in this implementation */
  57
  58 /* XRAN spec: For this encapsulation, either the eCPRI Ethertype or the IEEE 1914.3 Ethertype shall be use */
  59 #define XRAN_ETHER_TYPE 0xAEFE /**< defined by eCPRI Specification V1.1 */
  60
  61 #define XRAN_ECPRI_VER      0x0001      /**< eCPRI protocol revision 3.1.3.1.1 */
  62 #define XRAN_PAYLOAD_VER    0x0001      /**< Payload version 5.4.4.2 */
  63
  64 #define VLAN_ID  0 /**< Default Tag protocol identifier (TPID)*/
  65 #define VLAN_PCP 7 /**< U-Plane and C-Plane only see Table 3 5 : Quality of service classes */
  66
  67 #define XRAN_MTU_DEFAULT        RTE_ETHER_MTU
  68 #define XRAN_APP_LAYER_MAX_SIZE_L2_DEFAUT    (XRAN_MTU_DEFAULT - 8) /**< In case of L2 only solution, application layer maximum transmission unit size
  69                                                                          is standard IEEE 802.3 Ethernet frame payload
  70                                                                          size (1500 bytes) ? transport overhead (8 bytes) = 1492 bytes (or larger for Jumbo frames) */
  71
  72 #ifndef OK
  73 #define OK 0    /* Function executed correctly */
  74 #endif
  75 #ifndef FAIL
  76 #define FAIL 1  /* Function failed to execute */
  77 #endif
  78 #define NS_PER_SEC 1000000000LL
  79
  80 /**
  81  ******************************************************************************
  82  * @ingroup xran_common_pkt
  83  *
  84  * @description
  85  *       eCPRI message types
  86  *       as per eCPRI spec 3.2.4. Message Types
  87  *****************************************************************************/
  88 enum ecpri_msg_type
  89 {
  90      ECPRI_IQ_DATA           = 0x00, /**< U-plane: IQ data */
  91      ECPRI_BIT_SEQUENCE      = 0x01, /* msg type is not supported */
  92      ECPRI_RT_CONTROL_DATA   = 0x02, /**< C-plane: Control */
  93
  94      /* Below msg types are not supported */
  95      ECPRI_GEN_DATA_TRANSFER = 0x03,
  96      ECPRI_REMOTE_MEM_ACCESS = 0x04,
  97      ECPRI_DELAY_MEASUREMENT = 0x05,
  98      ECPRI_REMOTE_RESET      = 0x06,
  99      ECPRI_EVENT_INDICATION  = 0x07,
 100      ECPRI_MSG_TYPE_MAX
 101 };
 102
 103 /**
 104  ******************************************************************************
 105  * @ingroup xran_common_pkt
 106  *
 107  * @description
 108  *       eCPRI Timestamp for one-way delay measurements format per IEEE-1588
 109  *       clause 5.3.3.
 110  *****************************************************************************/
 111
 112 typedef struct  {
 113     uint16_t    secs_msb;    // 6 bytes for seconds
 114     uint32_t    secs_lsb;
 115     uint32_t    ns;          // 4 bytes for nanoseconds
 116     } TimeStamp;
 117
 118
 119 /**
 120  ******************************************************************************
 121  * @ingroup xran_common_pkt
 122  *
 123  * @description
 124  *       eCPRI action types
 125  *       as per eCPRI spec Table 8 action Types
 126  *****************************************************************************/
 127 enum ecpri_action_type
 128 {
 129     ECPRI_REQUEST             = 0x00, /* Uses Time Stamp T1 and Comp Delay 1 */
 130     ECPRI_REQUEST_W_FUP       = 0x01, /* Uses 0 for Time Stamp and Comp Delay 1 */
 131     ECPRI_RESPONSE            = 0x02, /* Uses Time Stamp T2 and Comp Delay 2 */
 132     ECPRI_REMOTE_REQ          = 0x03, /* Uses 0 for Time Stamp and Comp Delay */
 133     ECPRI_REMOTE_REQ_W_FUP    = 0x04, /* Uses 0 for Time Stamp and Comp Delay */
 134     ECPRI_FOLLOW_UP           = 0x05, /* Uses Time Info and Comp Delay Info */
 135     ECPRI_ACTION_TYPE_MAX
 136 };
 137
 138 /**
 139  ******************************************************************************
 140  * @ingroup xran_common_pkt
 141  *
 142  * @description
 143  *       see 3.1.3.1.7 ecpriSeqid (message identifier)
 144  *****************************************************************************/
 145 union ecpri_seq_id
 146 {
 147     struct
 148 {
 149     uint8_t seq_id:8;       /**< Sequence ID */
 150     uint8_t sub_seq_id:7;   /**< Subsequence ID */
 151     uint8_t e_bit:1;        /**< E bit */
 152     } bits;
 153     struct
 154     {
 155         uint16_t data_num_1;
 156     } data;
 157 } __rte_packed;
 158
 159 #define ecpri_seq_id_bitfield_seq_id          0
 160 #define ecpri_seq_id_bitfield_sub_seq_id      8
 161 #define ecpri_seq_id_bitfield_e_bit           15
 162
 163 /**
 164  ******************************************************************************
 165  * @ingroup xran_common_pkt
 166  *
 167  * @description
 168  *       Structure holds common eCPRI header as per
 169  *       Table 3 1 : eCPRI Transport Header Field Definitions
 170  *****************************************************************************/
 171 union xran_ecpri_cmn_hdr
 172 {
 173     struct
 174 {
 175     uint8_t     ecpri_concat:1;     /**< 3.1.3.1.3 eCPRI concatenation indicator */
 176     uint8_t     ecpri_resv:3;       /**< 3.1.3.1.2 eCPRI reserved */
 177     uint8_t     ecpri_ver:4;        /**< 3.1.3.1.1 eCPRI protocol revision, defined in XRAN_ECPRI_VER */
 178     uint8_t     ecpri_mesg_type;    /**< 3.1.3.1.4 eCPRI message type, defined in ecpri_msg_type */
 179     uint16_t    ecpri_payl_size;    /**< 3.1.3.1.5 eCPRI payload size, without common header and any padding bytes */
 180     } bits;
 181     struct
 182     {
 183         uint32_t    data_num_1;
 184     } data;
 185 } __rte_packed;
 186
 187 #define xran_ecpri_cmn_hdr_bitfield_EcpriVer        4
 188 #define xran_ecpri_cmn_hdr_bitfield_EcpriMsgType    8
 189 /**
 190  ******************************************************************************
 191  * @ingroup xran_common_pkt
 192  *
 193  * @description
 194  *       Structure holds common eCPRI delay measuurement header as per
 195  *       Table 2.17 : eCPRI One-Way delay measurement message
 196  *****************************************************************************/
 197 struct xran_ecpri_delay_meas_pl
 198 {
 199     uint8_t             MeasurementID;        /**< Table 2-17 Octet 5     */
 200     uint8_t             ActionType;           /**< Table 2-17 Octet 6     */
 201     TimeStamp           ts;                   /**< Table 2-17 Octet 7-16  */
 202     int64_t             CompensationValue;    /**< Table 2-17 Octet 17    */
 203     uint8_t             DummyBytes[1400];       /**< Table 2-17 Octet 25    */
 204 } /*__rte_packed*/;
 205
 206 /**
 207  ******************************************************************************
 208  * @ingroup xran_common_pkt
 209  *
 210  * @description
 211  *       Structure holds common eCPRI cmn header per eCPRI figure 8 and the measurement delay header and pl per
 212  *       eCPRI Figure 23  : eCPRI One-Way delay measurement message
 213  *****************************************************************************/
 214  struct xran_ecpri_del_meas_pkt
 215  {
 216     union xran_ecpri_cmn_hdr cmnhdr;
 217     struct xran_ecpri_delay_meas_pl  deMeasPl;
 218  }/*__rte_packed*/;
 219
 220 /**
 221  ******************************************************************************
 222  * @ingroup xran_common_pkt
 223  *
 224  * @description
 225  *       Structure holds eCPRI transport header as per
 226  *       Table 3 1 : eCPRI Transport Header Field Definitions
 227  *****************************************************************************/
 228 struct xran_ecpri_hdr
 229 {
 230     union xran_ecpri_cmn_hdr cmnhdr;
 231     rte_be16_t ecpri_xtc_id;            /**< 3.1.3.1.6 real time control data / IQ data transfer message series identifier */
 232     union ecpri_seq_id ecpri_seq_id;   /**< 3.1.3.1.7 message identifier */
 233 } __rte_packed;
 234
 235
 236 /**
 237  ******************************************************************************
 238  * @ingroup xran_common_pkt
 239  *
 240  * @description
 241  *      Enum used to set xRAN packet data direction (gNB Tx/Rx 5.4.4.1)
 242  *      uplink or downlink
 243  *****************************************************************************/
 244 enum xran_pkt_dir
 245 {
 246      XRAN_DIR_UL  = 0, /**< UL direction */
 247      XRAN_DIR_DL  = 1, /**< DL direction */
 248      XRAN_DIR_MAX
 249 };
 250
 251 /**
 252  ******************************************************************************
 253  * @ingroup xran_common_pkt
 254  *
 255  * @description
 256  *       Structure holds components of radio application header
 257  *       5.4.4 Coding of Information Elements - Application Layer, Common
 258  *       for U-plane as per 6.3.2       DL/UL Data
 259  *****************************************************************************/
 260 struct radio_app_common_hdr
 261 {
 262    /* Octet 9 */
 263     union {
 264         uint8_t value;
 265         struct {
 266    uint8_t filter_id:4; /**< This parameter defines an index to the channel filter to be
 267                               used between IQ data and air interface, both in DL and UL.
 268                               For most physical channels filterIndex =0000b is used which
 269                               indexes the standard channel filter, e.g. 100MHz channel filter
 270                               for 100MHz nominal carrier bandwidth. (see 5.4.4.3 for more) */
 271    uint8_t payl_ver:3; /**< This parameter defines the payload protocol version valid
 272                             for the following IEs in the application layer. In this version of
 273                             the specification payloadVersion=001b shall be used. */
 274    uint8_t data_direction:1; /**< This parameter indicates the gNB data direction. */
 275         };
 276     }data_feature;
 277
 278    /* Octet 10 */
 279    uint8_t frame_id:8;    /**< This parameter is a counter for 10 ms frames (wrapping period 2.56 seconds) */
 280
 281    /* Octet 11 */
 282    /* Octet 12 */
 283    union {
 284        uint16_t value;
 285        struct {
 286            uint16_t symb_id:6; /**< This parameter identifies the first symbol number within slot,
 287                                           to which the information of this message is applies. */
 288            uint16_t slot_id:6; /**< This parameter is the slot number within a 1ms sub-frame. All slots in
 289                                    one sub-frame are counted by this parameter, slotId running from 0 to Nslot-1.
 290                                    In this version of the specification the maximum Nslot=16, All
 291                                    other values of the 6 bits are reserved for future use. */
 292            uint16_t subframe_id:4; /**< This parameter is a counter for 1 ms sub-frames within 10ms frame. */
 293        };
 294    }sf_slot_sym;
 295
 296 } __rte_packed;
 297
 298 /**
 299  ******************************************************************************
 300  * @ingroup xran_common_pkt
 301  *
 302  * @description
 303  *      This parameter defines the compression method and IQ bit width for the
 304  *      user data in the data section.  This field is absent from U-Plane messages
 305  *      when the static IQ format and compression method is configured via the M-Plane.
 306  *      In this way a single compression method and IQ bit width is provided
 307  *     (per UL and DL, per LTE and NR) without adding more overhead to U-Plane messages.
 308  *****************************************************************************/
 309 struct compression_hdr
 310 {
 311     uint8_t ud_comp_meth:4;
 312     /**< udCompMeth|  compression method         |udIqWidth meaning
 313     ---------------+-----------------------------+--------------------------------------------
 314     0000b          | no compression              |bitwidth of each uncompressed I and Q value
 315     0001b          | block floating point        |bitwidth of each I and Q mantissa value
 316     0010b          | block scaling               |bitwidth of each I and Q scaled value
 317     0011b          | mu-law                      |bitwidth of each compressed I and Q value
 318     0100b          | modulation compression      |bitwidth of each compressed I and Q value
 319     0100b - 1111b  | reserved for future methods |depends on the specific compression method
 320     */
 321     uint8_t ud_iq_width:4; /**< Bit width of each I and each Q
 322                                 16 for udIqWidth=0, otherwise equals udIqWidth e.g. udIqWidth = 0000b means I and Q are each 16 bits wide;
 323                                 e.g. udIQWidth = 0001b means I and Q are each 1 bit wide;
 324                                 e.g. udIqWidth = 1111b means I and Q are each 15 bits wide
 325                                 */
 326 } __rte_packed;
 327
 328 /**
 329  ******************************************************************************
 330  * @ingroup xran_common_pkt
 331  *
 332  * @description
 333  *       Structure holds common xran packet header
 334  *       3.1.1  Ethernet Encapsulation
 335  *****************************************************************************/
 336 struct xran_pkt_comm_hdr
 337 {
 338     struct rte_ether_hdr eth_hdr; /**< Ethernet Header */
 339     struct xran_ecpri_hdr ecpri_hdr; /**< eCPRI Transport Header */
 340 } __rte_packed;
 341
 342 #ifdef __cplusplus
 343 }
 344 #endif
 345
 346 #endif