mirror of https://github.com/djcb/mu.git
320 lines
9.7 KiB
Plaintext
320 lines
9.7 KiB
Plaintext
From: attila <attila@stalphonsos.com>
|
|
Content-Transfer-Encoding: 7bit
|
|
Subject: [PATCH] Man pages: usbd_open_pipe(9), usbd_close_pipe(9)
|
|
MIME-Version: 1.0
|
|
Content-Type: multipart/mixed; boundary="=-=-="
|
|
To: tech@openbsd.org
|
|
Sender: attila <attila@stalphonsos.com>
|
|
X-Mailer: flail 1.0.2 - http://flail.org
|
|
Date: Sat, 02 May 2015 08:44:11 CDT
|
|
Return-Path: <attila@stalphonsos.com>
|
|
0:
|
|
|
|
--=-=-=
|
|
Content-Type: text/plain
|
|
|
|
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...
|
|
--
|
|
attila@stalphonsos.com | http://trac.haqistan.net/~attila
|
|
keyid E6CC1EDB | 4D91 1B98 A210 1D71 2A0E AC29 9677 D0A6 E6CC 1EDB
|
|
|
|
|
|
--=-=-=
|
|
Content-Type: text/x-patch
|
|
Content-Disposition: inline; filename=usbd_man_pages.diff
|
|
Content-Description: man pages: usbd_open_pipe(9), usbd_close_pipe(9)
|
|
|
|
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 <attila@stalphonsos.com>
|
|
+.\"
|
|
+.\" 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 <attila@stalphonsos.com>
|
|
+.\"
|
|
+.\" 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 ,
|
|
|
|
--=-=-=--
|