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 #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  guint8 radioType;
96  guint8 direction;
97  guint8 rntiType;
98 
99  /* Extra info to display */
100  guint16 rnti;
101  guint16 ueid;
102 
103  /* Timing info */
104  guint16 sysframeNumber;
105  guint16 subframeNumber;
106  gboolean sfnSfInfoPresent;
107 
108  /* Optional field. More interesting for TDD (FDD is always -4 subframeNumber) */
109  gboolean subframeNumberOfGrantPresent;
110  guint16 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  gboolean isPredefinedData;
115 
116  /* Length of DL PDU or UL grant size in bytes */
117  guint16 length;
118 
119  /* 0=newTx, 1=first-retx, etc */
120  guint8 reTxCount;
121  guint8 isPHICHNACK; /* FALSE=PDCCH retx grant, TRUE=PHICH NACK */
122 
123  /* UL only. Indicates if the R10 extendedBSR-Sizes parameter is set */
124  gboolean isExtendedBSRSizes;
125 
126  /* UL only. Indicates if the R10 simultaneousPUCCH-PUSCH parameter is set for PCell */
127  gboolean isSimultPUCCHPUSCHPCell;
128 
129  /* UL only. Indicates if the R10 extendedBSR-Sizes parameter is set for PSCell */
130  gboolean 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  gboolean 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  guint8 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  guint8 present; /* Remaining UL fields are present and should be displayed */
157  guint8 modulation_type;
158  guint8 tbs_index;
159  guint8 resource_block_length;
160  guint8 resource_block_start;
161  guint8 harq_id;
162  gboolean ndi;
163  } ul_info;
164  struct mac_lte_dl_phy_info
165  {
166  guint8 present; /* Remaining DL fields are present and should be displayed */
167  guint8 dci_format;
168  guint8 resource_allocation_type;
169  guint8 aggregation_level;
170  guint8 mcs_index;
171  guint8 redundancy_version_index;
172  guint8 resource_block_length;
173  guint8 harq_id;
174  gboolean ndi;
175  guint8 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  guint8 rapid;
183  guint8 rach_attempt_number;
184  #define MAX_SRs 20
185  guint16 number_of_srs;
186  guint16 oob_ueid[MAX_SRs];
187  guint16 oob_rnti[MAX_SRs];
188 } mac_lte_info;
189 
190 
191 /* Accessor function to check if a frame was considered to be ReTx */
192 int is_mac_lte_frame_retx(packet_info *pinfo, guint8 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  guint16 ueid; /* Mandatory */
290  guint8 drbid; /* Mandatory */
291  gboolean lcid_present;
292  guint8 lcid; /* Part of LogicalChannelConfig - optional */
293  gboolean rlcMode_present;
294  guint8 rlcMode; /* Part of RLC config - optional */
295  gboolean rlc_ul_ext_li_field; /* Part of RLC config - optional */
296  gboolean rlc_dl_ext_li_field; /* Part of RLC config - optional */
297  gboolean rlc_ul_ext_am_sn; /* Part of RLC config - optional */
298  gboolean rlc_dl_ext_am_sn; /* Part of RLC config - optional */
299  gboolean um_sn_length_present;
300  guint8 um_sn_length; /* Part of RLC config - optional */
301  gboolean ul_priority_present;
302  guint8 ul_priority; /* Part of LogicalChannelConfig - optional */
303  gboolean pdcp_sn_size_present;
304  guint8 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 
313 /* Dedicated DRX config. Used to verify that a sensible config is given.
314  Also, beginning to configure MAC with this config and (optionally) show
315  DRX config and state (cycles/timers) attached to each UL/DL PDU! */
316 typedef struct drx_config_t {
317  gboolean configured;
318  guint32 frameNum;
319  guint32 previousFrameNum;
320 
321  guint32 onDurationTimer;
322  guint32 inactivityTimer;
323  guint32 retransmissionTimer;
324  guint32 longCycle;
325  guint32 cycleOffset;
326  /* Optional Short cycle */
327  gboolean shortCycleConfigured;
328  guint32 shortCycle;
329  guint32 shortCycleTimer;
330 } drx_config_t;
331 
332 /* Functions to set/release up dedicated DRX config */
333 void set_mac_lte_drx_config(guint16 ueid, drx_config_t *drx_config, packet_info *pinfo);
334 void set_mac_lte_drx_config_release(guint16 ueid, packet_info *pinfo);
335 
336 /* RRC can tell this dissector which RAPIDs are Group A, Group A&B */
337 void set_mac_lte_rapid_ranges(guint groupA, guint all_RA);
338 
339 /* RRC can indicate whether extended BSR sizes are used */
340 void set_mac_lte_extended_bsr_sizes(guint16 ueid, gboolean use_ext_bsr_sizes, packet_info *pinfo);
341 
342 /* RRC can indicate whether simultaneous PUCCH/PUSCH is used */
343 typedef enum {
344  SIMULT_PUCCH_PUSCH_PCELL = 0,
345  SIMULT_PUCCH_PUSCH_PSCELL
346 } simult_pucch_pusch_cell_type;
347 void set_mac_lte_simult_pucch_pusch(guint16 ueid, simult_pucch_pusch_cell_type cell_type, gboolean use_simult_pucch_pusch, packet_info *pinfo);
348 
349 /* Functions to be called from outside this module (e.g. in a plugin, where mac_lte_info
350  isn't available) to get/set per-packet data */
351 WS_DLL_PUBLIC
352 mac_lte_info *get_mac_lte_proto_data(packet_info *pinfo);
353 WS_DLL_PUBLIC
354 void set_mac_lte_proto_data(packet_info *pinfo, mac_lte_info *p_mac_lte_info);
355 
356 /* Function to attempt to populate p_mac_lte_info using framing definition above */
357 gboolean dissect_mac_lte_context_fields(struct mac_lte_info *p_mac_lte_info, tvbuff_t *tvb,
358  packet_info *pinfo, proto_tree *tree, gint *p_offset);
359 
360 /*
361  * Editor modelines - https://www.wireshark.org/tools/modelines.html
362  *
363  * Local variables:
364  * c-basic-offset: 4
365  * tab-width: 8
366  * indent-tabs-mode: nil
367  * End:
368  *
369  * vi: set shiftwidth=4 tabstop=8 expandtab:
370  * :indentSize=4:tabSize=8:noTabs=true:
371  */
Definition: packet_info.h:44
Definition: proto.h:904
Definition: packet-mac-lte.h:288
Definition: packet-mac-lte.h:316
Definition: packet-mac-lte.h:93
Definition: tvbuff-int.h:35