| Wireshark 4.7.0 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
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
45typedef enum mac_lte_oob_event {
46 ltemac_send_preamble,
47 ltemac_send_sr,
48 ltemac_sr_failure
49} mac_lte_oob_event;
50
51typedef 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 */
59typedef 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 */
69typedef 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
80typedef 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
86typedef 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 */
192bool 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) */
310void set_mac_lte_channel_mapping(drb_mapping_t *drb_mapping);
311
312/* Return mode of bearer, or 0 if not found/known */
313uint8_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 */
335void set_mac_lte_drx_config(uint16_t ueid, drx_config_t *drx_config, packet_info *pinfo);
336void 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 */
339void set_mac_lte_rapid_ranges(unsigned groupA, unsigned all_RA);
340
341/* RRC can indicate whether extended BSR sizes are used */
342void 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 */
345typedef enum {
346 SIMULT_PUCCH_PUSCH_PCELL = 0,
347 SIMULT_PUCCH_PUSCH_PSCELL
348} simult_pucch_pusch_cell_type;
349void 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 */
353WS_DLL_PUBLIC
354 mac_lte_info *get_mac_lte_proto_data(packet_info *pinfo);
355WS_DLL_PUBLIC
356void 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 */
359bool 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 */
_packet_info
Definition packet_info.h:43
_proto_node
Definition proto.h:907
drb_mapping_t
Definition packet-mac-lte.h:288
drx_config_t
Definition packet-mac-lte.h:318
mac_lte_info
Definition packet-mac-lte.h:93
tvbuff
Definition tvbuff-int.h:35