epan/dissectors/packet-mac-lte.h

   1 /* packet-mac-lte.h
   2  *
   3  * Martin Mathieson
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  *
  11  * This header file may also be distributed under
  12  * the terms of the BSD Licence as follows:
  13  *
  14  * Copyright (C) 2009 Martin Mathieson. All rights reserved.
  15  *
  16  * SPDX-License-Identifier: BSD-2-Clause
  17  */
  18
  19 #include "ws_symbol_export.h"
  20
  21 #include "packet-mac-3gpp-common.h"
  22
  23
  24 /* radioType */
  25 #define FDD_RADIO 1
  26 #define TDD_RADIO 2
  27
  28 /* Direction */
  29 #define DIRECTION_UPLINK   0
  30 #define DIRECTION_DOWNLINK 1
  31
  32 /* rntiType */
  33 #define NO_RNTI     0
  34 #define P_RNTI      1
  35 #define RA_RNTI     2
  36 #define C_RNTI      3
  37 #define SI_RNTI     4
  38 #define SPS_RNTI    5
  39 #define M_RNTI      6
  40 #define SL_BCH_RNTI 7
  41 #define SL_RNTI     8
  42 #define SC_RNTI     9
  43 #define G_RNTI      10
  44
  45 typedef enum mac_lte_oob_event {
  46     ltemac_send_preamble,
  47     ltemac_send_sr,
  48     ltemac_sr_failure
  49 } mac_lte_oob_event;
  50
  51 typedef enum mac_lte_dl_retx {
  52     dl_retx_no,
  53     dl_retx_yes,
  54     dl_retx_unknown
  55 } mac_lte_dl_retx;
  56
  57 /* N.B. These error codes are too specific to one old implementation, */
  58 /* all just shown as failures */
  59 typedef enum mac_lte_crc_status {
  60     crc_fail = 0,
  61     crc_success = 1,
  62     crc_high_code_rate = 2,
  63     crc_pdsch_lost = 3,
  64     crc_duplicate_nonzero_rv = 4,
  65     crc_false_dci = 5
  66 } mac_lte_crc_status;
  67
  68 /* N.B. for SCellIndex-r13 extends to 31 */
  69 typedef enum mac_lte_carrier_id {
  70     carrier_id_primary,
  71     carrier_id_secondary_1,
  72     carrier_id_secondary_2,
  73     carrier_id_secondary_3,
  74     carrier_id_secondary_4,
  75     carrier_id_secondary_5,
  76     carrier_id_secondary_6,
  77     carrier_id_secondary_7
  78 } mac_lte_carrier_id;
  79
  80 typedef enum mac_lte_ce_mode {
  81     no_ce_mode = 0,
  82     ce_mode_a = 1,
  83     ce_mode_b = 2
  84 } mac_lte_ce_mode;
  85
  86 typedef enum mac_lte_nb_mode {
  87     no_nb_mode = 0,
  88     nb_mode = 1
  89 } mac_lte_nb_mode;
  90
  91 /* Context info attached to each LTE MAC frame */
  92 typedef struct mac_lte_info
  93 {
  94     /* Needed for decode */
  95     uint8_t         radioType;
  96     uint8_t         direction;
  97     uint8_t         rntiType;
  98
  99     /* Extra info to display */
 100     uint16_t        rnti;
 101     uint16_t        ueid;
 102
 103     /* Timing info */
 104     uint16_t        sysframeNumber;
 105     uint16_t        subframeNumber;
 106     bool            sfnSfInfoPresent;
 107
 108     /* Optional field. More interesting for TDD (FDD is always -4 subframeNumber) */
 109     bool            subframeNumberOfGrantPresent;
 110     uint16_t        subframeNumberOfGrant;
 111
 112     /* Flag set only if doing PHY-level data test - i.e. there may not be a
 113        well-formed MAC PDU so just show as raw data */
 114     bool            isPredefinedData;
 115
 116     /* Length of DL PDU or UL grant size in bytes */
 117     uint16_t        length;
 118
 119     /* 0=newTx, 1=first-retx, etc */
 120     uint8_t         reTxCount;
 121     uint8_t         isPHICHNACK; /* false=PDCCH retx grant, true=PHICH NACK */
 122
 123     /* UL only.  Indicates if the R10 extendedBSR-Sizes parameter is set */
 124     bool            isExtendedBSRSizes;
 125
 126     /* UL only.  Indicates if the R10 simultaneousPUCCH-PUSCH parameter is set for PCell */
 127     bool            isSimultPUCCHPUSCHPCell;
 128
 129     /* UL only.  Indicates if the R10 extendedBSR-Sizes parameter is set for PSCell */
 130     bool            isSimultPUCCHPUSCHPSCell;
 131
 132     /* Status of CRC check. For UE it is DL only. For eNodeB it is UL
 133        only. For an analyzer, it is present for both DL and UL. */
 134     bool            crcStatusValid;
 135     mac_lte_crc_status crcStatus;
 136
 137     /* Carrier ID */
 138     mac_lte_carrier_id   carrierId;
 139
 140     /* DL only.  Is this known to be a retransmission? */
 141     mac_lte_dl_retx dl_retx;
 142
 143     /* DL only. CE mode to be used for RAR decoding */
 144     mac_lte_ce_mode ceMode;
 145
 146     /* DL and UL. NB-IoT mode of the UE */
 147     mac_lte_nb_mode nbMode;
 148
 149     /* UL only, for now used for CE mode A RAR decoding */
 150     uint8_t         nUlRb;
 151
 152     /* More Physical layer info (see direction above for which side of union to use) */
 153     union {
 154         struct mac_lte_ul_phy_info
 155         {
 156             uint8_t present;  /* Remaining UL fields are present and should be displayed */
 157             uint8_t modulation_type;
 158             uint8_t tbs_index;
 159             uint8_t resource_block_length;
 160             uint8_t resource_block_start;
 161             uint8_t harq_id;
 162             bool ndi;
 163         } ul_info;
 164         struct mac_lte_dl_phy_info
 165         {
 166             uint8_t present; /* Remaining DL fields are present and should be displayed */
 167             uint8_t dci_format;
 168             uint8_t resource_allocation_type;
 169             uint8_t aggregation_level;
 170             uint8_t mcs_index;
 171             uint8_t redundancy_version_index;
 172             uint8_t resource_block_length;
 173             uint8_t harq_id;
 174             bool ndi;
 175             uint8_t  transport_block;  /* 0..1 */
 176         } dl_info;
 177     } detailed_phy_info;
 178
 179     /* Relating to out-of-band events */
 180     /* N.B. dissector will only look to these fields if length is 0... */
 181     mac_lte_oob_event  oob_event;
 182     uint8_t            rapid;
 183     uint8_t            rach_attempt_number;
 184     #define MAX_SRs 20
 185     uint16_t           number_of_srs;
 186     uint16_t           oob_ueid[MAX_SRs];
 187     uint16_t           oob_rnti[MAX_SRs];
 188 } mac_lte_info;
 189
 190
 191 /* Accessor function to check if a frame was considered to be ReTx */
 192 bool is_mac_lte_frame_retx(packet_info *pinfo, uint8_t direction);
 193
 194 /**********************************************************************/
 195 /* UDP framing format                                                 */
 196 /* -----------------------                                            */
 197 /* Several people have asked about dissecting MAC by framing          */
 198 /* PDUs over IP.  A suggested format over UDP has been created        */
 199 /* and implemented by this dissector, using the definitions           */
 200 /* below. A link to an example program showing you how to encode      */
 201 /* these headers and send LTE MAC PDUs on a UDP socket is             */
 202 /* provided at https://gitlab.com/wireshark/wireshark/-/wikis/MAC-LTE */
 203 /*                                                                    */
 204 /* A heuristic dissector (enabled by a preference) will               */
 205 /* recognise a signature at the beginning of these frames.            */
 206 /**********************************************************************/
 207
 208
 209 /* Signature.  Rather than try to define a port for this, or make the
 210    port number a preference, frames will start with this string (with no
 211    terminating NULL */
 212 #define MAC_LTE_START_STRING "mac-lte"
 213
 214 /* Fixed fields.  This is followed by the following 3 mandatory fields:
 215    - radioType (1 byte)
 216    - direction (1 byte)
 217    - rntiType (1 byte)
 218    (where the allowed values are defined above */
 219
 220 /* Optional fields. Attaching this info to frames will allow you
 221    to show you display/filter/plot/add-custom-columns on these fields, so should
 222    be added if available.
 223    The format is to have the tag, followed by the value (there is no length field,
 224    it's implicit from the tag) */
 225
 226 #define MAC_LTE_RNTI_TAG            0x02
 227 /* 2 bytes, network order */
 228
 229 #define MAC_LTE_UEID_TAG            0x03
 230 /* 2 bytes, network order */
 231
 232 #define MAC_LTE_FRAME_SUBFRAME_TAG  0x04
 233 /* 2 bytes, network order, SFN is stored in 12 MSB and SF in 4 LSB */
 234
 235 #define MAC_LTE_PREDEFINED_DATA_TAG 0x05
 236 /* 1 byte */
 237
 238 #define MAC_LTE_RETX_TAG            0x06
 239 /* 1 byte */
 240
 241 #define MAC_LTE_CRC_STATUS_TAG      0x07
 242 /* 1 byte */
 243
 244 #define MAC_LTE_EXT_BSR_SIZES_TAG   0x08
 245 /* 0 byte */
 246
 247 #define MAC_LTE_SEND_PREAMBLE_TAG   0x09
 248 /* 2 bytes, RAPID value (1 byte) followed by RACH attempt number (1 byte) */
 249
 250 #define MAC_LTE_CARRIER_ID_TAG      0x0A
 251 /* 1 byte */
 252
 253 #define MAC_LTE_PHY_TAG             0x0B
 254 /* variable length, length (1 byte) then depending on direction
 255    in UL: modulation type (1 byte), TBS index (1 byte), RB length (1 byte),
 256           RB start (1 byte), HARQ id (1 byte), NDI (1 byte)
 257    in DL: DCI format (1 byte), resource allocation type (1 byte), aggregation level (1 byte),
 258           MCS index (1 byte), redundancy version (1 byte), resource block length (1 byte),
 259           HARQ id (1 byte), NDI (1 byte), TB (1 byte), DL reTx (1 byte) */
 260
 261 #define MAC_LTE_SIMULT_PUCCH_PUSCH_PCELL_TAG  0x0C
 262 /* 0 byte */
 263
 264 #define MAC_LTE_SIMULT_PUCCH_PUSCH_PSCELL_TAG 0x0D
 265 /* 0 byte */
 266
 267 #define MAC_LTE_CE_MODE_TAG         0x0E
 268 /* 1 byte containing mac_lte_ce_mode enum value */
 269
 270 #define MAC_LTE_NB_MODE_TAG         0x0F
 271 /* 1 byte containing mac_lte_nb_mode enum value */
 272
 273 #define MAC_LTE_N_UL_RB_TAG         0x10
 274 /* 1 byte containing the number of UL resource blocks: 6, 15, 25, 50, 75 or 100 */
 275
 276 #define MAC_LTE_SR_TAG              0x11
 277 /* 2 bytes for the number of items, followed by that number of ueid, rnti (2 bytes each) */
 278
 279
 280 /* MAC PDU. Following this tag comes the actual MAC PDU (there is no length, the PDU
 281    continues until the end of the frame) */
 282 #define MAC_LTE_PAYLOAD_TAG 0x01
 283
 284
 285 /* Type to store parameters for configuring LCID->RLC channel settings for DRB */
 286 /* Some are optional, and may not be seen (e.g. on reestablishment) */
 287 typedef struct drb_mapping_t
 288 {
 289     uint16_t   ueid;                /* Mandatory */
 290     uint8_t    drbid;               /* Mandatory */
 291     bool       lcid_present;
 292     uint8_t    lcid;                /* Part of LogicalChannelConfig - optional */
 293     bool       rlcMode_present;
 294     uint8_t    rlcMode;             /* Part of RLC config - optional */
 295     bool       rlc_ul_ext_li_field; /* Part of RLC config - optional */
 296     bool       rlc_dl_ext_li_field; /* Part of RLC config - optional */
 297     bool       rlc_ul_ext_am_sn;    /* Part of RLC config - optional */
 298     bool       rlc_dl_ext_am_sn;    /* Part of RLC config - optional */
 299     bool       um_sn_length_present;
 300     uint8_t    um_sn_length;        /* Part of RLC config - optional */
 301     bool       ul_priority_present;
 302     uint8_t    ul_priority;         /* Part of LogicalChannelConfig - optional */
 303     bool       pdcp_sn_size_present;
 304     uint8_t    pdcp_sn_size;        /* Part of pdcp-Config - optional */
 305 } drb_mapping_t;
 306
 307
 308 /* Set details of an LCID -> drb channel mapping.  To be called from
 309    configuration protocol (e.g. RRC) */
 310 void set_mac_lte_channel_mapping(drb_mapping_t *drb_mapping);
 311
 312 /* Return mode of bearer, or 0 if not found/known */
 313 uint8_t get_mac_lte_channel_mode(uint16_t ueid, uint8_t drbid);
 314
 315 /* Dedicated DRX config. Used to verify that a sensible config is given.
 316    Also, beginning to configure MAC with this config and (optionally) show
 317    DRX config and state (cycles/timers) attached to each UL/DL PDU! */
 318 typedef struct drx_config_t {
 319     bool        configured;
 320     uint32_t    frameNum;
 321     uint32_t    previousFrameNum;
 322
 323     uint32_t    onDurationTimer;
 324     uint32_t    inactivityTimer;
 325     uint32_t    retransmissionTimer;
 326     uint32_t    longCycle;
 327     uint32_t    cycleOffset;
 328     /* Optional Short cycle */
 329     bool        shortCycleConfigured;
 330     uint32_t    shortCycle;
 331     uint32_t    shortCycleTimer;
 332 } drx_config_t;
 333
 334 /* Functions to set/release up dedicated DRX config */
 335 void set_mac_lte_drx_config(uint16_t ueid, drx_config_t *drx_config, packet_info *pinfo);
 336 void set_mac_lte_drx_config_release(uint16_t ueid,  packet_info *pinfo);
 337
 338 /* RRC can tell this dissector which RAPIDs are Group A, Group A&B */
 339 void set_mac_lte_rapid_ranges(unsigned groupA, unsigned all_RA);
 340
 341 /* RRC can indicate whether extended BSR sizes are used */
 342 void set_mac_lte_extended_bsr_sizes(uint16_t ueid, bool use_ext_bsr_sizes, packet_info *pinfo);
 343
 344 /* RRC can indicate whether simultaneous PUCCH/PUSCH is used */
 345 typedef enum {
 346     SIMULT_PUCCH_PUSCH_PCELL = 0,
 347     SIMULT_PUCCH_PUSCH_PSCELL
 348 } simult_pucch_pusch_cell_type;
 349 void set_mac_lte_simult_pucch_pusch(uint16_t ueid, simult_pucch_pusch_cell_type cell_type, bool use_simult_pucch_pusch, packet_info *pinfo);
 350
 351 /* Functions to be called from outside this module (e.g. in a plugin, where mac_lte_info
 352    isn't available) to get/set per-packet data */
 353 WS_DLL_PUBLIC
 354 mac_lte_info *get_mac_lte_proto_data(packet_info *pinfo);
 355 WS_DLL_PUBLIC
 356 void set_mac_lte_proto_data(packet_info *pinfo, mac_lte_info *p_mac_lte_info);
 357
 358 /* Function to attempt to populate p_mac_lte_info using framing definition above */
 359 bool dissect_mac_lte_context_fields(struct mac_lte_info  *p_mac_lte_info, tvbuff_t *tvb,
 360                                         packet_info *pinfo, proto_tree *tree, int *p_offset);
 361
 362 /*
 363  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 364  *
 365  * Local variables:
 366  * c-basic-offset: 4
 367  * tab-width: 8
 368  * indent-tabs-mode: nil
 369  * End:
 370  *
 371  * vi: set shiftwidth=4 tabstop=8 expandtab:
 372  * :indentSize=4:tabSize=8:noTabs=true:
 373  */