On 02/05/15(Sat) 08:44, attila wrote:
> 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.
Thanks, committed with some tweaks :
- These functions cannot be called from interrupt context because they
might sleep.
- I did not return the error values from usbd_open_pipe(9) because they
are almost never checked and useless.
I think we can improve them in-tree, it might be interesting to add more
USB specific information, since people dealing with USB know what
endpoints are but not how to deals with "usbd_pipes".
One more note, I think that our stack does not support shared endpoints,
it would be nice to do an audit, but I think that USBD_EXCLUSIVE_ACCESS
should/is the default.
>
> 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 ,
