xref: /freebsd/lib/libusb/usb.h (revision cfd6422a5217410fbd66f7a7a8a64d9d85e61229)
1 /* $FreeBSD$ */
2 /*-
3  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4  *
5  * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  * 1. Redistributions of source code must retain the above copyright
11  *    notice, this list of conditions and the following disclaimer.
12  * 2. 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  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26  * SUCH DAMAGE.
27  */
28 
29 #ifndef _LIBUSB20_COMPAT_01_H_
30 #define	_LIBUSB20_COMPAT_01_H_
31 
32 #ifndef LIBUSB_GLOBAL_INCLUDE_FILE
33 #include <stdint.h>
34 #include <sys/param.h>
35 #include <sys/endian.h>
36 #endif
37 
38 /* USB interface class codes */
39 
40 #define	USB_CLASS_PER_INTERFACE         0
41 #define	USB_CLASS_AUDIO                 1
42 #define	USB_CLASS_COMM                  2
43 #define	USB_CLASS_HID                   3
44 #define	USB_CLASS_PRINTER               7
45 #define	USB_CLASS_PTP                   6
46 #define	USB_CLASS_MASS_STORAGE          8
47 #define	USB_CLASS_HUB                   9
48 #define	USB_CLASS_DATA                  10
49 #define	USB_CLASS_VENDOR_SPEC           0xff
50 
51 /* USB descriptor types */
52 
53 #define	USB_DT_DEVICE                   0x01
54 #define	USB_DT_CONFIG                   0x02
55 #define	USB_DT_STRING                   0x03
56 #define	USB_DT_INTERFACE                0x04
57 #define	USB_DT_ENDPOINT                 0x05
58 
59 #define	USB_DT_HID                      0x21
60 #define	USB_DT_REPORT                   0x22
61 #define	USB_DT_PHYSICAL                 0x23
62 #define	USB_DT_HUB                      0x29
63 
64 /* USB descriptor type sizes */
65 
66 #define	USB_DT_DEVICE_SIZE              18
67 #define	USB_DT_CONFIG_SIZE              9
68 #define	USB_DT_INTERFACE_SIZE           9
69 #define	USB_DT_ENDPOINT_SIZE            7
70 #define	USB_DT_ENDPOINT_AUDIO_SIZE      9
71 #define	USB_DT_HUB_NONVAR_SIZE          7
72 
73 /* USB descriptor header */
74 struct usb_descriptor_header {
75 	uint8_t	bLength;
76 	uint8_t	bDescriptorType;
77 };
78 
79 /* USB string descriptor */
80 struct usb_string_descriptor {
81 	uint8_t	bLength;
82 	uint8_t	bDescriptorType;
83 	uint16_t wData[1];
84 };
85 
86 /* USB HID descriptor */
87 struct usb_hid_descriptor {
88 	uint8_t	bLength;
89 	uint8_t	bDescriptorType;
90 	uint16_t bcdHID;
91 	uint8_t	bCountryCode;
92 	uint8_t	bNumDescriptors;
93 	/* uint8_t  bReportDescriptorType; */
94 	/* uint16_t wDescriptorLength; */
95 	/* ... */
96 };
97 
98 /* USB endpoint descriptor */
99 #define	USB_MAXENDPOINTS        32
100 struct usb_endpoint_descriptor {
101 	uint8_t	bLength;
102 	uint8_t	bDescriptorType;
103 	uint8_t	bEndpointAddress;
104 #define	USB_ENDPOINT_ADDRESS_MASK       0x0f
105 #define	USB_ENDPOINT_DIR_MASK           0x80
106 	uint8_t	bmAttributes;
107 #define	USB_ENDPOINT_TYPE_MASK          0x03
108 #define	USB_ENDPOINT_TYPE_CONTROL       0
109 #define	USB_ENDPOINT_TYPE_ISOCHRONOUS   1
110 #define	USB_ENDPOINT_TYPE_BULK          2
111 #define	USB_ENDPOINT_TYPE_INTERRUPT     3
112 	uint16_t wMaxPacketSize;
113 	uint8_t	bInterval;
114 	uint8_t	bRefresh;
115 	uint8_t	bSynchAddress;
116 
117 	uint8_t *extra;			/* Extra descriptors */
118 	int	extralen;
119 };
120 
121 /* USB interface descriptor */
122 #define	USB_MAXINTERFACES       32
123 struct usb_interface_descriptor {
124 	uint8_t	bLength;
125 	uint8_t	bDescriptorType;
126 	uint8_t	bInterfaceNumber;
127 	uint8_t	bAlternateSetting;
128 	uint8_t	bNumEndpoints;
129 	uint8_t	bInterfaceClass;
130 	uint8_t	bInterfaceSubClass;
131 	uint8_t	bInterfaceProtocol;
132 	uint8_t	iInterface;
133 
134 	struct usb_endpoint_descriptor *endpoint;
135 
136 	uint8_t *extra;			/* Extra descriptors */
137 	int	extralen;
138 };
139 
140 #define	USB_MAXALTSETTING       128	/* Hard limit */
141 struct usb_interface {
142 	struct usb_interface_descriptor *altsetting;
143 
144 	int	num_altsetting;
145 };
146 
147 /* USB configuration descriptor */
148 #define	USB_MAXCONFIG           8
149 struct usb_config_descriptor {
150 	uint8_t	bLength;
151 	uint8_t	bDescriptorType;
152 	uint16_t wTotalLength;
153 	uint8_t	bNumInterfaces;
154 	uint8_t	bConfigurationValue;
155 	uint8_t	iConfiguration;
156 	uint8_t	bmAttributes;
157 	uint8_t	MaxPower;
158 
159 	struct usb_interface *interface;
160 
161 	uint8_t *extra;			/* Extra descriptors */
162 	int	extralen;
163 };
164 
165 /* USB device descriptor */
166 struct usb_device_descriptor {
167 	uint8_t	bLength;
168 	uint8_t	bDescriptorType;
169 	uint16_t bcdUSB;
170 	uint8_t	bDeviceClass;
171 	uint8_t	bDeviceSubClass;
172 	uint8_t	bDeviceProtocol;
173 	uint8_t	bMaxPacketSize0;
174 	uint16_t idVendor;
175 	uint16_t idProduct;
176 	uint16_t bcdDevice;
177 	uint8_t	iManufacturer;
178 	uint8_t	iProduct;
179 	uint8_t	iSerialNumber;
180 	uint8_t	bNumConfigurations;
181 };
182 
183 /* USB setup packet */
184 struct usb_ctrl_setup {
185 	uint8_t	bRequestType;
186 #define	USB_RECIP_DEVICE                0x00
187 #define	USB_RECIP_INTERFACE             0x01
188 #define	USB_RECIP_ENDPOINT              0x02
189 #define	USB_RECIP_OTHER                 0x03
190 #define	USB_TYPE_STANDARD               (0x00 << 5)
191 #define	USB_TYPE_CLASS                  (0x01 << 5)
192 #define	USB_TYPE_VENDOR                 (0x02 << 5)
193 #define	USB_TYPE_RESERVED               (0x03 << 5)
194 #define	USB_ENDPOINT_IN                 0x80
195 #define	USB_ENDPOINT_OUT                0x00
196 	uint8_t	bRequest;
197 #define	USB_REQ_GET_STATUS              0x00
198 #define	USB_REQ_CLEAR_FEATURE           0x01
199 #define	USB_REQ_SET_FEATURE             0x03
200 #define	USB_REQ_SET_ADDRESS             0x05
201 #define	USB_REQ_GET_DESCRIPTOR          0x06
202 #define	USB_REQ_SET_DESCRIPTOR          0x07
203 #define	USB_REQ_GET_CONFIGURATION       0x08
204 #define	USB_REQ_SET_CONFIGURATION       0x09
205 #define	USB_REQ_GET_INTERFACE           0x0A
206 #define	USB_REQ_SET_INTERFACE           0x0B
207 #define	USB_REQ_SYNCH_FRAME             0x0C
208 	uint16_t wValue;
209 	uint16_t wIndex;
210 	uint16_t wLength;
211 };
212 
213 /* Error codes */
214 #define	USB_ERROR_BEGIN                 500000
215 
216 /* Byte swapping */
217 #define	USB_LE16_TO_CPU(x) le16toh(x)
218 
219 /* Data types */
220 struct usb_device;
221 struct usb_bus;
222 
223 /*
224  * To maintain compatibility with applications already built with libusb,
225  * we must only add entries to the end of this structure. NEVER delete or
226  * move members and only change types if you really know what you're doing.
227  */
228 struct usb_device {
229 	struct usb_device *next;
230 	struct usb_device *prev;
231 
232 	char	filename[PATH_MAX + 1];
233 
234 	struct usb_bus *bus;
235 
236 	struct usb_device_descriptor descriptor;
237 	struct usb_config_descriptor *config;
238 
239 	void   *dev;
240 
241 	uint8_t	devnum;
242 
243 	uint8_t	num_children;
244 	struct usb_device **children;
245 };
246 
247 struct usb_bus {
248 	struct usb_bus *next;
249 	struct usb_bus *prev;
250 
251 	char	dirname[PATH_MAX + 1];
252 
253 	struct usb_device *devices;
254 	uint32_t location;
255 
256 	struct usb_device *root_dev;
257 };
258 
259 struct usb_dev_handle;
260 typedef struct usb_dev_handle usb_dev_handle;
261 
262 /* Variables */
263 extern struct usb_bus *usb_busses;
264 
265 #ifdef __cplusplus
266 extern	"C" {
267 #endif
268 #if 0
269 }					/* style */
270 
271 #endif
272 
273 /* Function prototypes from "libusb20_compat01.c" */
274 
275 usb_dev_handle *usb_open(struct usb_device *dev);
276 int	usb_close(usb_dev_handle * dev);
277 int	usb_get_string(usb_dev_handle * dev, int index, int langid, char *buf, size_t buflen);
278 int	usb_get_string_simple(usb_dev_handle * dev, int index, char *buf, size_t buflen);
279 int	usb_get_descriptor_by_endpoint(usb_dev_handle * udev, int ep, uint8_t type, uint8_t index, void *buf, int size);
280 int	usb_get_descriptor(usb_dev_handle * udev, uint8_t type, uint8_t index, void *buf, int size);
281 int	usb_parse_descriptor(uint8_t *source, char *description, void *dest);
282 int	usb_parse_configuration(struct usb_config_descriptor *config, uint8_t *buffer);
283 void	usb_destroy_configuration(struct usb_device *dev);
284 void	usb_fetch_and_parse_descriptors(usb_dev_handle * udev);
285 int	usb_bulk_write(usb_dev_handle * dev, int ep, char *bytes, int size, int timeout);
286 int	usb_bulk_read(usb_dev_handle * dev, int ep, char *bytes, int size, int timeout);
287 int	usb_interrupt_write(usb_dev_handle * dev, int ep, char *bytes, int size, int timeout);
288 int	usb_interrupt_read(usb_dev_handle * dev, int ep, char *bytes, int size, int timeout);
289 int	usb_control_msg(usb_dev_handle * dev, int requesttype, int request, int value, int index, char *bytes, int size, int timeout);
290 int	usb_set_configuration(usb_dev_handle * dev, int configuration);
291 int	usb_claim_interface(usb_dev_handle * dev, int interface);
292 int	usb_release_interface(usb_dev_handle * dev, int interface);
293 int	usb_set_altinterface(usb_dev_handle * dev, int alternate);
294 int	usb_resetep(usb_dev_handle * dev, unsigned int ep);
295 int	usb_clear_halt(usb_dev_handle * dev, unsigned int ep);
296 int	usb_reset(usb_dev_handle * dev);
297 int	usb_check_connected(usb_dev_handle * dev);
298 const char *usb_strerror(void);
299 void	usb_init(void);
300 void	usb_set_debug(int level);
301 int	usb_find_busses(void);
302 int	usb_find_devices(void);
303 struct usb_device *usb_device(usb_dev_handle * dev);
304 struct usb_bus *usb_get_busses(void);
305 int	usb_get_driver_np(usb_dev_handle * dev, int interface, char *name, int namelen);
306 int	usb_detach_kernel_driver_np(usb_dev_handle * dev, int interface);
307 
308 #if 0
309 {					/* style */
310 #endif
311 #ifdef __cplusplus
312 }
313 
314 #endif
315 
316 #endif					/* _LIBUSB20_COMPAT01_H_ */
317