From 110e22f68b474e41829db548700db758cc81812e Mon Sep 17 00:00:00 2001 From: mpi Date: Mon, 4 May 2015 10:12:34 +0000 Subject: [PATCH] Document usbd_open_pipe(9) and friends, from Sean Levy with some tweaks. --- share/man/man9/Makefile | 6 +- share/man/man9/usbd_close_pipe.9 | 48 ++++++++++++ share/man/man9/usbd_open_pipe.9 | 130 +++++++++++++++++++++++++++++++ share/man/man9/usbd_transfer.9 | 13 +++- 4 files changed, 191 insertions(+), 6 deletions(-) create mode 100644 share/man/man9/usbd_close_pipe.9 create mode 100644 share/man/man9/usbd_open_pipe.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 74d7cdd5a2a..b8cfb599ad0 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.230 2015/02/10 21:56:08 miod Exp $ +# $OpenBSD: Makefile,v 1.231 2015/05/04 10:12:34 mpi Exp $ # $NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -31,7 +31,7 @@ MAN= aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \ 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_close_pipe.9 usbd_open_pipe.9 usbd_transfer.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 \ @@ -393,6 +393,8 @@ MLINKS+=tsleep.9 wakeup.9 tsleep.9 wakeup_n.9 tsleep.9 wakeup_one.9 \ tsleep.9 msleep.9 MLINKS+=tvtohz.9 tstohz.9 MLINKS+=uiomove.9 uio.9 uiomove.9 uiomovei.9 +MLINKS+=usbd_close_pipe.9 usbd_abort_pipe.9 +MLINKS+=usbd_open_pipe.9 usbd_open_pipe_intr.9 MLINKS+=usbd_transfer.9 usbd_setup_xfer.9 MLINKS+=uvm.9 uvm_init.9 uvm.9 uvm_init_limits.9 uvm.9 uvm_setpagesize.9 \ uvm.9 uvm_swap_init.9 uvm.9 uvm_map.9 uvm.9 uvm_map_pageable.9 \ diff --git a/share/man/man9/usbd_close_pipe.9 b/share/man/man9/usbd_close_pipe.9 new file mode 100644 index 00000000000..650182d5284 --- /dev/null +++ b/share/man/man9/usbd_close_pipe.9 @@ -0,0 +1,48 @@ +.\" $OpenBSD: usbd_close_pipe.9,v 1.1 2015/05/04 10:12:34 mpi Exp $ +.\" +.\" Copyright (c) 2015 Sean Levy +.\" +.\" 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: May 4 2015 $ +.Dt USBD_CLOSE_PIPE 9 +.Os +.Sh NAME +.Nm usbd_close_pipe , usbd_abort_pipe +.Nd delete 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 +The +.Fn usbd_abort_pipe +function aborts any transfers queued on +.Fa pipe . +.Pp +The +.Fn usbd_close_pipe +function aborts any transfers queued on +.Fa pipe +then deletes it. +.Sh CONTEXT +.Fn usbd_abort_pipe +and +.Fn usbd_close_pipe +can be called during autoconf or from process context. +.Sh SEE ALSO +.Xr usb 4 , +.Xr usbd_open_pipe 9 diff --git a/share/man/man9/usbd_open_pipe.9 b/share/man/man9/usbd_open_pipe.9 new file mode 100644 index 00000000000..6eaac4d7af5 --- /dev/null +++ b/share/man/man9/usbd_open_pipe.9 @@ -0,0 +1,130 @@ +.\" $OpenBSD: usbd_open_pipe.9,v 1.1 2015/05/04 10:12:34 mpi Exp $ +.\" +.\" Copyright (c) 2015 Sean Levy +.\" +.\" 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: May 4 2015 $ +.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" "uint8_t address" "uint8_t flags" "struct usbd_pipe **pipe" +.Ft usbd_status +.Fn usbd_open_pipe_intr "struct usbd_interface *iface" "uint8_t address" "uint8_t flags" "struct usbd_pipe **pipe" "void *priv" "void *buffer" "uint32_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 address of 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 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. +.Sh CONTEXT +.Fn usbd_open_pipe +and +.Fn usbd_open_pipe_intr +can be called during autoconf or from process context. +.Sh SEE ALSO +.Xr usb 4 , +.Xr usbd_close_pipe 9 , +.Xr usbd_transfer 9 diff --git a/share/man/man9/usbd_transfer.9 b/share/man/man9/usbd_transfer.9 index fbbe3f9536d..68f4fd0b030 100644 --- a/share/man/man9/usbd_transfer.9 +++ b/share/man/man9/usbd_transfer.9 @@ -1,4 +1,4 @@ -.\" $OpenBSD: usbd_transfer.9,v 1.5 2014/07/12 16:07:06 mpi Exp $ +.\" $OpenBSD: usbd_transfer.9,v 1.6 2015/05/04 10:12:34 mpi Exp $ .\" .\" Copyright (c) 2013 Martin Pieuchot .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 12 2014 $ +.Dd $Mdocdate: May 4 2015 $ .Dt USBD_TRANSFER 9 .Os .Sh NAME @@ -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 @@ -108,4 +111,6 @@ has not been passed via .Xr ohci 4 , .Xr uhci 4 , .Xr usb 4 , -.Xr tsleep 9 +.Xr tsleep 9 , +.Xr usbd_open_pipe 9 , +.Xr usbd_open_pipe_intr 9 -- 2.20.1