source: mainline/uspace/lib/usb/include/usb/descriptor.h@ ae3a941

lfn serial ticket/834-toolchain-update topic/msim-upgrade topic/simplify-dev-export
Last change on this file since ae3a941 was ae3a941, checked in by Ondřej Hlavatý <aearsis@…>, 8 years ago

usb: cstyle
  • Property mode set to 100644
File size: 10.0 KB
Line 
1/*
2 * Copyright (c) 2010 Vojtech Horky
3 * Copyright (c) 2018 Michal Staruch, Ondrej Hlavaty
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * - Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * - Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 * - The name of the author may not be used to endorse or promote products
16 * derived from this software without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
19 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
22 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 */
29
30/** @addtogroup libusb
31 * @{
32 */
33/** @file
34 * Standard USB descriptors.
35 */
36#ifndef LIBUSB_DESCRIPTOR_H_
37#define LIBUSB_DESCRIPTOR_H_
38
39#include <stdint.h>
40
41/** Descriptor type. */
42typedef enum {
43 USB_DESCTYPE_DEVICE = 1,
44 USB_DESCTYPE_CONFIGURATION = 2,
45 USB_DESCTYPE_STRING = 3,
46 USB_DESCTYPE_INTERFACE = 4,
47 USB_DESCTYPE_ENDPOINT = 5,
48 /* New in USB 2.0 */
49 USB_DESCTYPE_DEVICE_QUALIFIER = 6,
50 USB_DESCTYPE_OTHER_SPEED_CONFIGURATION = 7,
51 USB_DESCTYPE_INTERFACE_POWER = 8,
52 /* USB 3.0 types */
53 USB_DESCTYPE_OTG = 9,
54 USB_DESCTYPE_DEBUG = 0xa,
55 USB_DESCTYPE_IFACE_ASSOC = 0xb,
56 USB_DESCTYPE_BOS = 0xf,
57 USB_DESCTYPE_DEVICE_CAP = 0x10,
58 /* Class specific */
59 USB_DESCTYPE_HID = 0x21,
60 USB_DESCTYPE_HID_REPORT = 0x22,
61 USB_DESCTYPE_HID_PHYSICAL = 0x23,
62 USB_DESCTYPE_HUB = 0x29,
63 USB_DESCTYPE_SSPEED_HUB = 0x2a,
64 USB_DESCTYPE_SSPEED_EP_COMPANION = 0x30
65 /* USB_DESCTYPE_ = */
66} usb_descriptor_type_t;
67
68/** Standard USB device descriptor.
69 */
70typedef struct {
71 /** Size of this descriptor in bytes. */
72 uint8_t length;
73 /** Descriptor type (USB_DESCTYPE_DEVICE). */
74 uint8_t descriptor_type;
75 /** USB specification release number.
76 * The number shall be coded as binary-coded decimal (BCD).
77 */
78 uint16_t usb_spec_version;
79 /** Device class. */
80 uint8_t device_class;
81 /** Device sub-class. */
82 uint8_t device_subclass;
83 /** Device protocol. */
84 uint8_t device_protocol;
85 /** Maximum packet size for endpoint zero.
86 * Valid values are only 8, 16, 32, 64).
87 */
88 uint8_t max_packet_size;
89 /** Vendor ID. */
90 uint16_t vendor_id;
91 /** Product ID. */
92 uint16_t product_id;
93 /** Device release number (in BCD). */
94 uint16_t device_version;
95 /** Manufacturer descriptor index. */
96 uint8_t str_manufacturer;
97 /** Product descriptor index. */
98 uint8_t str_product;
99 /** Device serial number descriptor index. */
100 uint8_t str_serial_number;
101 /** Number of possible configurations. */
102 uint8_t configuration_count;
103} __attribute__((packed)) usb_standard_device_descriptor_t;
104
105/** USB device qualifier decriptor is basically a cut down version of the device
106 * descriptor with values that would be valid if the device operated on the
107 * other speed (HIGH vs. FULL)
108 */
109typedef struct {
110 /** Size of this descriptor in bytes */
111 uint8_t length;
112 /** Descriptor type (USB_DESCTYPE_DEVICE_QUALIFIER) */
113 uint8_t descriptor_type;
114 /** USB specification release number.
115 * The number shall be coded as binary-coded decimal (BCD).
116 */
117 uint16_t usb_spec_version;
118 /** Device class. */
119 uint8_t device_class;
120 /** Device sub-class. */
121 uint8_t device_subclass;
122 /** Device protocol. */
123 uint8_t device_protocol;
124 /** Maximum packet size for endpoint zero.
125 * Valid values are only 8, 16, 32, 64).
126 */
127 uint8_t max_packet_size;
128 /** Number of possible configurations. */
129 uint8_t configuration_count;
130 uint8_t reserved;
131} __attribute__((packed)) usb_standard_device_qualifier_descriptor_t;
132
133/** Standard USB configuration descriptor.
134 */
135typedef struct {
136 /** Size of this descriptor in bytes. */
137 uint8_t length;
138 /** Descriptor type (USB_DESCTYPE_CONFIGURATION). */
139 uint8_t descriptor_type;
140 /** Total length of all data of this configuration.
141 * This includes the combined length of all descriptors
142 * (configuration, interface, endpoint, class-specific and
143 * vendor-specific) valid for this configuration.
144 */
145 uint16_t total_length;
146 /** Number of possible interfaces under this configuration. */
147 uint8_t interface_count;
148 /** Configuration value used when setting this configuration. */
149 uint8_t configuration_number;
150 /** String descriptor describing this configuration. */
151 uint8_t str_configuration;
152 /** Attribute bitmap. */
153 uint8_t attributes;
154 /** Maximum power consumption from the USB under this configuration.
155 * Expressed in 2mA unit (e.g. 50 ~ 100mA).
156 */
157 uint8_t max_power;
158} __attribute__((packed)) usb_standard_configuration_descriptor_t;
159
160/** USB Other Speed Configuration descriptor shows values that would change
161 * in the configuration descriptor if the device operated at its other
162 * possible speed (HIGH vs. FULL)
163 */
164typedef usb_standard_configuration_descriptor_t
165 usb_other_speed_configuration_descriptor_t;
166
167/** Standard USB interface descriptor.
168 */
169typedef struct {
170 /** Size of this descriptor in bytes. */
171 uint8_t length;
172 /** Descriptor type (USB_DESCTYPE_INTERFACE). */
173 uint8_t descriptor_type;
174 /** Number of interface.
175 * Zero-based index into array of interfaces for current configuration.
176 */
177 uint8_t interface_number;
178 /** Alternate setting for value in interface_number. */
179 uint8_t alternate_setting;
180 /** Number of endpoints used by this interface.
181 * This number must exclude usage of endpoint zero
182 * (default control pipe).
183 */
184 uint8_t endpoint_count;
185 /** Class code. */
186 uint8_t interface_class;
187 /** Subclass code. */
188 uint8_t interface_subclass;
189 /** Protocol code. */
190 uint8_t interface_protocol;
191 /** String descriptor describing this interface. */
192 uint8_t str_interface;
193} __attribute__((packed)) usb_standard_interface_descriptor_t;
194
195/** Standard USB endpoint descriptor.
196 */
197typedef struct {
198 /** Size of this descriptor in bytes. */
199 uint8_t length;
200 /** Descriptor type (USB_DESCTYPE_ENDPOINT). */
201 uint8_t descriptor_type;
202 /** Endpoint address together with data flow direction. */
203 uint8_t endpoint_address;
204#define USB_ED_GET_EP(ed) ((ed).endpoint_address & 0xf)
205#define USB_ED_GET_DIR(ed) (!(((ed).endpoint_address >> 7) & 0x1))
206
207 /** Endpoint attributes.
208 * Includes transfer type (usb_transfer_type_t).
209 */
210 uint8_t attributes;
211#define USB_ED_GET_TRANSFER_TYPE(ed) ((ed).attributes & 0x3)
212 /** Maximum packet size.
213 * Lower 10 bits represent the actuall size
214 * Bits 11,12 specify addtional transfer opportunitities for
215 * HS INT and ISO transfers. */
216 uint16_t max_packet_size;
217#define USB_ED_GET_MPS(ed) \
218 (uint16_usb2host((ed).max_packet_size) & 0x7ff)
219#define USB_ED_GET_ADD_OPPS(ed) \
220 ((uint16_usb2host((ed).max_packet_size) >> 11) & 0x3)
221 /** Polling interval. Different semantics for various (speed, type)
222 * pairs.
223 */
224 uint8_t poll_interval;
225} __attribute__((packed)) usb_standard_endpoint_descriptor_t;
226
227/** Superspeed USB endpoint companion descriptor.
228 * See USB 3 specification, section 9.6.7.
229 */
230typedef struct {
231 /** Size of this descriptor in bytes */
232 uint8_t length;
233 /** Descriptor type (USB_DESCTYPE_SSPEED_EP_COMPANION). */
234 uint8_t descriptor_type;
235 /** The maximum number of packets the endpoint can send
236 * or receive as part of a burst. Valid values are from 0 to 15.
237 * The endpoint can only burst max_burst + 1 packets at a time.
238 */
239 uint8_t max_burst;
240 /** Valid only for bulk and isochronous endpoints.
241 * For bulk endpoints, this field contains the amount of streams
242 * supported by the endpoint.
243 * For isochronous endpoints, this field contains maximum
244 * number of packets supported within a service interval.
245 * Warning: the values returned by macros may not make any sense
246 * for specific endpoint types.
247 */
248 uint8_t attributes;
249#define USB_SSC_MAX_STREAMS(sscd) ((sscd).attributes & 0x1f)
250#define USB_SSC_MULT(sscd) ((sscd).attributes & 0x3)
251 /** The total number of bytes this endpoint will transfer
252 * every service interval (SI).
253 * This field is only valid for periodic endpoints.
254 */
255 uint16_t bytes_per_interval;
256} __attribute__((packed)) usb_superspeed_endpoint_companion_descriptor_t;
257
258/** Part of standard USB HID descriptor specifying one class descriptor.
259 *
260 * (See HID Specification, p.22)
261 */
262typedef struct {
263 /** Type of class-specific descriptor (Report or Physical). */
264 uint8_t type;
265 /** Length of class-specific descriptor in bytes. */
266 uint16_t length;
267} __attribute__((packed)) usb_standard_hid_class_descriptor_info_t;
268
269/** Standard USB HID descriptor.
270 *
271 * (See HID Specification, p.22)
272 *
273 * It is actually only the "header" of the descriptor, it does not contain
274 * the last two mandatory fields (type and length of the first class-specific
275 * descriptor).
276 */
277typedef struct {
278 /** Total size of this descriptor in bytes.
279 *
280 * This includes all class-specific descriptor info - type + length
281 * for each descriptor.
282 */
283 uint8_t length;
284 /** Descriptor type (USB_DESCTYPE_HID). */
285 uint8_t descriptor_type;
286 /** HID Class Specification release. */
287 uint16_t spec_release;
288 /** Country code of localized hardware. */
289 uint8_t country_code;
290 /** Total number of class-specific (i.e. Report and Physical)
291 * descriptors.
292 *
293 * @note There is always only one Report descriptor.
294 */
295 uint8_t class_desc_count;
296 /** First mandatory class descriptor (Report) info. */
297 usb_standard_hid_class_descriptor_info_t report_desc_info;
298} __attribute__((packed)) usb_standard_hid_descriptor_t;
299
300#endif
301/**
302 * @}
303 */
Note: See TracBrowser for help on using the repository browser.