Date: Tue, 17 Feb 2009 19:21:11 GMT From: Hans Petter Selasky <hselasky@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 157855 for review Message-ID: <200902171921.n1HJLBJw096839@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=157855 Change 157855 by hselasky@hselasky_laptop001 on 2009/02/17 19:20:39 USB documentation: Update. Affected files ... .. //depot/projects/usb/src/share/man/man4/usb2_core.4#6 edit .. //depot/projects/usb/src/sys/dev/usb2/core/README.TXT#8 edit Differences ... ==== //depot/projects/usb/src/share/man/man4/usb2_core.4#6 (text+ko) ==== @@ -23,7 +23,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd September 20, 2008 +.Dd February 17, 2009 .Dt USB2_CORE 4 .Os . @@ -459,6 +459,11 @@ 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 ==== //depot/projects/usb/src/sys/dev/usb2/core/README.TXT#8 (text+ko) ==== @@ -1,411 +1,6 @@ $FreeBSD: src/sys/dev/usb2/core/README.TXT,v 1.1 2008/11/04 02:31:03 alfred Exp $ -DESCRIPTION OF THE NEW USB API - -The new USB 2.0 API consists of 5 functions. All transfer types are -managed using these functions. There is no longer need for separate -functions to setup INTERRUPT- and ISOCHRONOUS- transfers. - -+--------------------------------------------------------------+ -| | -| "usb2_transfer_setup" - This function will allocate all | -| necessary DMA memory and might | -| sleep! | -| | -| "usb2_transfer_unsetup" - This function will stop the USB | -| transfer, if it is currently | -| active, release all DMA | -| memory and might sleep! | -| | -| "usb2_transfer_start" - This function will start an USB | -| transfer, if not already started.| -| This function is always | -| non-blocking. ** | -| | -| "usb2_transfer_stop" - This function will stop an USB | -| transfer, if not already stopped.| -| The callback function will be | -| called before this function | -| returns. This function is always | -| non-blocking. ** | -| | -| "usb2_transfer_drain" - This function will stop an USB | -| transfer, if not already stopped | -| and wait for any additional | -| DMA load 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. | -| | -| ** These functions must be called with the private driver's | -| lock locked. | -| | -| NOTE: These USB API functions are NULL safe, with regard | -| to the USB transfer structure pointer. | -+--------------------------------------------------------------+ - -Reference: /sys/dev/usb2/core/usb2_transfer.c - -/* - * A simple USB callback state-machine: - * - * +->-----------------------+ - * | | - * +-<-+-------[tr_setup]--------+-<-+-<-[start/restart] - * | | - * | | - * | | - * +------>-[tr_transferred]---------+ - * | | - * +--------->-[tr_error]------------+ - */ - -void -usb2_default_callback(struct usb2_xfer *xfer) -{ - /* - * NOTE: it is not allowed to return - * before "USB_CHECK_STATUS()", - * even if the system is tearing down! - */ - 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); - return; - - case USB_ST_TRANSFERRED: - /* - * Read data from xfer->frbuffers[], if any. - * "xfer->frlengths[]" should now have been - * updated to the actual length. - */ - return; - - default: /* Error */ - /* print error message and clear stall for example */ - return; - } -} - -=== Notes for 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. - -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: frbuffer[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); - - -=== General USB transfer notes === - - 1) Something that one should be aware of is that all USB callbacks support -recursation. That means one can start/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. - - 2) After that the "usb2_start_hardware()" function has been called in -the callback one can always depend on that "tr_error" or "tr_transferred" -will get jumped afterwards. Always! - - 3) Sleeping functions can only be called from the attach routine of the -driver. Else one should not use sleeping functions unless one has to. It is -very difficult with sleep, because one has to think that the device might have -detached when the thread returns from sleep. - - 4) Polling. - - use_polling - This flag can be used with any callback and will cause the - "usb2_transfer_start()" function to wait using "DELAY()", - without exiting any mutexes, until the transfer is finished or - has timed out. This flag can be changed during operation. - - NOTE: If polling is used the "timeout" field should be non-zero! - NOTE: USB_ERR_CANCELLED is returned in case of timeout - instead of USB_ERR_TIMEOUT! - - - -USB device driver examples: - -/sys/dev/usb2/ethernet/if_axe.c -/sys/dev/usb2/ethernet/if_aue.c - -QUICK REFERENCE -=============== - - -/*------------------------------------------------------------------------* - * usb2_error_t - * usb2_transfer_setup(udev, ifaces, pxfer, setup_start, - * n_setup, priv_sc, priv_mtx) - *------------------------------------------------------------------------*/ - -- "udev" is a pointer to "struct usb2_device". - -- "ifaces" array of interface index numbers to use. See "if_index". - -- "pxfer" is a pointer to an array of USB transfer pointers that are - initialized to NULL, and then pointed to allocated USB transfers. - -- "setup_start" is a pointer to an array of USB config structures. - -- "n_setup" is a number telling the USB system how many USB transfers - should be setup. - -- "priv_sc" is the private softc pointer, which will be used to - initialize "xfer->priv_sc". - -- "priv_mtx" is the private mutex protecting the transfer structure and - the softc. This pointer is used to initialize "xfer->priv_mtx". - -/*------------------------------------------------------------------------* - * void - * usb2_transfer_unsetup(pxfer, n_setup) - *------------------------------------------------------------------------*/ - -- "pxfer" is a pointer to an array of USB transfer pointers, that may - be NULL, that should be freed by the USB system. - -- "n_setup" is a number telling the USB system how many USB transfers - should be unsetup - -NOTE: This function can sleep, waiting for active mutexes to become unlocked! -NOTE: It is not allowed to call "usb2_transfer_unsetup" from the callback - of a USB transfer. - -/*------------------------------------------------------------------------* - * void - * usb2_transfer_start(xfer) - *------------------------------------------------------------------------*/ - -- "xfer" is pointer to a USB transfer that should be started - -NOTE: this function must be called with "priv_mtx" locked - -/*------------------------------------------------------------------------* - * void - * usb2_transfer_stop(xfer) - *------------------------------------------------------------------------*/ - -- "xfer" is a pointer to a USB transfer that should be stopped - -NOTE: this function must be called with "priv_mtx" locked - -NOTE: if the transfer was in progress, the callback will called with - "xfer->error=USB_ERR_CANCELLED", before this function returns - -/*------------------------------------------------------------------------* - * struct usb2_config { - * type, endpoint, direction, interval, timeout, frames, index - * flags, bufsize, callback - * }; - *------------------------------------------------------------------------*/ - -- The "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. - -- The "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. - -- The "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 ORed 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. - -- The "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: - - UE_INTERRUPT) - "0" use the default interrupt interval based on endpoint descriptor. - "Else" use the given value for polling rate. - - UE_ISOCHRONOUS) - "0" use default. - "Else" the value is ignored. - - UE_BULK) - 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. - NOTE: The transfer timeout, if any, is started after that - the pre-delay has elapsed! - -- The "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. - -- The "frames" field sets the maximum number of frames. If zero is - specified it will yield the following results: - - UE_BULK) - UE_INTERRUPT) - xfer->nframes = 1; - - UE_CONTROL) - xfer->nframes = 2; - - UE_ISOCHRONOUS) - Not allowed. Will cause an error. - -- The "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. - -- The "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. - -- The "flags" field has type "struct usb2_xfer_flags" and allows one - to set initial flags an USB transfer. Valid flags are: - - 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. - - 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. - - 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: - - 1) The failing USB transfer is stopped using "usb2_transfer_stop()". - 2) The failing USB transfer performs a successful transfer. - - 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. - - "BOF" is short for "Block On Failure" - - 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. - - 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. - - 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. - - 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. - - no_pipe_ok - Setting this flag causes the USB_ERR_NO_PIPE error to be - ignored. This flag can not be changed during operation. - - stall_pipe - 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. This flag does only have effect - in USB device side mode except for control endpoints. This - flag is cleared when the stall command has been executed. This - flag can only be changed outside the callback function by - using the functions "usb2_transfer_set_stall()" and - "usb2_transfer_clear_stall()" ! - -- The "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. - - NOTE: For control transfers "bufsize" includes - the length of the request structure. - -- The "callback" pointer sets the USB callback. This field is mandatory. - -MUTEX NOTE: -=========== - -When you create a mutex using "mtx_init()", don't forget to call -"mtx_destroy()" at detach, else you can get "freed memory accessed" -panics. +Please see "man usb2_core" or "src/share/man/man4/usb2_core.4". --HPS
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200902171921.n1HJLBJw096839>