epan/dissectors/packet-mac-lte.h

   1 /* packet-mac-lte.h
   2  *
   3  * Martin Mathieson
   4  * $Id$
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public License
  12  * as published by the Free Software Foundation; either version 2
  13  * of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  23  *
  24  * This header file may also be distributed under
  25  * the terms of the BSD Licence as follows:
  26  *
  27  * Copyright (C) 2009 Martin Mathieson. All rights reserved.
  28  *
  29  * Redistribution and use in source and binary forms, with or without
  30  * modification, are permitted provided that the following conditions
  31  * are met:
  32  * 1. Redistributions of source code must retain the above copyright
  33  *    notice, this list of conditions and the following disclaimer.
  34  * 2. Redistributions in binary form must reproduce the above copyright
  35  *    notice, this list of conditions and the following disclaimer in the
  36  *    documentation and/or other materials provided with the distribution.
  37  *
  38  * THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  39  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  41  * ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  42  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  43  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  44  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  45  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  46  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  47  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  48  * SUCH DAMAGE
  49  */
  50
  51 #include "ws_symbol_export.h"
  52
  53 /* radioType */
  54 #define FDD_RADIO 1
  55 #define TDD_RADIO 2
  56
  57 /* Direction */
  58 #define DIRECTION_UPLINK   0
  59 #define DIRECTION_DOWNLINK 1
  60
  61 /* rntiType */
  62 #define NO_RNTI  0
  63 #define P_RNTI   1
  64 #define RA_RNTI  2
  65 #define C_RNTI   3
  66 #define SI_RNTI  4
  67 #define SPS_RNTI 5
  68 #define M_RNTI   6
  69
  70
  71 typedef enum mac_lte_oob_event {
  72     ltemac_send_preamble,
  73     ltemac_send_sr,
  74     ltemac_sr_failure
  75 } mac_lte_oob_event;
  76
  77 typedef enum mac_lte_dl_retx {
  78     dl_retx_no,
  79     dl_retx_yes,
  80     dl_retx_unknown
  81 } mac_lte_dl_retx;
  82
  83 typedef enum mac_lte_crc_status {
  84     crc_fail = 0,
  85     crc_success = 1,
  86     crc_high_code_rate = 2,
  87     crc_pdsch_lost = 3,
  88     crc_duplicate_nonzero_rv = 4,
  89     crc_false_dci = 5
  90 } mac_lte_crc_status;
  91
  92 typedef enum mac_lte_carrier_id {
  93     carrier_id_primary,
  94     carrier_id_secondary_1,
  95     carrier_id_secondary_2,
  96     carrier_id_secondary_3,
  97     carrier_id_secondary_4
  98 } mac_lte_carrier_id;
  99
 100 /* Context info attached to each LTE MAC frame */
 101 typedef struct mac_lte_info
 102 {
 103     /* Needed for decode */
 104     guint8          radioType;
 105     guint8          direction;
 106     guint8          rntiType;
 107
 108     /* Extra info to display */
 109     guint16         rnti;
 110     guint16         ueid;
 111
 112     /* Timing info */
 113     guint16         sysframeNumber;
 114     guint16         subframeNumber;
 115
 116     /* Optional field. More interesting for TDD (FDD is always -4 subframeNumber) */
 117     gboolean        subframeNumberOfGrantPresent;
 118     guint16         subframeNumberOfGrant;
 119
 120     /* Flag set only if doing PHY-level data test - i.e. there may not be a
 121        well-formed MAC PDU so just show as raw data */
 122     gboolean        isPredefinedData;
 123
 124     /* Length of DL PDU or UL grant size in bytes */
 125     guint16         length;
 126
 127     /* UL only.  0=newTx, 1=first-retx, etc */
 128     guint8          reTxCount;
 129     guint8          isPHICHNACK; /* FALSE=PDCCH retx grant, TRUE=PHICH NACK */
 130
 131     /* UL only.  Indicates if the R10 extendedBSR-Sizes parameter is set */
 132     gboolean        isExtendedBSRSizes;
 133
 134     /* DL only.  Status of CRC check */
 135     mac_lte_crc_status   crcStatusValid;
 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     /* More Physical layer info (see direction above for which side of union to use) */
 144     union {
 145         struct mac_lte_ul_phy_info
 146         {
 147             guint8 present;  /* Remaining UL fields are present and should be displayed */
 148             guint8 modulation_type;
 149             guint8 tbs_index;
 150             guint8 resource_block_length;
 151             guint8 resource_block_start;
 152             guint8 harq_id;
 153             gboolean ndi;
 154         } ul_info;
 155         struct mac_lte_dl_phy_info
 156         {
 157             guint8 present; /* Remaining DL fields are present and should be displayed */
 158             guint8 dci_format;
 159             guint8 resource_allocation_type;
 160             guint8 aggregation_level;
 161             guint8 mcs_index;
 162             guint8 redundancy_version_index;
 163             guint8 resource_block_length;
 164             mac_lte_crc_status crc_status;
 165             guint8 harq_id;
 166             gboolean ndi;
 167             guint8   transport_block;  /* 0..1 */
 168         } dl_info;
 169     } detailed_phy_info;
 170
 171     /* Relating to out-of-band events */
 172     /* N.B. dissector will only look to these fields if length is 0... */
 173     mac_lte_oob_event  oob_event;
 174     guint8             rapid;
 175     guint8             rach_attempt_number;
 176     #define MAX_SRs 20
 177     guint16            number_of_srs;
 178     guint16            oob_ueid[MAX_SRs];
 179     guint16            oob_rnti[MAX_SRs];
 180 } mac_lte_info;
 181
 182
 183 typedef struct mac_lte_tap_info {
 184     /* Info from context */
 185     guint16  rnti;
 186     guint16  ueid;
 187     guint8   rntiType;
 188     guint8   isPredefinedData;
 189     guint8   crcStatusValid;
 190     mac_lte_crc_status   crcStatus;
 191     guint8   direction;
 192
 193     guint8   isPHYRetx;
 194     guint16  ueInTTI;
 195
 196     nstime_t time;
 197
 198     /* Number of bytes (which part is used depends upon context settings) */
 199     guint32  single_number_of_bytes;
 200     guint32  bytes_for_lcid[11];
 201     guint32  sdus_for_lcid[11];
 202     guint8   number_of_rars;
 203     guint8   number_of_paging_ids;
 204
 205     /* Number of padding bytes includes padding subheaders and trailing padding */
 206     guint16  padding_bytes;
 207     guint16  raw_length;
 208 } mac_lte_tap_info;
 209
 210
 211 /* Accessor function to check if a frame was considered to be ReTx */
 212 int is_mac_lte_frame_retx(packet_info *pinfo, guint8 direction);
 213
 214 /*****************************************************************/
 215 /* UDP framing format                                            */
 216 /* -----------------------                                       */
 217 /* Several people have asked about dissecting MAC by framing     */
 218 /* PDUs over IP.  A suggested format over UDP has been created   */
 219 /* and implemented by this dissector, using the definitions      */
 220 /* below. A link to an example program showing you how to encode */
 221 /* these headers and send LTE MAC PDUs on a UDP socket is        */
 222 /* provided at http://wiki.wireshark.org/MAC-LTE                 */
 223 /*                                                               */
 224 /* A heuristic dissecter (enabled by a preference) will          */
 225 /* recognise a signature at the beginning of these frames.       */
 226 /*****************************************************************/
 227
 228
 229 /* Signature.  Rather than try to define a port for this, or make the
 230    port number a preference, frames will start with this string (with no
 231    terminating NULL */
 232 #define MAC_LTE_START_STRING "mac-lte"
 233
 234 /* Fixed fields.  This is followed by the following 3 mandatory fields:
 235    - radioType (1 byte)
 236    - direction (1 byte)
 237    - rntiType (1 byte)
 238    (where the allowed values are defined above */
 239
 240 /* Optional fields. Attaching this info to frames will allow you
 241    to show you display/filter/plot/add-custom-columns on these fields, so should
 242    be added if available.
 243    The format is to have the tag, followed by the value (there is no length field,
 244    it's implicit from the tag) */
 245
 246 #define MAC_LTE_RNTI_TAG            0x02
 247 /* 2 bytes, network order */
 248
 249 #define MAC_LTE_UEID_TAG            0x03
 250 /* 2 bytes, network order */
 251
 252 #define MAC_LTE_SUBFRAME_TAG        0x04
 253 /* 2 bytes, network order */
 254
 255 #define MAC_LTE_PREDEFINED_DATA_TAG 0x05
 256 /* 1 byte */
 257
 258 #define MAC_LTE_RETX_TAG            0x06
 259 /* 1 byte */
 260
 261 #define MAC_LTE_CRC_STATUS_TAG      0x07
 262 /* 1 byte */
 263
 264 #define MAC_LTE_EXT_BSR_SIZES_TAG   0x08
 265 /* 0 byte */
 266
 267 /* MAC PDU. Following this tag comes the actual MAC PDU (there is no length, the PDU
 268    continues until the end of the frame) */
 269 #define MAC_LTE_PAYLOAD_TAG 0x01
 270
 271
 272 /* Type to store parameters for configuring LCID->RLC channel settings for DRB */
 273 /* Some are optional, and may not be seen (e.g. on reestablishment) */
 274 typedef struct drb_mapping_t
 275 {
 276     guint16    ueid;              /* Mandatory */
 277     guint8     drbid;             /* Mandatory */
 278     gboolean   lcid_present;
 279     guint8     lcid;              /* Part of LogicalChannelConfig - optional */
 280     gboolean   rlcMode_present;
 281     guint8     rlcMode;           /* Part of RLC config - optional */
 282     gboolean   um_sn_length_present;
 283     guint8     um_sn_length;      /* Part of RLC config - optional */
 284     gboolean   ul_priority_present;
 285     guint8     ul_priority;       /* Part of LogicalChannelConfig - optional */
 286     gboolean   pdcp_sn_size_present;
 287     guint8     pdcp_sn_size;      /* Part of pdcp-Config - optional */
 288 } drb_mapping_t;
 289
 290
 291 /* Set details of an LCID -> drb channel mapping.  To be called from
 292    configuration protocol (e.g. RRC) */
 293 void set_mac_lte_channel_mapping(drb_mapping_t *drb_mapping);
 294
 295
 296 /* Dedicated DRX config. Used to verify that a sensible config is given.
 297    Also, beginning to configure MAC with this config and (optionally) show
 298    DRX config and state (cycles/timers) attached to each UL/DL PDU! */
 299 typedef struct drx_config_t {
 300     gboolean    configured;
 301     guint32     frameNum;
 302     guint32     previousFrameNum;
 303
 304     guint32     onDurationTimer;
 305     guint32     inactivityTimer;
 306     guint32     retransmissionTimer;
 307     guint32     longCycle;
 308     guint32     cycleOffset;
 309     /* Optional Short cycle */
 310     gboolean    shortCycleConfigured;
 311     guint32     shortCycle;
 312     guint32     shortCycleTimer;
 313 } drx_config_t;
 314
 315 /* Functions to set/release up dedicated DRX config */
 316 void set_mac_lte_drx_config(guint16 ueid, drx_config_t *drx_config, packet_info *pinfo);
 317 void set_mac_lte_drx_config_release(guint16 ueid,  packet_info *pinfo);
 318
 319
 320 /* Functions to be called from outside this module (e.g. in a plugin, where mac_lte_info
 321    isn't available) to get/set per-packet data */
 322 WS_DLL_PUBLIC
 323 mac_lte_info *get_mac_lte_proto_data(packet_info *pinfo);
 324 WS_DLL_PUBLIC
 325 void set_mac_lte_proto_data(packet_info *pinfo, mac_lte_info *p_mac_lte_info);
 326
 327 /* Function to attempt to populate p_mac_lte_info using framing definition above */
 328 gboolean dissect_mac_lte_context_fields(struct mac_lte_info  *p_mac_lte_info, tvbuff_t *tvb,
 329                                         gint *p_offset);
 330