diff options
| -rw-r--r-- | ObsoleteFiles.inc | 47 | ||||
| -rw-r--r-- | share/man/man4/usb.4 | 543 | ||||
| -rw-r--r-- | share/man/man9/Makefile | 95 | ||||
| -rw-r--r-- | share/man/man9/usbdi.9 | 1767 |
4 files changed, 673 insertions, 1779 deletions
diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc index 4bfe840..4588a4d 100644 --- a/ObsoleteFiles.inc +++ b/ObsoleteFiles.inc @@ -14,6 +14,53 @@ # The file is partitioned: OLD_FILES first, then OLD_LIBS and OLD_DIRS last. # +# 20090624: update usbdi(9) +OLD_FILES+=usr/share/man/man9/usbd_abort_default_pipe.9 +OLD_FILES+=usr/share/man/man9/usbd_abort_pipe.9 +OLD_FILES+=usr/share/man/man9/usbd_alloc_buffer.9 +OLD_FILES+=usr/share/man/man9/usbd_alloc_xfer.9 +OLD_FILES+=usr/share/man/man9/usbd_clear_endpoint_stall.9 +OLD_FILES+=usr/share/man/man9/usbd_clear_endpoint_stall_async.9 +OLD_FILES+=usr/share/man/man9/usbd_clear_endpoint_toggle.9 +OLD_FILES+=usr/share/man/man9/usbd_close_pipe.9 +OLD_FILES+=usr/share/man/man9/usbd_device2interface_handle.9 +OLD_FILES+=usr/share/man/man9/usbd_do_request_async.9 +OLD_FILES+=usr/share/man/man9/usbd_do_request_flags_pipe.9 +OLD_FILES+=usr/share/man/man9/usbd_endpoint_count.9 +OLD_FILES+=usr/share/man/man9/usbd_find_edesc.9 +OLD_FILES+=usr/share/man/man9/usbd_find_idesc.9 +OLD_FILES+=usr/share/man/man9/usbd_free_buffer.9 +OLD_FILES+=usr/share/man/man9/usbd_free_xfer.9 +OLD_FILES+=usr/share/man/man9/usbd_get_buffer.9 +OLD_FILES+=usr/share/man/man9/usbd_get_config.9 +OLD_FILES+=usr/share/man/man9/usbd_get_config_desc.9 +OLD_FILES+=usr/share/man/man9/usbd_get_config_desc_full.9 +OLD_FILES+=usr/share/man/man9/usbd_get_config_descriptor.9 +OLD_FILES+=usr/share/man/man9/usbd_get_device_descriptor.9 +OLD_FILES+=usr/share/man/man9/usbd_get_endpoint_descriptor.9 +OLD_FILES+=usr/share/man/man9/usbd_get_interface_altindex.9 +OLD_FILES+=usr/share/man/man9/usbd_get_interface_descriptor.9 +OLD_FILES+=usr/share/man/man9/usbd_get_no_alts.9 +OLD_FILES+=usr/share/man/man9/usbd_get_quirks.9 +OLD_FILES+=usr/share/man/man9/usbd_get_speed.9 +OLD_FILES+=usr/share/man/man9/usbd_get_string.9 +OLD_FILES+=usr/share/man/man9/usbd_get_string_desc.9 +OLD_FILES+=usr/share/man/man9/usbd_get_xfer_status.9 +OLD_FILES+=usr/share/man/man9/usbd_interface2device_handle.9 +OLD_FILES+=usr/share/man/man9/usbd_interface2endpoint_descriptor.9 +OLD_FILES+=usr/share/man/man9/usbd_interface_count.9 +OLD_FILES+=usr/share/man/man9/usbd_open_pipe.9 +OLD_FILES+=usr/share/man/man9/usbd_open_pipe_intr.9 +OLD_FILES+=usr/share/man/man9/usbd_pipe2device_handle.9 +OLD_FILES+=usr/share/man/man9/usbd_set_config_index.9 +OLD_FILES+=usr/share/man/man9/usbd_set_config_no.9 +OLD_FILES+=usr/share/man/man9/usbd_set_interface.9 +OLD_FILES+=usr/share/man/man9/usbd_setup_default_xfer.9 +OLD_FILES+=usr/share/man/man9/usbd_setup_isoc_xfer.9 +OLD_FILES+=usr/share/man/man9/usbd_setup_xfer.9 +OLD_FILES+=usr/share/man/man9/usbd_sync_transfer.9 +OLD_FILES+=usr/share/man/man9/usbd_transfer.9 +OLD_FILES+=usr/share/man/man9/usb_find_desc.9 # 20090605: removal of clists OLD_FILES+=usr/include/sys/clist.h # 20090602: removal of window(1) diff --git a/share/man/man4/usb.4 b/share/man/man4/usb.4 index 4fcfd96..e2b236a 100644 --- a/share/man/man4/usb.4 +++ b/share/man/man4/usb.4 @@ -162,548 +162,6 @@ Any interface specific driver can attach to the device. .It If none is found, generic interface class drivers can attach. .El -.Sh USB KERNEL PROGRAMMING -Here is a list of commonly used functions: -.Pp -. -.Ft "usb2_error_t" -.Fo "usb2_transfer_setup" -.Fa "udev" -.Fa "ifaces" -.Fa "pxfer" -.Fa "setup_start" -.Fa "n_setup" -.Fa "priv_sc" -.Fa "priv_mtx" -.Fc -. -.Pp -. -.Ft "void" -.Fo "usb2_transfer_unsetup" -.Fa "pxfer" -.Fa "n_setup" -.Fc -. -.Pp -. -.Ft "void" -.Fo "usb2_transfer_start" -.Fa "xfer" -.Fc -. -.Pp -. -.Ft "void" -.Fo "usb2_transfer_stop" -.Fa "xfer" -.Fc -. -.Pp -. -.Ft "void" -.Fo "usb2_transfer_drain" -.Fa "xfer" -.Fc -. -. -.Sh DESCRIPTION -The -.Nm -module implements the core functionality of the USB standard and many -helper functions to make USB device driver programming easier and more -safe. -. -The -.Nm -module supports both USB Host and USB Device side mode! -. -.Sh USB TRANSFER MANAGEMENT FUNCTIONS -The USB standard defines four types of USB transfers. -. -Control transfers, Bulk transfers, Interrupt transfers and Isochronous -transfers. -. -All the transfer types are managed using the following five functions: -. -.Pp -. -.Fn usb2_transfer_setup -This function will allocate memory for and initialise an array of USB -transfers and all required DMA memory. -. -This function can sleep or block waiting for resources to become -available. -.Fa udev -is a pointer to "struct usb2_device". -.Fa ifaces -is an array of interface index numbers to use. See "if_index". -.Fa pxfer -is a pointer to an array of USB transfer pointers that are initialized -to NULL, and then pointed to allocated USB transfers. -.Fa setup_start -is a pointer to an array of USB config structures. -.Fa n_setup -is a number telling the USB system how many USB transfers should be -setup. -.Fa priv_sc -is the private softc pointer, which will be used to initialize -"xfer->priv_sc". -.Fa priv_mtx -is the private mutex protecting the transfer structure and the -softc. This pointer is used to initialize "xfer->priv_mtx". -This function returns -zero upon success. A non-zero return value indicates failure. -. -.Pp -. -.Fn usb2_transfer_unsetup -This function will release the given USB transfers and all allocated -resources associated with these USB transfers. -.Fa pxfer -is a pointer to an array of USB transfer pointers, that may be NULL, -that should be freed by the USB system. -.Fa n_setup -is a number telling the USB system how many USB transfers should be -unsetup. -. -This function can sleep waiting for USB transfers to complete. -. -This function is NULL safe with regard to the USB transfer structure -pointer. -. -It is not allowed to call this function from the USB transfer -callback. -. -.Pp -. -.Fn usb2_transfer_start -This function will start the USB transfer pointed to by -.Fa xfer, -if not already started. -. -This function is always non-blocking and must be called with the -so-called private USB mutex locked. -. -This function is NULL safe with regard to the USB transfer structure -pointer. -. -.Pp -. -.Fn usb2_transfer_stop -This function will stop the USB transfer pointed to by -.Fa xfer, -if not already stopped. -. -This function is always non-blocking and must be called with the -so-called private USB mutex locked. -. -This function can return before the USB callback has been called. -. -This function is NULL safe with regard to the USB transfer structure -pointer. -. -If the transfer was in progress, the callback will called with -"USB_ST_ERROR" and "xfer->error = USB_ERR_CANCELLED". -. -.Pp -. -.Fn usb2_transfer_drain -This function will stop an USB transfer, if not already stopped and -wait for any additional USB hardware operations to complete. -. -Buffers that are loaded into DMA using "usb2_set_frame_data()" can -safely be freed after that this function has returned. -. -This function can block the caller and will not return before the USB -callback has been called. -. -This function is NULL safe with regard to the USB transfer structure -pointer. -. -.Sh USB TRANSFER CALLBACK -. -The USB callback has three states. -. -USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the -initial state. -. -After the callback has been called with this state it will always be -called back at a later stage in one of the other two states. -. -In the USB_ST_ERROR state the "error" field of the USB transfer -structure is set to the error cause. -. -The USB callback should not restart the USB transfer in case the error -cause is USB_ERR_CANCELLED. -. -The USB callback is protected from recursion. -. -That means one can start and stop whatever transfer from the callback -of another transfer one desires. -. -Also the transfer that is currently called back. -. -Recursion is handled like this that when the callback that wants to -recurse returns it is called one more time. -. -. -.Pp -. -.Fn usb2_start_hardware -This function should only be called from within the USB callback and -is used to start the USB hardware. -. -Typical parameters that should be set in the USB transfer structure -before this function is called are "frlengths[]", "nframes" and -"frbuffers[]". -. -An USB transfer can have multiple frames consisting of one or more USB -packets making up an I/O vector for all USB transfer types. -. -After the USB transfer is complete "frlengths[]" is updated to the -actual USB transfer length for the given frame. -.Bd -literal -offset indent -void -usb2_default_callback(struct usb2_xfer *xfer) -{ - switch (USB_GET_STATE(xfer)) { - case USB_ST_SETUP: - /* - * Setup xfer->frlengths[], xfer->nframes - * and write data to xfer->frbuffers[], if any - */ - usb2_start_hardware(xfer); - break; - - case USB_ST_TRANSFERRED: - /* - * Read data from xfer->frbuffers[], if any. - * "xfer->frlengths[]" should now have been - * updated to the actual length. - */ - break; - - default: /* Error */ - /* - * Print error message and clear stall - * for example. - */ - break; - } - /* - * Here it is safe to do something without the private - * USB mutex locked. - */ - return; -} -.Ed -. -.Sh USB CONTROL TRANSFERS -An USB control transfer has three parts. -. -First the SETUP packet, then DATA packet(s) and then a STATUS -packet. -. -The SETUP packet is always pointed to by "xfer->frbuffers[0]" and the -length is stored in "xfer->frlengths[0]" also if there should not be -sent any SETUP packet! If an USB control transfer has no DATA stage, -then "xfer->nframes" should be set to 1. -. -Else the default value is "xfer->nframes" equal to 2. -. -.Bd -literal -offset indent - -Example1: SETUP + STATUS - xfer->nframes = 1; - xfer->frlenghts[0] = 8; - usb2_start_hardware(xfer); - -Example2: SETUP + DATA + STATUS - xfer->nframes = 2; - xfer->frlenghts[0] = 8; - xfer->frlenghts[1] = 1; - usb2_start_hardware(xfer); - -Example3: SETUP + DATA + STATUS - split -1st callback: - xfer->nframes = 1; - xfer->frlenghts[0] = 8; - usb2_start_hardware(xfer); - -2nd callback: - /* IMPORTANT: frbuffers[0] must still point at the setup packet! */ - xfer->nframes = 2; - xfer->frlenghts[0] = 0; - xfer->frlenghts[1] = 1; - usb2_start_hardware(xfer); - -Example4: SETUP + STATUS - split -1st callback: - xfer->nframes = 1; - xfer->frlenghts[0] = 8; - xfer->flags.manual_status = 1; - usb2_start_hardware(xfer); - -2nd callback: - xfer->nframes = 1; - xfer->frlenghts[0] = 0; - xfer->flags.manual_status = 0; - usb2_start_hardware(xfer); - -.Ed -.Sh USB TRANSFER CONFIG -To simply the search for endpoints the -.Nm -module defines a USB config structure where it is possible to specify -the characteristics of the wanted endpoint. -.Bd -literal -offset indent - -struct usb2_config { - bufsize, - callback - direction, - endpoint, - frames, - index flags, - interval, - timeout, - type, -}; - -.Ed -. -.Pp -.Fa type -field selects the USB pipe type. -. -Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK, -UE_ISOCHRONOUS. -. -The special value UE_BULK_INTR will select BULK and INTERRUPT pipes. -. -This field is mandatory. -. -.Pp -.Fa endpoint -field selects the USB endpoint number. -. -A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching -endpoint. -. -This field is mandatory. -. -.Pp -.Fa direction -field selects the USB endpoint direction. -. -A value of "UE_DIR_ANY" will select the first matching endpoint. -. -Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT". -. -"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which -means that the direction will be swapped in case of -USB_MODE_DEVICE. -. -Note that "UE_DIR_IN" refers to the data transfer direction of the -"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of -the "OUT" tokens. -. -This field is mandatory. -. -.Pp -.Fa interval -field selects the interrupt interval. -. -The value of this field is given in milliseconds and is independent of -device speed. -. -Depending on the endpoint type, this field has different meaning: -.Bl -tag -.It UE_INTERRUPT -"0" use the default interrupt interval based on endpoint descriptor. -"Else" use the given value for polling rate. -.It UE_ISOCHRONOUS -"0" use default. "Else" the value is ignored. -.It UE_BULK -.It UE_CONTROL -"0" no transfer pre-delay. "Else" a delay as given by this field in -milliseconds is inserted before the hardware is started when -"usb2_start_hardware()" is called. -.Pp -NOTE: The transfer timeout, if any, is started after that the -pre-delay has elapsed! -.El -. -.Pp -.Fa timeout -field, if non-zero, will set the transfer timeout in milliseconds. If -the "timeout" field is zero and the transfer type is ISOCHRONOUS a -timeout of 250ms will be used. -. -.Pp -.Fa frames -field sets the maximum number of frames. If zero is specified it will -yield the following results: -.Bl -tag -.It UE_BULK -xfer->nframes = 1; -.It UE_INTERRUPT -xfer->nframes = 1; -.It UE_CONTROL -xfer->nframes = 2; -.It UE_ISOCHRONOUS -Not allowed. Will cause an error. -.El -. -.Pp -.Fa ep_index -field allows you to give a number, in case more endpoints match the -description, that selects which matching "ep_index" should be used. -. -.Pp -.Fa if_index -field allows you to select which of the interface numbers in the -"ifaces" array parameter passed to "usb2_transfer_setup" that should -be used when setting up the given USB transfer. -. -.Pp -.Fa flags -field has type "struct usb2_xfer_flags" and allows one to set initial -flags an USB transfer. Valid flags are: -.Bl -tag -.It force_short_xfer -This flag forces the last transmitted USB packet to be short. A short -packet has a length of less than "xfer->max_packet_size", which -derives from "wMaxPacketSize". This flag can be changed during -operation. -.It short_xfer_ok -This flag allows the received transfer length, "xfer->actlen" to be -less than "xfer->sumlen" upon completion of a transfer. This flag can -be changed during operation. -.It short_frames_ok -This flag allows the reception of multiple short USB frames. This flag -only has effect for BULK and INTERRUPT endpoints and if the number of -frames received is greater than 1. This flag can be changed during -operation. -.It pipe_bof -This flag causes a failing USB transfer to remain first in the PIPE -queue except in the case of "xfer->error" equal to -"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue -will be started until either: -.Bl -tag -.It 1 -The failing USB transfer is stopped using "usb2_transfer_stop()". -.It 2 -The failing USB transfer performs a successful transfer. -.El -The purpose of this flag is to avoid races when multiple transfers are -queued for execution on an USB endpoint, and the first executing -transfer fails leading to the need for clearing of stall for -example. -. -In this case this flag is used to prevent the following USB transfers -from being executed at the same time the clear-stall command is -executed on the USB control endpoint. -. -This flag can be changed during operation. -.Pp -"BOF" is short for "Block On Failure" -.Pp -NOTE: This flag should be set on all BULK and INTERRUPT USB transfers -which use an endpoint that can be shared between userland and kernel. -. -. -.It proxy_buffer -Setting this flag will cause that the total buffer size will be -rounded up to the nearest atomic hardware transfer size. -. -The maximum data length of any USB transfer is always stored in the -"xfer->max_data_length". -. -For control transfers the USB kernel will allocate additional space -for the 8-bytes of SETUP header. -. -These 8-bytes are not counted by the "xfer->max_data_length" -variable. -. -This flag can not be changed during operation. -. -. -.It ext_buffer -Setting this flag will cause that no data buffer will be -allocated. -. -Instead the USB client must supply a data buffer. -. -This flag can not be changed during operation. -. -. -.It manual_status -Setting this flag prevents an USB STATUS stage to be appended to the -end of the USB control transfer. -. -If no control data is transferred this flag must be cleared. -. -Else an error will be returned to the USB callback. -. -This flag is mostly useful for the USB device side. -. -This flag can be changed during operation. -. -. -.It no_pipe_ok -Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This -flag can not be changed during operation. -. -. -.It stall_pipe -.Bl -tag -.It Device Side Mode -Setting this flag will cause STALL pids to be sent to the endpoint -belonging to this transfer before the transfer is started. -. -The transfer is started at the moment the host issues a clear-stall -command on the STALL'ed endpoint. -. -This flag can be changed during operation. -.It Host Side Mode -Setting this flag will cause a clear-stall control request to be -executed on the endpoint before the USB transfer is started. -.El -.Pp -If this flag is changed outside the USB callback function you have to -use the "usb2_transfer_set_stall()" and "usb2_transfer_clear_stall()" -functions! This flag is automatically cleared after that the stall or -clear stall has been executed. -. -.El -.Pp -.Fa bufsize -field sets the total buffer size in bytes. -. -If this field is zero, "wMaxPacketSize" will be used, multiplied by -the "frames" field if the transfer type is ISOCHRONOUS. -. -This is useful for setting up interrupt pipes. -. -This field is mandatory. -.Pp -NOTE: For control transfers "bufsize" includes the length of the -request structure. -. -.Pp -.Fa callback -pointer sets the USB callback. This field is mandatory. -. -. -.Sh USB LINUX COMPAT LAYER -The -.Nm -module supports the Linux USB API. -. -. -. .Sh SEE ALSO The .Tn USB @@ -712,6 +170,7 @@ specifications can be found at: .D1 Pa http://www.usb.org/developers/docs/ .Pp .Xr libusb 3 , +.Xr usbdi 4 , .Xr aue 4 , .Xr axe 4 , .Xr cue 4 , diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 2ad85ce..d7a611c 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1210,55 +1210,58 @@ MLINKS+=uidinfo.9 uifind.9 \ uidinfo.9 uihashinit.9 \ uidinfo.9 uihold.9 MLINKS+=uio.9 uiomove.9 -MLINKS+=usbdi.9 usbd_abort_default_pipe.9 \ - usbdi.9 usbd_abort_pipe.9 \ - usbdi.9 usbd_alloc_buffer.9 \ - usbdi.9 usbd_alloc_xfer.9 \ - usbdi.9 usbd_clear_endpoint_stall.9 \ - usbdi.9 usbd_clear_endpoint_stall_async.9 \ - usbdi.9 usbd_clear_endpoint_toggle.9 \ - usbdi.9 usbd_close_pipe.9 \ - usbdi.9 usbd_device2interface_handle.9 \ +MLINKS+=usbdi.9 usb_fifo_alloc_buffer.9 \ + usbdi.9 usb_fifo_attach.9 \ + usbdi.9 usb_fifo_detach.9 \ + usbdi.9 usb_fifo_free_buffer.9 \ + usbdi.9 usb_fifo_get_data.9 \ + usbdi.9 usb_fifo_get_data_buffer.9 \ + usbdi.9 usb_fifo_get_data_error.9 \ + usbdi.9 usb_fifo_get_data_linear.9 \ + usbdi.9 usb_fifo_put_bytes_max.9 \ + usbdi.9 usb_fifo_put_data.9 \ + usbdi.9 usb_fifo_put_data_buffer.9 \ + usbdi.9 usb_fifo_put_data_error.9 \ + usbdi.9 usb_fifo_put_data_linear.9 \ + usbdi.9 usb_fifo_reset.9 \ + usbdi.9 usb_fifo_softc.9 \ + usbdi.9 usb_fifo_wakeup.9 \ usbdi.9 usbd_do_request.9 \ - usbdi.9 usbd_do_request_async.9 \ usbdi.9 usbd_do_request_flags.9 \ - usbdi.9 usbd_do_request_flags_pipe.9 \ - usbdi.9 usbd_endpoint_count.9 \ usbdi.9 usbd_errstr.9 \ - usbdi.9 usbd_find_edesc.9 \ - usbdi.9 usbd_find_idesc.9 \ - usbdi.9 usbd_free_buffer.9 \ - usbdi.9 usbd_free_xfer.9 \ - usbdi.9 usbd_get_buffer.9 \ - usbdi.9 usbd_get_config.9 \ - usbdi.9 usbd_get_config_desc.9 \ - usbdi.9 usbd_get_config_desc_full.9 \ - usbdi.9 usbd_get_config_descriptor.9 \ - usbdi.9 usbd_get_device_descriptor.9 \ - usbdi.9 usbd_get_endpoint_descriptor.9 \ - usbdi.9 usbd_get_interface_altindex.9 \ - usbdi.9 usbd_get_interface_descriptor.9 \ - usbdi.9 usbd_get_no_alts.9 \ - usbdi.9 usbd_get_quirks.9 \ - usbdi.9 usbd_get_speed.9 \ - usbdi.9 usbd_get_string.9 \ - usbdi.9 usbd_get_string_desc.9 \ - usbdi.9 usbd_get_xfer_status.9 \ - usbdi.9 usbd_interface2device_handle.9 \ - usbdi.9 usbd_interface2endpoint_descriptor.9 \ - usbdi.9 usbd_interface_count.9 \ - usbdi.9 usbd_open_pipe.9 \ - usbdi.9 usbd_open_pipe_intr.9 \ - usbdi.9 usbd_pipe2device_handle.9 \ - usbdi.9 usbd_set_config_index.9 \ - usbdi.9 usbd_set_config_no.9 \ - usbdi.9 usbd_set_interface.9 \ - usbdi.9 usbd_setup_default_xfer.9 \ - usbdi.9 usbd_setup_isoc_xfer.9 \ - usbdi.9 usbd_setup_xfer.9 \ - usbdi.9 usbd_sync_transfer.9 \ - usbdi.9 usbd_transfer.9 \ - usbdi.9 usb_find_desc.9 + usbdi.9 usbd_lookup_id_by_info.9 \ + usbdi.9 usbd_lookup_id_by_uaa.9 \ + usbdi.9 usbd_transfer_clear_stall.9 \ + usbdi.9 usbd_transfer_drain.9 \ + usbdi.9 usbd_transfer_pending.9 \ + usbdi.9 usbd_transfer_poll.9 \ + usbdi.9 usbd_transfer_setup.9 \ + usbdi.9 usbd_transfer_start.9 \ + usbdi.9 usbd_transfer_stop.9 \ + usbdi.9 usbd_transfer_submit.9 \ + usbdi.9 usbd_transfer_unsetup.9 \ + usbdi.9 usbd_xfer_clr_flag.9 \ + usbdi.9 usbd_xfer_frame_data.9 \ + usbdi.9 usbd_xfer_frame_len.9 \ + usbdi.9 usbd_xfer_get_frame.9 \ + usbdi.9 usbd_xfer_get_priv.9 \ + usbdi.9 usbd_xfer_is_stalled.9 \ + usbdi.9 usbd_xfer_max_framelen.9 \ + usbdi.9 usbd_xfer_max_frames.9 \ + usbdi.9 usbd_xfer_max_len.9 \ + usbdi.9 usbd_xfer_set_flag.9 \ + usbdi.9 usbd_xfer_set_frame_data.9 \ + usbdi.9 usbd_xfer_set_frame_len.9 \ + usbdi.9 usbd_xfer_set_frame_offset.9 \ + usbdi.9 usbd_xfer_set_frames.9 \ + usbdi.9 usbd_xfer_set_interval.9 \ + usbdi.9 usbd_xfer_set_priv.9 \ + usbdi.9 usbd_xfer_set_stall.9 \ + usbdi.9 usbd_xfer_set_timeout.9 \ + usbdi.9 usbd_xfer_softc.9 \ + usbdi.9 usbd_xfer_state.9 \ + usbdi.9 usbd_xfer_state.9 \ + usbdi.9 usbd_xfer_status.9 MLINKS+=vcount.9 count_dev.9 MLINKS+=vfsconf.9 vfs_modevent.9 \ vfsconf.9 vfs_register.9 \ diff --git a/share/man/man9/usbdi.9 b/share/man/man9/usbdi.9 index 582754f..d58e599 100644 --- a/share/man/man9/usbdi.9 +++ b/share/man/man9/usbdi.9 @@ -24,1230 +24,615 @@ .\" SUCH DAMAGE. .\" .\" $FreeBSD$ -.Dd December 30, 2005 +.Dd June 24, 2009 .Os .Dt USBDI 9 .Sh NAME -.Nm usb_detach_wait , -.Nm usb_detach_wakeup , -.Nm usb_find_desc , -.Nm usbd_abort_default_pipe , -.Nm usbd_abort_pipe , -.Nm usbd_alloc_buffer , -.Nm usbd_alloc_xfer , -.Nm usbd_bulk_transfer , -.Nm usbd_clear_endpoint_stall , -.Nm usbd_clear_endpoint_stall_async , -.Nm usbd_clear_endpoint_toggle , -.Nm usbd_close_pipe , -.Nm usbd_device2interface_handle , -.Nm usbd_devinfo , +.Nm usb_fifo_alloc_buffer , +.Nm usb_fifo_attach , +.Nm usb_fifo_detach , +.Nm usb_fifo_free_buffer , +.Nm usb_fifo_get_data , +.Nm usb_fifo_get_data_buffer , +.Nm usb_fifo_get_data_error , +.Nm usb_fifo_get_data_linear , +.Nm usb_fifo_put_bytes_max , +.Nm usb_fifo_put_data , +.Nm usb_fifo_put_data_buffer , +.Nm usb_fifo_put_data_error , +.Nm usb_fifo_put_data_linear , +.Nm usb_fifo_reset , +.Nm usb_fifo_softc , +.Nm usb_fifo_wakeup , .Nm usbd_do_request , -.Nm usbd_do_request_async , .Nm usbd_do_request_flags , -.Nm usbd_do_request_flags_pipe , -.Nm usbd_dopoll , -.Nm usbd_endpoint_count , .Nm usbd_errstr , -.Nm usbd_fill_deviceinfo , -.Nm usbd_find_edesc , -.Nm usbd_find_idesc , -.Nm usbd_free_buffer , -.Nm usbd_free_xfer , -.Nm usbd_get_buffer , -.Nm usbd_get_config , -.Nm usbd_get_config_desc , -.Nm usbd_get_config_desc_full , -.Nm usbd_get_config_descriptor , -.Nm usbd_get_device_descriptor , -.Nm usbd_get_endpoint_descriptor , -.Nm usbd_get_interface_altindex , -.Nm usbd_get_interface_descriptor , -.Nm usbd_get_no_alts , -.Nm usbd_get_quirks , -.Nm usbd_get_speed , -.Nm usbd_get_string , -.Nm usbd_get_string_desc , -.Nm usbd_get_xfer_status , -.Nm usbd_interface2device_handle , -.Nm usbd_interface2endpoint_descriptor , -.Nm usbd_interface_count , -.Nm usbd_intr_transfer , -.Nm usbd_open_pipe , -.Nm usbd_open_pipe_intr , -.Nm usbd_pipe2device_handle , -.Nm usbd_ratecheck , -.Nm usbd_set_config_index , -.Nm usbd_set_config_no , -.Nm usbd_set_interface , -.Nm usbd_set_polling , -.Nm usbd_setup_default_xfer , -.Nm usbd_setup_isoc_xfer , -.Nm usbd_setup_xfer , -.Nm usbd_sync_transfer , -.Nm usbd_transfer +.Nm usbd_lookup_id_by_info , +.Nm usbd_lookup_id_by_uaa , +.Nm usbd_transfer_clear_stall , +.Nm usbd_transfer_drain , +.Nm usbd_transfer_pending , +.Nm usbd_transfer_poll , +.Nm usbd_transfer_setup , +.Nm usbd_transfer_start , +.Nm usbd_transfer_stop , +.Nm usbd_transfer_submit , +.Nm usbd_transfer_unsetup , +.Nm usbd_xfer_clr_flag , +.Nm usbd_xfer_frame_data , +.Nm usbd_xfer_frame_len , +.Nm usbd_xfer_get_frame , +.Nm usbd_xfer_get_priv , +.Nm usbd_xfer_is_stalled , +.Nm usbd_xfer_max_framelen , +.Nm usbd_xfer_max_frames , +.Nm usbd_xfer_max_len , +.Nm usbd_xfer_set_flag , +.Nm usbd_xfer_set_frame_data , +.Nm usbd_xfer_set_frame_len , +.Nm usbd_xfer_set_frame_offset , +.Nm usbd_xfer_set_frames , +.Nm usbd_xfer_set_interval , +.Nm usbd_xfer_set_priv , +.Nm usbd_xfer_set_stall , +.Nm usbd_xfer_set_timeout , +.Nm usbd_xfer_softc , +.Nm usbd_xfer_state , +.Nm usbd_xfer_state , +.Nm usbd_xfer_status .Nd Universal Serial Bus driver programming interface .Sh SYNOPSIS .In dev/usb/usb.h .In dev/usb/usbdi.h .In dev/usb/usbdi_util.h -.Pp -.Ft void -.Fn usb_detach_wait "device_ptr_t dv" -.Ft void -.Fn usb_detach_wakeup "device_ptr_t dv" -.Ft "const usb_descriptor_t *" -.Fn usb_find_desc "usbd_device_handle dev" "int type" "int subtype" -.Ft usbd_status -.Fn usbd_abort_default_pipe "usbd_device_handle dev" -.Ft usbd_status -.Fn usbd_abort_pipe "usbd_pipe_handle pipe" -.Ft "void *" -.Fn usbd_alloc_buffer "usbd_xfer_handle xfer" "u_int32_t size" -.Ft usbd_xfer_handle -.Fn usbd_alloc_xfer "usbd_device_handle dev" -.Ft usbd_status -.Fo usbd_bulk_transfer -.Fa "usbd_xfer_handle xfer" -.Fa "usbd_pipe_handle pipe" -.Fa "u_int16_t flags" -.Fa "u_int32_t timeout" -.Fa "void *buf" -.Fa "u_int32_t *size" -.Fa "char *lbl" -.Fc -.Ft usbd_status -.Fn usbd_clear_endpoint_stall "usbd_pipe_handle pipe" -.Ft usbd_status -.Fn usbd_clear_endpoint_stall_async "usbd_pipe_handle" -.Ft void -.Fn usbd_clear_endpoint_toggle "usbd_pipe_handle pipe" -.Ft usbd_status -.Fn usbd_close_pipe "usbd_pipe_handle pipe" -.Ft usbd_status -.Fo usbd_device2interface_handle -.Fa "usbd_device_handle dev" -.Fa "u_int8_t ifaceno" -.Fa "usbd_interface_handle *iface" -.Fc -.Ft void -.Fn usbd_devinfo "usbd_device_handle dev" "int showclass" "char *cp" -.Ft usbd_status -.Fo usbd_do_request -.Fa "usbd_device_handle dev" -.Fa "usb_device_request_t *req" -.Fa "void *data" -.Fc -.Ft usbd_status -.Fo usbd_do_request_async -.Fa "usbd_device_handle dev" -.Fa "usb_device_request_t *req" -.Fa "void *data" -.Fc -.Ft usbd_status -.Fo usbd_do_request_flags -.Fa "usbd_device_handle dev" -.Fa "usb_device_request_t *req" -.Fa "void *data" -.Fa "u_int16_t flags" -.Fa "int *actlen" -.Fa "u_int32_t timo" -.Fc -.Ft usbd_status -.Fo usbd_do_request_flags_pipe -.Fa "usbd_device_handle dev" -.Fa "usbd_pipe_handle pipe" -.Fa "usb_device_request_t *req" -.Fa "void *data" -.Fa "u_int16_t flags" -.Fa "int *actlen" -.Fa "u_int32_t timeout" -.Fc -.Ft void -.Fn usbd_dopoll "usbd_interface_handle iface" -.Ft usbd_status -.Fn usbd_endpoint_count "usbd_interface_handle iface" "u_int8_t *count" -.Ft "const char *" -.Fn usbd_errstr "usbd_status err" -.Ft void -.Fo usbd_fill_deviceinfo -.Fa "usbd_device_handle dev" -.Fa "struct usb_device_info *di" -.Fa "int usedev" -.Fc -.Ft "usb_endpoint_descriptor_t *" -.Fo usbd_find_edesc -.Fa "usb_config_descriptor_t *cd" -.Fa "int ifaceidx" -.Fa "int altidx" -.Fa "int endptidx" -.Fc -.Ft "usb_interface_descriptor_t *" -.Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" -.Ft void -.Fn usbd_free_buffer "usbd_xfer_handle xfer" -.Ft usbd_status -.Fn usbd_free_xfer "usbd_xfer_handle xfer" -.Ft "void *" -.Fn usbd_get_buffer "usbd_xfer_handle xfer" -.Ft usbd_status -.Fn usbd_get_config "usbd_device_handle dev" "u_int8_t *conf" -.Ft usbd_status -.Fo usbd_get_config_desc -.Fa "usbd_device_handle dev" -.Fa "int confidx" -.Fa "usb_config_descriptor_t *d" -.Fc -.Ft usbd_status -.Fo usbd_get_config_desc_full -.Fa "usbd_device_handle dev" -.Fa "int conf" -.Fa "void *d" -.Fa "int size" -.Fc -.Ft "usb_config_descriptor_t *" -.Fn usbd_get_config_descriptor "usbd_device_handle dev" -.Ft "usb_device_descriptor_t *" -.Fn usbd_get_device_descriptor "usbd_device_handle dev" -.Ft "usb_endpoint_descriptor_t *" -.Fo usbd_get_endpoint_descriptor -.Fa "usbd_interface_handle iface" -.Fa "u_int8_t address" -.Fc -.Ft int -.Fn usbd_get_interface_altindex "usbd_interface_handle iface" -.Ft "usb_interface_descriptor_t *" -.Fn usbd_get_interface_descriptor "usbd_interface_handle iface" -.Ft int -.Fn usbd_get_no_alts "usb_config_descriptor_t *cdesc" "int ifaceno" -.Ft "const struct usbd_quirks *" -.Fn usbd_get_quirks "usbd_device_handle dev" -.Ft int -.Fn usbd_get_speed "usbd_device_handle dev" -.Ft usbd_status -.Fn usbd_get_string "usbd_device_handle dev" "int si" "char *buf" -.Ft usbd_status -.Fo usbd_get_string_desc -.Fa "usbd_device_handle dev" -.Fa "int sindex" -.Fa "int langid" -.Fa "usb_string_descriptor_t *sdesc" -.Fa "int *sizep" -.Fc -.Ft void -.Fo usbd_get_xfer_status -.Fa "usbd_xfer_handle xfer" -.Fa "usbd_private_handle *priv" -.Fa "void **buffer" -.Fa "u_int32_t *count" -.Fa "usbd_status *status" -.Fc -.Ft void -.Fo usbd_interface2device_handle -.Fa "usbd_interface_handle iface" -.Fa "usbd_device_handle *dev" -.Fc -.Ft "usb_endpoint_descriptor_t *" -.Fo usbd_interface2endpoint_descriptor -.Fa "usbd_interface_handle iface" -.Fa "u_int8_t index" -.Fc -.Ft usbd_status -.Fn usbd_interface_count "usbd_device_handle dev" "u_int8_t *count" -.Ft usbd_status -.Fo usbd_intr_transfer -.Fa "usbd_xfer_handle xfer" -.Fa "usbd_pipe_handle pipe" -.Fa "u_int16_t flags" -.Fa "u_int32_t timeout" -.Fa "void *buf" -.Fa "u_int32_t *size" -.Fa "char *lbl" -.Fc -.Ft usbd_status -.Fo usbd_open_pipe -.Fa "usbd_interface_handle iface" -.Fa "u_int8_t address" -.Fa "u_int8_t flags" -.Fa "usbd_pipe_handle *pipe" -.Fc -.Ft usbd_status -.Fo usbd_open_pipe_intr -.Fa "usbd_interface_handle iface" -.Fa "u_int8_t address" -.Fa "u_int8_t flags" -.Fa "usbd_pipe_handle *pipe" -.Fa "usbd_private_handle priv" -.Fa "void *buffer" -.Fa "u_int32_t len" -.Fa "usbd_callback cb" -.Fa "int ival" -.Fc -.Ft usbd_device_handle -.Fn usbd_pipe2device_handle "usbd_pipe_handle pipe" -.Ft int -.Fn usbd_ratecheck "struct timeval *last" -.Ft usbd_status -.Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg" -.Ft usbd_status -.Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg" -.Ft usbd_status -.Fn usbd_set_interface "usbd_interface_handle iface" "int altidx" -.Ft void -.Fn usbd_set_polling "usbd_device_handle dev" "int on" -.Ft void -.Fo usbd_setup_default_xfer -.Fa "usbd_xfer_handle xfer" -.Fa "usbd_device_handle dev" -.Fa "usbd_private_handle priv" -.Fa "u_int32_t timeout" -.Fa "usb_device_request_t *req" -.Fa "void *buffer" -.Fa "u_int32_t length" -.Fa "u_int16_t flags" -.Fa "usbd_callback callback" -.Fc -.Ft void -.Fo usbd_setup_isoc_xfer -.Fa "usbd_xfer_handle xfer" -.Fa "usbd_pipe_handle pipe" -.Fa "usbd_private_handle priv" -.Fa "u_int16_t *frlengths" -.Fa "u_int32_t nframes" -.Fa "u_int16_t flags" -.Fa "usbd_callback callback" -.Fc -.Ft void -.Fo usbd_setup_xfer -.Fa "usbd_xfer_handle xfer" -.Fa "usbd_pipe_handle pipe" -.Fa "usbd_private_handle priv" -.Fa "void *buffer" -.Fa "u_int32_t length" -.Fa "u_int16_t flags" -.Fa "u_int32_t timeout" -.Fa "usbd_callback callback" -.Fc -.Ft usbd_status -.Fn usbd_sync_transfer "usbd_xfer_handle xfer" -.Ft usbd_status -.Fn usbd_transfer "usbd_xfer_handle xfer" .Sh DESCRIPTION The Universal Serial Bus (USB) driver programming interface provides USB peripheral drivers with a host controller independent API for controlling and communicating with USB peripherals. -.Pp -Typically, drivers will first use some combination of the functions -.Fn usbd_set_config_no , -.Fn usbd_get_config_descriptor , -.Fn usbd_set_interface , -.Fn usbd_get_interface_descriptor , -.Fn usbd_device2interface_handle , -.Fn usbd_endpoint_count -and -.Fn usbd_interface2endpoint_descriptor -to query the device's properties and prepare it for use. -Drivers can then perform requests on the USB control pipe using -.Fn usbd_do_request , -they can open pipes using the functions -.Fn usbd_open_pipe -and -.Fn usbd_open_pipe_intr , -and perform transfers over these pipes using -.Fn usbd_alloc_xfer , -.Fn usbd_setup_xfer -and -.Fn usbd_transfer . -Finally, the functions -.Fn usbd_abort_pipe , -.Fn usbd_close_pipe -and -.Fn usbd_free_xfer -are used to cancel outstanding transfers, close open pipes and deallocate -transfer structures. -.Pp -The -.Fn usbd_get_device_descriptor -function returns a pointer to the USB device descriptor for -.Fa dev . -See -.Sx "USB Descriptors" -below for information about the USB device descriptor. -.Pp -The -.Fn usbd_get_config_desc -function retrieves the specified configuration descriptor from the device. -The -.Fa confidx -parameter specifies the configuration descriptor index, which must be less -than the -.Fa bNumConfigurations -value in the device descriptor. -The function -.Fn usbd_get_config_desc_full -retrieves a full configuration descriptor, which has all related interface -and endpoint descriptors appended to a normal configuration descriptor. -The parameter -.Fa d -should point to memory that is at least -.Fa size -bytes in length, and this should be at least as long as the -.Fa wTotalLength -value from the configuration descriptor. -See -.Sx "USB Descriptors" -below for information about the USB configuration descriptor. -.Pp -The -.Fn usbd_get_config -function retrieves the current configuration number from the device, i.e.\& -the -.Fa bConfigurationValue -value from the configuration that is active. -If the device is unconfigured then -.Dv USB_UNCONFIG_NO -is returned. -The current configuration can be changed by calling either -.Fn usbd_set_config_index -or -.Fn usbd_set_config_no . -The difference between these functions is that -.Fn usbd_set_config_index -accepts a configuration index number that is less than the -.Fa bNumConfigurations -value from the device descriptor, whereas -.Fn usbd_set_config_no -requires the -.Fa bConfigurationValue -value of the desired configuration to be provided instead. -To unconfigure the device, supply a configuration index of -.Dv USB_UNCONFIG_INDEX -to -.Fn usbd_set_config_index , -or else specify a configuration number of -.Dv USB_UNCONFIG_NO -to -.Fn usbd_set_config_no . -.Pp -The -.Fn usbd_get_config_descriptor -function returns a pointer to an in-memory copy of the full configuration -descriptor of the configuration that is currently active. -The returned pointer remains valid until the device configuration -is changed using -.Fn usbd_set_config_index -or -.Fn usbd_set_config_no . -If the device is unconfigured then -.Dv NULL -is returned instead. -.Pp -The function -.Fn usbd_interface_count -returns the number of interfaces available in the current device -configuration. The -.Fn usbd_get_no_alts -function determines the number of alternate interfaces in a full -configuration descriptor by counting the interface descriptors with -.Fa bInterfaceNumber -equal to -.Fa ifaceno -(the count includes alternate index zero). -The -.Fn usbd_find_idesc -function locates an interface descriptor within a full configuration -descriptor. -The -.Fa ifaceidx -parameter specifies the interface index number, which should be less than -the number of interfaces in the configuration descriptor (i.e.\& the value -returned by -.Fn usbd_interface_count -or the -.Fa bNumInterface -field from the configuration descriptor). -An alternate interface can be specified using a non-zero -.Fa altidx , -which should be less than the value returned by -.Fn usbd_get_no_alts . -The return value is a pointer to the requested interface descriptor -within the full configuration descriptor, or -.Dv NULL -if the specified interface descriptor does not exist. -Note that the -.Fa altidx -parameter specifies the alternate setting by index number starting -at zero; it is not the alternate setting number defined in the -interface descriptor. -.Pp -The function -.Fn usbd_find_edesc -locates an endpoint descriptor within a full configuration descriptor. -The -.Fa ifaceidx -and -.Fa altidx -parameters are the same as described for -.Fn usbd_find_idesc , -and the -.Fa endptidx -parameter is an endpoint index number that should be less than the -.Fa bNumEndpoints -field in the interface descriptor. -The return value is a pointer to the requested endpoint descriptor -within the full configuration descriptor, or -.Dv NULL -if the specified endpoint descriptor does not exist. -Note that the -.Fa altidx -and -.Fa endptidx -parameters are index numbers starting at zero; they are not the -alternate setting and endpoint address defined in the descriptors. -.Pp -The -.Fn usbd_get_speed -function returns the device speed. -This can be -.Dv USB_SPEED_LOW , -.Dv USB_SPEED_FULL -or -.Dv USB_SPEED_HIGH . +.Nm usb +module supports both USB Host and USB Device side mode. +. +.Sh USB KERNEL PROGRAMMING +Here is a list of commonly used functions: +.Pp +. +.Ft "usb_error_t" +.Fo "usbd_transfer_setup" +.Fa "udev" +.Fa "ifaces" +.Fa "pxfer" +.Fa "setup_start" +.Fa "n_setup" +.Fa "priv_sc" +.Fa "priv_mtx" +.Fc +. .Pp -USB devices optionally support string descriptors, which can be -retrieved using the -.Fn usbd_get_string -or -.Fn usbd_get_string_desc -functions. -Device, configuration and interface descriptors reference strings by -an index number that can be supplied to these functions. -The -.Fn usbd_get_string -function should be used unless a non-default language is required. -It requires that -.Fa buf -points to a buffer of at least -.Dv USB_MAX_STRING_LEN -bytes in size. -The -.Fa si -parameter specified which string to retrieve. +. +.Ft "void" +.Fo "usbd_transfer_unsetup" +.Fa "pxfer" +.Fa "n_setup" +.Fc +. .Pp -The -.Fn usb_find_desc -function searches through the in-memory full configuration descriptor -for the active configuration and finds the first descriptor that has a -.Fa bDescriptorType -equal to -.Fa type , -and if -.Fa subtype -is not equal to -.Dv USBD_SUBTYPE_ANY , -the descriptor must also have a -.Fa bDescriptorSubtype -equal to -.Fa subtype . -If found, then a pointer to the descriptor is returned. -Otherwise, -.Fn usb_find_desc -returns -.Dv NULL . -The returned pointer is valid until the device configuration is changed using -.Fn usbd_set_config_index -or -.Fn usbd_set_config_no . +. +.Ft "void" +.Fo "usbd_transfer_start" +.Fa "xfer" +.Fc +. .Pp -The USB driver interface uses opaque interface handles to refer to -configuration interfaces. -These handles remain valid until the device configuration is changed using -.Fn usbd_set_config_index -or -.Fn usbd_set_config_no . -The -.Fn usbd_device2interface_handle -function retrieves an interface handle. -The -.Fa ifaceno -parameter is an interface index number starting at zero. -If the device is configured and the specified interface exists, then -.Dv USBD_NORMAL_COMPLETION -is returned and the interface handle is stored in -.Fa *iface . -Otherwise an error code is returned and -.Fa *iface -is not changed. -The -.Fn usbd_interface2device_handle -function retrieves the device handle from an interface handle. -This is just for convenience to save passing around the device -handle as well as the interface handle. -The -.Fn usbd_set_interface -function changes the alternate setting number for an interface to -the alternate setting identified by the zero-based index number -.Fa altidx . -This operation invalidates any existing endpoints on this -interface and their descriptors. -The -.Fn usbd_get_interface_altindex -function returns the current alternative setting index as was -specified when calling -.Fn usbd_set_interface . -The -.Fn usbd_endpoint_count -function retrieves the number of endpoints associated with the -specified interface. -The -.Fn usbd_interface2endpoint_descriptor -function returns a pointer to an in-memory endpoint descriptor for -the endpoint that has an index number of -.Fa index . -This pointer remains valid until the configuration or alternate setting -number are changed. -The function -.Fn usbd_get_endpoint_descriptor -is like -.Fn usbd_interface2endpoint_descriptor -but it accepts a -.Fa bEndpointAddress -address value instead of an index. +. +.Ft "void" +.Fo "usbd_transfer_stop" +.Fa "xfer" +.Fc +. .Pp -The -.Fn usbd_fill_deviceinfo -function fills out a -.Vt usb_device_info -structure with information about the device. -The vendor and product names come from the device itself, falling back to -a table lookup or just providing the IDs in hexadecimal. -If -.Fa usedev -is zero then -.Fn usbd_fill_deviceinfo -will not attempt to retrieve the vendor and product names from the -device. -The usb_device_info structure is defined in -.In dev/usb/usb.h -as follows: -.Bd -literal -struct usb_device_info { - u_int8_t udi_bus; - u_int8_t udi_addr; /* device address */ - usb_event_cookie_t udi_cookie; - char udi_product[USB_MAX_STRING_LEN]; - char udi_vendor[USB_MAX_STRING_LEN]; - char udi_release[8]; - u_int16_t udi_productNo; - u_int16_t udi_vendorNo; - u_int16_t udi_releaseNo; - u_int8_t udi_class; - u_int8_t udi_subclass; - u_int8_t udi_protocol; - u_int8_t udi_config; - u_int8_t udi_speed; -#define USB_SPEED_LOW 1 -#define USB_SPEED_FULL 2 -#define USB_SPEED_HIGH 3 - int udi_power; /* power consumption in mA */ - int udi_nports; - char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; - /* hub only: addresses of devices on ports */ - u_int8_t udi_ports[16]; -#define USB_PORT_ENABLED 0xff -#define USB_PORT_SUSPENDED 0xfe -#define USB_PORT_POWERED 0xfd +. +.Ft "void" +.Fo "usbd_transfer_drain" +.Fa "xfer" +.Fc +. +. +. +.Sh USB TRANSFER MANAGEMENT FUNCTIONS +The USB standard defines four types of USB transfers. +. +Control transfers, Bulk transfers, Interrupt transfers and Isochronous +transfers. +. +All the transfer types are managed using the following five functions: +. +.Pp +. +.Fn usbd_transfer_setup +This function will allocate memory for and initialise an array of USB +transfers and all required DMA memory. +. +This function can sleep or block waiting for resources to become +available. +.Fa udev +is a pointer to "struct usb_device". +.Fa ifaces +is an array of interface index numbers to use. See "if_index". +.Fa pxfer +is a pointer to an array of USB transfer pointers that are initialized +to NULL, and then pointed to allocated USB transfers. +.Fa setup_start +is a pointer to an array of USB config structures. +.Fa n_setup +is a number telling the USB system how many USB transfers should be +setup. +.Fa priv_sc +is the private softc pointer, which will be used to initialize +"xfer->priv_sc". +.Fa priv_mtx +is the private mutex protecting the transfer structure and the +softc. This pointer is used to initialize "xfer->priv_mtx". +This function returns +zero upon success. A non-zero return value indicates failure. +. +.Pp +. +.Fn usbd_transfer_unsetup +This function will release the given USB transfers and all allocated +resources associated with these USB transfers. +.Fa pxfer +is a pointer to an array of USB transfer pointers, that may be NULL, +that should be freed by the USB system. +.Fa n_setup +is a number telling the USB system how many USB transfers should be +unsetup. +. +This function can sleep waiting for USB transfers to complete. +. +This function is NULL safe with regard to the USB transfer structure +pointer. +. +It is not allowed to call this function from the USB transfer +callback. +. +.Pp +. +.Fn usbd_transfer_start +This function will start the USB transfer pointed to by +.Fa xfer, +if not already started. +. +This function is always non-blocking and must be called with the +so-called private USB mutex locked. +. +This function is NULL safe with regard to the USB transfer structure +pointer. +. +.Pp +. +.Fn usbd_transfer_stop +This function will stop the USB transfer pointed to by +.Fa xfer, +if not already stopped. +. +This function is always non-blocking and must be called with the +so-called private USB mutex locked. +. +This function can return before the USB callback has been called. +. +This function is NULL safe with regard to the USB transfer structure +pointer. +. +If the transfer was in progress, the callback will called with +"USB_ST_ERROR" and "error = USB_ERR_CANCELLED". +. +.Pp +. +.Fn usbd_transfer_drain +This function will stop an USB transfer, if not already stopped and +wait for any additional USB hardware operations to complete. +. +Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can +safely be freed after that this function has returned. +. +This function can block the caller and will not return before the USB +callback has been called. +. +This function is NULL safe with regard to the USB transfer structure +pointer. +. +.Sh USB TRANSFER CALLBACK +. +The USB callback has three states. +. +USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the +initial state. +. +After the callback has been called with this state it will always be +called back at a later stage in one of the other two states. +. +The USB callback should not restart the USB transfer in case the error +cause is USB_ERR_CANCELLED. +. +The USB callback is protected from recursion. +. +That means one can start and stop whatever transfer from the callback +of another transfer one desires. +. +Also the transfer that is currently called back. +. +Recursion is handled like this that when the callback that wants to +recurse returns it is called one more time. +. +. +.Pp +. +.Fn usbd_transfer_submit +This function should only be called from within the USB callback and +is used to start the USB hardware. +. +An USB transfer can have multiple frames consisting of one or more USB +packets making up an I/O vector for all USB transfer types. +. +.Bd -literal -offset indent +void +usb_default_callback(struct usb_xfer *xfer, usb_error_t error) +{ + int actlen; + + usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL); + + switch (USB_GET_STATE(xfer)) { + case USB_ST_SETUP: + /* + * Setup xfer frame lengths/count and data + */ + usbd_transfer_submit(xfer); + break; + + case USB_ST_TRANSFERRED: + /* + * Read usb frame data, if any. + * "actlen" has the total length for all frames + * transfered. + */ + break; + + default: /* Error */ + /* + * Print error message and clear stall + * for example. + */ + break; + } + /* + * Here it is safe to do something without the private + * USB mutex locked. + */ + return; } .Ed -.Pp -The -.Fn usbd_devinfo -function generates a string description of the USB device. -The -.Fa cp -argument should point to a 1024-byte buffer (XXX the maximum length -is approximately 320 chars, but there is no sanity checking and everything uses -1024-character buffers). -Device class information is included if the -.Fa showclass -parameter is non-zero. -.Pp -The -.Fn usbd_get_quirks -function returns information from a table of devices that require -special workarounds in order to function correctly. -The returned structure is defined in -.In dev/usb/usb_quirks.h -as follows: -.Bd -literal -struct usbd_quirks { - u_int32_t uq_flags; /* Device problems */ -}; +. +.Sh USB CONTROL TRANSFERS +An USB control transfer has three parts. +. +First the SETUP packet, then DATA packet(s) and then a STATUS +packet. +. +The SETUP packet is always pointed to by frame 0 and the +length is set by +.Fn usbd_xfer_frame_len +also if there should not be +sent any SETUP packet! If an USB control transfer has no DATA stage, +then the number of frames should be set to 1. +. +Else the default number of frames is 2. +. +.Bd -literal -offset indent + +Example1: SETUP + STATUS + usbd_xfer_set_frames(xfer, 1); + usbd_xfer_set_frame_len(xfer, 0, 8); + usbd_transfer_submit(xfer); + +Example2: SETUP + DATA + STATUS + usbd_xfer_set_frames(xfer, 2); + usbd_xfer_set_frame_len(xfer, 0, 8); + usbd_xfer_set_frame_len(xfer, 1, 1); + usbd_transfer_submit(xfer); + +Example3: SETUP + DATA + STATUS - split +1st callback: + usbd_xfer_set_frames(xfer, 1); + usbd_xfer_set_frame_len(xfer, 0, 8); + usbd_transfer_submit(xfer); + +2nd callback: + /* IMPORTANT: frbuffers[0] must still point at the setup packet! */ + usbd_xfer_set_frames(xfer, 2); + usbd_xfer_set_frame_len(xfer, 0, 0); + usbd_xfer_set_frame_len(xfer, 1, 1); + usbd_transfer_submit(xfer); + +Example4: SETUP + STATUS - split +1st callback: + usbd_xfer_set_frames(xfer, 1); + usbd_xfer_set_frame_len(xfer, 0, 8); + usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS); + usbd_transfer_submit(xfer); + +2nd callback: + usbd_xfer_set_frames(xfer, 1); + usbd_xfer_set_frame_len(xfer, 0, 0); + usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS); + usbd_transfer_submit(xfer); + .Ed -.Pp -See -.In dev/usb/usb_quirks.h -for a list of all currently defined quirks. -.Pp -USB control requests are performed via -.Vt usb_device_request_t -structures, defined in -.In dev/usb/usb.h -as follows: -.Bd -literal -typedef struct { - uByte bmRequestType; - uByte bRequest; - uWord wValue; - uWord wIndex; - uWord wLength; -} UPACKED usb_device_request_t; +.Sh USB TRANSFER CONFIG +To simply the search for endpoints the +.Nm usb +module defines a USB config structure where it is possible to specify +the characteristics of the wanted endpoint. +.Bd -literal -offset indent + +struct usb_config { + bufsize, + callback + direction, + endpoint, + frames, + index flags, + interval, + timeout, + type, +}; + .Ed -.Pp -The -.Fn usbd_do_request -function performs a single request synchronously. -The -.Fa req -parameter should point to a properly initialized -.Vt usb_device_request_t , -and when the -.Fa wLength -field is non-zero, -.Fa data -should point at a buffer that is at least -.Fa wLength -bytes in length. -The request timeout is set to 5 seconds, so the operation will fail -with -.Er USBD_TIMEOUT -if the device does not respond within that time. -The -.Fn usbd_do_request_async -function is like -.Fn usbd_do_request , -but it does not wait for the request to complete before returning. -This routine does not block so it can be used from contexts where -sleeping is not allowed. -Note that there is no notification mechanism to report when the -operation completed nor is there a way to determine whether the -request succeeded, so this function is of limited use. -See -.Fn usbd_setup_default_xfer -and -.Fn usbd_transfer -for a way to invoke an asynchronous callback upon completion of -a control request. -The -.Fn usbd_do_request_flags -function is like -.Fn usbd_do_request , -but additional flags can be specified, the timeout is configurable, -and the actual number of bytes transferred is made available to the -caller. -The -.Fn usbd_do_request_flags_pipe -function uses a specified pipe instead of the default pipe. -.Pp -The function -.Fn usbd_open_pipe -creates a pipe connected to a specified endpoint on a specified interface. -The parameter -.Fa address -should be the -.Fa bEndpointAddress -value from one of this interface's endpoint descriptors. -If -.Fa flags -contains -.Dv USBD_EXCLUSIVE_USE -then the operation will only succeed if there are no open pipes -already connected to the specified endpoint. -The -.Fn usbd_open_pipe_intr -function creates an interrupt pipe connected to the specified endpoint. -The parameter -.Fa address -should be the -.Fa bEndpointAddress -value from one of this interface's endpoint descriptors. -The -.Fa flags -parameter is passed to -.Fn usbd_setup_xfer . -The -.Fa buffer -and -.Fa len -parameters define a buffer that is to be used for the interrupt transfers. -The callback to be invoked each time a transfer completes is specified by -.Fa cb , -and -.Fa priv -is an argument to be passed to the callback function. -The -.Fa ival -parameter specifies the maximum acceptable interval between transfers; -in practice the transfers may occur more frequently. -The function -.Fn usbd_pipe2device_handle -returns the device associated with the specified -.Fa pipe . -.Pp -The -.Fn usbd_abort_pipe -function aborts all active or waiting transfers on the specified pipe. -Each transfer is aborted with a -.Dv USBD_CANCELLED -status; callback routines must detect this error code to ensure that -they do not attempt to initiate a new transfer in response to one being -aborted. -This routine blocks while it is waiting for the hardware to complete -processing of aborted transfers, so it is only safe to call it in -contexts where sleeping is allowed. -The function -.Fn usbd_abort_default_pipe -aborts all active or waiting transfers on the default pipe. -Like -.Fn usbd_abort_pipe , -it blocks waiting for the hardware processing to complete. -.Pp -When a pipe has no active or waiting transfers, the pipe may be closed -using the -.Fn usbd_close_pipe -function. -Once a pipe is closed, its pipe handle becomes invalid and may no longer -be used. -.Pp -USB transfer handles are allocated using the function -.Fn usbd_alloc_xfer -and may be freed using -.Fn usbd_free_xfer . -.Pp -The function -.Fn usbd_setup_xfer -initializes a transfer handle with the details of a transfer to or from -a USB device. -The -.Fa xfer -parameter specifies the transfer handle to initialize, -.Fa pipe -specifies the pipe on which the transfer is to take place, and -.Fa priv -is an argument that will be passed to callback function. -The arguments -.Fa buffer -and -.Fa length -define the data buffer for the transfer. -If -.Fa length -is zero then the -.Fa buffer -may be -.Dv NULL . -The -.Fa flags -parameter may contain the following flags: -.Bl -tag -width ".Dv USBD_FORCE_SHORT_XFER" -.It Dv USBD_NO_COPY -This is used in association with -.Fn usbd_alloc_buffer -and -.Fn usbd_free_buffer -to use a dedicated DMA-capable buffer for the transfer. -.It Dv USBD_SYNCHRONOUS -Wait for the transfer to compete in -.Fn usbd_transfer . -.It Dv USBD_SHORT_XFER_OK -Permit transfers shorter than the requested data length. -.It Dv USBD_FORCE_SHORT_XFER -Force a short transfer at the end of a write operation to let the -device know that the transfer has ended. +. +.Pp +.Fa type +field selects the USB pipe type. +. +Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK, +UE_ISOCHRONOUS. +. +The special value UE_BULK_INTR will select BULK and INTERRUPT pipes. +. +This field is mandatory. +. +.Pp +.Fa endpoint +field selects the USB endpoint number. +. +A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching +endpoint. +. +This field is mandatory. +. +.Pp +.Fa direction +field selects the USB endpoint direction. +. +A value of "UE_DIR_ANY" will select the first matching endpoint. +. +Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT". +. +"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which +means that the direction will be swapped in case of +USB_MODE_DEVICE. +. +Note that "UE_DIR_IN" refers to the data transfer direction of the +"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of +the "OUT" tokens. +. +This field is mandatory. +. +.Pp +.Fa interval +field selects the interrupt interval. +. +The value of this field is given in milliseconds and is independent of +device speed. +. +Depending on the endpoint type, this field has different meaning: +.Bl -tag +.It UE_INTERRUPT +"0" use the default interrupt interval based on endpoint descriptor. +"Else" use the given value for polling rate. +.It UE_ISOCHRONOUS +"0" use default. "Else" the value is ignored. +.It UE_BULK +.It UE_CONTROL +"0" no transfer pre-delay. "Else" a delay as given by this field in +milliseconds is inserted before the hardware is started when +"usbd_transfer_submit()" is called. +.Pp +NOTE: The transfer timeout, if any, is started after that the +pre-delay has elapsed! .El +. .Pp -The .Fa timeout -parameter specifies a timeout for the transfer in milliseconds. -A value of -.Dv USBD_NO_TIMEOUT -indicates that no timeout should be configured. -The parameter -.Fa callback -specifies the function to call when the transfer completes. -Note that -.Fn usbd_setup_xfer -does not actually initiate the transfer. -The -.Fn usbd_setup_default_xfer -initializes a control transfer for the default pipe. -The -.Fa req -parameter should point at a completed -.Vt usb_device_request_t -structure. -The function -.Fa usbd_setup_isoc_xfer -initializes a transfer for an isochronous pipe. -.Pp -The function -.Fn usbd_transfer -initiates a transfer. -Normally it returns -.Dv USBD_IN_PROGRESS -to indicate that the transfer has been queued. -If the USB stack is operating in polling mode, or if the transfer -is synchronous, then -.Dv USBD_NORMAL_COMPLETION -may be returned. -Other return values indicate that the transfer could not be -initiated due to an error. -The -.Fn usbd_sync_transfer -function executes a transfer synchronously. -It will sleep waiting for the transfer to complete and then return -the transfer status. -Note that if the transfer has a callback routine, this will be -invoked before -.Fn usbd_sync_transfer -returns. -.Pp -The -.Fn usbd_intr_transfer -and -.Fn usbd_bulk_transfer -functions set up a transfer and wait synchronously for it to complete -but they allows signals to interrupt the wait. -They returns -.Dv USBD_INTERRUPTED -if the transfer was interrupted by a signal. -XXX these two functions are identical apart from their names. -.Pp -The function -.Fn usbd_get_xfer_status -retrieves various information from a completed transfer. -If the -.Fa priv -parameter is not NULL then the callback private argument is -stored in -.Fa *priv . -If -.Fa buffer -is not NULL then the transfer buffer pointer is stored in -.Fa *buffer . -The actual number of bytes transferred is stored in -.Fa *count -if -.Fa count is not NULL. -Finally, the transfer status is stored in -.Fa *status -if -.Fa status -is not NULL. -.Pp -The -.Fn usbd_clear_endpoint_stall -function clears an endpoint stall condition synchronously, i.e.\& -it sleeps waiting for the stall clear request to complete. -The function -.Fn usbd_clear_endpoint_stall_async -performs the same function asynchronously, but it provides no -way to determine when the request completed, or whether it was -successful. -The -.Fn usbd_clear_endpoint_toggle -function instructs the host controller driver to reset the toggle bit -on a pipe. -This is used when manually clearing an endpoint stall using a -control pipe request, in order to ensure that the host controller -driver and the USB device restart with the same toggle value. -.Pp -Normally the USB subsystem maps and copies data to and from -DMA-capable memory each time a transfer is performed. -The function -.Fn usbd_alloc_buffer -allocates a permanent DMA-capable buffer associated with the -transfer to avoid this overhead. -The return value is the virtual address of the buffer. -Any time that -.Fn usbd_setup_xfer -is called on the transfer with the -.Dv USBD_NO_COPY -flag enabled, the allocated buffer will be used directly and -the -.Fa buffer -argument passed to -.Fn usbd_setup_xfer -will be ignored. -The -.Fn usbd_get_buffer -function returns a pointer to the virtual address of a buffer previously -allocated by -.Fn usbd_alloc_buffer . -Finally, -.Fn usbd_free_buffer -deallocates the buffer. -.Pp -The -.Fn usbd_errstr -function converts a status code into a string for display. -.Pp -The function -.Fn usbd_set_polling -enables or disables polling mode. -In polling mode, all operations will busy-wait for the device to -respond, so its use is effectively limited to boot time and kernel -debuggers. -It is important to match up calls that enable and disable polling -mode, because the implementation just increments a polling reference -count when -.Fa on -is non-zero and decrements it when -.Fa on -is zero. -The -.Fn usbd_dopoll -causes the host controller driver to poll for any activity. -This should only be used when polling mode is enabled. +field, if non-zero, will set the transfer timeout in milliseconds. If +the "timeout" field is zero and the transfer type is ISOCHRONOUS a +timeout of 250ms will be used. +. +.Pp +.Fa frames +field sets the maximum number of frames. If zero is specified it will +yield the following results: +.Bl -tag +.It UE_BULK +xfer->nframes = 1; +.It UE_INTERRUPT +xfer->nframes = 1; +.It UE_CONTROL +xfer->nframes = 2; +.It UE_ISOCHRONOUS +Not allowed. Will cause an error. +.El +. .Pp -The -.Fn usbd_ratecheck -function is used to limit the rate at which error messages are -printed to approximately once per second. -The -.Fa last -argument should point at a persistent -.Vt "struct timeval" . -A value of 1 will be returned if a message should be printed, but if -.Fn usbd_ratecheck -has already been called with the same -.Vt "struct timeval" -parameter in the last second then 0 is returned and the error message -should be suppressed. +.Fa ep_index +field allows you to give a number, in case more endpoints match the +description, that selects which matching "ep_index" should be used. +. .Pp -The functions -.Fn usb_detach_wait -and -.Fn usb_detach_wakeup -are used to wait for references to drain before completing the -detachment of a device. -The -.Fn usb_detach_wait -function will wait up to 60 seconds to receive a signal from -.Fn usb_detach_wait . -.Ss "USB Descriptors" -The USB specification defines a number of standard descriptors by -which USB devices report their attributes. -These descriptors are fixed-format structures that all USB devices -make available through USB control pipe requests. +.Fa if_index +field allows you to select which of the interface numbers in the +"ifaces" array parameter passed to "usbd_transfer_setup" that should +be used when setting up the given USB transfer. +. .Pp -Every USB device has exactly one USB device descriptor. -The USB subsystem retrieves this automatically when a device is -attached, and a copy of the descriptor is kept in memory. -The -.Fn usbd_get_device_descriptor -function returns a pointer to the descriptor. -The device descriptor structure is defined in -.In dev/usb/usb.h -as follows: -.Bd -literal -typedef struct { - uByte bLength; - uByte bDescriptorType; - uWord bcdUSB; -#define UD_USB_2_0 0x0200 -#define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0) - uByte bDeviceClass; - uByte bDeviceSubClass; - uByte bDeviceProtocol; - uByte bMaxPacketSize; - /* The fields below are not part of the initial descriptor. */ - uWord idVendor; - uWord idProduct; - uWord bcdDevice; - uByte iManufacturer; - uByte iProduct; - uByte iSerialNumber; - uByte bNumConfigurations; -} UPACKED usb_device_descriptor_t; -#define USB_DEVICE_DESCRIPTOR_SIZE 18 -.Ed +.Fa flags +field has type "struct usb_xfer_flags" and allows one to set initial +flags an USB transfer. Valid flags are: +.Bl -tag +.It force_short_xfer +This flag forces the last transmitted USB packet to be short. A short +packet has a length of less than "xfer->max_packet_size", which +derives from "wMaxPacketSize". This flag can be changed during +operation. +.It short_xfer_ok +This flag allows the received transfer length, "xfer->actlen" to be +less than "xfer->sumlen" upon completion of a transfer. This flag can +be changed during operation. +.It short_frames_ok +This flag allows the reception of multiple short USB frames. This flag +only has effect for BULK and INTERRUPT endpoints and if the number of +frames received is greater than 1. This flag can be changed during +operation. +.It pipe_bof +This flag causes a failing USB transfer to remain first in the PIPE +queue except in the case of "xfer->error" equal to +"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue +will be started until either: +.Bl -tag +.It 1 +The failing USB transfer is stopped using "usbd_transfer_stop()". +.It 2 +The failing USB transfer performs a successful transfer. +.El +The purpose of this flag is to avoid races when multiple transfers are +queued for execution on an USB endpoint, and the first executing +transfer fails leading to the need for clearing of stall for +example. +. +In this case this flag is used to prevent the following USB transfers +from being executed at the same time the clear-stall command is +executed on the USB control endpoint. +. +This flag can be changed during operation. +.Pp +"BOF" is short for "Block On Failure" +.Pp +NOTE: This flag should be set on all BULK and INTERRUPT USB transfers +which use an endpoint that can be shared between userland and kernel. +. +. +.It proxy_buffer +Setting this flag will cause that the total buffer size will be +rounded up to the nearest atomic hardware transfer size. +. +The maximum data length of any USB transfer is always stored in the +"xfer->max_data_length". +. +For control transfers the USB kernel will allocate additional space +for the 8-bytes of SETUP header. +. +These 8-bytes are not counted by the "xfer->max_data_length" +variable. +. +This flag can not be changed during operation. +. +. +.It ext_buffer +Setting this flag will cause that no data buffer will be +allocated. +. +Instead the USB client must supply a data buffer. +. +This flag can not be changed during operation. +. +. +.It manual_status +Setting this flag prevents an USB STATUS stage to be appended to the +end of the USB control transfer. +. +If no control data is transferred this flag must be cleared. +. +Else an error will be returned to the USB callback. +. +This flag is mostly useful for the USB device side. +. +This flag can be changed during operation. +. +. +.It no_pipe_ok +Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This +flag can not be changed during operation. +. +. +.It stall_pipe +.Bl -tag +.It Device Side Mode +Setting this flag will cause STALL pids to be sent to the endpoint +belonging to this transfer before the transfer is started. +. +The transfer is started at the moment the host issues a clear-stall +command on the STALL'ed endpoint. +. +This flag can be changed during operation. +.It Host Side Mode +Setting this flag will cause a clear-stall control request to be +executed on the endpoint before the USB transfer is started. +.El .Pp -USB devices have at least one configuration descriptor. -The -.Fa bNumConfigurations -field of the device descriptor specifies the number of configuration -descriptors that a device supports. -The -.Fn usbd_get_config_desc -function retrieves a particular configuration descriptor from the device -and the -.Fn usbd_get_config_desc_full -function retrieves a full -.Fa wTotalLength -length configuration descriptor, which includes all related interface -and endpoint descriptors. -Only one configuration may be active at a time. -The -.Fn usbd_set_config_index -function activates a specified configuration. -The configuration descriptor structure is defined in -.In dev/usb/usb.h -as follows: -.Bd -literal -typedef struct { - uByte bLength; - uByte bDescriptorType; - uWord wTotalLength; - uByte bNumInterface; - uByte bConfigurationValue; - uByte iConfiguration; - uByte bmAttributes; -#define UC_BUS_POWERED 0x80 -#define UC_SELF_POWERED 0x40 -#define UC_REMOTE_WAKEUP 0x20 - uByte bMaxPower; /* max current in 2 mA units */ -#define UC_POWER_FACTOR 2 -} UPACKED usb_config_descriptor_t; -#define USB_CONFIG_DESCRIPTOR_SIZE 9 -.Ed +If this flag is changed outside the USB callback function you have to +use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()" +functions! This flag is automatically cleared after that the stall or +clear stall has been executed. +. +.El .Pp -Each device configuration provides one or more interfaces. -The -.Fa bNumInterface -field of the configuration descriptor specifies the number of -interfaces associated with a device configuration. -Interfaces are described by an interface descriptor, which is defined in -.In dev/usb/usb.h -as follows: -.Bd -literal -typedef struct { - uByte bLength; - uByte bDescriptorType; - uByte bInterfaceNumber; - uByte bAlternateSetting; - uByte bNumEndpoints; - uByte bInterfaceClass; - uByte bInterfaceSubClass; - uByte bInterfaceProtocol; - uByte iInterface; -} UPACKED usb_interface_descriptor_t; -#define USB_INTERFACE_DESCRIPTOR_SIZE 9 -.Ed +.Fa bufsize +field sets the total buffer size in bytes. +. +If this field is zero, "wMaxPacketSize" will be used, multiplied by +the "frames" field if the transfer type is ISOCHRONOUS. +. +This is useful for setting up interrupt pipes. +. +This field is mandatory. .Pp -Configurations may also have alternate interfaces with the same -.Fa bInterfaceNumber -but different -.Fa bAlternateSetting -values. -These alternate interface settings may be selected by passing a -non-zero -.Fa altidx -parameter to -.Fn usbd_set_interface . +NOTE: For control transfers "bufsize" includes the length of the +request structure. +. .Pp -Interfaces have zero or more endpoints, and each endpoint has an -endpoint descriptor. -Note that endpoint zero, which is always present, does not have an -endpoint descriptor, and it is never included in the -.Fa bNumEndpoints -count of endpoints. -The endpoint descriptor is defined in -.In dev/usb/usb.h -as follows: -.Bd -literal -typedef struct { - uByte bLength; - uByte bDescriptorType; - uByte bEndpointAddress; -#define UE_GET_DIR(a) ((a) & 0x80) -#define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7)) -#define UE_DIR_IN 0x80 -#define UE_DIR_OUT 0x00 -#define UE_ADDR 0x0f -#define UE_GET_ADDR(a) ((a) & UE_ADDR) - uByte bmAttributes; -#define UE_XFERTYPE 0x03 -#define UE_CONTROL 0x00 -#define UE_ISOCHRONOUS 0x01 -#define UE_BULK 0x02 -#define UE_INTERRUPT 0x03 -#define UE_GET_XFERTYPE(a) ((a) & UE_XFERTYPE) -#define UE_ISO_TYPE 0x0c -#define UE_ISO_ASYNC 0x04 -#define UE_ISO_ADAPT 0x08 -#define UE_ISO_SYNC 0x0c -#define UE_GET_ISO_TYPE(a) ((a) & UE_ISO_TYPE) - uWord wMaxPacketSize; - uByte bInterval; -} UPACKED usb_endpoint_descriptor_t; -#define USB_ENDPOINT_DESCRIPTOR_SIZE 7 -.Ed -.Sh RETURN VALUES -Many functions return a -.Vt usbd_status -type to indicate the outcome of the operation. -If the operation completed successfully then -.Dv USBD_NORMAL_COMPLETION -is returned. -Operations that have been started but not yet completed will return -.Dv USBD_IN_PROGRESS . -Other errors usually indicate a problem. -Error codes can be converted to strings using -.Fn usbd_errstr . -.Sh ERRORS -.Bl -tag -width ".Er USBD_PENDING_REQUESTS" -.It Bq Er USBD_PENDING_REQUESTS -A pipe could not be closed because there are active requests. -.It Bq Er USBD_NOT_STARTED -The transfer has not yet been started. -.It Bq Er USBD_INVAL -An invalid value was supplied. -.It Bq Er USBD_NOMEM -An attempt to allocate memory failed. -.It Bq Er USBD_CANCELLED -The transfer was aborted. -.It Bq Er USBD_BAD_ADDRESS -The specified endpoint address was not found. -.It Bq Er USBD_IN_USE -The endpoint is already in use, or the configuration cannot be changed -because some of its endpoints are in use. -.It Bq Er USBD_NO_ADDR -No free USB devices addresses were found to assign to the device. -.It Bq Er USBD_SET_ADDR_FAILED -The device address could not be set. -.It Bq Er USBD_NO_POWER -Insufficient power was available for the device. -.It Bq Er USBD_TOO_DEEP -Too many levels of chained hubs were found. -.It Bq Er USBD_IOERROR -There was an error communicating with the device. -.It Bq Er USBD_NOT_CONFIGURED -An operation that requires an active configuration was attempted while -the device was in an unconfigured state. -.It Bq Er USBD_TIMEOUT -A transfer timed out. -.It Bq Er USBD_SHORT_XFER -A transfer that disallowed short data lengths completed with less than -the requested length transferred. -.It Bq Er USBD_STALLED -A transfer failed because the pipe is stalled. -.It Bq Er USBD_INTERRUPTED -An interruptible operation caught a signal. -.El +.Fa callback +pointer sets the USB callback. This field is mandatory. +. +. +.Sh USB LINUX COMPAT LAYER +The +.Nm usb +module supports the Linux USB API. +. +. .Sh SEE ALSO -.Xr usb 4 +.Xr libusb 3 , +.Xr usb 4 , +.Xr usbconfig 8 +.Sh STANDARDS +The +.Nm usb +module complies with the USB 2.0 standard. .Sh HISTORY -The USB driver interface first appeared in -.Fx 3.0 . -.Sh AUTHORS -The USB driver was written by -.An Lennart Augustsson -for the -.Nx -project. -.Pp -.An -nosplit -This manual page was written by -.An Ian Dowse Aq iedowse@FreeBSD.org . +The +.Nm usb +module has been inspired by the NetBSD USB stack initially written by +Lennart Augustsson. The +.Nm usb +module was written by +.An Hans Petter Selasky Aq hselasky@freebsd.org . |
