[src/trunk]: src/share/man/man9 gives pipes and transfers their own .Sh section.

[mrg <mrg%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/84f13ef443c6
branches:  trunk
changeset: 779559:84f13ef443c6
user:      mrg <mrg%NetBSD.org@localhost>
date:      Sat Jun 02 23:39:03 2012 +0000

description:
gives pipes and transfers their own .Sh section.

diffstat:

 share/man/man9/usbdi.9 |  353 ++++++++++++++++++++++++------------------------
 1 files changed, 180 insertions(+), 173 deletions(-)

diffs (truncated from 375 to 300 lines):

diff -r a3697cbec8de -r 84f13ef443c6 share/man/man9/usbdi.9
--- a/share/man/man9/usbdi.9    Sat Jun 02 23:33:16 2012 +0000
+++ b/share/man/man9/usbdi.9    Sat Jun 02 23:39:03 2012 +0000
@@ -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,179 +292,12 @@
 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
-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
-Transfers are allocated and deallocated with
-.Fn usbd_alloc_xfer
+See the
+.Sx TRANSFERS
 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.
+.Sx PIPES
+sections for more details.
+
 .Pp
 There are a number of functions to obtain a handle, descriptor
 of resource count:
@@ -671,6 +504,180 @@
 .\" .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