usb.4 (190100) | usb.4 (192551) |
---|---|
1.\" Copyright (c) 1997, 1998 2.\" Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 11 unchanged lines hidden (view full) --- 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 26.\" THE POSSIBILITY OF SUCH DAMAGE. 27.\" | 1.\" Copyright (c) 1997, 1998 2.\" Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 11 unchanged lines hidden (view full) --- 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 26.\" THE POSSIBILITY OF SUCH DAMAGE. 27.\" |
28.\" $FreeBSD: head/share/man/man4/usb.4 190100 2009-03-19 20:33:26Z thompsa $ | 28.\" Copyright (c) 2008 Hans Petter Selasky. All rights reserved. |
29.\" | 29.\" |
30.Dd November 22, 2006 | 30.\" Redistribution and use in source and binary forms, with or without 31.\" modification, are permitted provided that the following conditions 32.\" are met: 33.\" 1. Redistributions of source code must retain the above copyright 34.\" notice, this list of conditions and the following disclaimer. 35.\" 2. Redistributions in binary form must reproduce the above copyright 36.\" notice, this list of conditions and the following disclaimer in the 37.\" documentation and/or other materials provided with the distribution. 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 40.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 42.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 43.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 44.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 45.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 47.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 48.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 49.\" SUCH DAMAGE. 50.\" 51.\" $FreeBSD: head/share/man/man4/usb.4 192551 2009-05-21 17:26:20Z thompsa $ 52.\" 53.Dd May 20, 2009 |
31.Dt USB 4 32.Os 33.Sh NAME 34.Nm usb 35.Nd Universal Serial Bus 36.Sh SYNOPSIS 37To compile this driver into the kernel, 38place the following line in your 39kernel configuration file: 40.Bd -ragged -offset indent 41.Cd "device usb" 42.Ed 43.Pp 44Alternatively, to load the driver as a 45module at boot time, place the following line in 46.Xr loader.conf 5 : 47.Bd -literal -offset indent 48usb_load="YES" 49.Ed | 54.Dt USB 4 55.Os 56.Sh NAME 57.Nm usb 58.Nd Universal Serial Bus 59.Sh SYNOPSIS 60To compile this driver into the kernel, 61place the following line in your 62kernel configuration file: 63.Bd -ragged -offset indent 64.Cd "device usb" 65.Ed 66.Pp 67Alternatively, to load the driver as a 68module at boot time, place the following line in 69.Xr loader.conf 5 : 70.Bd -literal -offset indent 71usb_load="YES" 72.Ed |
50.Pp 51.In dev/usb/usb.h 52.In dev/usb/usbhid.h | 73.Sh USERLAND PROGRAMMING 74USB functions can be accessed from userland through the libusb library. 75See 76.Xr libusb 3 77for more information. |
53.Sh DESCRIPTION 54.Fx 55provides machine-independent bus support and drivers for 56.Tn USB | 78.Sh DESCRIPTION 79.Fx 80provides machine-independent bus support and drivers for 81.Tn USB |
57devices. | 82devices in host and device side mode. |
58.Pp 59The 60.Nm | 83.Pp 84The 85.Nm |
61driver has three layers: the controller, the bus, and the 62device layer. | 86driver has three layers: 87.Bl -tag 88.It USB Controller (Bus) 89.It USB Device 90.It USB Driver 91.El 92.Pp |
63The controller attaches to a physical bus | 93The controller attaches to a physical bus |
64(like 65.Xr pci 4 ) . | 94like 95.Xr pci 4 . |
66The 67.Tn USB 68bus attaches to the controller, and the root hub attaches 69to the controller. 70Any devices attached to the bus will attach to the root hub 71or another hub attached to the 72.Tn USB 73bus. 74.Pp 75The 76.Nm uhub 77device will always be present as it is needed for the 78root hub. 79.Sh INTRODUCTION TO USB 80The 81.Tn USB | 96The 97.Tn USB 98bus attaches to the controller, and the root hub attaches 99to the controller. 100Any devices attached to the bus will attach to the root hub 101or another hub attached to the 102.Tn USB 103bus. 104.Pp 105The 106.Nm uhub 107device will always be present as it is needed for the 108root hub. 109.Sh INTRODUCTION TO USB 110The 111.Tn USB |
82is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). | 112is a system where external devices can be connected to a PC. 113The most common USB speeds are: 114.Bl -tag 115.It Low Speed (1.5MBit/sec) 116.It Full Speed (12MBit/sec) 117.It High Speed (480MBit/sec) 118.El 119.Pp |
83Each 84.Tn USB | 120Each 121.Tn USB |
85has a host controller that is the master of the bus; 86all other devices on the bus only speak when spoken to. | 122has a USB controller that is the master of the bus. 123The physical communication is simplex which means the host controller only communicates with one USB device at a time. |
87.Pp | 124.Pp |
88There can be up to 127 devices (apart from the host controller) 89on a bus, each with its own address. | 125There can be up to 127 devices connected to an USB HUB tree. |
90The addresses are assigned 91dynamically by the host when each device is attached to the bus. 92.Pp 93Within each device there can be up to 16 endpoints. 94Each endpoint 95is individually addressed and the addresses are static. 96Each of these endpoints will communicate in one of four different modes: 97.Em control , isochronous , bulk , --- 13 unchanged lines hidden (view full) --- 111called alternate settings, which affects how it operates. 112Different alternate settings can have different endpoints 113within it. 114.Pp 115A device may operate in different configurations. 116Depending on the 117configuration, the device may present different sets of endpoints 118and interfaces. | 126The addresses are assigned 127dynamically by the host when each device is attached to the bus. 128.Pp 129Within each device there can be up to 16 endpoints. 130Each endpoint 131is individually addressed and the addresses are static. 132Each of these endpoints will communicate in one of four different modes: 133.Em control , isochronous , bulk , --- 13 unchanged lines hidden (view full) --- 147called alternate settings, which affects how it operates. 148Different alternate settings can have different endpoints 149within it. 150.Pp 151A device may operate in different configurations. 152Depending on the 153configuration, the device may present different sets of endpoints 154and interfaces. |
119.\" .Pp 120.\" Each device located on a hub has several 121.\" .Xr config 8 122.\" locators: 123.\" .Bl -tag -compact -width xxxxxx 124.\" .It Cd port 125.\" this is the number of the port on the closest upstream hub. 126.\" .It Cd configuration 127.\" this is the configuration the device must be in for this driver to attach. 128.\" This locator does not set the configuration; it is iterated by the bus 129.\" enumeration. 130.\" .It Cd interface 131.\" this is the interface number within a device that an interface driver 132.\" attaches to. 133.\" .It Cd vendor 134.\" this is the 16 bit vendor id of the device. 135.\" .It Cd product 136.\" this is the 16 bit product id of the device. 137.\" .It Cd release 138.\" this is the 16 bit release (revision) number of the device. 139.\" .El 140.\" The first locator can be used to pin down a particular device 141.\" according to its physical position in the device tree. 142.\" The last three locators can be used to pin down a particular 143.\" device according to what device it actually is. | |
144.Pp 145The bus enumeration of the 146.Tn USB 147bus proceeds in several steps: 148.Bl -enum 149.It | 155.Pp 156The bus enumeration of the 157.Tn USB 158bus proceeds in several steps: 159.Bl -enum 160.It |
150Any device specific driver can attach to the device. | 161Any interface specific driver can attach to the device. |
151.It | 162.It |
152If none is found, any device class specific driver can attach. 153.It 154If none is found, all configurations are iterated over. 155For each configuration, all the interfaces are iterated over, and interface 156drivers can attach. 157If any interface driver attached in a certain 158configuration, the iteration over configurations is stopped. 159.It 160If still no drivers have been found, the generic 161.Tn USB 162driver can attach. | 163If none is found, generic interface class drivers can attach. |
163.El | 164.El |
164.Sh USB CONTROLLER INTERFACE 165Use the following to get access to the 166.Tn USB 167specific structures and defines. | 165.Sh USB KERNEL PROGRAMMING 166Here is a list of commonly used functions: |
168.Pp | 167.Pp |
169The 170.Pa /dev/usb Ns Ar N 171can be opened and a few operations can be performed on it. 172The 173.Xr poll 2 174system call will say that I/O is possible on the controller device when a 175.Tn USB 176device has been connected or disconnected to the bus. | 168. 169.Ft "usb2_error_t" 170.Fo "usb2_transfer_setup" 171.Fa "udev" 172.Fa "ifaces" 173.Fa "pxfer" 174.Fa "setup_start" 175.Fa "n_setup" 176.Fa "priv_sc" 177.Fa "priv_mtx" 178.Fc 179. |
177.Pp | 180.Pp |
178The following 179.Xr ioctl 2 180commands are supported on the controller device: 181.Bl -tag -width xxxxxx 182.It Dv USB_DISCOVER 183This command will cause a complete bus discovery to be initiated. 184If any devices attached or detached from the bus they will be 185processed during this command. 186This is the only way that new devices are found on the bus. 187.It Dv USB_DEVICEINFO Vt "struct usb_device_info" 188This command can be used to retrieve some information about a device 189on the bus. 190The 191.Va udi_addr 192field should be filled before the call and the other fields will 193be filled by information about the device on that address. 194Should no such device exist, an error is reported. 195.Bd -literal 196#define USB_MAX_DEVNAMES 4 197#define USB_MAX_DEVNAMELEN 16 198struct usb_device_info { 199 u_int8_t udi_bus; 200 u_int8_t udi_addr; /* device address */ 201 usb_event_cookie_t udi_cookie; 202 char udi_product[USB_MAX_STRING_LEN]; 203 char udi_vendor[USB_MAX_STRING_LEN]; 204 char udi_release[8]; 205 u_int16_t udi_productNo; 206 u_int16_t udi_vendorNo; 207 u_int16_t udi_releaseNo; 208 u_int8_t udi_class; 209 u_int8_t udi_subclass; 210 u_int8_t udi_protocol; 211 u_int8_t udi_config; 212 u_int8_t udi_speed; 213#define USB_SPEED_LOW 1 214#define USB_SPEED_FULL 2 215#define USB_SPEED_HIGH 3 216 int udi_power;/* power consumption in mA, 0 if selfpowered */ 217 int udi_nports; 218 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 219 u_int8_t udi_ports[16];/* hub only: addresses of devices on ports */ 220#define USB_PORT_ENABLED 0xff 221#define USB_PORT_SUSPENDED 0xfe 222#define USB_PORT_POWERED 0xfd 223#define USB_PORT_DISABLED 0xfc 224}; 225.Ed | 181. 182.Ft "void" 183.Fo "usb2_transfer_unsetup" 184.Fa "pxfer" 185.Fa "n_setup" 186.Fc 187. |
226.Pp | 188.Pp |
227.Va udi_bus 228and 229.Va udi_addr 230contain the topological information for the device. 231.Va udi_devnames 232contains the device names of the connected drivers. 233For example, the 234third 235.Tn USB 236Zip drive connected will be 237.Li umass2 . | 189. 190.Ft "void" 191.Fo "usb2_transfer_start" 192.Fa "xfer" 193.Fc 194. 195.Pp 196. 197.Ft "void" 198.Fo "usb2_transfer_stop" 199.Fa "xfer" 200.Fc 201. 202.Pp 203. 204.Ft "void" 205.Fo "usb2_transfer_drain" 206.Fa "xfer" 207.Fc 208. 209. 210.Sh DESCRIPTION |
238The | 211The |
239.Va udi_product , udi_vendor 240and 241.Va udi_release 242fields contain self-explanatory descriptions of the device. 243.Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass 244and 245.Va udi_protocol 246contain the corresponding values from the device descriptors. | 212.Nm 213module implements the core functionality of the USB standard and many 214helper functions to make USB device driver programming easier and more 215safe. 216. |
247The | 217The |
248.Va udi_config 249field shows the current configuration of the device. | 218.Nm 219module supports both USB Host and USB Device side mode! 220. 221.Sh USB TRANSFER MANAGEMENT FUNCTIONS 222The USB standard defines four types of USB transfers. 223. 224Control transfers, Bulk transfers, Interrupt transfers and Isochronous 225transfers. 226. 227All the transfer types are managed using the following five functions: 228. |
250.Pp | 229.Pp |
251.Va udi_speed 252indicates whether the device is at low speed 253.Pq Dv USB_SPEED_LOW , 254full speed 255.Pq Dv USB_SPEED_FULL 256or high speed 257.Pq Dv USB_SPEED_HIGH . 258The 259.Va udi_power 260field shows the power consumption in milli-amps drawn at 5 volts, 261or zero if the device is self powered. | 230. 231.Fn usb2_transfer_setup 232This function will allocate memory for and initialise an array of USB 233transfers and all required DMA memory. 234. 235This function can sleep or block waiting for resources to become 236available. 237.Fa udev 238is a pointer to "struct usb2_device". 239.Fa ifaces 240is an array of interface index numbers to use. See "if_index". 241.Fa pxfer 242is a pointer to an array of USB transfer pointers that are initialized 243to NULL, and then pointed to allocated USB transfers. 244.Fa setup_start 245is a pointer to an array of USB config structures. 246.Fa n_setup 247is a number telling the USB system how many USB transfers should be 248setup. 249.Fa priv_sc 250is the private softc pointer, which will be used to initialize 251"xfer->priv_sc". 252.Fa priv_mtx 253is the private mutex protecting the transfer structure and the 254softc. This pointer is used to initialize "xfer->priv_mtx". 255This function returns 256zero upon success. A non-zero return value indicates failure. 257. |
262.Pp | 258.Pp |
263If the device is a hub, the 264.Va udi_nports 265field is non-zero, and the 266.Va udi_ports 267field contains the addresses of the connected devices. 268If no device is connected to a port, one of the 269.Dv USB_PORT_* 270values indicates its status. 271.It Dv USB_DEVICESTATS Vt "struct usb_device_stats" 272This command retrieves statistics about the controller. 273.Bd -literal 274struct usb_device_stats { 275 u_long uds_requests[4]; | 259. 260.Fn usb2_transfer_unsetup 261This function will release the given USB transfers and all allocated 262resources associated with these USB transfers. 263.Fa pxfer 264is a pointer to an array of USB transfer pointers, that may be NULL, 265that should be freed by the USB system. 266.Fa n_setup 267is a number telling the USB system how many USB transfers should be 268unsetup. 269. 270This function can sleep waiting for USB transfers to complete. 271. 272This function is NULL safe with regard to the USB transfer structure 273pointer. 274. 275It is not allowed to call this function from the USB transfer 276callback. 277. 278.Pp 279. 280.Fn usb2_transfer_start 281This function will start the USB transfer pointed to by 282.Fa xfer, 283if not already started. 284. 285This function is always non-blocking and must be called with the 286so-called private USB mutex locked. 287. 288This function is NULL safe with regard to the USB transfer structure 289pointer. 290. 291.Pp 292. 293.Fn usb2_transfer_stop 294This function will stop the USB transfer pointed to by 295.Fa xfer, 296if not already stopped. 297. 298This function is always non-blocking and must be called with the 299so-called private USB mutex locked. 300. 301This function can return before the USB callback has been called. 302. 303This function is NULL safe with regard to the USB transfer structure 304pointer. 305. 306If the transfer was in progress, the callback will called with 307"USB_ST_ERROR" and "xfer->error = USB_ERR_CANCELLED". 308. 309.Pp 310. 311.Fn usb2_transfer_drain 312This function will stop an USB transfer, if not already stopped and 313wait for any additional USB hardware operations to complete. 314. 315Buffers that are loaded into DMA using "usb2_set_frame_data()" can 316safely be freed after that this function has returned. 317. 318This function can block the caller and will not return before the USB 319callback has been called. 320. 321This function is NULL safe with regard to the USB transfer structure 322pointer. 323. 324.Sh USB TRANSFER CALLBACK 325. 326The USB callback has three states. 327. 328USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the 329initial state. 330. 331After the callback has been called with this state it will always be 332called back at a later stage in one of the other two states. 333. 334In the USB_ST_ERROR state the "error" field of the USB transfer 335structure is set to the error cause. 336. 337The USB callback should not restart the USB transfer in case the error 338cause is USB_ERR_CANCELLED. 339. 340The USB callback is protected from recursion. 341. 342That means one can start and stop whatever transfer from the callback 343of another transfer one desires. 344. 345Also the transfer that is currently called back. 346. 347Recursion is handled like this that when the callback that wants to 348recurse returns it is called one more time. 349. 350. 351.Pp 352. 353.Fn usb2_start_hardware 354This function should only be called from within the USB callback and 355is used to start the USB hardware. 356. 357Typical parameters that should be set in the USB transfer structure 358before this function is called are "frlengths[]", "nframes" and 359"frbuffers[]". 360. 361An USB transfer can have multiple frames consisting of one or more USB 362packets making up an I/O vector for all USB transfer types. 363. 364After the USB transfer is complete "frlengths[]" is updated to the 365actual USB transfer length for the given frame. 366.Bd -literal -offset indent 367void 368usb2_default_callback(struct usb2_xfer *xfer) 369{ 370 switch (USB_GET_STATE(xfer)) { 371 case USB_ST_SETUP: 372 /* 373 * Setup xfer->frlengths[], xfer->nframes 374 * and write data to xfer->frbuffers[], if any 375 */ 376 usb2_start_hardware(xfer); 377 break; 378 379 case USB_ST_TRANSFERRED: 380 /* 381 * Read data from xfer->frbuffers[], if any. 382 * "xfer->frlengths[]" should now have been 383 * updated to the actual length. 384 */ 385 break; 386 387 default: /* Error */ 388 /* 389 * Print error message and clear stall 390 * for example. 391 */ 392 break; 393 } 394 /* 395 * Here it is safe to do something without the private 396 * USB mutex locked. 397 */ 398 return; 399} 400.Ed 401. 402.Sh USB CONTROL TRANSFERS 403An USB control transfer has three parts. 404. 405First the SETUP packet, then DATA packet(s) and then a STATUS 406packet. 407. 408The SETUP packet is always pointed to by "xfer->frbuffers[0]" and the 409length is stored in "xfer->frlengths[0]" also if there should not be 410sent any SETUP packet! If an USB control transfer has no DATA stage, 411then "xfer->nframes" should be set to 1. 412. 413Else the default value is "xfer->nframes" equal to 2. 414. 415.Bd -literal -offset indent 416 417Example1: SETUP + STATUS 418 xfer->nframes = 1; 419 xfer->frlenghts[0] = 8; 420 usb2_start_hardware(xfer); 421 422Example2: SETUP + DATA + STATUS 423 xfer->nframes = 2; 424 xfer->frlenghts[0] = 8; 425 xfer->frlenghts[1] = 1; 426 usb2_start_hardware(xfer); 427 428Example3: SETUP + DATA + STATUS - split 4291st callback: 430 xfer->nframes = 1; 431 xfer->frlenghts[0] = 8; 432 usb2_start_hardware(xfer); 433 4342nd callback: 435 /* IMPORTANT: frbuffers[0] must still point at the setup packet! */ 436 xfer->nframes = 2; 437 xfer->frlenghts[0] = 0; 438 xfer->frlenghts[1] = 1; 439 usb2_start_hardware(xfer); 440 441Example4: SETUP + STATUS - split 4421st callback: 443 xfer->nframes = 1; 444 xfer->frlenghts[0] = 8; 445 xfer->flags.manual_status = 1; 446 usb2_start_hardware(xfer); 447 4482nd callback: 449 xfer->nframes = 1; 450 xfer->frlenghts[0] = 0; 451 xfer->flags.manual_status = 0; 452 usb2_start_hardware(xfer); 453 454.Ed 455.Sh USB TRANSFER CONFIG 456To simply the search for endpoints the 457.Nm 458module defines a USB config structure where it is possible to specify 459the characteristics of the wanted endpoint. 460.Bd -literal -offset indent 461 462struct usb2_config { 463 bufsize, 464 callback 465 direction, 466 endpoint, 467 frames, 468 index flags, 469 interval, 470 timeout, 471 type, |
276}; | 472}; |
473 |
|
277.Ed | 474.Ed |
475. |
|
278.Pp | 476.Pp |
279The 280.Va udi_requests 281field is indexed by the transfer kind, i.e.\& 282.Dv UE_* , 283and indicates how many transfers of each kind that has been completed 284by the controller. 285.It Dv USB_REQUEST Vt "struct usb_ctl_request" 286This command can be used to execute arbitrary requests on the control pipe. 287This is 288.Em DANGEROUS 289and should be used with great care since it 290can destroy the bus integrity. | 477.Fa type 478field selects the USB pipe type. 479. 480Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK, 481UE_ISOCHRONOUS. 482. 483The special value UE_BULK_INTR will select BULK and INTERRUPT pipes. 484. 485This field is mandatory. 486. 487.Pp 488.Fa endpoint 489field selects the USB endpoint number. 490. 491A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching 492endpoint. 493. 494This field is mandatory. 495. 496.Pp 497.Fa direction 498field selects the USB endpoint direction. 499. 500A value of "UE_DIR_ANY" will select the first matching endpoint. 501. 502Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT". 503. 504"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which 505means that the direction will be swapped in case of 506USB_MODE_DEVICE. 507. 508Note that "UE_DIR_IN" refers to the data transfer direction of the 509"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of 510the "OUT" tokens. 511. 512This field is mandatory. 513. 514.Pp 515.Fa interval 516field selects the interrupt interval. 517. 518The value of this field is given in milliseconds and is independent of 519device speed. 520. 521Depending on the endpoint type, this field has different meaning: 522.Bl -tag 523.It UE_INTERRUPT 524"0" use the default interrupt interval based on endpoint descriptor. 525"Else" use the given value for polling rate. 526.It UE_ISOCHRONOUS 527"0" use default. "Else" the value is ignored. 528.It UE_BULK 529.It UE_CONTROL 530"0" no transfer pre-delay. "Else" a delay as given by this field in 531milliseconds is inserted before the hardware is started when 532"usb2_start_hardware()" is called. 533.Pp 534NOTE: The transfer timeout, if any, is started after that the 535pre-delay has elapsed! |
291.El | 536.El |
537. |
|
292.Pp | 538.Pp |
293The include file 294.In dev/usb/usb.h 295contains definitions for the types used by the various 296.Xr ioctl 2 297calls. 298The naming convention of the fields for the various 299.Tn USB 300descriptors exactly follows the naming in the 301.Tn USB 302specification. 303Byte sized fields can be accessed directly, but word (16 bit) 304sized fields must be access by the 305.Fn UGETW field 306and 307.Fn USETW field value 308macros to handle byte order and alignment properly. | 539.Fa timeout 540field, if non-zero, will set the transfer timeout in milliseconds. If 541the "timeout" field is zero and the transfer type is ISOCHRONOUS a 542timeout of 250ms will be used. 543. |
309.Pp | 544.Pp |
310The include file 311.In dev/usb/usbhid.h 312similarly contains the definitions for 313Human Interface Devices 314.Pq Tn HID . 315.Sh USB EVENT INTERFACE 316All 317.Tn USB 318events are reported via the 319.Pa /dev/usb 320device. 321This device can be opened for reading and each 322.Xr read 2 323will yield an event record (if something has happened). 324The 325.Xr poll 2 326system call can be used to determine if an event record is available 327for reading. | 545.Fa frames 546field sets the maximum number of frames. If zero is specified it will 547yield the following results: 548.Bl -tag 549.It UE_BULK 550xfer->nframes = 1; 551.It UE_INTERRUPT 552xfer->nframes = 1; 553.It UE_CONTROL 554xfer->nframes = 2; 555.It UE_ISOCHRONOUS 556Not allowed. Will cause an error. 557.El 558. |
328.Pp | 559.Pp |
329The event record has the following definition: 330.Bd -literal 331struct usb_event { 332 int ue_type; 333#define USB_EVENT_CTRLR_ATTACH 1 334#define USB_EVENT_CTRLR_DETACH 2 335#define USB_EVENT_DEVICE_ATTACH 3 336#define USB_EVENT_DEVICE_DETACH 4 337#define USB_EVENT_DRIVER_ATTACH 5 338#define USB_EVENT_DRIVER_DETACH 6 339 struct timespec ue_time; 340 union { 341 struct { 342 int ue_bus; 343 } ue_ctrlr; 344 struct usb_device_info ue_device; 345 struct { 346 usb_event_cookie_t ue_cookie; 347 char ue_devname[16]; 348 } ue_driver; 349 } u; 350}; 351.Ed 352The 353.Va ue_type 354field identifies the type of event that is described. 355The possible events are attach/detach of a host controller, 356a device, or a device driver. 357The union contains information 358pertinent to the different types of events. 359Macros, 360.Fn USB_EVENT_IS_ATTACH "ue_type" 361and 362.Fn USB_EVENT_IS_DETACH "ue_type" 363can be used to determine if an event was an 364.Dq attach 365or a 366.Dq detach 367request. | 560.Fa ep_index 561field allows you to give a number, in case more endpoints match the 562description, that selects which matching "ep_index" should be used. 563. |
368.Pp | 564.Pp |
369The 370.Va ue_bus 371contains the number of the 372.Tn USB 373bus for host controller events. | 565.Fa if_index 566field allows you to select which of the interface numbers in the 567"ifaces" array parameter passed to "usb2_transfer_setup" that should 568be used when setting up the given USB transfer. 569. |
374.Pp | 570.Pp |
375The 376.Va ue_device 377record contains information about the device in a device event event. | 571.Fa flags 572field has type "struct usb2_xfer_flags" and allows one to set initial 573flags an USB transfer. Valid flags are: 574.Bl -tag 575.It force_short_xfer 576This flag forces the last transmitted USB packet to be short. A short 577packet has a length of less than "xfer->max_packet_size", which 578derives from "wMaxPacketSize". This flag can be changed during 579operation. 580.It short_xfer_ok 581This flag allows the received transfer length, "xfer->actlen" to be 582less than "xfer->sumlen" upon completion of a transfer. This flag can 583be changed during operation. 584.It short_frames_ok 585This flag allows the reception of multiple short USB frames. This flag 586only has effect for BULK and INTERRUPT endpoints and if the number of 587frames received is greater than 1. This flag can be changed during 588operation. 589.It pipe_bof 590This flag causes a failing USB transfer to remain first in the PIPE 591queue except in the case of "xfer->error" equal to 592"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue 593will be started until either: 594.Bl -tag 595.It 1 596The failing USB transfer is stopped using "usb2_transfer_stop()". 597.It 2 598The failing USB transfer performs a successful transfer. 599.El 600The purpose of this flag is to avoid races when multiple transfers are 601queued for execution on an USB endpoint, and the first executing 602transfer fails leading to the need for clearing of stall for 603example. 604. 605In this case this flag is used to prevent the following USB transfers 606from being executed at the same time the clear-stall command is 607executed on the USB control endpoint. 608. 609This flag can be changed during operation. |
378.Pp | 610.Pp |
379The 380.Va ue_cookie 381is an opaque value that uniquely determines which 382device a device driver has been attached to (i.e., it equals 383the cookie value in the device that the driver attached to). | 611"BOF" is short for "Block On Failure" |
384.Pp | 612.Pp |
385The 386.Va ue_devname 387contains the name of the device (driver) as seen in, e.g., 388kernel messages. | 613NOTE: This flag should be set on all BULK and INTERRUPT USB transfers 614which use an endpoint that can be shared between userland and kernel. 615. 616. 617.It proxy_buffer 618Setting this flag will cause that the total buffer size will be 619rounded up to the nearest atomic hardware transfer size. 620. 621The maximum data length of any USB transfer is always stored in the 622"xfer->max_data_length". 623. 624For control transfers the USB kernel will allocate additional space 625for the 8-bytes of SETUP header. 626. 627These 8-bytes are not counted by the "xfer->max_data_length" 628variable. 629. 630This flag can not be changed during operation. 631. 632. 633.It ext_buffer 634Setting this flag will cause that no data buffer will be 635allocated. 636. 637Instead the USB client must supply a data buffer. 638. 639This flag can not be changed during operation. 640. 641. 642.It manual_status 643Setting this flag prevents an USB STATUS stage to be appended to the 644end of the USB control transfer. 645. 646If no control data is transferred this flag must be cleared. 647. 648Else an error will be returned to the USB callback. 649. 650This flag is mostly useful for the USB device side. 651. 652This flag can be changed during operation. 653. 654. 655.It no_pipe_ok 656Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This 657flag can not be changed during operation. 658. 659. 660.It stall_pipe 661.Bl -tag 662.It Device Side Mode 663Setting this flag will cause STALL pids to be sent to the endpoint 664belonging to this transfer before the transfer is started. 665. 666The transfer is started at the moment the host issues a clear-stall 667command on the STALL'ed endpoint. 668. 669This flag can be changed during operation. 670.It Host Side Mode 671Setting this flag will cause a clear-stall control request to be 672executed on the endpoint before the USB transfer is started. 673.El |
389.Pp | 674.Pp |
390Note that there is a separation between device and device 391driver events. 392A device event is generated when a physical 393.Tn USB 394device is attached or detached. 395A single 396.Tn USB 397device may 398have zero, one, or many device drivers associated with it. | 675If this flag is changed outside the USB callback function you have to 676use the "usb2_transfer_set_stall()" and "usb2_transfer_clear_stall()" 677functions! This flag is automatically cleared after that the stall or 678clear stall has been executed. 679. 680.El 681.Pp 682.Fa bufsize 683field sets the total buffer size in bytes. 684. 685If this field is zero, "wMaxPacketSize" will be used, multiplied by 686the "frames" field if the transfer type is ISOCHRONOUS. 687. 688This is useful for setting up interrupt pipes. 689. 690This field is mandatory. 691.Pp 692NOTE: For control transfers "bufsize" includes the length of the 693request structure. 694. 695.Pp 696.Fa callback 697pointer sets the USB callback. This field is mandatory. 698. 699. 700.Sh USB LINUX COMPAT LAYER 701The 702.Nm 703module supports the Linux USB API. 704. 705. 706. |
399.Sh SEE ALSO 400The 401.Tn USB 402specifications can be found at: 403.Pp 404.D1 Pa http://www.usb.org/developers/docs/ 405.Pp | 707.Sh SEE ALSO 708The 709.Tn USB 710specifications can be found at: 711.Pp 712.D1 Pa http://www.usb.org/developers/docs/ 713.Pp |
714.Xr libusb 3 , |
|
406.Xr aue 4 , 407.Xr axe 4 , 408.Xr cue 4 , 409.Xr ehci 4 , 410.Xr kue 4 , 411.Xr ohci 4 , 412.Xr pci 4 , 413.Xr rue 4 , 414.Xr ucom 4 , 415.Xr udav 4 , | 715.Xr aue 4 , 716.Xr axe 4 , 717.Xr cue 4 , 718.Xr ehci 4 , 719.Xr kue 4 , 720.Xr ohci 4 , 721.Xr pci 4 , 722.Xr rue 4 , 723.Xr ucom 4 , 724.Xr udav 4 , |
416.Xr ugen 4 , | |
417.Xr uhci 4 , 418.Xr uhid 4 , 419.Xr ukbd 4 , 420.Xr ulpt 4 , 421.Xr umass 4 , 422.Xr ums 4 , 423.Xr uplcom 4 , 424.Xr urio 4 , 425.Xr uvscom 4 , | 725.Xr uhci 4 , 726.Xr uhid 4 , 727.Xr ukbd 4 , 728.Xr ulpt 4 , 729.Xr umass 4 , 730.Xr ums 4 , 731.Xr uplcom 4 , 732.Xr urio 4 , 733.Xr uvscom 4 , |
426.Xr usbdevs 8 427.Sh HISTORY | 734.Xr usbconfig 8 735.Sh STANDARDS |
428The 429.Nm | 736The 737.Nm |
430driver first appeared in 431.Fx 3.0 . 432.Sh AUTHORS | 738module complies with the USB 2.0 standard. 739.Sh HISTORY |
433The 434.Nm | 740The 741.Nm |
435driver was written by 436.An Lennart Augustsson Aq augustss@carlstedt.se 437for the 438.Nx 439project. | 742module has been inspired by the NetBSD USB stack initially written by 743Lennart Augustsson. The 744.Nm 745module was written by 746.An Hans Petter Selasky Aq hselasky@freebsd.org . |