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