.\"	$NetBSD: usbnet.9,v 1.1 2019/08/10 20:35:35 mrg Exp $
.\"
.\" Copyright (c) 2019 Matthew R. Green
.\" 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.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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.
.\"
.Dd August 10, 2019
.Dt USBNET 9
.Os
.Sh NAME
.Nm usbnet
.Nd common USB ethernet driver framework
.Sh SYNOPSIS
.In dev/usb/usbnet.h
.Ss Functions offered by usbnet.h
.Ft void
.Fn usbnet_set_link "struct usbnet *un" "bool link"
.Ft void
.Fn usbnet_set_dying "struct usbnet *un" "bool dying"
.Ft struct ifnet *
.Fn usbnet_ifp "struct usbnet *un"
.Ft struct ethercom *
.Fn usbnet_ec "struct usbnet *un"
.Ft struct mii_data *
.Fn usbnet_mii "struct usbnet *un"
.Ft krndsource_t *
.Fn usbnet_rndsrc "struct usbnet *un"
.Ft void *
.Fn usbnet_softc "struct usbnet *un"
.Ft bool
.Fn usbnet_havelink "struct usbnet *un"
.Ft bool
.Fn usbnet_isdying "struct usbnet *un"
.Ft void
.Fn usbnet_lock "struct usbnet *un"
.Ft void
.Fn usbnet_unlock "struct usbnet *un"
.Ft kmutex_t *
.Fn usbnet_mutex "struct usbnet *un"
.Ft void
.Fn usbnet_isowned "struct usbnet *un"
.Ft void
.Fn usbnet_lock_rx "struct usbnet *un"
.Ft void
.Fn usbnet_unlock_rx "struct usbnet *un"
.Ft kmutex_t *
.Fn usbnet_mutex_rx "struct usbnet *un"
.Ft void
.Fn usbnet_isowned_rx "struct usbnet *un"
.Ft void
.Fn usbnet_lock_tx "struct usbnet *un"
.Ft void
.Fn usbnet_unlock_tx "struct usbnet *un"
.Ft kmutex_t *
.Fn usbnet_mutex_tx "struct usbnet *un"
.Ft void
.Fn usbnet_isowned_tx "struct usbnet *un"
.Ft int
.Fn usbnet_init_rx_tx "struct usbnet *un" "unsigned rxflags" "unsigned txflags"
.Ft void
.Fn usbnet_lock_mii "struct usbnet *un"
.Ft void
.Fn usbnet_lock_mii_un_locked "struct usbnet *un"
.Ft void
.Fn usbnet_unlock_mii "struct usbnet *un"
.Ft void
.Fn usbnet_unlock_mii_un_locked "struct usbnet *un"
.Ft kmutex_t *
.Fn usbnet_mutex_mii "struct usbnet *un"
.Ft void
.Fn usbnet_isowned_mii "struct usbnet *un"
.Ft int
.Fn usbnet_miibus_readreg "device_t dev" "int phy" "int reg" "uint16_t *val"
.Ft int
.Fn usbnet_miibus_writereg "device_t dev" "int phy" "int reg" "uint16_t val"
.Ft void
.Fn usbnet_miibus_statchg "struct ifnet *"
.Ft void
.Fn usbnet_enqueue "struct usbnet *un" "uint8_t *buf" "size_t buflen" "int csum_flags" "uint32_t csum_data" "int mbuf_flags"
.Ft void
.Fn usbnet_input "struct usbnet *un" "uint8_t *buf" "size_t buflen"
.Ft void
.Fn usbnet_attach "struct usbnet *un" "const char *detname"
.Ft void
.Fn usbnet_attach_ifp "struct usbnet *un" "bool have_mii" "unsigned if_flags" "unsigned if_extflags" "int mii_flags"
.Ft int
.Fn usbnet_detach "device_t dev" "int flags"
.Ft int
.Fn usbnet_activate "device_t dev" "devact_t act"
.Ft void
.Fn usbnet_stop "struct usbnet *un" "struct ifnet *ifp" "int disable"
.Sh DESCRIPTION
The
.Nm
framework provides methods usable for USB ethernet drivers.
The framework has support for these features:
.Pp
.Bl -tag -width "123456"
.It
Partial autoconf handling
.It
USB endpoint pipe handling
.It
Rx and Tx chain handling
.It
Generic handlers or support for several struct ifnet callbacks
.It
MII bus locking
.It
Interrupt handling  
.El
.Pp
.Nm
provides many or all of the traditional
.Dq softc
members inside
.Va struct usbnet ,
which can be used directly as the device softc structure if
no additional storage is required.
An structure exists for receive and transmit chain management,
.Va struct usbnet_chain ,
that tracks the metadata for each transfer descriptor available,
minimum of one each for Rx and Tx slot, and will be passed
to the Rx and Tx callbacks.
.Pp
There is a
.Va struct usbnet_ops
structure that provides a number of optional and required callbacks
that will be described below.
.Pp
For autoconfiguration the device attach routine is expected to
ensure that this device's
.Va struct usbnet
is set to the device
.Fa dv_private ,
if it can not be used directly as the device softc, as well as set
up the necessary structure members, find end-points, find the
ethernet address if relevant, call
.Fn usbnet_attach ,
setup interface, ethernet, and MII capabilities, and finally call
.Fn usbnet_attach_ifp .
The device detach routine should free any resources allocated
by attach and then call
.Fn usbnet_detach ,
possibly directly using
.Fn usbnet_detach
as most consumers have no additional resources not owned and
released by the
.Nm
framework itself.
The device activate function should be set to
.Fn usbnet_activate .
.Pp
To manage all Rx and Tx chains the
.Dq uno_init
callback of
.Va struct usbnet_ops
should perform any device specific initialisation and then call
.Fn usbnet_init_rx_tx
which will allocate chains, setup and open pipes, and start the
Rx transfers so that packets can arrived.
These allocations and pipes can be closed and destroyed by calling
.Fn usbnet_stop .
Both of
.Fn usbnet_init_rx_tx
and
.Fn usbnet_stop
must be called with the
.Nm
lock held, see
.Fn usbnet_lock
and 
.Fn usbnet_unlock .
See the
.Sx RECEIVE AND SEND
section for details on using the chains.
.Pp
The interface init, ioctl, start, and stop, routines are handled by the
framework with callbacks for device-specific handling.
For interface init (ie, when bringing the interface up), the
.Dq uno_init
callback should perform any device specific initialisation and then call
.Fn usbnet_init_rx_tx
to finalise Rx and Tx queue initialisation.
For interface ioctl, most of the handling is in the framework and the
optional
.Dq uno_ioctl
callback should be used to program special settings
like multicast filters or offload handling.
If ioctl handling requires capturing device-specific ioctls then the
.Dq uno_override_ioctl
callback may be used instead to replace the framework's
ioctl handler completely (i.e., the replacement should call any generic
ioctl handlers such as
.Fn ether_ioctl
as required.)
For interface start, the
.Dq uno_tx_prepare
callback must be used to convert
an mbuf into a chain buffer ready for transmission.
For interface stop, there is an optional
.Dq uno_stop
callback to turn off any chipset specific values if required.
.Pp
For devices requiring MII handling there are callbacks for reading and
writing registers, and for status change events.
The framework provides an MII-specific lock per interface which will be
held when calling these functions, and these locks should be used by
internal code that also requires serialised access to registers with the 
.Fn usbnet_lock_mii ,
.Fn usbnet_unlock_mii ,
.Fn usbnet_lock_mii_un_locked ,
and 
.Fn usbnet_unlock_mii_un_locked
functions.
These functions handle device detach events safely, and as such take
and release a reference on this device and use the usbnet lock for
this.
Sometimes the usbnet lock is already held and instead the
.Dq un_locked
versions should be used.
.Pp
As receive must handle the case of multiple packets in one buffer,
the support is split between the driver and the framework.
A
.Dq uno_rx_loop
callback must be provided that loops over the incoming
packet data found in a chain, performs necessary checking and passes
the network frame up the stack via either
.Fn usbnet_enqueue
or
.Fn usbnet_input .
Typically ethernet devices prefer
.Fn usbnet_enqueue .
.Pp
General accessor functions for
.Fa struct usbnet :
.Bl -tag -width 4n
.It Fn usbnet_set_link un link
Set the link status for this
.Fa un
to
.Fa link .
.It Fn usbnet_set_dying un dying
Set the dying status for this
.Fa un
to
.Fa dying .
.It Fn usbnet_ifp un
Returns pointer to this
.Fa un's
.Va struct ifnet .
.It Fn usbnet_ec un
Returns pointer to this
.Fa un's
.Va struct ethercom .
.It Fn usbnet_mii un
Returns pointer to this
.Fa un's
.Va struct mii_data .
.It Fn usbnet_rndsrc un
Returns pointer to this
.Fa un's
.Va krndsource_t .
.It Fn usbnet_softc un
Returns pointer to this
.Fa un's
device softc.
.It Fn bool usbnet_havelink un
Returns true if link is active.
.It Fn bool usbnet_isdying un
Returns true if device is dying (has been pulled or deactivated,
pending detach.)
.El
.Pp

Lock handling functions for
.Fa struct usbnet :
.Pp
.Bl -compact -tag -width 4n
.It Fn usbnet_lock un
.It Fn usbnet_unlock un
.It Fn usbnet_isowned un
.It Fn usbnet_lock_rx un
.It Fn usbnet_unlock_rx un
.It Fn usbnet_isowned_rx un
.It Fn usbnet_lock_tx un
.It Fn usbnet_unlock_tx un
.It Fn usbnet_isowned_tx un
.It Fn usbnet_lock_mii un
.It Fn usbnet_lock_mii_un_locked un
.It Fn usbnet_unlock_mii un
.It Fn usbnet_unlock_mii_un_locked un
.It Fn usbnet_isowned_mii un
These groups of three or five functions provide methods to lock,
unlock, and assert ownership of one of the four locks provided by
.Nm .
The four locks are the
.Dq softc
lock, the
.Dq Tx
lock, the
.Dq Rx
lock, and the
.Dq MII
lock.
The MII lock is special in that it blocks device detach using
an internal reference count and is frequently required when
both the
.Dq softc
lock is held or unheld, and two versions are provided that
either hold the
.Dq softc
lock while increasing or decreasing the reference count, or
assume (and in debug builds, assert) the lock is held for
the
.Dq un_locked
versions.
.El
.Pp
MII access functions for
.Fa struct usbnet :
.Pp
.Bl -tag -width 4n
.It Fn usbnet_mii_readreg dev phy reg valp
Read register
.Fa reg
on PHY number
.Fa phy
and return the value in
.Fa valp .
.It Fn usbnet_mii_writereg dev phy reg val
Write register
.Fa reg
on PHY number
.Fa phy
with
.Fa val .
.It Fn usbnet_mii_statchg ifp
Trigger a status change update for interface
.Fa ifp
.El
.Pp
Buffer enqueue handling for
.Fa struct usbnet :
.Pp
.Bl -tag -width 4n
.It Fn usbnet_enqueue un buf buflen csum_flags csum_data mbuf_flags
Enqueue buffer
.Fa buf
for length
.Fa buflen
with higher layers, using the provided
.Fa csum_flags ,
and
.Fa csum_data ,
which are written directly to the mbuf packet header, and
.Fa mbuf_flags ,
which is or-ed into the mbuf flags for the created mbuf.
.It Fn usbnet_input un buf buflen
Enqueue buffer
.Fa buf
for length
.Fa buflen
with higher layers
.El
.Pp
Autoconfiguration handling for
.Fa struct usbnet .
See the
.Sx AUTOCONFIGURATION
section for more details about these functions.
.Pp
.Bl -tag -width 4n
.It Fn usbnet_attach un detachname
Initial stage attach of a usb network device.
The
.Fa detachname
will be used while waiting for final references to drain when detaching.
.It Fn usbnet_attach_ifp un have_mii if_flags if_extflags mii_flags
Final stage attach of usb network device.
If
.Fa have_mii
is true then an MII interface will be created and
.Fa mii_flags
added.
The
.Fa if_flags
and
.Fa if_extflags
will be or-ed into the interface flags and extflags.
.It Fn usbnet_detach dev flags
Device detach.
Usable as actual device method.
.It Fn usbnet_activate dev act
Device activate (deactivate) method.
Usable as actual device method.
.It Fn usbnet_stop un ifp disable
Interface stop routine.
.Pp
.Sh AUTOCONFIGURATION
The framework expects the usbnet structure to have these members
filled in with valid values or functions:
.Bl -tag 
.It un_sc
Real softc allocated by autoconf and provided to attach, should be
set to the usbnet structure if no device-specific softc is needed.
.It un_dev
device_t saved in attach, used for messages mostly.
.It un_iface
The USB iface handle for data interactions, see
.Fn usbd_device2interface_handle
for more details.
.It un_udev
The struct usbd_device for this device, provided as the usb_attach_arg's
.Va uaa_device
member.
.It un_ops
Points to a
.Va struct usbnet_ops
structure which contains these members:
.Bl -tag -width 4n
.It uno_stop
Stop interface (optional.)
.It uno_ioctl
Simple ioctl callback (optional.)
.It uno_override_ioctl
Full ioctl callback (optional.)
.It uno_init
Initialise (bring up) interface.
Required.
Must call
.Fn usbnet_rx_tx_init .
.It uno_read_reg
Read MII register.
Required with MII.
.It uno_write_reg
Write MII register.
Required with MII.
.It uno_statchg
Handle MII status change.
Required with MII.
.It uno_tx_prepare
Prepare an mbuf for transmit. Required.
.It uno_rx_loop
Prepare one or more chain for enqueue. Required.
.It uno_intr
Process periodic interrupt (optional.)
.El
.It un_intr
Points to a
.Va struct usbnet_intr
structure which should have these members set:
.Bl -tag -width 4n
.It uni_intr_buf
If non-NULL, points to a buffer passed to
Fn usbd_open_pipe_intr
in the device init callback, along with the size and interval.
.It uni_intr_bufsz
Size of interrupt pipe buffer.
.It uni_intr_interval
Frequency of the interrupt in milliseconds.
.El
.It un_ed
Array of endpoint descriptors.
There indexes are provded:
.Dq USBNET_ENDPT_RX ,
.Dq USBNET_ENDPT_TX ,
and
.Dq USBNET_ENDPT_INTR .
The Rx and Tx endpoints are required.
.It un_phyno
MII phy number.
.It un_eaddr
6 bytes of ethernet address that must be provided before calling
.Fn usbnet_attach_ifp
if the device has ethernet.
.It un_flags
Device owned flags word.
The
.Nm
framework will not touch this value.
.It un_rx_xfer_flags
Passed to usbd_setup_xfer() for receiving packets.
.It un_tx_xfer_flags
Passed to usbd_setup_xfer() for sending packets.
.It un_rx_list_cnt
Number of chain elements to allocate for Rx.
.It un_tx_list_cnt
Number of chain elements to allocate for Tx.
.It un_rx_bufsz
Rx buffer size.
.It un_tx_bufsz
Tx buffer size.
.El
.Pp
The device detach and activate callbacks can typically be set to
.Fn usbnet_detach
and
.Fn usbnet_activate
unless device-specific handling is required, in which case, they
can be called before or after such handling.
.Pp
The capabilities described in both
.Va struct ifp
and
.Va struct ethercom
must be set before calling
.Fn usbnet_attach_ifp .
.Sh RECEIVE AND SEND
Receive and send routines are structured around a the
.Va usbnet_cdata
and
.Va usbnet_chain
structures, then
.Dv un_ed ,
.Dv un_rx_xfer_flags ,
and
.Dv un_tx_xfer_flags ,
members, and the
.Fn uno_stop ,
.Fn uno_init ,
.Fn uno_tx_prepare ,
and
.Fn uno_rx_loop
callbacks of
.Va usbnet_ops .
.Pp
Typically, the device attach routine will fill in members of the 
.Va usbnet
structure, as listed in
.Sx AUTOCONFIGURATION .
The
.Fn un_ed
should have the
.Dv USBNET_ENDPT_RX
and
.Dv USBNET_ENDPT_TX
array entries filled in, and optionally the
.Dv USBNET_ENDPT_INTR
entry filled in if applicable.
.Pp
The optional
.Fn uno_stop
callback performs device-specific operations to shutdown the
transmit or receive handling.
.Pp
The
.Fn uno_init
callback both performs device-specific enablement and then calls
.Fn usbnet_rx_tx_init ,
which sets up the receieve, transmit, and, optionally, the interrupt
pipes, as well as starting the receive pipes.
All USB transfer setup is handled internally to the framework, and
the driver callbacks merely copy data in or out of a chain entry using
what is typically a device-specific method.
.Pp
.The
.Fn uno_rx_loop
callback converts the provided
.Va usbnet_chain
data and length into a series (one or more) of packets that are
enqueued with the higher layers using either
.Fn usbnet_enqueue
(for most devices) or
.Fn usbnet_input
for devices that currently use
.Fn if_input.
.Pp
The
.Fn uno_tx_prepare
callback must convert the provided
.Va struct mbuf
into the provided
.Va struct usbnet_chain
performing any device-specific padding, checksum, header or other.
This callback is only called once per packet.
.Pp
The
.Fa struct usbnet_chain
structure which contains a
.Dq unc_buf
member which has the chain buffer allocated where data should be
copied to or from for receive or transmit operations.
It also contains pointers back to the owning
.Fa struct usbnet ,
and the
.Va struct usbd_xfer
associated with this transfer.
.Pp
.Sh MII
For devices that have MII support these callbacks in
.Fa struct usbnet_ops
must be provided:
.Bl -tag -width 4n
.It uno_read_reg
Read an MII register for a particular PHY.
Returns
.Fr usbd_status .
.It uno_write_reg
Write an MII register for a particular PHY.
Returns
.Fr usbd_status .
.It uno_statchg
Handle a status change event for this interface.
.El
.Pp
.Pp
.Sh INTERRUPT PIPE
The interrupt speicifc callback,
.Dq uno_intr ,
is an optional callback that can be called periodically, registered by
.Nm
using the
.Fn usbd_open_pipe_intr
function (instead of the
.Fn usbd_open_pipe
function.)
To enable the
.Dq uno_intr
callback the
.Va struct usbnet
member
.Dq un_intr
must point to a
.Va struct usbnet_intr
structure that has the data buffer, size and interval to be passed to
.Fn usbd_open_pipe_intr .
.Pp
.Sh SEE ALSO
.Xr usb 4 ,
.Xr driver 9
.Xr usbdi 9
.Xr usbd_status 9
.Sh AUTHORS
.An Matthew R. Green Mt mrg@eterna.com.au
.Sh HISTORY
This
.Nm
interface first appeared in
.Nx 9.0 .