Subject: [PATCH] Man pages: usbd_open_pipe(9), usbd_close_pipe(9)
From: attila <[email-masked]>
To: [email-masked]
Date: Sat, 02 May 2015 08:44:11 CDT

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-masked] | 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-masked]>
+.\"
+.\" 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-masked]>
+.\"
+.\" 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 ,