perl: Integrate the mup interface from https://github.com/StAlphonsos/mup
This commit is contained in:
attila
319
perl/t/sample.eml
Normal file
319
perl/t/sample.eml
Normal file
@ -0,0 +1,319 @@
|
||||
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 ,
|
||||
|
||||
--=-=-=--
|
||||
Reference in New Issue
Block a user