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