Module Name: src
Committed By: mrg
Date: Sat Aug 10 20:35:36 UTC 2019
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: usbnet.9
Log Message:
usbnet may be stable now. document it.
To generate a diff of this commit:
cvs rdiff -u -r1.2278 -r1.2279 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.437 -r1.438 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/usbnet.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2278 src/distrib/sets/lists/comp/mi:1.2279
--- src/distrib/sets/lists/comp/mi:1.2278 Wed Jul 24 14:07:16 2019
+++ src/distrib/sets/lists/comp/mi Sat Aug 10 20:35:35 2019
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2278 2019/07/24 14:07:16 joerg Exp $
+# $NetBSD: mi,v 1.2279 2019/08/10 20:35:35 mrg Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -11952,6 +11952,7 @@
./usr/share/man/cat9/uprintf.0 comp-sys-catman .cat
./usr/share/man/cat9/usbd_status.0 comp-sys-catman .cat
./usr/share/man/cat9/usbdi.0 comp-sys-catman .cat
+./usr/share/man/cat9/usbnet.0 comp-sys-catman .cat
./usr/share/man/cat9/useracc.0 comp-obsolete obsolete
./usr/share/man/cat9/userret.0 comp-sys-catman .cat
./usr/share/man/cat9/ustore.0 comp-sys-catman .cat
@@ -19839,6 +19840,7 @@
./usr/share/man/html9/uprintf.html comp-sys-htmlman html
./usr/share/man/html9/usbd_status.html comp-sys-htmlman html
./usr/share/man/html9/usbdi.html comp-sys-htmlman html
+./usr/share/man/html9/usbnet.html comp-sys-htmlman html
./usr/share/man/html9/userret.html comp-sys-htmlman html
./usr/share/man/html9/ustore.html comp-sys-htmlman html
./usr/share/man/html9/ustore_16.html comp-sys-htmlman html
@@ -27933,6 +27935,7 @@
./usr/share/man/man9/uprintf.9 comp-sys-man .man
./usr/share/man/man9/usbd_status.9 comp-sys-man .man
./usr/share/man/man9/usbdi.9 comp-sys-man .man
+./usr/share/man/man9/usbnet.9 comp-sys-man .man
./usr/share/man/man9/useracc.9 comp-obsolete obsolete
./usr/share/man/man9/userret.9 comp-sys-man .man
./usr/share/man/man9/ustore.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.437 src/share/man/man9/Makefile:1.438
--- src/share/man/man9/Makefile:1.437 Wed May 8 14:25:39 2019
+++ src/share/man/man9/Makefile Sat Aug 10 20:35:35 2019
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.437 2019/05/08 14:25:39 isaki Exp $
+# $NetBSD: Makefile,v 1.438 2019/08/10 20:35:35 mrg Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -53,17 +53,18 @@ MAN= accept_filter.9 accf_data.9 accf_ht
SET.9 setbit.9 setjmp.9 shutdownhook_establish.9 \
signal.9 skpc.9 sockopt.9 softintr.9 spl.9 specificdata.9 \
spi.9 splraiseipl.9 \
+ store.9 \
suspendsched.9 \
sysctl.9 sysmon_envsys.9 sysmon_pswitch.9 sysmon_taskq.9 tc.9 \
tcp_congctl.9 threadpool.9 timecounter.9 time_second.9 todr.9 \
ts2timo.9 tvtohz.9 \
- ucas.9 uiomove.9 ucom.9 userret.9 \
+ ubc.9 ucas.9 ucom.9 ufetch.9 uiomove.9 \
+ usbd_status.9 usbdi.9 usbnet.9 \
+ userret.9 \
+ uvm.9 uvm_hotplug.9 uvm_km.9 uvm_map.9 \
vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
- video.9 vme.9 \
- vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \
- ubc.9 ufetch.9 usbd_status.9 usbdi.9 ustore.9 uvm.9 uvm_hotplug.9 \
- uvm_km.9 uvm_map.9 \
- vmem.9 wapbl.9 wdc.9 workqueue.9 \
+ video.9 vme.9 vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 vmem.9 \
+ wapbl.9 wdc.9 workqueue.9 \
wsbell.9 wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9 \
xcall.9
Added files:
Index: src/share/man/man9/usbnet.9
diff -u /dev/null src/share/man/man9/usbnet.9:1.1
--- /dev/null Sat Aug 10 20:35:36 2019
+++ src/share/man/man9/usbnet.9 Sat Aug 10 20:35:35 2019
@@ -0,0 +1,663 @@
+.\" $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 m...@eterna.com.au
+.Sh HISTORY
+This
+.Nm
+interface first appeared in
+.Nx 9.0 .
