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