xref: /freebsd/sys/compat/linuxkpi/common/include/linux/usb.h (revision 71625ec9ad2a9bc8c09784fbd23b759830e0ee5f)
1 /*-
2  * Copyright (c) 2007 Luigi Rizzo - Universita` di Pisa. All rights reserved.
3  * Copyright (c) 2007 Hans Petter Selasky. All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24  * SUCH DAMAGE.
25  */
26 
27 #ifndef _USB_COMPAT_LINUX_H
28 #define	_USB_COMPAT_LINUX_H
29 
30 #include <sys/types.h>
31 #include <sys/param.h>
32 #include <sys/proc.h>
33 #include <sys/condvar.h>
34 
35 #include <dev/usb/usb.h>
36 #include <dev/usb/usbdi.h>
37 #include <dev/usb/usbdi_util.h>
38 
39 #include <linux/pm.h>
40 
41 struct usb_device;
42 struct usb_interface;
43 struct usb_driver;
44 struct urb;
45 
46 typedef void (usb_complete_t)(struct urb *);
47 
48 #define	USB_MAX_FULL_SPEED_ISOC_FRAMES (60 * 1)
49 #define	USB_MAX_HIGH_SPEED_ISOC_FRAMES (60 * 8)
50 
51 #define	USB_DEVICE_ID_MATCH_DEVICE \
52 	(USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
53 
54 #define	USB_DEVICE(vend,prod) \
55 	.match_flags = USB_DEVICE_ID_MATCH_DEVICE, .idVendor = (vend), \
56 	.idProduct = (prod)
57 
58 /* The "usb_driver" structure holds the Linux USB device driver
59  * callbacks, and a pointer to device ID's which this entry should
60  * match against. Usually this entry is exposed to the USB emulation
61  * layer using the "USB_DRIVER_EXPORT()" macro, which is defined
62  * below.
63  */
64 struct usb_driver {
65 	const char *name;
66 
67 	int (*probe)(struct usb_interface *intf,
68 	    const struct usb_device_id *id);
69 
70 	void (*disconnect)(struct usb_interface *intf);
71 
72 	int (*ioctl)(struct usb_interface *intf, unsigned int code, void *buf);
73 
74 	int (*suspend)(struct usb_interface *intf, pm_message_t message);
75 	int (*resume)(struct usb_interface *intf);
76 
77 	const struct usb_device_id *id_table;
78 
79 	void (*shutdown)(struct usb_interface *intf);
80 
81 	LIST_ENTRY(usb_driver) linux_driver_list;
82 };
83 
84 #define	USB_DRIVER_EXPORT(id,p_usb_drv) \
85   SYSINIT(id,SI_SUB_KLD,SI_ORDER_FIRST,usb_linux_register,p_usb_drv); \
86   SYSUNINIT(id,SI_SUB_KLD,SI_ORDER_ANY,usb_linux_deregister,p_usb_drv)
87 
88 #define	USB_DT_ENDPOINT_SIZE		7
89 #define	USB_DT_ENDPOINT_AUDIO_SIZE	9
90 
91 /*
92  * Endpoints
93  */
94 #define	USB_ENDPOINT_NUMBER_MASK	0x0f	/* in bEndpointAddress */
95 #define	USB_ENDPOINT_DIR_MASK		0x80
96 
97 #define	USB_ENDPOINT_XFERTYPE_MASK	0x03	/* in bmAttributes */
98 #define	USB_ENDPOINT_XFER_CONTROL	0
99 #define	USB_ENDPOINT_XFER_ISOC		1
100 #define	USB_ENDPOINT_XFER_BULK		2
101 #define	USB_ENDPOINT_XFER_INT		3
102 #define	USB_ENDPOINT_MAX_ADJUSTABLE	0x80
103 
104 /* CONTROL REQUEST SUPPORT */
105 
106 /*
107  * Definition of direction mask for
108  * "bEndpointAddress" and "bmRequestType":
109  */
110 #define	USB_DIR_MASK			0x80
111 #define	USB_DIR_OUT			0x00	/* write to USB device */
112 #define	USB_DIR_IN			0x80	/* read from USB device */
113 
114 /*
115  * Definition of type mask for
116  * "bmRequestType":
117  */
118 #define	USB_TYPE_MASK			(0x03 << 5)
119 #define	USB_TYPE_STANDARD		(0x00 << 5)
120 #define	USB_TYPE_CLASS			(0x01 << 5)
121 #define	USB_TYPE_VENDOR			(0x02 << 5)
122 #define	USB_TYPE_RESERVED		(0x03 << 5)
123 
124 /*
125  * Definition of receiver mask for
126  * "bmRequestType":
127  */
128 #define	USB_RECIP_MASK			0x1f
129 #define	USB_RECIP_DEVICE		0x00
130 #define	USB_RECIP_INTERFACE		0x01
131 #define	USB_RECIP_ENDPOINT		0x02
132 #define	USB_RECIP_OTHER			0x03
133 
134 /*
135  * Definition of standard request values for
136  * "bRequest":
137  */
138 #define	USB_REQ_GET_STATUS		0x00
139 #define	USB_REQ_CLEAR_FEATURE		0x01
140 #define	USB_REQ_SET_FEATURE		0x03
141 #define	USB_REQ_SET_ADDRESS		0x05
142 #define	USB_REQ_GET_DESCRIPTOR		0x06
143 #define	USB_REQ_SET_DESCRIPTOR		0x07
144 #define	USB_REQ_GET_CONFIGURATION	0x08
145 #define	USB_REQ_SET_CONFIGURATION	0x09
146 #define	USB_REQ_GET_INTERFACE		0x0A
147 #define	USB_REQ_SET_INTERFACE		0x0B
148 #define	USB_REQ_SYNCH_FRAME		0x0C
149 
150 #define	USB_REQ_SET_ENCRYPTION		0x0D	/* Wireless USB */
151 #define	USB_REQ_GET_ENCRYPTION		0x0E
152 #define	USB_REQ_SET_HANDSHAKE		0x0F
153 #define	USB_REQ_GET_HANDSHAKE		0x10
154 #define	USB_REQ_SET_CONNECTION		0x11
155 #define	USB_REQ_SET_SECURITY_DATA	0x12
156 #define	USB_REQ_GET_SECURITY_DATA	0x13
157 #define	USB_REQ_SET_WUSB_DATA		0x14
158 #define	USB_REQ_LOOPBACK_DATA_WRITE	0x15
159 #define	USB_REQ_LOOPBACK_DATA_READ	0x16
160 #define	USB_REQ_SET_INTERFACE_DS	0x17
161 
162 /*
163  * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and
164  * are read as a bit array returned by USB_REQ_GET_STATUS.  (So there
165  * are at most sixteen features of each type.)
166  */
167 #define	USB_DEVICE_SELF_POWERED		0	/* (read only) */
168 #define	USB_DEVICE_REMOTE_WAKEUP	1	/* dev may initiate wakeup */
169 #define	USB_DEVICE_TEST_MODE		2	/* (wired high speed only) */
170 #define	USB_DEVICE_BATTERY		2	/* (wireless) */
171 #define	USB_DEVICE_B_HNP_ENABLE		3	/* (otg) dev may initiate HNP */
172 #define	USB_DEVICE_WUSB_DEVICE		3	/* (wireless) */
173 #define	USB_DEVICE_A_HNP_SUPPORT	4	/* (otg) RH port supports HNP */
174 #define	USB_DEVICE_A_ALT_HNP_SUPPORT	5	/* (otg) other RH port does */
175 #define	USB_DEVICE_DEBUG_MODE		6	/* (special devices only) */
176 
177 #define	USB_ENDPOINT_HALT		0	/* IN/OUT will STALL */
178 
179 #define	PIPE_ISOCHRONOUS		0x01	/* UE_ISOCHRONOUS */
180 #define	PIPE_INTERRUPT			0x03	/* UE_INTERRUPT */
181 #define	PIPE_CONTROL			0x00	/* UE_CONTROL */
182 #define	PIPE_BULK			0x02	/* UE_BULK */
183 
184 /* Whenever Linux references an USB endpoint:
185  * a) to initialize "urb->endpoint"
186  * b) second argument passed to "usb_control_msg()"
187  *
188  * Then it uses one of the following macros. The "endpoint" argument
189  * is the physical endpoint value masked by 0xF. The "dev" argument
190  * is a pointer to "struct usb_device".
191  */
192 #define	usb_sndctrlpipe(dev,endpoint) \
193   usb_find_host_endpoint(dev, PIPE_CONTROL, (endpoint) | USB_DIR_OUT)
194 
195 #define	usb_rcvctrlpipe(dev,endpoint) \
196   usb_find_host_endpoint(dev, PIPE_CONTROL, (endpoint) | USB_DIR_IN)
197 
198 #define	usb_sndisocpipe(dev,endpoint) \
199   usb_find_host_endpoint(dev, PIPE_ISOCHRONOUS, (endpoint) | USB_DIR_OUT)
200 
201 #define	usb_rcvisocpipe(dev,endpoint) \
202   usb_find_host_endpoint(dev, PIPE_ISOCHRONOUS, (endpoint) | USB_DIR_IN)
203 
204 #define	usb_sndbulkpipe(dev,endpoint) \
205   usb_find_host_endpoint(dev, PIPE_BULK, (endpoint) | USB_DIR_OUT)
206 
207 #define	usb_rcvbulkpipe(dev,endpoint) \
208   usb_find_host_endpoint(dev, PIPE_BULK, (endpoint) | USB_DIR_IN)
209 
210 #define	usb_sndintpipe(dev,endpoint) \
211   usb_find_host_endpoint(dev, PIPE_INTERRUPT, (endpoint) | USB_DIR_OUT)
212 
213 #define	usb_rcvintpipe(dev,endpoint) \
214   usb_find_host_endpoint(dev, PIPE_INTERRUPT, (endpoint) | USB_DIR_IN)
215 
216 /*
217  * The following structure is used to extend "struct urb" when we are
218  * dealing with an isochronous endpoint. It contains information about
219  * the data offset and data length of an isochronous packet.
220  * The "actual_length" field is updated before the "complete"
221  * callback in the "urb" structure is called.
222  */
223 struct usb_iso_packet_descriptor {
224 	uint32_t offset;		/* depreciated buffer offset (the
225 					 * packets are usually back to back) */
226 	uint16_t length;		/* expected length */
227 	uint16_t actual_length;
228 	 int16_t status;		/* transfer status */
229 };
230 
231 /*
232  * The following structure holds various information about an USB
233  * transfer. This structure is used for all kinds of USB transfers.
234  *
235  * URB is short for USB Request Block.
236  */
237 struct urb {
238 	TAILQ_ENTRY(urb) bsd_urb_list;
239 	struct cv cv_wait;
240 
241 	struct usb_device *dev;		/* (in) pointer to associated device */
242 	struct usb_host_endpoint *endpoint;	/* (in) pipe pointer */
243 	uint8_t *setup_packet;		/* (in) setup packet (control only) */
244 	uint8_t *bsd_data_ptr;
245 	void   *transfer_buffer;	/* (in) associated data buffer */
246 	void   *context;		/* (in) context for completion */
247 	usb_complete_t *complete;	/* (in) completion routine */
248 
249 	usb_size_t transfer_buffer_length;/* (in) data buffer length */
250 	usb_size_t bsd_length_rem;
251 	usb_size_t actual_length;	/* (return) actual transfer length */
252 	usb_timeout_t timeout;		/* FreeBSD specific */
253 
254 	uint16_t transfer_flags;	/* (in) */
255 #define	URB_SHORT_NOT_OK	0x0001	/* report short transfers like errors */
256 #define	URB_ISO_ASAP		0x0002	/* ignore "start_frame" field */
257 #define	URB_ZERO_PACKET		0x0004	/* the USB transfer ends with a short
258 					 * packet */
259 #define	URB_NO_TRANSFER_DMA_MAP 0x0008	/* "transfer_dma" is valid on submit */
260 #define	URB_WAIT_WAKEUP		0x0010	/* custom flags */
261 #define	URB_IS_SLEEPING		0x0020	/* custom flags */
262 
263 	usb_frcount_t start_frame;	/* (modify) start frame (ISO) */
264 	usb_frcount_t number_of_packets;	/* (in) number of ISO packets */
265 	uint16_t interval;		/* (modify) transfer interval
266 					 * (INT/ISO) */
267 	uint16_t error_count;		/* (return) number of ISO errors */
268 	int16_t	status;			/* (return) status */
269 
270 	uint8_t	setup_dma;		/* (in) not used on FreeBSD */
271 	uint8_t	transfer_dma;		/* (in) not used on FreeBSD */
272 	uint8_t	bsd_isread;
273 	uint8_t kill_count;		/* FreeBSD specific */
274 
275 	struct usb_iso_packet_descriptor iso_frame_desc[];	/* (in) ISO ONLY */
276 };
277 
278 /* various prototypes */
279 
280 int	usb_submit_urb(struct urb *urb, uint16_t mem_flags);
281 int	usb_unlink_urb(struct urb *urb);
282 int	usb_clear_halt(struct usb_device *dev, struct usb_host_endpoint *uhe);
283 int	usb_control_msg(struct usb_device *dev, struct usb_host_endpoint *ep,
284 	    uint8_t request, uint8_t requesttype, uint16_t value,
285 	    uint16_t index, void *data, uint16_t size, usb_timeout_t timeout);
286 int	usb_set_interface(struct usb_device *dev, uint8_t ifnum,
287 	    uint8_t alternate);
288 int	usb_setup_endpoint(struct usb_device *dev,
289 	    struct usb_host_endpoint *uhe, usb_frlength_t bufsize);
290 
291 struct usb_host_endpoint *usb_find_host_endpoint(struct usb_device *dev,
292 	    uint8_t type, uint8_t ep);
293 struct urb *usb_alloc_urb(uint16_t iso_packets, uint16_t mem_flags);
294 struct usb_host_interface *usb_altnum_to_altsetting(
295 	    const struct usb_interface *intf, uint8_t alt_index);
296 struct usb_interface *usb_ifnum_to_if(struct usb_device *dev, uint8_t iface_no);
297 
298 void   *usb_buffer_alloc(struct usb_device *dev, usb_size_t size,
299 	    uint16_t mem_flags, uint8_t *dma_addr);
300 void   *usbd_get_intfdata(struct usb_interface *intf);
301 
302 void	usb_buffer_free(struct usb_device *dev, usb_size_t size, void *addr, uint8_t dma_addr);
303 void	usb_free_urb(struct urb *urb);
304 void	usb_init_urb(struct urb *urb);
305 void	usb_kill_urb(struct urb *urb);
306 void	usb_set_intfdata(struct usb_interface *intf, void *data);
307 void	usb_linux_register(void *arg);
308 void	usb_linux_deregister(void *arg);
309 
310 void	usb_fill_bulk_urb(struct urb *, struct usb_device *,
311 	    struct usb_host_endpoint *, void *, int, usb_complete_t, void *);
312 int	usb_bulk_msg(struct usb_device *, struct usb_host_endpoint *,
313 	    void *, int, uint16_t *, usb_timeout_t);
314 
315 #define	interface_to_usbdev(intf) (intf)->linux_udev
316 #define	interface_to_bsddev(intf) (intf)->linux_udev
317 
318 #endif					/* _USB_COMPAT_LINUX_H */
319