usb.h revision 184610
1/* $FreeBSD: head/sys/dev/usb2/core/usb2_compat_linux.h 184610 2008-11-04 02:31:03Z alfred $ */ 2/*- 3 * Copyright (c) 2007 Luigi Rizzo - Universita` di Pisa. All rights reserved. 4 * Copyright (c) 2007 Hans Petter Selasky. 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 * 1. Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25 * SUCH DAMAGE. 26 */ 27 28#ifndef _USB_COMPAT_LINUX_H 29#define _USB_COMPAT_LINUX_H 30 31struct usb_device; 32struct usb_interface; 33struct usb_driver; 34struct urb; 35 36typedef void *pm_message_t; 37typedef void (usb_complete_t)(struct urb *); 38 39#define USB_MAX_FULL_SPEED_ISOC_FRAMES (60 * 1) 40#define USB_MAX_HIGH_SPEED_ISOC_FRAMES (60 * 8) 41 42/* 43 * Linux compatible USB device drivers put their device information 44 * into the "usb_device_id" structure using the "USB_DEVICE()" macro. 45 * The "MODULE_DEVICE_TABLE()" macro can be used to export this 46 * information to userland. 47 */ 48struct usb_device_id { 49 /* which fields to match against */ 50 uint16_t match_flags; 51#define USB_DEVICE_ID_MATCH_VENDOR 0x0001 52#define USB_DEVICE_ID_MATCH_PRODUCT 0x0002 53#define USB_DEVICE_ID_MATCH_DEV_LO 0x0004 54#define USB_DEVICE_ID_MATCH_DEV_HI 0x0008 55#define USB_DEVICE_ID_MATCH_DEV_CLASS 0x0010 56#define USB_DEVICE_ID_MATCH_DEV_SUBCLASS 0x0020 57#define USB_DEVICE_ID_MATCH_DEV_PROTOCOL 0x0040 58#define USB_DEVICE_ID_MATCH_INT_CLASS 0x0080 59#define USB_DEVICE_ID_MATCH_INT_SUBCLASS 0x0100 60#define USB_DEVICE_ID_MATCH_INT_PROTOCOL 0x0200 61 62 /* Used for product specific matches; the BCD range is inclusive */ 63 uint16_t idVendor; 64 uint16_t idProduct; 65 uint16_t bcdDevice_lo; 66 uint16_t bcdDevice_hi; 67 68 /* Used for device class matches */ 69 uint8_t bDeviceClass; 70 uint8_t bDeviceSubClass; 71 uint8_t bDeviceProtocol; 72 73 /* Used for interface class matches */ 74 uint8_t bInterfaceClass; 75 uint8_t bInterfaceSubClass; 76 uint8_t bInterfaceProtocol; 77 78 /* Hook for driver specific information */ 79 unsigned long driver_info; 80}; 81 82#define USB_DEVICE_ID_MATCH_DEVICE \ 83 (USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT) 84 85#define USB_DEVICE(vend,prod) \ 86 .match_flags = USB_DEVICE_ID_MATCH_DEVICE, .idVendor = (vend), \ 87 .idProduct = (prod) 88 89/* The "usb_driver" structure holds the Linux USB device driver 90 * callbacks, and a pointer to device ID's which this entry should 91 * match against. Usually this entry is exposed to the USB emulation 92 * layer using the "USB_DRIVER_EXPORT()" macro, which is defined 93 * below. 94 */ 95struct usb_driver { 96 const char *name; 97 98 int (*probe) (struct usb_interface *intf, 99 const struct usb_device_id *id); 100 101 void (*disconnect) (struct usb_interface *intf); 102 103 int (*ioctl) (struct usb_interface *intf, unsigned int code, 104 void *buf); 105 106 int (*suspend) (struct usb_interface *intf, pm_message_t message); 107 int (*resume) (struct usb_interface *intf); 108 109 const struct usb_device_id *id_table; 110 111 void (*shutdown) (struct usb_interface *intf); 112 113 LIST_ENTRY(usb_driver) linux_driver_list; 114}; 115 116#define USB_DRIVER_EXPORT(id,p_usb_drv) \ 117 SYSINIT(id,SI_SUB_KLD,SI_ORDER_FIRST,usb_linux_register,p_usb_drv); \ 118 SYSUNINIT(id,SI_SUB_KLD,SI_ORDER_ANY,usb_linux_deregister,p_usb_drv) 119 120/* 121 * The following structure is the same as "usb_device_descriptor_t" 122 * except that 16-bit values are "uint16_t" and not an array of "uint8_t". 123 * It is used by Linux USB device drivers. 124 */ 125struct usb_device_descriptor { 126 uint8_t bLength; 127 uint8_t bDescriptorType; 128 129 uint16_t bcdUSB; 130 uint8_t bDeviceClass; 131 uint8_t bDeviceSubClass; 132 uint8_t bDeviceProtocol; 133 uint8_t bMaxPacketSize0; 134 uint16_t idVendor; 135 uint16_t idProduct; 136 uint16_t bcdDevice; 137 uint8_t iManufacturer; 138 uint8_t iProduct; 139 uint8_t iSerialNumber; 140 uint8_t bNumConfigurations; 141} __packed; 142 143/* 144 * The following structure is the same as 145 * "usb_interface_descriptor_t". It is used by 146 * Linux USB device drivers. 147 */ 148struct usb_interface_descriptor { 149 uint8_t bLength; 150 uint8_t bDescriptorType; 151 152 uint8_t bInterfaceNumber; 153 uint8_t bAlternateSetting; 154 uint8_t bNumEndpoints; 155 uint8_t bInterfaceClass; 156 uint8_t bInterfaceSubClass; 157 uint8_t bInterfaceProtocol; 158 uint8_t iInterface; 159} __packed; 160 161/* 162 * The following structure is the same as "usb_endpoint_descriptor_t" 163 * except that 16-bit values are "uint16_t" and not an array of "uint8_t". 164 * It is used by Linux USB device drivers. 165 */ 166struct usb_endpoint_descriptor { 167 uint8_t bLength; 168 uint8_t bDescriptorType; 169 170 uint8_t bEndpointAddress; 171 uint8_t bmAttributes; 172 uint16_t wMaxPacketSize; 173 uint8_t bInterval; 174 175 /* extension for audio endpoints only: */ 176 uint8_t bRefresh; 177 uint8_t bSynchAddress; 178} __packed; 179 180#define USB_DT_ENDPOINT_SIZE 7 181#define USB_DT_ENDPOINT_AUDIO_SIZE 9 182 183/* 184 * Endpoints 185 */ 186#define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */ 187#define USB_ENDPOINT_DIR_MASK 0x80 188 189#define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */ 190#define USB_ENDPOINT_XFER_CONTROL 0 191#define USB_ENDPOINT_XFER_ISOC 1 192#define USB_ENDPOINT_XFER_BULK 2 193#define USB_ENDPOINT_XFER_INT 3 194#define USB_ENDPOINT_MAX_ADJUSTABLE 0x80 195 196/* CONTROL REQUEST SUPPORT */ 197 198/* 199 * Definition of direction mask for 200 * "bEndpointAddress" and "bmRequestType": 201 */ 202#define USB_DIR_MASK 0x80 203#define USB_DIR_OUT 0x00 /* write to USB device */ 204#define USB_DIR_IN 0x80 /* read from USB device */ 205 206/* 207 * Definition of type mask for 208 * "bmRequestType": 209 */ 210#define USB_TYPE_MASK (0x03 << 5) 211#define USB_TYPE_STANDARD (0x00 << 5) 212#define USB_TYPE_CLASS (0x01 << 5) 213#define USB_TYPE_VENDOR (0x02 << 5) 214#define USB_TYPE_RESERVED (0x03 << 5) 215 216/* 217 * Definition of receiver mask for 218 * "bmRequestType": 219 */ 220#define USB_RECIP_MASK 0x1f 221#define USB_RECIP_DEVICE 0x00 222#define USB_RECIP_INTERFACE 0x01 223#define USB_RECIP_ENDPOINT 0x02 224#define USB_RECIP_OTHER 0x03 225 226/* 227 * Definition of standard request values for 228 * "bRequest": 229 */ 230#define USB_REQ_GET_STATUS 0x00 231#define USB_REQ_CLEAR_FEATURE 0x01 232#define USB_REQ_SET_FEATURE 0x03 233#define USB_REQ_SET_ADDRESS 0x05 234#define USB_REQ_GET_DESCRIPTOR 0x06 235#define USB_REQ_SET_DESCRIPTOR 0x07 236#define USB_REQ_GET_CONFIGURATION 0x08 237#define USB_REQ_SET_CONFIGURATION 0x09 238#define USB_REQ_GET_INTERFACE 0x0A 239#define USB_REQ_SET_INTERFACE 0x0B 240#define USB_REQ_SYNCH_FRAME 0x0C 241 242#define USB_REQ_SET_ENCRYPTION 0x0D /* Wireless USB */ 243#define USB_REQ_GET_ENCRYPTION 0x0E 244#define USB_REQ_SET_HANDSHAKE 0x0F 245#define USB_REQ_GET_HANDSHAKE 0x10 246#define USB_REQ_SET_CONNECTION 0x11 247#define USB_REQ_SET_SECURITY_DATA 0x12 248#define USB_REQ_GET_SECURITY_DATA 0x13 249#define USB_REQ_SET_WUSB_DATA 0x14 250#define USB_REQ_LOOPBACK_DATA_WRITE 0x15 251#define USB_REQ_LOOPBACK_DATA_READ 0x16 252#define USB_REQ_SET_INTERFACE_DS 0x17 253 254/* 255 * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and 256 * are read as a bit array returned by USB_REQ_GET_STATUS. (So there 257 * are at most sixteen features of each type.) 258 */ 259#define USB_DEVICE_SELF_POWERED 0 /* (read only) */ 260#define USB_DEVICE_REMOTE_WAKEUP 1 /* dev may initiate wakeup */ 261#define USB_DEVICE_TEST_MODE 2 /* (wired high speed only) */ 262#define USB_DEVICE_BATTERY 2 /* (wireless) */ 263#define USB_DEVICE_B_HNP_ENABLE 3 /* (otg) dev may initiate HNP */ 264#define USB_DEVICE_WUSB_DEVICE 3 /* (wireless) */ 265#define USB_DEVICE_A_HNP_SUPPORT 4 /* (otg) RH port supports HNP */ 266#define USB_DEVICE_A_ALT_HNP_SUPPORT 5 /* (otg) other RH port does */ 267#define USB_DEVICE_DEBUG_MODE 6 /* (special devices only) */ 268 269#define USB_ENDPOINT_HALT 0 /* IN/OUT will STALL */ 270 271#define PIPE_ISOCHRONOUS 0x01 /* UE_ISOCHRONOUS */ 272#define PIPE_INTERRUPT 0x03 /* UE_INTERRUPT */ 273#define PIPE_CONTROL 0x00 /* UE_CONTROL */ 274#define PIPE_BULK 0x02 /* UE_BULK */ 275 276/* Whenever Linux references an USB endpoint: 277 * a) to initialize "urb->pipe" 278 * b) second argument passed to "usb_control_msg()" 279 * 280 * Then it uses one of the following macros. The "endpoint" argument 281 * is the physical endpoint value masked by 0xF. The "dev" argument 282 * is a pointer to "struct usb_device". 283 */ 284#define usb_sndctrlpipe(dev,endpoint) \ 285 usb_find_host_endpoint(dev, PIPE_CONTROL, (endpoint) | USB_DIR_OUT) 286 287#define usb_rcvctrlpipe(dev,endpoint) \ 288 usb_find_host_endpoint(dev, PIPE_CONTROL, (endpoint) | USB_DIR_IN) 289 290#define usb_sndisocpipe(dev,endpoint) \ 291 usb_find_host_endpoint(dev, PIPE_ISOCHRONOUS, (endpoint) | USB_DIR_OUT) 292 293#define usb_rcvisocpipe(dev,endpoint) \ 294 usb_find_host_endpoint(dev, PIPE_ISOCHRONOUS, (endpoint) | USB_DIR_IN) 295 296#define usb_sndbulkpipe(dev,endpoint) \ 297 usb_find_host_endpoint(dev, PIPE_BULK, (endpoint) | USB_DIR_OUT) 298 299#define usb_rcvbulkpipe(dev,endpoint) \ 300 usb_find_host_endpoint(dev, PIPE_BULK, (endpoint) | USB_DIR_IN) 301 302#define usb_sndintpipe(dev,endpoint) \ 303 usb_find_host_endpoint(dev, PIPE_INTERRUPT, (endpoint) | USB_DIR_OUT) 304 305#define usb_rcvintpipe(dev,endpoint) \ 306 usb_find_host_endpoint(dev, PIPE_INTERRUPT, (endpoint) | USB_DIR_IN) 307 308/* The following four structures makes up a tree, where we have the 309 * leaf structure, "usb_host_endpoint", first, and the root structure, 310 * "usb_device", last. The four structures below mirror the structure 311 * of the USB descriptors belonging to an USB configuration. Please 312 * refer to the USB specification for a definition of "endpoints" and 313 * "interfaces". 314 */ 315struct usb_host_endpoint { 316 struct usb_endpoint_descriptor desc; 317 318 TAILQ_HEAD(, urb) bsd_urb_list; 319 320 struct usb2_xfer *bsd_xfer[2]; 321 322 uint8_t *extra; /* Extra descriptors */ 323 324 uint32_t fbsd_buf_size; 325 326 uint16_t extralen; 327 328 uint8_t bsd_iface_index; 329} __aligned(USB_HOST_ALIGN); 330 331struct usb_host_interface { 332 struct usb_interface_descriptor desc; 333 334 /* the following array has size "desc.bNumEndpoint" */ 335 struct usb_host_endpoint *endpoint; 336 337 const char *string; /* iInterface string, if present */ 338 uint8_t *extra; /* Extra descriptors */ 339 340 uint16_t extralen; 341 342 uint8_t bsd_iface_index; 343} __aligned(USB_HOST_ALIGN); 344 345struct usb_interface { 346 /* array of alternate settings for this interface */ 347 struct usb_host_interface *altsetting; 348 struct usb_host_interface *cur_altsetting; 349 struct usb_device *linux_udev; 350 void *bsd_priv_sc; /* device specific information */ 351 352 uint8_t num_altsetting; /* number of alternate settings */ 353 uint8_t bsd_iface_index; 354} __aligned(USB_HOST_ALIGN); 355 356struct usb_device { 357 struct usb_device_descriptor descriptor; 358 struct usb_host_endpoint ep0; 359 360 struct usb2_device *bsd_udev; 361 struct usb_interface *bsd_iface_start; 362 struct usb_interface *bsd_iface_end; 363 struct usb_host_endpoint *bsd_endpoint_start; 364 struct usb_host_endpoint *bsd_endpoint_end; 365 366 /* static strings from the device */ 367 const char *product; /* iProduct string, if present */ 368 const char *manufacturer; /* iManufacturer string, if present */ 369 const char *serial; /* iSerialNumber string, if present */ 370 371 uint16_t devnum; 372 373 uint8_t speed; /* USB_SPEED_XXX */ 374} __aligned(USB_HOST_ALIGN); 375 376/* 377 * The following structure is used to extend "struct urb" when we are 378 * dealing with an isochronous endpoint. It contains information about 379 * the data offset and data length of an isochronous packet. 380 * The "actual_length" field is updated before the "complete" 381 * callback in the "urb" structure is called. 382 */ 383struct usb_iso_packet_descriptor { 384 uint32_t offset; /* depreciated buffer offset (the 385 * packets are usually back to back) */ 386 uint16_t length; /* expected length */ 387 uint16_t actual_length; 388 uint16_t status; 389}; 390 391/* 392 * The following structure holds various information about an USB 393 * transfer. This structure is used for all kinds of USB transfers. 394 * 395 * URB is short for USB Request Block. 396 */ 397struct urb { 398 TAILQ_ENTRY(urb) bsd_urb_list; 399 struct cv cv_wait; 400 401 struct usb_device *dev; /* (in) pointer to associated device */ 402 struct usb_host_endpoint *pipe; /* (in) pipe pointer */ 403 uint8_t *setup_packet; /* (in) setup packet (control only) */ 404 uint8_t *bsd_data_ptr; 405 void *transfer_buffer; /* (in) associated data buffer */ 406 void *context; /* (in) context for completion */ 407 usb_complete_t *complete; /* (in) completion routine */ 408 409 uint32_t transfer_buffer_length;/* (in) data buffer length */ 410 uint32_t actual_length; /* (return) actual transfer length */ 411 uint32_t bsd_length_rem; 412 uint32_t timeout; /* FreeBSD specific */ 413 414 uint16_t transfer_flags; /* (in) */ 415#define URB_SHORT_NOT_OK 0x0001 /* report short transfers like errors */ 416#define URB_ISO_ASAP 0x0002 /* ignore "start_frame" field */ 417#define URB_ZERO_PACKET 0x0004 /* the USB transfer ends with a short 418 * packet */ 419#define URB_NO_TRANSFER_DMA_MAP 0x0008 /* "transfer_dma" is valid on submit */ 420#define URB_WAIT_WAKEUP 0x0010 /* custom flags */ 421#define URB_IS_SLEEPING 0x0020 /* custom flags */ 422 423 uint16_t start_frame; /* (modify) start frame (ISO) */ 424 uint16_t number_of_packets; /* (in) number of ISO packets */ 425 uint16_t interval; /* (modify) transfer interval 426 * (INT/ISO) */ 427 uint16_t error_count; /* (return) number of ISO errors */ 428 int16_t status; /* (return) status */ 429 430 uint8_t setup_dma; /* (in) not used on FreeBSD */ 431 uint8_t transfer_dma; /* (in) not used on FreeBSD */ 432 uint8_t bsd_isread; 433 434 struct usb_iso_packet_descriptor iso_frame_desc[]; /* (in) ISO ONLY */ 435}; 436 437/* various prototypes */ 438 439int usb_submit_urb(struct urb *urb, uint16_t mem_flags); 440int usb_unlink_urb(struct urb *urb); 441int usb_clear_halt(struct usb_device *dev, struct usb_host_endpoint *uhe); 442int usb_control_msg(struct usb_device *dev, struct usb_host_endpoint *pipe, uint8_t request, uint8_t requesttype, uint16_t value, uint16_t index, void *data, uint16_t size, uint32_t timeout); 443int usb_set_interface(struct usb_device *dev, uint8_t ifnum, uint8_t alternate); 444int usb_setup_endpoint(struct usb_device *dev, struct usb_host_endpoint *uhe, uint32_t bufsize); 445 446struct usb_host_endpoint *usb_find_host_endpoint(struct usb_device *dev, uint8_t type, uint8_t ep); 447struct urb *usb_alloc_urb(uint16_t iso_packets, uint16_t mem_flags); 448struct usb_host_interface *usb_altnum_to_altsetting(const struct usb_interface *intf, uint8_t alt_index); 449struct usb_interface *usb_ifnum_to_if(struct usb_device *dev, uint8_t iface_no); 450 451void *usb_buffer_alloc(struct usb_device *dev, uint32_t size, uint16_t mem_flags, uint8_t *dma_addr); 452void *usb_get_intfdata(struct usb_interface *intf); 453 454void usb_buffer_free(struct usb_device *dev, uint32_t size, void *addr, uint8_t dma_addr); 455void usb_free_urb(struct urb *urb); 456void usb_init_urb(struct urb *urb); 457void usb_kill_urb(struct urb *urb); 458void usb_set_intfdata(struct usb_interface *intf, void *data); 459void usb_linux_register(void *arg); 460void usb_linux_deregister(void *arg); 461 462#define interface_to_usbdev(intf) (intf)->linux_udev 463#define interface_to_bsddev(intf) (intf)->linux_udev->bsd_udev 464 465#endif /* _USB_COMPAT_LINUX_H */ 466