Add a way for configuration protocol (e.g. RRC) to configure MAC-> RLC mappings,...
[obnox/wireshark/wip.git] / 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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, 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 /* radioType */
52 #define FDD_RADIO 1
53 #define TDD_RADIO 2
54
55 /* Direction */
56 #define DIRECTION_UPLINK   0
57 #define DIRECTION_DOWNLINK 1
58
59 /* rntiType */
60 #define NO_RNTI  0
61 #define P_RNTI   1
62 #define RA_RNTI  2
63 #define C_RNTI   3
64 #define SI_RNTI  4
65 #define SPS_RNTI 5
66
67
68 typedef enum mac_lte_oob_event {
69     ltemac_send_preamble,
70     ltemac_send_sr,
71     ltemac_sr_failure
72 } mac_lte_oob_event;
73
74 typedef enum mac_lte_dl_retx {
75     dl_retx_no,
76     dl_retx_yes,
77     dl_retx_unknown
78 } mac_lte_dl_retx;
79
80 typedef enum mac_lte_crc_status {
81     crc_fail = 0,
82     crc_success = 1,
83     crc_high_code_rate = 2,
84     crc_pdsch_lost = 3,
85     crc_duplicate_nonzero_rv = 4
86 } mac_lte_crc_status;
87
88 /* Context info attached to each LTE MAC frame */
89 typedef struct mac_lte_info
90 {
91     /* Needed for decode */
92     guint8          radioType;
93     guint8          direction;
94     guint8          rntiType;
95
96     /* Extra info to display */
97     guint16         rnti;
98     guint16         ueid;
99
100     /* Timing info. TODO: sysframe too? */
101     guint16         subframeNumber;
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     /* UL only.  0=newTx, 1=first-retx, etc */
115     guint8          reTxCount;
116
117     /* DL only.  Status of CRC check */
118     mac_lte_crc_status   crcStatusValid;
119
120     /* DL only.  Is this known to be a retransmission? */
121     mac_lte_dl_retx dl_retx;
122
123     /* More Physical layer info (see direction above for which side of union to use) */
124     union {
125         struct mac_lte_ul_phy_info
126         {
127             guint8 present;  /* Remaining UL fields are present and should be displayed */
128             guint8 modulation_type;
129             guint8 tbs_index;
130             guint8 resource_block_length;
131             guint8 resource_block_start;
132             guint8 harq_id;
133             gboolean ndi;
134         } ul_info;
135         struct mac_lte_dl_phy_info
136         {
137             guint8 present; /* Remaining UL fields are present and should be displayed */
138             guint8 dci_format;
139             guint8 resource_allocation_type;
140             guint8 aggregation_level;
141             guint8 mcs_index;
142             guint8 redundancy_version_index;
143             guint8 resource_block_length;
144             mac_lte_crc_status crc_status;
145             guint8 harq_id;
146             gboolean ndi;
147             guint8   transport_block;  /* 1..2 */
148         } dl_info;
149     } detailed_phy_info;
150
151     /* Relating to out-of-band events */
152     /* N.B. dissector will only look to these fields if length is 0... */
153     mac_lte_oob_event  oob_event;
154     guint8             rapid;
155     guint8             rach_attempt_number;
156 } mac_lte_info;
157
158
159 typedef struct mac_lte_tap_info {
160     /* Info from context */
161     guint16  rnti;
162     guint16  ueid;
163     guint8   rntiType;
164     guint8   isPredefinedData;
165     guint8   crcStatusValid;
166     mac_lte_crc_status   crcStatus;
167     guint8   direction;
168
169     guint8   isPHYRetx;
170     guint16  ueInTTI;
171
172     nstime_t time;
173
174     /* Number of bytes (which part is used depends upon context settings) */
175     guint32  single_number_of_bytes;
176     guint32  bytes_for_lcid[11];
177     guint32  sdus_for_lcid[11];
178     guint8   number_of_rars;
179
180     /* Number of padding bytes includes padding subheaders and trailing padding */
181     guint16  padding_bytes;
182     guint16  raw_length;
183 } mac_lte_tap_info;
184
185
186 /* Accessor function to check if a frame was considered to be ReTx */
187 int is_mac_lte_frame_retx(packet_info *pinfo, guint8 direction);
188
189 /*****************************************************************/
190 /* UDP framing format                                            */
191 /* -----------------------                                       */
192 /* Several people have asked about dissecting MAC by framing     */
193 /* PDUs over IP.  A suggested format over UDP has been created   */
194 /* and implemented by this dissector, using the definitions      */
195 /* below. A link to an example program showing you how to encode */
196 /* these headers and send LTE MAC PDUs on a UDP socket is        */
197 /* provided at http://wiki.wireshark.org/MAC-LTE                 */
198 /*                                                               */
199 /* A heuristic dissecter (enabled by a preference) will          */
200 /* recognise a signature at the beginning of these frames   .    */
201 /* Until someone is using this format, suggestions for changes   */
202 /* are welcome.                                                  */
203 /*****************************************************************/
204
205
206 /* Signature.  Rather than try to define a port for this, or make the
207    port number a preference, frames will start with this string (with no
208    terminating NULL */
209 #define MAC_LTE_START_STRING "mac-lte"
210
211 /* Fixed fields.  This is followed by the following 3 mandatory fields:
212    - radioType (1 byte)
213    - direction (1 byte) 
214    - rntiType (1 byte)
215    (where the allowed values are defined above */
216
217 /* Optional fields. Attaching this info to frames will allow you
218    to show you display/filter/plot/add-custom-columns on these fields, so should
219    be added if available.
220    The format is to have the tag, followed by the value (there is no length field,
221    its implicit from the tag) */
222
223 #define MAC_LTE_RNTI_TAG            0x02
224 /* 2 bytes, network order */
225
226 #define MAC_LTE_UEID_TAG            0x03
227 /* 2 bytes, network order */
228
229 #define MAC_LTE_SUBFRAME_TAG        0x04
230 /* 2 bytes, network order */
231
232 #define MAC_LTE_PREDFINED_DATA_TAG  0x05
233 /* 1 byte */
234
235 #define MAC_LTE_RETX_TAG            0x06
236 /* 1 byte */
237
238 #define MAC_LTE_CRC_STATUS_TAG      0x07
239 /* 1 byte */
240
241
242 /* MAC PDU. Following this tag comes the actual MAC PDU (there is no length, the PDU
243    continues until the end of the frame) */
244 #define MAC_LTE_PAYLOAD_TAG 0x01
245
246
247 /* Set details of an LCID -> drb channel mapping.  To be called from
248    configuration protocol (e.g. RRC) */
249 void set_mac_lte_channel_mapping(guint16 ueid, guint8 lcid,
250                                  guint8 srbid, guint8 drbid,
251                                  guint8  rlcMode, guint8 um_sn_length);
252
253 /* Functions to be called from outside this module (e.g. in a plugin, where mac_lte_info
254    isn't available) to get/set per-packet data */
255 mac_lte_info *get_mac_lte_proto_data(packet_info *pinfo);
256 void set_mac_lte_proto_data(packet_info *pinfo, mac_lte_info *p_mac_lte_info);
257