Module Name: src
Committed By: mrg
Date: Sat Jun 2 23:39:03 UTC 2012
Modified Files:
src/share/man/man9: usbdi.9
Log Message:
gives pipes and transfers their own .Sh section.
To generate a diff of this commit:
cvs rdiff -u -r1.18 -r1.19 src/share/man/man9/usbdi.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/usbdi.9
diff -u src/share/man/man9/usbdi.9:1.18 src/share/man/man9/usbdi.9:1.19
--- src/share/man/man9/usbdi.9:1.18 Sat Jun 2 23:33:16 2012
+++ src/share/man/man9/usbdi.9 Sat Jun 2 23:39:03 2012
@@ -1,4 +1,4 @@
-.\" $NetBSD: usbdi.9,v 1.18 2012/06/02 23:33:16 mrg Exp $
+.\" $NetBSD: usbdi.9,v 1.19 2012/06/02 23:39:03 mrg Exp $
.\"
.\" Copyright (c) 2012 Matthew R. Green
.\" All rights reserved.
@@ -292,180 +292,13 @@ A pipe is a logical connection to a USB
It is described by the
.Va usbd_pipe_handle
cookie.
-.Pp
-Pipes are created and destroyed by using the
-.Fn usbd_open_pipe ,
-.Fn usbd_open_pipe_intr
-and
-.Fn usbd_close_pipe
-functions.
-The open functions take the interface handle
-.Fa iface ,
-the
-.Fa address
-of this pipe and
-.Fa flags
-for this pipe which currently may be 0 or
-.Dv USBD_EXCLUSIVE_USE ,
-to enable exclusive access to this interface and address.
-The
-.Fn usbd_open_pipe_intr
-takes additional arguments
-.Fa priv
-to set the default private handle.
-.Fa buffer
+See the
+.Sx TRANSFERS
and
-.Fa len
-to describe the buffer to be used,
-.Fa callback
-for the function to call at interrupt time, and finally the
-.Fa interval
-for interrupts to be delivered in milliseconds.
-The
-.Fa interval
-may be set to
-.Dv USBD_DEFAULT_INTERVAL
-use the default interval, specified by the ep. description.
-It is common to have more than one pipe per device.
+.Sx PIPES
+sections for more details.
.Pp
-Transfers are allocated and deallocated with
-.Fn usbd_alloc_xfer
-and
-.Fn usbd_free_xfer ,
-respectively, and are associated with a pipe at their creation time.
-.Pp
-The data describing the transfer is filled by either
-.Fn usbd_setup_default_xfer
-for control pipe transfers, by
-.Fn usbd_setup_xfer
-for bulk and interrupt transfers, and by
-.Fn usbd_setup_isoc_xfer
-for isochronous transfers.
-Private data may be passed between setup and completion or status
-calls using the
-.Ft usbd_private_handle priv
-argument, which must be an integral type.
-.Pp
-Arguments to the setup functions include the newly allocated
-.Fa xfer ,
-the
-.Fa pipe
-to associate this transfer with,
-the private data
-.Fa priv ,
-the
-.Fa timeout
-in milliseconds,
-for control, bulk and interrupt transfers
-.Fa buffer
-the data to transfer and its
-.Fa length
-and for isochronous transfers the the frame length
-.Fa frlengths
-and number of frames
-.Fa nframes ,
-and for default transfers a usb request structure
-.Fa req
-must be presented (see below.)
-.Pp
-The transfer specific
-.Fa flags
-that can be set are:
-.Bl -tag -width 10n
-.It Dv USBD_NO_COPY
-Do not copy data to DMA buffer
-.It Dv USBD_SYNCHRONOUS
-Wait for completion
-.It Dv USBD_SYNCHRONOUS_SIG
-When waiting for completion, allow signals to trigger wake up.
-.It Dv USBD_SHORT_XFER_OK
-Short reads are not an error
-.It Dv USBD_FORCE_SHORT_XFER
-Force last short packet on write
-.El
-.Pp
-Upon completion the
-.Fa callback
-function is called, which takes the completed
-.Fa xfer ,
-the private data
-.Fa priv
-originally assocated with this transfer, and
-.Fa status
-the status of this transfer.
-.Pp
-Transfers are initiated by calling
-.Fn usbd_transfer ,
-and their results made be later obtained by calling
-.Fa usbd_get_xfer_status ,
-which fills in the private data
-.Fa priv ,
-original buffer location
-.Fa buffer ,
-the length
-.Fa length ,
-and the
-.Fa status
-of this request.
-.Pp
-The
-.Fn usbd_bulk_transfer
-and
-.Fn usbd_intr_transfer
-functions are used to transfer data in either an interrupt or
-bulk fashion, and are front-ends to the
-.Fn usbd_setup_xfer ,
-.Fn usbd_transfer
-and
-.Fn usbd_get_xfer_status ,
-as well as associated error handling.
-The
-.Fa lbl
-option is deprecated and will be removed.
-The
-.Fn usbd_sync_transfer
-is identical to
-.Fn usbd_transfer
-with the
-.Dv USBD_SYNCHRONOUS
-flag set.
-The
-.Fn usbd_sync_transfer_sig
-is identical to
-.Fn usbd_transfer
-with the
-.Dv USBD_SYNCHRONOUS
-and
-.Dv USBD_SYNCHRONOUS_SIG
-flags set.
-.Pp
-Transfers are aborted via this pipe with
-.Fn usbd_abort_pipe
-and
-.Fn usbd_abort_default_pipe .
-.Pp
-The
-.Fn usbd_clear_endpoint_stall
-and
-.Fn usbd_clear_endpoint_stall_async
-functions are used to clear endpoint halt in either a synchronous
-or asynchronous fashion.
-To clear the toggle state of an endpoint the
-.Fn usbd_clear_endpoint_toggle
-function should be used.
-.Pp
-A request is described by a
-.Va usb_device_request_t
-which must be initialised as necessary before calling either
-.Fn usbd_do_request
-or
-.Fn usbd_do_request_flags
-to submit the request.
-See the
-.Sx INITIALISING USB REQUESTS
-section for more details.
-.Pp
There are a number of functions to obtain a handle, descriptor
of resource count:
.Bl -tag -width 10n
@@ -671,6 +504,180 @@ macro can be used to match any USB produ
.\" .Ft void
.\" .Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv"
.\"
+.Pp
+.Sh PIPES
+Pipes are created and destroyed by using the
+.Fn usbd_open_pipe ,
+.Fn usbd_open_pipe_intr
+and
+.Fn usbd_close_pipe
+functions.
+The open functions take the interface handle
+.Fa iface ,
+the
+.Fa address
+of this pipe and
+.Fa flags
+for this pipe which currently may be 0 or
+.Dv USBD_EXCLUSIVE_USE ,
+to enable exclusive access to this interface and address.
+The
+.Fn usbd_open_pipe_intr
+takes additional arguments
+.Fa priv
+to set the default private handle.
+.Fa buffer
+and
+.Fa len
+to describe the buffer to be used,
+.Fa callback
+for the function to call at interrupt time, and finally the
+.Fa interval
+for interrupts to be delivered in milliseconds.
+The
+.Fa interval
+may be set to
+.Dv USBD_DEFAULT_INTERVAL
+use the default interval, specified by the ep. description.
+It is common to have more than one pipe per device.
+.Pp
+.Sh TRANSFERS
+Transfers are allocated and deallocated with
+.Fn usbd_alloc_xfer
+and
+.Fn usbd_free_xfer ,
+respectively, and are associated with a pipe at their creation time.
+.Pp
+The data describing the transfer is filled by either
+.Fn usbd_setup_default_xfer
+for control pipe transfers, by
+.Fn usbd_setup_xfer
+for bulk and interrupt transfers, and by
+.Fn usbd_setup_isoc_xfer
+for isochronous transfers.
+Private data may be passed between setup and completion or status
+calls using the
+.Ft usbd_private_handle priv
+argument, which must be an integral type.
+.Pp
+Arguments to the setup functions include the newly allocated
+.Fa xfer ,
+the
+.Fa pipe
+to associate this transfer with,
+the private data
+.Fa priv ,
+the
+.Fa timeout
+in milliseconds,
+for control, bulk and interrupt transfers
+.Fa buffer
+the data to transfer and its
+.Fa length
+and for isochronous transfers the the frame length
+.Fa frlengths
+and number of frames
+.Fa nframes ,
+and for default transfers a USB request structure
+.Fa req
+must be presented.
+See the
+.Sx INITIALISING USB REQUESTS
+section for more details on USB requests.
+.Pp
+The transfer specific
+.Fa flags
+that can be set are:
+.Bl -tag -width 10n
+.It Dv USBD_NO_COPY
+Do not copy data to DMA buffer
+.It Dv USBD_SYNCHRONOUS
+Wait for completion
+.It Dv USBD_SYNCHRONOUS_SIG
+When waiting for completion, allow signals to trigger wake up.
+.It Dv USBD_SHORT_XFER_OK
+Short reads are not an error
+.It Dv USBD_FORCE_SHORT_XFER
+Force last short packet on write
+.El
+.Pp
+Upon completion the
+.Fa callback
+function is called, which takes the completed
+.Fa xfer ,
+the private data
+.Fa priv
+originally assocated with this transfer, and
+.Fa status
+the status of this transfer.
+.Pp
+Transfers are initiated by calling
+.Fn usbd_transfer ,
+and their results made be later obtained by calling
+.Fa usbd_get_xfer_status ,
+which fills in the private data
+.Fa priv ,
+original buffer location
+.Fa buffer ,
+the length
+.Fa length ,
+and the
+.Fa status
+of this request.
+.Pp
+The
+.Fn usbd_bulk_transfer
+and
+.Fn usbd_intr_transfer
+functions are used to transfer data in either an interrupt or
+bulk fashion, and are front-ends to the
+.Fn usbd_setup_xfer ,
+.Fn usbd_transfer
+and
+.Fn usbd_get_xfer_status ,
+as well as associated error handling.
+The
+.Fa lbl
+option is deprecated and will be removed.
+The
+.Fn usbd_sync_transfer
+is identical to
+.Fn usbd_transfer
+with the
+.Dv USBD_SYNCHRONOUS
+flag set.
+The
+.Fn usbd_sync_transfer_sig
+is identical to
+.Fn usbd_transfer
+with the
+.Dv USBD_SYNCHRONOUS
+and
+.Dv USBD_SYNCHRONOUS_SIG
+flags set.
+.Pp
+Transfers are aborted via this pipe with
+.Fn usbd_abort_pipe
+and
+.Fn usbd_abort_default_pipe .
+.Pp
+The
+.Fn usbd_clear_endpoint_stall
+and
+.Fn usbd_clear_endpoint_stall_async
+functions are used to clear endpoint halt in either a synchronous
+or asynchronous fashion.
+To clear the toggle state of an endpoint the
+.Fn usbd_clear_endpoint_toggle
+function should be used.
+.Pp
+A request is described by a
+.Va usb_device_request_t
+which must be initialised as necessary before calling either
+.Fn usbd_do_request
+or
+.Fn usbd_do_request_flags
+to submit the request.
.Sh INITIALISING USB REQUESTS
There are 5 members of a
.Va usb_device_request_t
