Hi tech@, This patch adds man pages for usbd_open_pipe, usbd_open_pipe_intr, usbd_close_pipe and usbd_abort_pipe, done as two files: usbd_open_pipe.9 and usbd_close_pipe.9. It also adds these two new .9 files to the appropriate Makefile and tweaks usbd_transfer(9) to refer to usbd_open_pipe(9).
Comments, feedback most welcome. Pax, -A P.S. I f'ing love mandoc. Just sayin... -- [email protected] | http://trac.haqistan.net/~attila keyid E6CC1EDB | 4D91 1B98 A210 1D71 2A0E AC29 9677 D0A6 E6CC 1EDB
Index: Makefile =================================================================== RCS file: /cvs/src/share/man/man9/Makefile,v retrieving revision 1.230 diff -u -p -r1.230 Makefile --- Makefile 10 Feb 2015 21:56:08 -0000 1.230 +++ Makefile 2 May 2015 00:07:16 -0000 @@ -31,7 +31,7 @@ MAN= aml_evalnode.9 atomic_add_int.9 ato tsleep.9 spl.9 startuphook_establish.9 \ socreate.9 sosplice.9 style.9 syscall.9 systrace.9 sysctl_int.9 \ task_add.9 tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 \ - usbd_transfer.9 \ + usbd_transfer.9 usbd_open_pipe.9 usbd_close_pipe.9 \ vfs.9 vfs_busy.9 \ vfs_cache.9 vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \ vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vnode.9 vnsubr.9 \ Index: usbd_close_pipe.9 =================================================================== RCS file: usbd_close_pipe.9 diff -N usbd_close_pipe.9 --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ usbd_close_pipe.9 2 May 2015 00:07:16 -0000 @@ -0,0 +1,59 @@ +.\" $OpenBSD$ +.\" +.\" Copyright (c) 2015 Sean Levy <[email protected]> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate$ +.Dt USBD_CLOSE_PIPE 9 +.Os +.Sh NAME +.Nm usbd_close_pipe , usbd_abort_pipe +.Nd close or abort transfers on a USB pipe +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.Ft usbd_status +.Fn usbd_close_pipe "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_abort_pipe "struct usbd_pipe *pipe" +.Sh DESCRIPTION +A pipe is a logical connection between the host and an endpoint +on a USB device, created by one of +.Xr usbd_open_pipe 9 +or +.Xr usbd_open_pipe_intr 9 . +.Pp +The +.Fn usbd_abort_pipe +function aborts any transfers queued on the pipe and ensures it is quiescent +before returning. +.Pp +The +.Fn usbd_close_pipe +function first calls +.Fn usbd_abort_pipe , +then removes the pipe from the relevant USB interface's list of pipes +and cleans up any memory associated with the pipe, including any +implicit transfer created by +.Xr usbd_open_pipe_intr 9 . +.Sh CONTEXT +.Fn usbd_abort_pipe +and +.Fn usbd_close_pipe +can be called during autoconf, from process context or from interrupt +context. +.Sh SEE ALSO +.Xr usbd_open_pipe 9 , +.Xr usb 4 , +.Xr intro 4 Index: usbd_open_pipe.9 =================================================================== RCS file: usbd_open_pipe.9 diff -N usbd_open_pipe.9 --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ usbd_open_pipe.9 2 May 2015 00:07:16 -0000 @@ -0,0 +1,162 @@ +.\" $OpenBSD$ +.\" +.\" Copyright (c) 2015 Sean Levy <[email protected]> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate$ +.Dt USBD_OPEN_PIPE 9 +.Os +.Sh NAME +.Nm usbd_open_pipe , usbd_open_pipe_intr +.Nd create USB pipe +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.Ft usbd_status +.Fn usbd_open_pipe "struct usbd_interface *iface" "u_int8_t address" "u_int8_t flags" "struct usbd_pipe **pipe" +.Ft usbd_status +.Fn usbd_open_pipe_intr "struct usbd_interface *iface" "u_int8_t address" "u_int8_t flags" "struct usbd_pipe **pipe" "void *priv" "void *buffer" "u_int32_t len" "usbd_callback cb" "int ival" +.Sh DESCRIPTION +The +.Fn usbd_open_pipe +and +.Fn usbd_open_pipe_intr +functions create pipes. +A pipe is a logical connection between the host and an endpoint on a +USB device. +USB drivers use pipes to manage transfers to or from a USB +endpoint. +.Pp +The +.Fn usbd_open_pipe +function takes the following arguments: +.Bl -tag -width callback +.It Fa iface +the USB interface for which the pipe is to be created. +.It Fa address +The endpoint in that interface to which the pipe should be connected. +.It Fa flags +A bitmask of flags. Currently there is only one flag bit defined: +.Bl -tag -width xxx -offset indent +.It Dv USBD_EXCLUSIVE_ACCESS +Do not allow other pipes to use this endpoint on this interface +while this pipe exists. +.El +.It Fa pipe +A pointer to where the resulting +.Ql struct usbd_pipe * +should be stored if the call is successful. +.El +.Pp +The +.Fn usbd_open_pipe_intr +takes the following arguments: +.Bl -tag -width callback +.It Fa iface +The USB interface for which the pipe is to be created. +.It Fa address +The endpoint in that interface to which the pipe should be connected. +.It Fa flags +A bitmask of flags. These flags are not interpreted in the same +way as the +.Fa flags +passed to +.Fn usbd_open_pipe . +Instead, +.Fn usbd_open_pipe_intr +implicitly turns on the +.Dv USBD_EXCLUSIVE_ACCESS +bit for the pipe, disallowing multiple interrupt pipes for +the same endpoint. The +.Fa flags +argument in this case is instead passed directly to +.Xr usbd_setup_xfer 9 +as its +.Fa flags +argument, whose interpretation is documented in +its man page. +.It Fa pipe +A pointer to where the resulting +.Ql struct usbd_pipe * +should be stored if the call is successful. +.It Fa priv +A pointer to a private cookie untouched by the USB stack for reuse in +the callback specified by the +.Fa cb +argument. +.It Fa buffer +A pointer to the data buffer for use by the implicit transfer +(see below). +.It Fa len +The length in bytes of +.Fa buffer . +.It Fa cb +A callback invoked every time the interrupt transfer completes. +.It Fa ival +The interval in milliseconds with which the interrupt pipe +should be polled by the USB stack. +.El +.Pp +Pipes created by +.Fn usbd_open_pipe_intr +implicitly have a repeating transfer queued on them which +is run every +.Fa ival +milliseconds. +This implicit transfer is not automatically removed from the list of +transfers maintained by the pipe, unlike normal transfers, and will +continue to be processed every +.Fa ival +milliseconds. +.Pp +These functions return +.Dv USBD_NORMAL_COMPLETION +when they are successful; in both cases +.Ql *pipe +will contain the newly created pipe. +Both functions can return +.Dv USBD_IN_USE +if the interface/address pair already has a pipe associated with it; +in the case of +.Fn usbd_open_pipe +this happens only if +.Dv USBD_EXCLUSIVE_ACCESS +is turned on in +.Fa flags . +For +.Fn usbd_open_pipe_intr +this flag is always assumed, so any attempt to create multiple +pipes to the same interrupt endpoint on the same interface will +return +.Dv USBD_IN_USE. +Both functions can also return +.Dv USBD_NOMEM +if they fail to allocate memory for any reason. +In addition, +.Fn usbd_open_pipe_intr +can return any error code returned by +.Xr usbd_setup_xfer 9 +or +.Xr usbd_transfer 9 . +.Sh CONTEXT +.Fn usbd_open_pipe +and +.Fn usbd_open_pipe_intr +can be called during autoconf, from process context, +or from interrupt context. +.Sh SEE ALSO +.Xr usbd_transfer 9 , +.Xr usbd_close_pipe 9 , +.Xr usb 4 , +.Xr intro 4 Index: usbd_transfer.9 =================================================================== RCS file: /cvs/src/share/man/man9/usbd_transfer.9,v retrieving revision 1.5 diff -u -p -r1.5 usbd_transfer.9 --- usbd_transfer.9 12 Jul 2014 16:07:06 -0000 1.5 +++ usbd_transfer.9 2 May 2015 00:07:16 -0000 @@ -31,7 +31,10 @@ .Fn usbd_transfer "struct usbd_xfer *xfer" .Sh DESCRIPTION These functions provide a controller independent mechanism to perform USB -data transfers. +data transfers. They make use of a pipe created by +.Xr usbd_open_pipe 9 +or +.Xr usbd_open_pipe_intr 9 . .Pp The function .Fn usbd_setup_xfer @@ -104,6 +107,8 @@ if has not been passed via .Fa flags . .Sh SEE ALSO +.Xr usbd_open_pipe 9 , +.Xr usbd_open_pipe_intr 9 , .Xr ehci 4 , .Xr ohci 4 , .Xr uhci 4 ,
