Wireshark  4.3.0
The Wireshark network protocol analyzer
packet-usb.h
1 /* packet-usb.h
2  *
3  * Wireshark - Network traffic analyzer
4  * By Gerald Combs <gerald@wireshark.org>
5  * Copyright 1998 Gerald Combs
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  */
9 
10 #ifndef __PACKET_USB_H__
11 #define __PACKET_USB_H__
12 
13 #include <epan/value_string.h>
14 #include <epan/wmem_scopes.h>
15 #include <epan/conversation.h>
16 
17 typedef struct _usb_address_t {
18  guint32 device;
19  guint32 endpoint;
20  guint16 bus_id;
22 #define USB_ADDR_LEN (sizeof(usb_address_t))
23 
24 /* Flag used to mark usb_address_t.endpoint as an interface
25  * address instead of the normal endpoint address.
26  */
27 #define INTERFACE_PORT 0x80000000
28 
29 
30 typedef struct _usb_conv_info_t usb_conv_info_t;
31 
32 /* Wireshark specific (i.e. numeric values are arbitrary) enum representing
33  * USB device speed.
34  */
35 typedef enum {
36  USB_SPEED_UNKNOWN, /* Unknown, skip speed specific processing */
37  USB_SPEED_LOW,
38  USB_SPEED_FULL,
39  USB_SPEED_HIGH,
40 } usb_speed_t;
41 
42 /* header type */
43 typedef enum {
44  USB_HEADER_LINUX_48_BYTES,
45  USB_HEADER_LINUX_64_BYTES,
46  USB_HEADER_USBPCAP,
47  USB_HEADER_MAUSB,
48  USB_HEADER_USBIP,
49  USB_HEADER_DARWIN,
50  USB_HEADER_PSEUDO_URB,
51 } usb_header_t;
52 
53 #define USB_HEADER_IS_LINUX(type) \
54  ((type) == USB_HEADER_LINUX_48_BYTES || (type) == USB_HEADER_LINUX_64_BYTES)
55 
56 typedef struct _usb_pseudo_urb_t {
57  gboolean from_host;
58  guint8 transfer_type;
59  guint8 device_address;
60  guint8 endpoint;
61  guint16 bus_id;
62  usb_speed_t speed;
64 
65 /* there is one such structure for each request/response */
66 typedef struct _usb_trans_info_t {
67  guint32 request_in;
68  guint32 response_in;
69  nstime_t req_time;
70  usb_header_t header_type;
71 
72  /* Valid only for SETUP transactions */
73  struct _usb_setup {
74  guint8 requesttype;
75  guint8 request;
76  guint16 wValue;
77  guint16 wIndex;
78  guint16 wLength;
79  } setup;
80 
81  /* Valid only during GET DESCRIPTOR transactions */
82  union {
83  struct {
84  guint8 type;
85  guint8 usb_index;
86  } get_descriptor;
87  } u;
88 
89 
90  /* used to pass the interface class from the
91  * interface descriptor onto the endpoint
92  * descriptors so that we can create a
93  * conversation with the appropriate class
94  * once we know the endpoint.
95  * Valid only during GET CONFIGURATION response.
96  */
97  usb_conv_info_t *interface_info;
98 
99  guint64 usb_id;
101 
102 enum usb_conv_class_data_type {
103  USB_CONV_UNKNOWN = 0,
104  USB_CONV_U3V,
105  USB_CONV_AUDIO,
106  USB_CONV_VIDEO,
107  USB_CONV_MASS_STORAGE_BOT,
108  USB_CONV_MASS_STORAGE_UASP,
109  USB_CONV_CDC_DATA,
110 };
111 
112 /* Conversation Structure
113  * there is one such structure for each device/endpoint conversation */
115  guint16 bus_id;
116  guint16 device_address;
117  guint8 endpoint;
118  gint direction;
119  guint8 transfer_type; /* transfer type from URB */
120  guint8 descriptor_transfer_type; /* transfer type lifted from the configuration descriptor */
121  guint16 max_packet_size; /* max packet size from configuration descriptor */
122  guint32 device_protocol;
123  gboolean is_request;
124  gboolean is_setup;
125  guint8 setup_requesttype;
126  usb_speed_t speed;
127 
128  guint16 interfaceClass; /* Interface Descriptor - class */
129  guint16 interfaceSubclass; /* Interface Descriptor - subclass */
130  guint16 interfaceProtocol; /* Interface Descriptor - protocol */
131  guint8 interfaceNum; /* Most recent interface number */
132 
133  guint16 deviceVendor; /* Device Descriptor - USB Vendor ID */
134  guint32 deviceProduct; /* Device Descriptor - USB Product ID - MSBs only for encoding unknown */
135  guint16 deviceVersion; /* Device Descriptor - USB device version number BCD */
136  guint8 iSerialNumber; /* Device Descriptor - iSerialNumber (0 if no serial number available) */
137  wmem_tree_t *transactions;
138  usb_trans_info_t *usb_trans_info; /* pointer to the current transaction */
139 
140  void *class_data; /* private class/id decode data */
141  enum usb_conv_class_data_type class_data_type;
142 
143  wmem_array_t *alt_settings;
144 };
145 
146 /* This is what a tap will tap */
147 typedef struct _usb_tap_data_t {
148  guint8 urb_type;
149  guint8 transfer_type;
150  usb_conv_info_t *conv_info;
151  usb_trans_info_t *trans_info;
153 
154 
155 /* the value for "no endpoint" that's used usb_addr_t, e.g. for the address of the host */
156 #define NO_ENDPOINT 0xffffffff
157 /* the 8bit version of NO_ENDPOINT, it's used in usb_conv_info_t
158  0xff would be an invalid endpoint number (reserved bits are 1) */
159 #define NO_ENDPOINT8 ((guint8)(NO_ENDPOINT& G_MAXUINT8))
160 
161 /*
162  * Values from the Linux USB pseudo-header.
163  */
164 
165 /*
166  * event_type values
167  */
168 #define URB_SUBMIT 'S'
169 #define URB_COMPLETE 'C'
170 #define URB_ERROR 'E'
171 
172 /*
173  * URB transfer_type values
174  */
175 #define URB_ISOCHRONOUS 0x0
176 #define URB_INTERRUPT 0x1
177 #define URB_CONTROL 0x2
178 #define URB_BULK 0x3
179 #define URB_UNKNOWN 0xFF
180 
181 #define URB_TRANSFER_IN 0x80 /* to host */
182 
183 
184 /* http://www.usb.org/developers/defined_class */
185 #define IF_CLASS_DEVICE 0x00
186 #define IF_CLASS_AUDIO 0x01
187 #define IF_CLASS_COMMUNICATIONS 0x02
188 #define IF_CLASS_HID 0x03
189 #define IF_CLASS_PHYSICAL 0x05
190 #define IF_CLASS_IMAGE 0x06
191 #define IF_CLASS_PRINTER 0x07
192 #define IF_CLASS_MASS_STORAGE 0x08
193 #define IF_CLASS_HUB 0x09
194 #define IF_CLASS_CDC_DATA 0x0a
195 #define IF_CLASS_SMART_CARD 0x0b
196 #define IF_CLASS_CONTENT_SECURITY 0x0d
197 #define IF_CLASS_VIDEO 0x0e
198 #define IF_CLASS_PERSONAL_HEALTHCARE 0x0f
199 #define IF_CLASS_AUDIO_VIDEO 0x10
200 #define IF_CLASS_DIAGNOSTIC_DEVICE 0xdc
201 #define IF_CLASS_WIRELESS_CONTROLLER 0xe0
202 #define IF_CLASS_MISCELLANEOUS 0xef
203 #define IF_CLASS_APPLICATION_SPECIFIC 0xfe
204 #define IF_CLASS_VENDOR_SPECIFIC 0xff
205 
206 #define IF_CLASS_UNKNOWN 0xffff
207 #define IF_SUBCLASS_UNKNOWN 0xffff
208 #define IF_PROTOCOL_UNKNOWN 0xffff
209 #define DEV_VENDOR_UNKNOWN 0x0000 /* this id is unassigned */
210 #define DEV_PRODUCT_UNKNOWN 0xfffffff /* 0x0000 and 0xffff are used values by vendors, so MSBs encode unknown */
211 #define DEV_VERSION_UNKNOWN 0xffff
212 
213 #define IF_SUBCLASS_MISC_U3V 0x05
214 
215 #define IF_SUBCLASS_APP_DFU 0x01
216 
217 #define IF_PROTOCOL_DFU_RUNTIME 0x01
218 #define IF_PROTOCOL_DFU_MODE 0x02
219 
220 /* Key to be used with "usb.control", "usb.bulk" and/or "usb.interrupt"
221  * dissector tables when the dissector only applies to specific triple.
222  * Use class code directly if the code is not shared with other specifications.
223  *
224  * MSB (bit 31) is arbitrarily chosen to ensure class registered dissectors
225  * won't clash with protocol key.
226  */
227 #define USB_PROTOCOL_KEY(class, subclass, protocol) \
228  (1u << 31 | (class & 0xff) << 16 | (subclass & 0xff) << 8 | (protocol & 0xff))
229 
230 /* bmRequestType values */
231 #define USB_DIR_OUT 0 /* to device */
232 #define USB_DIR_IN 0x80 /* to host */
233 
234 #define USB_TYPE_MASK (0x03 << 5)
235 #define USB_TYPE(type) (((type) & USB_TYPE_MASK) >> 5)
236 #define RQT_SETUP_TYPE_STANDARD 0
237 #define RQT_SETUP_TYPE_CLASS 1
238 #define RQT_SETUP_TYPE_VENDOR 2
239 
240 #define USB_RECIPIENT_MASK 0x1F
241 #define USB_RECIPIENT(type) ((type) & USB_RECIPIENT_MASK)
242 #define RQT_SETUP_RECIPIENT_DEVICE 0
243 #define RQT_SETUP_RECIPIENT_INTERFACE 1
244 #define RQT_SETUP_RECIPIENT_ENDPOINT 2
245 #define RQT_SETUP_RECIPIENT_OTHER 3
246 
247 /* Endpoint descriptor bmAttributes */
248 #define ENDPOINT_TYPE(ep_attrib) ((ep_attrib) & 0x03)
249 #define ENDPOINT_TYPE_CONTROL 0
250 #define ENDPOINT_TYPE_ISOCHRONOUS 1
251 #define ENDPOINT_TYPE_BULK 2
252 #define ENDPOINT_TYPE_INTERRUPT 3
253 #define ENDPOINT_TYPE_NOT_SET 255
254 
255 
256 #define USB_SETUP_GET_STATUS 0
257 #define USB_SETUP_CLEAR_FEATURE 1
258 #define USB_SETUP_SET_FEATURE 3
259 #define USB_SETUP_SET_ADDRESS 5
260 #define USB_SETUP_GET_DESCRIPTOR 6
261 #define USB_SETUP_SET_DESCRIPTOR 7
262 #define USB_SETUP_GET_CONFIGURATION 8
263 #define USB_SETUP_SET_CONFIGURATION 9
264 #define USB_SETUP_GET_INTERFACE 10
265 #define USB_SETUP_SET_INTERFACE 11
266 #define USB_SETUP_SYNCH_FRAME 12
267 #define USB_SETUP_SET_SEL 48
268 #define USB_SETUP_SET_ISOCH_DELAY 49
269 
270 /* transfer_flags */
271 #define URB_SHORT_NOT_OK 0x0001 /* report short reads as errors */
272 #define URB_ISO_ASAP 0x0002 /* iso-only; use the first unexpired
273  * slot in the schedule */
274 #define URB_NO_TRANSFER_DMA_MAP 0x0004 /* urb->transfer_dma valid on submit */
275 #define URB_NO_FSBR 0x0020 /* UHCI-specific */
276 #define URB_ZERO_PACKET 0x0040 /* Finish bulk OUT with short packet */
277 #define URB_NO_INTERRUPT 0x0080 /* HINT: no non-error interrupt
278  * needed */
279 #define URB_FREE_BUFFER 0x0100 /* Free transfer buffer with the URB */
280 
281 /* The following flags are used internally by usbcore and HCDs */
282 #define URB_DIR_IN 0x0200 /* Transfer from device to host */
283 #define URB_DIR_OUT 0
284 #define URB_DIR_MASK URB_DIR_IN
285 
286 #define URB_DMA_MAP_SINGLE 0x00010000 /* Non-scatter-gather mapping */
287 #define URB_DMA_MAP_PAGE 0x00020000 /* HCD-unsupported S-G */
288 #define URB_DMA_MAP_SG 0x00040000 /* HCD-supported S-G */
289 #define URB_MAP_LOCAL 0x00080000 /* HCD-local-memory mapping */
290 #define URB_SETUP_MAP_SINGLE 0x00100000 /* Setup packet DMA mapped */
291 #define URB_SETUP_MAP_LOCAL 0x00200000 /* HCD-local setup packet */
292 #define URB_DMA_SG_COMBINED 0x00400000 /* S-G entries were combined */
293 #define URB_ALIGNED_TEMP_BUFFER 0x00800000 /* Temp buffer was alloc'd */
294 
295 
296 /* 9.6.6 */
297 extern const true_false_string tfs_endpoint_direction;
298 
299 extern value_string_ext usb_class_vals_ext;
300 
301 usb_conv_info_t *get_usb_iface_conv_info(packet_info *pinfo, guint8 interface_num);
302 usb_conv_info_t *get_existing_usb_ep_conv_info(packet_info *pinfo, guint16 bus_id,
303  guint16 device_address, int endpoint);
304 
305 proto_item * dissect_usb_descriptor_header(proto_tree *tree,
306  tvbuff_t *tvb, int offset,
307  value_string_ext *type_val_str);
308 
309 void dissect_usb_endpoint_address(proto_tree *tree, tvbuff_t *tvb, int offset);
310 
311 unsigned int
312 sanitize_usb_max_packet_size(guint8 ep_type, usb_speed_t speed,
313  unsigned int max_packet_size);
314 
315 int
316 dissect_usb_endpoint_descriptor(packet_info *pinfo, proto_tree *parent_tree,
317  tvbuff_t *tvb, int offset,
318  usb_conv_info_t *usb_conv_info,
319  guint8 *out_ep_type, usb_speed_t speed);
320 
321 int
322 dissect_usb_unknown_descriptor(packet_info *pinfo _U_, proto_tree *parent_tree,
323  tvbuff_t *tvb, int offset,
324  usb_conv_info_t *usb_conv_info _U_);
325 
326 int
327 dissect_urb_transfer_flags(tvbuff_t *tvb, int offset, proto_tree* tree, int hf, int endian);
328 
329 struct mausb_header;
330 
331 void
332 dissect_usb_common(tvbuff_t *tvb, packet_info *pinfo, proto_tree *parent,
333  usb_header_t header_type, void *extra_data);
334 
335 void usb_lpm_besl_str(gchar *buf, guint32 value);
336 
337 #endif
338 
339 /*
340  * Editor modelines - https://www.wireshark.org/tools/modelines.html
341  *
342  * Local variables:
343  * c-basic-offset: 4
344  * tab-width: 8
345  * indent-tabs-mode: nil
346  * End:
347  *
348  * vi: set shiftwidth=4 tabstop=8 expandtab:
349  * :indentSize=4:tabSize=8:noTabs=true:
350  */
Definition: packet_info.h:44
Definition: proto.h:904
Definition: packet-usb.h:17
Definition: packet-usb.h:114
Definition: packet-usb.h:56
Definition: packet-usb.h:147
Definition: packet-usb.h:73
Definition: packet-usb.h:66
Definition: value_string.h:170
Definition: wmem_array.c:27
Definition: wmem_tree-int.h:48
Definition: packet-mausb.h:18
Definition: nstime.h:26
Definition: tfs.h:27
Definition: tvbuff-int.h:35