fhi_lib/lib/api/xran_pkt.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 /**
  21  * @brief Definitions and support functions to process XRAN packet
  22  * @file xran_pkt.h
  23  * @ingroup group_source_xran
  24  * @author Intel Corporation
  25  **/
  26
  27 /* XRAN-FH.CUS.0-v02.01.03 xRAN Front haul Working Group Control, User and Synchronization Plane Specification */
  28
  29 /*
  30  * Layer common to data and control packets
  31  */
  32
  33 #ifndef _XRAN_PKT_H_
  34 #define _XRAN_PKT_H_
  35
  36 #include <rte_common.h>
  37 #include <rte_ether.h>
  38 #include <rte_byteorder.h>
  39
  40
  41 /**
  42  *****************************************************************************
  43  * @file xran_pkt.h
  44  *
  45  * @defgroup xran_common_pkt XRAN Packet definitions and functions
  46  * @ingroup xran
  47  *
  48  * @description
  49  *      Definitions and support functions to process XRAN packet
  50  *****************************************************************************/
  51
  52 #define ECPRI_MAX_PAYLOAD_SIZE 65535 /**< Max packet size taken in this implementation */
  53
  54 /* XRAN spec: For this encapsulation, either the eCPRI Ethertype or the IEEE 1914.3 Ethertype shall be use */
  55 #define XRAN_ETHER_TYPE 0xAEFE /**< defined by eCPRI Specification V1.1 */
  56
  57 #define XRAN_ECPRI_VER      0x0001      /**< eCPRI protocol revision 3.1.3.1.1 */
  58 #define XRAN_PAYLOAD_VER    0x0001      /**< Payload version 5.4.4.2 */
  59
  60 #define VLAN_ID  0 /**< Default Tag protocol identifier (TPID)*/
  61 #define VLAN_PCP 7 /**< U-Plane and C-Plane only see Table 3 5 : Quality of service classes */
  62
  63 /**
  64  ******************************************************************************
  65  * @ingroup xran_common_pkt
  66  *
  67  * @description
  68  *       eCPRI message types
  69  *       as per eCPRI spec 3.2.4. Message Types
  70  *****************************************************************************/
  71 enum ecpri_msg_type
  72 {
  73      ECPRI_IQ_DATA           = 0x00, /**< U-plane: IQ data */
  74      ECPRI_BIT_SEQUENCE      = 0x01, /* msg type is not supported */
  75      ECPRI_RT_CONTROL_DATA   = 0x02, /**< C-plane: Control */
  76
  77      /* Below msg types are not supported */
  78      ECPRI_GEN_DATA_TRANSFER = 0x03,
  79      ECPRI_REMOTE_MEM_ACCESS = 0x04,
  80      ECPRI_DELAY_MEASUREMENT = 0x05,
  81      ECPRI_REMOTE_RESET      = 0x06,
  82      ECPRI_EVENT_INDICATION  = 0x07,
  83      ECPRI_MSG_TYPE_MAX
  84 };
  85
  86 /**
  87  ******************************************************************************
  88  * @ingroup xran_common_pkt
  89  *
  90  * @description
  91  *       see 3.1.3.1.7 ecpriSeqid (message identifier)
  92  *****************************************************************************/
  93 struct ecpri_seq_id
  94 {
  95     uint8_t seq_id:8; /**< Sequence ID */
  96     uint8_t sub_seq_id:7; /**< Subsequence ID */
  97     uint8_t e_bit:1;  /**< E bit */
  98 } __rte_packed;
  99
 100
 101 /**
 102  ******************************************************************************
 103  * @ingroup xran_common_pkt
 104  *
 105  * @description
 106  *       Structure holds common eCPRI header as per
 107  *       Table 3 1 : eCPRI Transport Header Field Definitions
 108  *****************************************************************************/
 109 struct xran_ecpri_hdr
 110 {
 111     uint8_t ecpri_concat:1; /**< This parameter indicates when eCPRI concatenation is in use
 112                             (allowing multiple eCPRI messages in a single Ethernet payload).
 113                             NOTE: This parameter is part of the eCPRI common header. */
 114     uint8_t ecpri_resv:3; /**< This parameter is reserved for eCPRI future use.
 115                                NOTE: This parameter is part of the eCPRI common header. */
 116     uint8_t ecpri_ver:4; /**< This parameter indicates the eCPRI protocol version.
 117                               NOTE: This parameter is part of the eCPRI common header. */
 118     uint8_t ecpri_mesg_type:8; /**< This parameter indicates the type of service conveyed by
 119                                the message type. NOTE: This parameter is part of the eCPRI
 120                                common header. NOTE: In this version of the specification,
 121                                only values "0000 0000b" and "0000 0010b" and "0000 0101b" are used. */
 122     rte_be16_t ecpri_payl_size:16; /**< This parameter is the size in bytes of the payload part
 123                                     of the corresponding eCPRI message. It does not include any padding bytes
 124                                     following the eCPRI message. The maximum supported payload size is 216-1,
 125                                     but the actual size may be further limited by the maximum payload size of
 126                                     the underlying transport network. NOTE: This parameter is part of the
 127                                     eCPRI common header. */
 128
 129     rte_be16_t ecpri_xtc_id;  /**< 3.1.3.1.6 This parameter is a component_eAxC identifier (c_eAxC ID) and
 130                             identifies the specific data flow associated with each C-Plane (ecpriRtcid) or
 131                             U-Plane (ecpriPcid) message.  It is the analog of CPRI's "AxC" (antenna-carrier)
 132                             value so is designated here as "eAxC" ("e" for "extended" to accommodate multiple
 133                             bands and multiple component carriers).  In addition, the "eAxC" is divided into
 134                             "component eAxC" parts (c_eAxC) because multiple lls-CU processors may contribute
 135                             to a single eAxC and must be identified for correct data routing. */
 136
 137     struct ecpri_seq_id ecpri_seq_id; /**< This parameter provides unique message identification and ordering on
 138         two different levels. The first octet of this parameter is the Sequence ID, which is used to identify ordering of
 139         messages within an eAxC message stream.  The Sequence ID field increments and wraps independently for each U-Plane
 140         eAxC DL, U-Plane eAxC UL, C-Plane eAxC DL, and C-Plane eAxC UL, even if they share the same eAxC ID.
 141         The Sequence ID is used to verify that all messages are received and also to reorder messages that are received out of order.
 142         The second octet of this parameter is the Subsequence ID. The Subsequence ID is used to verify ordering and implement
 143         reordering when radio-transport-level (eCPRI or IEEE-1914.3) fragmentation occurs.
 144         Radio-transport (eCPRI or IEEE-1914.3) fragmentation is a method of splitting U-plane messages containing one or
 145         more sections whose length exceeds the maximum packet or message length of the underlying protocol.
 146         The Subsequence ID field consists of a 7 bit Subsequence counter and a single bit field, called E-bit.
 147         The Subsequence number increments starting from zero for each fragment of a U-plane message.  The E bit
 148         is used to indicate the last message of the radio-transport level fragments.  It is always set to zero
 149         except for the last message of the U-plane fragment. In the case of C-plane messages radio-transport
 150         fragmentation is not allowed, therefore the Subsequence ID shall be set to zero, and the E bit set to one.
 151         See Section 3.1.4 for a description of the fragmentation process.
 152         NOTE: As an alternative to radio-transport-level fragmentation, application fragmentation can be implemented.
 153         In this case the application can take the responsibility to ensure all transport messages are not too long
 154         (fit within the necessary transport payload size).  When this "application layer fragmentation" is used,
 155         the subsequence identifier shall always be set to "0", and the E-bit set to "1" (See Section 3.1.4). */
 156
 157 } __rte_packed;
 158
 159 /**
 160  ******************************************************************************
 161  * @ingroup xran_common_pkt
 162  *
 163  * @description
 164  *       Structure holds complete xran packet header
 165  *       3.1.1  Ethernet Encapsulation
 166  *****************************************************************************/
 167 struct xran_pkt_hdr
 168 {
 169     struct ether_hdr eth_hdr; /**< Ethernet Header */
 170     struct vlan_hdr vlan_hdr; /**< VLAN Header */
 171     struct xran_ecpri_hdr ecpri_hdr; /**< eCPRI Transport Header */
 172 };
 173
 174 /**
 175  ******************************************************************************
 176  * @ingroup xran_common_pkt
 177  *
 178  * @description
 179  *      Enum used to set xRAN packet data direction (gNB Tx/Rx 5.4.4.1)
 180  *      uplink or downlink
 181  *****************************************************************************/
 182 enum xran_pkt_dir
 183 {
 184      XRAN_DIR_UL  = 0, /**< UL direction */
 185      XRAN_DIR_DL  = 1, /**< DL direction */
 186      XRAN_DIR_MAX
 187 };
 188
 189 /**
 190  ******************************************************************************
 191  * @ingroup xran_common_pkt
 192  *
 193  * @description
 194  *       Structure holds components of radio application header
 195  *       5.4.4 Coding of Information Elements - Application Layer, Common
 196  *       for U-plane as per 6.3.2       DL/UL Data
 197  *****************************************************************************/
 198 struct radio_app_common_hdr
 199 {
 200    /* Octet 9 */
 201    uint8_t filter_id:4; /**< This parameter defines an index to the channel filter to be
 202                               used between IQ data and air interface, both in DL and UL.
 203                               For most physical channels filterIndex =0000b is used which
 204                               indexes the standard channel filter, e.g. 100MHz channel filter
 205                               for 100MHz nominal carrier bandwidth. (see 5.4.4.3 for more) */
 206    uint8_t payl_ver:3; /**< This parameter defines the payload protocol version valid
 207                             for the following IEs in the application layer. In this version of
 208                             the specification payloadVersion=001b shall be used. */
 209    uint8_t data_direction:1; /**< This parameter indicates the gNB data direction. */
 210
 211    /* Octet 10 */
 212    uint8_t frame_id:8;    /**< This parameter is a counter for 10 ms frames (wrapping period 2.56 seconds) */
 213
 214    /* Octet 11 */
 215    /* Octet 12 */
 216    union {
 217        uint16_t value;
 218        struct {
 219            uint16_t symb_id:6; /**< This parameter identifies the first symbol number within slot,
 220                                           to which the information of this message is applies. */
 221            uint16_t slot_id:6; /**< This parameter is the slot number within a 1ms sub-frame. All slots in
 222                                    one sub-frame are counted by this parameter, slotId running from 0 to Nslot-1.
 223                                    In this version of the specification the maximum Nslot=16, All
 224                                    other values of the 6 bits are reserved for future use. */
 225            uint16_t subframe_id:4; /**< This parameter is a counter for 1 ms sub-frames within 10ms frame. */
 226        };
 227    }sf_slot_sym;
 228
 229 } __rte_packed;
 230
 231 /**
 232  ******************************************************************************
 233  * @ingroup xran_common_pkt
 234  *
 235  * @description
 236  *      This parameter defines the compression method and IQ bit width for the
 237  *      user data in the data section.  This field is absent from U-Plane messages
 238  *      when the static IQ format and compression method is configured via the M-Plane.
 239  *      In this way a single compression method and IQ bit width is provided
 240  *     (per UL and DL, per LTE and NR) without adding more overhead to U-Plane messages.
 241  *****************************************************************************/
 242 struct compression_hdr
 243 {
 244     uint8_t ud_iq_width:4; /**< Bit width of each I and each Q
 245                                 16 for udIqWidth=0, otherwise equals udIqWidth e.g. udIqWidth = 0000b means I and Q are each 16 bits wide;
 246                                 e.g. udIQWidth = 0001b means I and Q are each 1 bit wide;
 247                                 e.g. udIqWidth = 1111b means I and Q are each 15 bits wide
 248                                 */
 249     uint8_t ud_comp_meth:4;
 250     /**< udCompMeth|  compression method         |udIqWidth meaning
 251     ---------------+-----------------------------+--------------------------------------------
 252     0000b          | no compression              |bitwidth of each uncompressed I and Q value
 253     0001b          | block floating point        |bitwidth of each I and Q mantissa value
 254     0010b          | block scaling               |bitwidth of each I and Q scaled value
 255     0011b          | mu-law                      |bitwidth of each compressed I and Q value
 256     0100b          | modulation compression      |bitwidth of each compressed I and Q value
 257     0100b - 1111b  | reserved for future methods |depends on the specific compression method
 258     */
 259 } __rte_packed;
 260
 261 #endif