Index: head/share/man/man9/socket.9
===================================================================
--- head/share/man/man9/socket.9	(revision 268817)
+++ head/share/man/man9/socket.9	(revision 268818)
@@ -1,636 +1,636 @@
 .\"-
 .\" Copyright (c) 2006 Robert N. M. Watson
 .\" Copyright (c) 2014 Benjamin J. Kaduk
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" $FreeBSD$
 .\"
 .Dd May 26, 2014
 .Dt SOCKET 9
 .Os
 .Sh NAME
 .Nm socket
 .Nd "kernel socket interface"
 .Sh SYNOPSIS
 .In sys/socket.h
 .In sys/socketvar.h
 .Ft void
 .Fn soabort "struct socket *so"
 .Ft int
 .Fn soaccept "struct socket *so" "struct sockaddr **nam"
 .Ft int
 .Fn socheckuid "struct socket *so" "uid_t uid"
 .Ft int
 .Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td"
 .Ft void
 .Fn soclose "struct socket *so"
 .Ft int
 .Fn soconnect "struct socket *so" "struct sockaddr *nam" "struct thread *td"
 .Ft int
 .Fo socreate
 .Fa "int dom" "struct socket **aso" "int type" "int proto"
 .Fa "struct ucred *cred" "struct thread *td"
 .Fc
 .Ft int
 .Fn sodisconnect "struct socket *so"
 .Ft struct  sockaddr *
 .Fn sodupsockaddr "const struct sockaddr *sa" "int mflags"
 .Ft void
 .Fn sofree "struct socket *so"
 .Ft void
 .Fn sohasoutofband "struct socket *so"
 .Ft int
 .Fn solisten "struct socket *so" "int backlog" "struct thread *td"
 .Ft void
 .Fn solisten_proto "struct socket *so" "int backlog"
 .Ft int
 .Fn solisten_proto_check "struct socket *so"
 .Ft struct socket *
 .Fn sonewconn "struct socket *head" "int connstatus"
 .Ft int
 .Fo sopoll
 .Fa "struct socket *so" "int events" "struct ucred *active_cred"
 .Fa "struct thread *td"
 .Fc
 .Ft int
 .Fo sopoll_generic
 .Fa "struct socket *so" "int events" "struct ucred *active_cred"
 .Fa "struct thread *td"
 .Fc
 .Ft int
 .Fo soreceive
 .Fa "struct socket *so" "struct sockaddr **psa" "struct uio *uio"
 .Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp"
 .Fc
 .Ft int
 .Fo soreceive_stream
 .Fa "struct socket *so" "struct sockaddr **paddr"
 .Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp"
 .Fa "int *flagsp"
 .Fc
 .Ft int
 .Fo soreceive_dgram
 .Fa "struct socket *so" "struct sockaddr **paddr"
 .Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp"
 .Fa "int *flagsp"
 .Fc
 .Ft int
 .Fo soreceive_generic
 .Fa "struct socket *so" "struct sockaddr **paddr"
 .Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp"
 .Fa "int *flagsp"
 .Fc
 .Ft int
 .Fn soreserve "struct socket *so" "u_long sndcc" "u_long rcvcc"
 .Ft void
 .Fn sorflush "struct socket *so"
 .Ft int
 .Fo sosend
 .Fa "struct socket *so" "struct sockaddr *addr" "struct uio *uio"
 .Fa "struct mbuf *top" "struct mbuf *control" "int flags" "struct thread *td"
 .Fc
 .Ft int
 .Fo sosend_dgram
 .Fa "struct socket *so" "struct sockaddr *addr"
 .Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control"
 .Fa "int flags" "struct thread *td"
 .Fc
 .Ft int
 .Fo sosend_generic
 .Fa "struct socket *so" "struct sockaddr *addr"
 .Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control"
 .Fa "int flags" "struct thread *td"
 .Fc
 .Ft int
 .Fn soshutdown "struct socket *so" "int how"
 .Ft void
 .Fn sotoxsocket "struct socket *so" "struct xsocket *xso"
 .Ft void
 .Fn soupcall_clear "struct socket *so" "int which"
 .Ft void
 .Fo soupcall_set
 .Fa "struct socket *so" "int which"
 .Fa "int (*func)(struct socket *, void *, int)" "void *arg"
 .Fc
 .Ft void
 .Fn sowakeup "struct socket *so" "struct sockbuf *sb"
 .In sys/sockopt.h
 .Ft int
 .Fn sosetopt "struct socket *so" "struct sockopt *sopt"
 .Ft int
 .Fn sogetopt "struct socket *so" "struct sockopt *sopt"
 .Ft int
 .Fn sooptcopyin "struct sockopt *sopt" "void *buf" "size_t len" "size_t minlen"
 .Ft int
 .Fn sooptcopyout "struct sockopt *sopt" "const void *buf" "size_t len"
 .Sh DESCRIPTION
 The kernel
 .Nm
 programming interface permits in-kernel consumers to interact with
 local and network socket objects in a manner similar to that permitted using
 the
 .Xr socket 2
 user API.
 These interfaces are appropriate for use by distributed file systems and
 other network-aware kernel services.
 While the user API operates on file descriptors, the kernel interfaces
 operate directly on
 .Vt "struct socket"
 pointers.
 Some portions of the kernel API exist only to implement the user API,
 and are not expected to be used by kernel code.
 The portions of the socket API used by socket consumers and
 implementations of network protocols will differ; some routines
 are only useful for protocol implementors.
 .Pp
 Except where otherwise indicated,
 .Nm
 functions may sleep, and are not appropriate for use in an
 .Xr ithread 9
 context or while holding non-sleepable kernel locks.
 .Ss Creating and Destroying Sockets
 A new socket may be created using
 .Fn socreate .
 As with
 .Xr socket 2 ,
 arguments specify the requested domain, type, and protocol via
 .Fa dom , type ,
 and
 .Fa proto .
 The socket is returned via
 .Fa aso
 on success.
 In addition, the credential used to authorize operations associated with the
 socket will be passed via
 .Fa cred
 (and will be cached for the lifetime of the socket), and the thread
 performing the operation via
 .Fa td .
 .Em Warning :
 authorization of the socket creation operation will be performed
 using the thread credential for some protocols (such as raw sockets).
 .Pp
 Sockets may be closed and freed using
 .Fn soclose ,
 which has similar semantics to
 .Xr close 2 .
 .Pp
 In certain circumstances, it is appropriate to destroy a socket without
 waiting for it to disconnect, for which
 .Fn soabort
 is used.
 This is only appropriate for incoming connections which are in a
 partially connected state.
 It must be called on an unreferenced socket, by the thread which
 removed the socket from its listen queue, to prevent races.
 It will call into protocol code, so no socket locks may be held
 over the call.
 The caller of
 .Fn soabort
 is responsible for setting the VNET context.
 The normal path to freeing a socket is
 .Fn sofree ,
 which handles reference counting on the socket.
 It should be called whenever a reference is released, and also whenever
 reference flags are cleared in socket or protocol code.
 Calls to
 .Fn sofree
 should not be made from outside the socket layer; outside callers
 should use
 .Fn soclose
 instead.
 .Ss Connections and Addresses
 The
 .Fn sobind
 function is equivalent to the
 .Xr bind 2
 system call, and binds the socket
 .Fa so
 to the address
 .Fa nam .
 The operation would be authorized using the credential on thread
 .Fa td .
 .Pp
 The
 .Fn soconnect
 function is equivalent to the
 .Xr connect 2
 system call, and initiates a connection on the socket
 .Fa so
 to the address
 .Fa nam .
 The operation will be authorized using the credential on thread
 .Fa td .
 Unlike the user system call,
 .Fn soconnect
 returns immediately; the caller may
 .Xr msleep 9
 on
 .Fa so->so_timeo
 while holding the socket mutex and waiting for the
 .Dv SS_ISCONNECTING
 flag to clear or
 .Fa so->so_error
 to become non-zero.
 If
 .Fn soconnect
 fails, the caller must manually clear the
 .Dv SS_ISCONNECTING
 flag.
 .Pp
 A call to
 .Fn sodisconnect
 disconnects the socket without closing it.
 .Pp
 The
 .Fn soshutdown
 function is equivalent to the
 .Xr shutdown 2
 system call, and causes part or all of a connection on a socket to be closed
 down.
 .Pp
 Sockets are transitioned from non-listening status to listening with
 .Fn solisten .
 .Ss Socket Options
 The
 .Fn sogetopt
 function is equivalent to the
 .Xr getsockopt 2
 system call, and retrieves a socket option on socket
 .Fa so .
 The
 .Fn sosetopt
 function is equivalent to the
 .Xr setsockopt 2
 system call, and sets a socket option on socket
 .Fa so .
 .Pp
 The second argument in both
 .Fn sogetopt
 and
 .Fn sosetopt
 is the
 .Fa sopt
 pointer to a
 .Vt "struct sopt"
 describing the socket option operation.
 The caller-allocated structure must be zeroed, and then have its fields
 initialized to specify socket option operation arguments:
 .Bl -tag -width ".Va sopt_valsize"
 .It Va sopt_dir
 Set to
 .Dv SOPT_SET
 or
 .Dv SOPT_GET
 depending on whether this is a get or set operation.
 .It Va sopt_level
 Specify the level in the network stack the operation is targeted at; for
 example,
 .Dv SOL_SOCKET .
 .It Va sopt_name
 Specify the name of the socket option to set.
 .It Va sopt_val
 Kernel space pointer to the argument value for the socket option.
 .It Va sopt_valsize
 Size of the argument value in bytes.
 .El
 .Ss Socket Upcalls
 In order for the owner of a socket to be notified when the socket
 is ready to send or receive data, an upcall may be registered on
 the socket.
 The upcall is a function that will be called by the socket framework
 when a socket buffer associated with the given socket is ready for
 reading or writing.
 .Fn soupcall_set
 is used to register a socket upcall.
 The function
 .Va func
 is registered, and the pointer
 .Va arg
 will be passed as its second argument when it is called by the framework.
 The possible values for
 .Va which
 are
 .Dv SO_RCV
 and
 .Dv SO_SND ,
 which register upcalls for receive and send events, respectively.
 The upcall function
 .Fn func
 must return either
 .Dv SU_OK
 or
 .Dv SU_ISCONNECTED ,
 depending on whether or not a call to
 .Xr soisconnected
 should be made by the socket framework after the upcall returns.
 The upcall
 .Va func
 cannot call
 .Xr soisconnected
 itself due to lock ordering with the socket buffer lock.
 Only
 .Dv SO_RCV
 upcalls should return
 .Dv SU_ISCONNECTED .
 When a
 .Dv SO_RCV
 upcall returns
 .Dv SU_ISCONNECTED ,
 the upcall will be removed from the socket.
 .Pp
 Upcalls are removed from their socket by
 .Fn soupcall_clear .
 The
 .Va which
 argument again specifies whether the sending or receiving upcall is to
 be cleared, with
 .Dv SO_RCV
 or
 .Dv SO_SND .
 .Ss Socket I/O
 The
 .Fn soreceive
 function is equivalent to the
 .Xr recvmsg 2
 system call, and attempts to receive bytes of data from the socket
 .Fa so ,
 optionally blocking awaiting for data if none is ready to read.
 Data may be retrieved directly to kernel or user memory via the
 .Fa uio
 argument, or as an mbuf chain returned to the caller via
 .Fa mp0 ,
 avoiding a data copy.
 The
 .Fa uio
 must always be
 .Pf non- Dv NULL .
 If
 .Fa mp0
 is
 .Pf non- Dv NULL ,
 only the
-.Pf uio_resid
+.Fa uio_resid
 of
 .Fa uio
 is used.
 The caller may optionally retrieve a socket address on a protocol with the
 .Dv PR_ADDR
 capability by providing storage via
 .Pf non- Dv NULL
 .Fa psa
 argument.
 The caller may optionally retrieve control data mbufs via a
 .Pf non- Dv NULL
 .Fa controlp
 argument.
 Optional flags may be passed to
 .Fn soreceive
 via a
 .Pf non- Dv NULL
 .Fa flagsp
 argument, and use the same flag name space as the
 .Xr recvmsg 2
 system call.
 .Pp
 The
 .Fn sosend
 function is equivalent to the
 .Xr sendmsg 2
 system call, and attempts to send bytes of data via the socket
 .Fa so ,
 optionally blocking if data cannot be immediately sent.
 Data may be sent directly from kernel or user memory via the
 .Fa uio
 argument, or as an mbuf chain via
 .Fa top ,
 avoiding a data copy.
 Only one of the
 .Fa uio
 or
 .Fa top
 pointers may be
 .Pf non- Dv NULL .
 An optional destination address may be specified via a
 .Pf non- Dv NULL
 .Fa addr
 argument, which may result in an implicit connect if supported by the
 protocol.
 The caller may optionally send control data mbufs via a
 .Pf non- Dv NULL
 .Fa control
 argument.
 Flags may be passed to
 .Fn sosend
 using the
 .Fa flags
 argument, and use the same flag name space as the
 .Xr sendmsg 2
 system call.
 .Pp
 Kernel callers running in
 .Xr ithread 9
 context, or with a mutex held, will wish to use non-blocking sockets and pass
 the
 .Dv MSG_DONTWAIT
 flag in order to prevent these functions from sleeping.
 .Pp
 A socket can be queried for readability, writability, out-of-band data,
 or end-of-file using
 .Fn sopoll .
 The possible values for
 .Va events
 are as for
 .Xr poll 2 ,
 with symbolic values
 .Dv POLLIN ,
 .Dv POLLPRI ,
 .Dv POLLOUT ,
 .Dv POLLRDNORM ,
 .Dv POLLWRNORM ,
 .Dv POLLRDBAND ,
 and
 .Dv POLLINGEOF
 taken from
 .In sys/poll.h .
 .Pp
 Calls to
 .Fn soaccept
 pass through to the protocol's accept routine to accept an incoming connection.
 .Ss Socket Utility Functions
 The uid of a socket's credential may be compared against a
 .Va uid
 with
 .Fn socheckuid .
 .Pp
 A copy of an existing
 .Vt struct sockaddr
 may be made using
 .Fn sodupsockaddr .
 .Pp
 Protocol implementations notify the socket layer of the arrival of
 out-of-band data using
 .Fn sohasoutofband ,
 so that the socket layer can notify socket consumers of the available data.
 .Pp
 An
 .Dq external-format
 version of a
 .Vt struct socket
 can be created using
 .Fn sotoxsocket ,
 suitable for isolating user code from changes in the kernel structure.
 .Ss Protocol Implementations
 Protocols must supply an implementation for
 .Fn solisten ;
 such protocol implementations can call back into the socket layer using
 .Fn solisten_proto_check
 and
 .Fn solisten_proto
 to check and set the socket-layer listen state.
 These callbacks are provided so that the protocol implementation
 can order the socket layer and protocol locks as necessary.
 Protocols must supply an implementation of
 .Fn soreceive ;
 the functions
 .Fn soreceive_stream ,
 .Fn soreceive_dgram ,
 and
 .Fn soreceive_generic
 are supplied for use by such implementations.
 .Pp
 Protocol implementations can use
 .Fn sonewconn
 to create a socket and attach protocol state to that socket.
 This can be used to create new sockets available for
 .Fn soaccept
 on a listen socket.
 The returned socket has a reference count of zero.
 .Pp
 Protocols must supply an implementation for
 .Fn sopoll ;
 .Fn sopoll_generic
 is provided for the use by protocol implementations.
 .Pp
 The functions
 .Fn sosend_dgram
 and
 .Fn sosend_generic
 are supplied to assist in protocol implementations of
 .Fn sosend .
 .Pp
 When a protocol creates a new socket structure, it is necessary to
 reserve socket buffer space for that socket, by calling
 .Fn soreserve .
 The rough inverse of this reservation is performed by
 .Fn sorflush ,
 which is called automatically by the socket framework.
 .Pp
 When a protocol needs to wake up threads waiting for the socket to
 become ready to read or write, variants of
 .Fn sowakeup
 are used.
 The
 .Fn sowakeup
 function should not be called directly by protocol code, instead use the
 wrappers
 .Fn sorwakeup ,
 .Fn sorwakeup_locked ,
 .Fn sowwakeup ,
 and
 .Fn sowwakeup_locked
 for readers and writers, with the corresponding socket buffer lock
 not already locked, or already held, respectively.
 .Pp
 The functions
 .Fn sooptcopyin
 and
 .Fn sooptcopyout
 are useful for transferring
 .Vt struct sockopt
 data between user and kernel code.
 .Sh SEE ALSO
 .Xr bind 2 ,
 .Xr close 2 ,
 .Xr connect 2 ,
 .Xr getsockopt 2 ,
 .Xr recv 2 ,
 .Xr send 2 ,
 .Xr setsockopt 2 ,
 .Xr shutdown 2 ,
 .Xr socket 2 ,
 .Xr ng_ksocket 4 ,
 .Xr ithread 9 ,
 .Xr msleep 9 ,
 .Xr ucred 9
 .Sh HISTORY
 The
 .Xr socket 2
 system call appeared in
 .Bx 4.2 .
 This manual page was introduced in
 .Fx 7.0 .
 .Sh AUTHORS
 This manual page was written by
 .An Robert Watson
 and
 .An Benjamin Kaduk .
 .Sh BUGS
 The use of explicitly passed credentials, credentials hung from explicitly
 passed threads, the credential on
 .Dv curthread ,
 and the cached credential from
 socket creation time is inconsistent, and may lead to unexpected behaviour.
 It is possible that several of the
 .Fa td
 arguments should be
 .Fa cred
 arguments, or simply not be present at all.
 .Pp
 The caller may need to manually clear
 .Dv SS_ISCONNECTING
 if
 .Fn soconnect
 returns an error.
 .Pp
 The
 .Dv MSG_DONTWAIT
 flag is not implemented for
 .Fn sosend ,
 and may not always work with
 .Fn soreceive
 when zero copy sockets are enabled.
 .Pp
 This manual page does not describe how to register socket upcalls or monitor
 a socket for readability/writability without using blocking I/O.
 .Pp
 The
 .Fn soref
 and
 .Fn sorele
 functions are not described, and in most cases should not be used, due to
 confusing and potentially incorrect interactions when
 .Fn sorele
 is last called after
 .Fn soclose .
Index: head/share/man/man9/usbdi.9
===================================================================
--- head/share/man/man9/usbdi.9	(revision 268817)
+++ head/share/man/man9/usbdi.9	(revision 268818)
@@ -1,641 +1,641 @@
 .\"
 .\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org>
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\"	$FreeBSD$
 .Dd June 24, 2009
 .Dt USBDI 9
 .Os
 .Sh NAME
 .Nm usb_fifo_alloc_buffer ,
 .Nm usb_fifo_attach ,
 .Nm usb_fifo_detach ,
 .Nm usb_fifo_free_buffer ,
 .Nm usb_fifo_get_data ,
 .Nm usb_fifo_get_data_buffer ,
 .Nm usb_fifo_get_data_error ,
 .Nm usb_fifo_get_data_linear ,
 .Nm usb_fifo_put_bytes_max ,
 .Nm usb_fifo_put_data ,
 .Nm usb_fifo_put_data_buffer ,
 .Nm usb_fifo_put_data_error ,
 .Nm usb_fifo_put_data_linear ,
 .Nm usb_fifo_reset ,
 .Nm usb_fifo_softc ,
 .Nm usb_fifo_wakeup ,
 .Nm usbd_do_request ,
 .Nm usbd_do_request_flags ,
 .Nm usbd_errstr ,
 .Nm usbd_lookup_id_by_info ,
 .Nm usbd_lookup_id_by_uaa ,
 .Nm usbd_transfer_clear_stall ,
 .Nm usbd_transfer_drain ,
 .Nm usbd_transfer_pending ,
 .Nm usbd_transfer_poll ,
 .Nm usbd_transfer_setup ,
 .Nm usbd_transfer_start ,
 .Nm usbd_transfer_stop ,
 .Nm usbd_transfer_submit ,
 .Nm usbd_transfer_unsetup ,
 .Nm usbd_xfer_clr_flag ,
 .Nm usbd_xfer_frame_data ,
 .Nm usbd_xfer_frame_len ,
 .Nm usbd_xfer_get_frame ,
 .Nm usbd_xfer_get_priv ,
 .Nm usbd_xfer_is_stalled ,
 .Nm usbd_xfer_max_framelen ,
 .Nm usbd_xfer_max_frames ,
 .Nm usbd_xfer_max_len ,
 .Nm usbd_xfer_set_flag ,
 .Nm usbd_xfer_set_frame_data ,
 .Nm usbd_xfer_set_frame_len ,
 .Nm usbd_xfer_set_frame_offset ,
 .Nm usbd_xfer_set_frames ,
 .Nm usbd_xfer_set_interval ,
 .Nm usbd_xfer_set_priv ,
 .Nm usbd_xfer_set_stall ,
 .Nm usbd_xfer_set_timeout ,
 .Nm usbd_xfer_softc ,
 .Nm usbd_xfer_state ,
 .Nm usbd_xfer_status
 .Nd Universal Serial Bus driver programming interface
 .Sh SYNOPSIS
 .In dev/usb/usb.h
 .In dev/usb/usbdi.h
 .In dev/usb/usbdi_util.h
 .Sh DESCRIPTION
 The Universal Serial Bus (USB) driver programming interface provides
 USB peripheral drivers with a host controller independent API for
 controlling and communicating with USB peripherals.
 The
 .Nm usb
 module supports both USB Host and USB Device side mode.
 .
 .Sh USB KERNEL PROGRAMMING
 Here is a list of commonly used functions:
 .Pp
 .
 .Ft "usb_error_t"
 .Fo "usbd_transfer_setup"
 .Fa "udev"
 .Fa "ifaces"
 .Fa "pxfer"
 .Fa "setup_start"
 .Fa "n_setup"
 .Fa "priv_sc"
 .Fa "priv_mtx"
 .Fc
 .
 .Pp
 .
 .Ft "void"
 .Fo "usbd_transfer_unsetup"
 .Fa "pxfer"
 .Fa "n_setup"
 .Fc
 .
 .Pp
 .
 .Ft "void"
 .Fo "usbd_transfer_start"
 .Fa "xfer"
 .Fc
 .
 .Pp
 .
 .Ft "void"
 .Fo "usbd_transfer_stop"
 .Fa "xfer"
 .Fc
 .
 .Pp
 .
 .Ft "void"
 .Fo "usbd_transfer_drain"
 .Fa "xfer"
 .Fc
 .
 .
 .
 .Sh USB TRANSFER MANAGEMENT FUNCTIONS
 The USB standard defines four types of USB transfers.
 .
 Control transfers, Bulk transfers, Interrupt transfers and Isochronous
 transfers.
 .
 All the transfer types are managed using the following five functions:
 .
 .Pp
 .
 .Fn usbd_transfer_setup
 This function will allocate memory for and initialise an array of USB
 transfers and all required DMA memory.
 .
 This function can sleep or block waiting for resources to become
 available.
 .Fa udev
 is a pointer to "struct usb_device".
 .Fa ifaces
 is an array of interface index numbers to use. See "if_index".
 .Fa pxfer
 is a pointer to an array of USB transfer pointers that are initialized
 to NULL, and then pointed to allocated USB transfers.
 .Fa setup_start
 is a pointer to an array of USB config structures.
 .Fa n_setup
 is a number telling the USB system how many USB transfers should be
 setup.
 .Fa priv_sc
 is the private softc pointer, which will be used to initialize
 "xfer->priv_sc".
 .Fa priv_mtx
 is the private mutex protecting the transfer structure and the
 softc. This pointer is used to initialize "xfer->priv_mtx".
 This function returns
 zero upon success. A non-zero return value indicates failure.
 .
 .Pp
 .
 .Fn usbd_transfer_unsetup
 This function will release the given USB transfers and all allocated
 resources associated with these USB transfers.
 .Fa pxfer
 is a pointer to an array of USB transfer pointers, that may be NULL,
 that should be freed by the USB system.
 .Fa n_setup
 is a number telling the USB system how many USB transfers should be
 unsetup.
 .
 This function can sleep waiting for USB transfers to complete.
 .
 This function is NULL safe with regard to the USB transfer structure
 pointer.
 .
 It is not allowed to call this function from the USB transfer
 callback.
 .
 .Pp
 .
 .Fn usbd_transfer_start
 This function will start the USB transfer pointed to by
 .Fa xfer,
 if not already started.
 .
 This function is always non-blocking and must be called with the
 so-called private USB mutex locked.
 .
 This function is NULL safe with regard to the USB transfer structure
 pointer.
 .
 .Pp
 .
 .Fn usbd_transfer_stop
 This function will stop the USB transfer pointed to by
 .Fa xfer,
 if not already stopped.
 .
 This function is always non-blocking and must be called with the
 so-called private USB mutex locked.
 .
 This function can return before the USB callback has been called.
 .
 This function is NULL safe with regard to the USB transfer structure
 pointer.
 .
 If the transfer was in progress, the callback will called with
 "USB_ST_ERROR" and "error = USB_ERR_CANCELLED".
 .
 .Pp
 .
 .Fn usbd_transfer_drain
 This function will stop an USB transfer, if not already stopped and
 wait for any additional USB hardware operations to complete.
 .
 Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can
 safely be freed after that this function has returned.
 .
 This function can block the caller and will not return before the USB
 callback has been called.
 .
 This function is NULL safe with regard to the USB transfer structure
 pointer.
 .
 .Sh USB TRANSFER CALLBACK
 .
 The USB callback has three states.
 .
 USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the
 initial state.
 .
 After the callback has been called with this state it will always be
 called back at a later stage in one of the other two states.
 .
 The USB callback should not restart the USB transfer in case the error
 cause is USB_ERR_CANCELLED.
 .
 The USB callback is protected from recursion.
 .
 That means one can start and stop whatever transfer from the callback
 of another transfer one desires.
 .
 Also the transfer that is currently called back.
 .
 Recursion is handled like this that when the callback that wants to
 recurse returns it is called one more time.
 .
 .
 .Pp
 .
 .Fn usbd_transfer_submit
 This function should only be called from within the USB callback and
 is used to start the USB hardware.
 .
 An USB transfer can have multiple frames consisting of one or more USB
 packets making up an I/O vector for all USB transfer types.
 .
 .Bd -literal -offset indent
 void
 usb_default_callback(struct usb_xfer *xfer, usb_error_t error)
 {
 	int actlen;
 
 	usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL);
 
 	switch (USB_GET_STATE(xfer)) {
 	case USB_ST_SETUP:
 		/*
 		 * Setup xfer frame lengths/count and data
 		 */
 		usbd_transfer_submit(xfer);
 		break;
 
 	case USB_ST_TRANSFERRED:
 		/*
 		 * Read	usb frame data, if any.
 		 * "actlen" has the total length for all frames
 		 * transferred.
 		 */
 		break;
 
 	default: /* Error */
 		/*
 		 * Print error message and clear stall
 		 * for example.
 		 */
 		break;
 	}
 	/*
 	 * Here it is safe to do something without the private
 	 * USB mutex locked.
 	 */
 	return;
 }
 .Ed
 .
 .Sh USB CONTROL TRANSFERS
 An USB control transfer has three parts.
 .
 First the SETUP packet, then DATA packet(s) and then a STATUS
 packet.
 .
 The SETUP packet is always pointed to by frame 0 and the
 length is set by
 .Fn usbd_xfer_frame_len
 also if there should not be
 sent any SETUP packet! If an USB control transfer has no DATA stage,
 then the number of frames should be set to 1.
 .
 Else the default number of frames is 2.
 .
 .Bd -literal -offset indent
 
 Example1: SETUP + STATUS
  usbd_xfer_set_frames(xfer, 1);
  usbd_xfer_set_frame_len(xfer, 0, 8);
  usbd_transfer_submit(xfer);
 
 Example2: SETUP + DATA + STATUS
  usbd_xfer_set_frames(xfer, 2);
  usbd_xfer_set_frame_len(xfer, 0, 8);
  usbd_xfer_set_frame_len(xfer, 1, 1);
  usbd_transfer_submit(xfer);
 
 Example3: SETUP + DATA + STATUS - split
 1st callback:
  usbd_xfer_set_frames(xfer, 1);
  usbd_xfer_set_frame_len(xfer, 0, 8);
  usbd_transfer_submit(xfer);
 
 2nd callback:
  /* IMPORTANT: frbuffers[0] must still point at the setup packet! */
  usbd_xfer_set_frames(xfer, 2);
  usbd_xfer_set_frame_len(xfer, 0, 0);
  usbd_xfer_set_frame_len(xfer, 1, 1);
  usbd_transfer_submit(xfer);
 
 Example4: SETUP + STATUS - split
 1st callback:
  usbd_xfer_set_frames(xfer, 1);
  usbd_xfer_set_frame_len(xfer, 0, 8);
  usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS);
  usbd_transfer_submit(xfer);
 
 2nd callback:
  usbd_xfer_set_frames(xfer, 1);
  usbd_xfer_set_frame_len(xfer, 0, 0);
  usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS);
  usbd_transfer_submit(xfer);
 
 .Ed
 .Sh USB TRANSFER CONFIG
 To simply the search for endpoints the
 .Nm usb
 module defines a USB config structure where it is possible to specify
 the characteristics of the wanted endpoint.
 .Bd -literal -offset indent
 
 struct usb_config {
 	bufsize,
 	callback
 	direction,
 	endpoint,
 	frames,
 	index flags,
 	interval,
 	timeout,
 	type,
 };
 
 .Ed
 .
 .Pp
 .Fa type
 field selects the USB pipe type.
 .
 Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK,
 UE_ISOCHRONOUS.
 .
 The special value UE_BULK_INTR will select BULK and INTERRUPT pipes.
 .
 This field is mandatory.
 .
 .Pp
 .Fa endpoint
 field selects the USB endpoint number.
 .
 A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching
 endpoint.
 .
 This field is mandatory.
 .
 .Pp
 .Fa direction
 field selects the USB endpoint direction.
 .
 A value of "UE_DIR_ANY" will select the first matching endpoint.
 .
 Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT".
 .
 "UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which
 means that the direction will be swapped in case of
 USB_MODE_DEVICE.
 .
 Note that "UE_DIR_IN" refers to the data transfer direction of the
 "IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of
 the "OUT" tokens.
 .
 This field is mandatory.
 .
 .Pp
 .Fa interval
 field selects the interrupt interval.
 .
 The value of this field is given in milliseconds and is independent of
 device speed.
 .
 Depending on the endpoint type, this field has different meaning:
 .Bl -tag -width "UE_ISOCHRONOUS"
 .It UE_INTERRUPT
 "0" use the default interrupt interval based on endpoint descriptor.
 "Else" use the given value for polling rate.
 .It UE_ISOCHRONOUS
 "0" use default. "Else" the value is ignored.
 .It UE_BULK
 .It UE_CONTROL
 "0" no transfer pre-delay. "Else" a delay as given by this field in
 milliseconds is inserted before the hardware is started when
 "usbd_transfer_submit()" is called.
 .Pp
 NOTE: The transfer timeout, if any, is started after that the
 pre-delay has elapsed!
 .El
 .
 .Pp
 .Fa timeout
 field, if non-zero, will set the transfer timeout in milliseconds. If
 the "timeout" field is zero and the transfer type is ISOCHRONOUS a
 timeout of 250ms will be used.
 .
 .Pp
 .Fa frames
 field sets the maximum number of frames. If zero is specified it will
 yield the following results:
 .Bl -tag -width "UE_INTERRUPT"
 .It UE_BULK
 xfer->nframes = 1;
 .It UE_INTERRUPT
 xfer->nframes = 1;
 .It UE_CONTROL
 xfer->nframes = 2;
 .It UE_ISOCHRONOUS
 Not allowed. Will cause an error.
 .El
 .
 .Pp
 .Fa ep_index
 field allows you to give a number, in case more endpoints match the
 description, that selects which matching "ep_index" should be used.
 .
 .Pp
 .Fa if_index
 field allows you to select which of the interface numbers in the
 "ifaces" array parameter passed to "usbd_transfer_setup" that should
 be used when setting up the given USB transfer.
 .
 .Pp
 .Fa flags
 field has type "struct usb_xfer_flags" and allows one to set initial
 flags an USB transfer. Valid flags are:
 .Bl -tag -width "force_short_xfer"
 .It force_short_xfer
 This flag forces the last transmitted USB packet to be short.  A short
 packet has a length of less than "xfer->max_packet_size", which
 derives from "wMaxPacketSize". This flag can be changed during
 operation.
 .It short_xfer_ok
 This flag allows the received transfer length, "xfer->actlen" to be
 less than "xfer->sumlen" upon completion of a transfer.  This flag can
 be changed during operation.
 .It short_frames_ok
 This flag allows the reception of multiple short USB frames. This flag
 only has effect for BULK and INTERRUPT endpoints and if the number of
 frames received is greater than 1. This flag can be changed during
 operation.
 .It pipe_bof
 This flag causes a failing USB transfer to remain first in the PIPE
 queue except in the case of "xfer->error" equal to
 "USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue
 will be started until either:
-.Bl -tag -width "1"
+.Bl -tag -width "X"
 .It 1
 The failing USB transfer is stopped using "usbd_transfer_stop()".
 .It 2
 The failing USB transfer performs a successful transfer.
 .El
 The purpose of this flag is to avoid races when multiple transfers are
 queued for execution on an USB endpoint, and the first executing
 transfer fails leading to the need for clearing of stall for
 example.
 .
 In this case this flag is used to prevent the following USB transfers
 from being executed at the same time the clear-stall command is
 executed on the USB control endpoint.
 .
 This flag can be changed during operation.
 .Pp
 "BOF" is short for "Block On Failure".
 .Pp
 NOTE: This flag should be set on all BULK and INTERRUPT USB transfers
 which use an endpoint that can be shared between userland and kernel.
 .
 .
 .It proxy_buffer
 Setting this flag will cause that the total buffer size will be
 rounded up to the nearest atomic hardware transfer size.
 .
 The maximum data length of any USB transfer is always stored in the
 "xfer->max_data_length".
 .
 For control transfers the USB kernel will allocate additional space
 for the 8-bytes of SETUP header.
 .
 These 8-bytes are not counted by the "xfer->max_data_length"
 variable.
 .
 This flag can not be changed during operation.
 .
 .
 .It ext_buffer
 Setting this flag will cause that no data buffer will be
 allocated.
 .
 Instead the USB client must supply a data buffer.
 .
 This flag can not be changed during operation.
 .
 .
 .It manual_status
 Setting this flag prevents an USB STATUS stage to be appended to the
 end of the USB control transfer.
 .
 If no control data is transferred this flag must be cleared.
 .
 Else an error will be returned to the USB callback.
 .
 This flag is mostly useful for the USB device side.
 .
 This flag can be changed during operation.
 .
 .
 .It no_pipe_ok
 Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This
 flag can not be changed during operation.
 .
 .
 .It stall_pipe
 .Bl -tag -width "Device Side Mode"
 .It Device Side Mode
 Setting this flag will cause STALL pids to be sent to the endpoint
 belonging to this transfer before the transfer is started.
 .
 The transfer is started at the moment the host issues a clear-stall
 command on the STALL'ed endpoint.
 .
 This flag can be changed during operation.
 .It Host Side Mode
 Setting this flag will cause a clear-stall control request to be
 executed on the endpoint before the USB transfer is started.
 .El
 .Pp
 If this flag is changed outside the USB callback function you have to
 use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()"
 functions! This flag is automatically cleared after that the stall or
 clear stall has been executed.
 .
 .It pre_scale_frames
 If this flag is set the number of frames specified is assumed to give the buffering time in milliseconds instead of frames.
 During transfer setup the frames field is pre scaled with the corresponding value for the endpoint and rounded to the nearest number of frames greater than zero.
 This option only has effect for ISOCHRONOUS transfers.
 .El
 .Pp
 .Fa bufsize
 field sets the total buffer size in bytes.
 .
 If this field is zero, "wMaxPacketSize" will be used, multiplied by
 the "frames" field if the transfer type is ISOCHRONOUS.
 .
 This is useful for setting up interrupt pipes.
 .
 This field is mandatory.
 .Pp
 NOTE: For control transfers "bufsize" includes the length of the
 request structure.
 .
 .Pp
 .Fa callback
 pointer sets the USB callback. This field is mandatory.
 .
 .
 .Sh USB LINUX COMPAT LAYER
 The
 .Nm usb
 module supports the Linux USB API.
 .
 .
 .Sh SEE ALSO
 .Xr libusb 3 ,
 .Xr usb 4 ,
 .Xr usbconfig 8
 .Sh STANDARDS
 The
 .Nm usb
 module complies with the USB 2.0 standard.
 .Sh HISTORY
 The
 .Nm usb
 module has been inspired by the NetBSD USB stack initially written by
 Lennart Augustsson. The
 .Nm usb
 module was written by
 .An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org .