feat: Added NetBSD man pages

1 files changed, 827 insertions, 0 deletions

diff --git a/static/netbsd/man9/usbnet.9 b/static/netbsd/man9/usbnet.9
new file mode 100644
index 00000000..f87f2a0f
--- /dev/null
+++ b/static/netbsd/man9/usbnet.9
@@ -0,0 +1,827 @@
+.\"	$NetBSD: usbnet.9,v 1.23 2026/01/26 00:19:29 gutteridge 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.
+.\"
+.\" 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 March 15, 2020
+.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 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 int
+.Fn usbnet_ispromisc "struct usbnet *un"
+.Ft bool
+.Fn usbnet_isdying "struct usbnet *un"
+.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"
+.Ft void
+.Fn usbnet_attach_ifp "struct usbnet *un" "unsigned if_flags" "unsigned if_extflags" "const struct usbnet_mii *unm"
+.Ft int
+.Fn usbnet_detach "device_t dev" "int flags"
+.Ft int
+.Fn usbnet_activate "device_t dev" "devact_t act"
+.Sh DESCRIPTION
+The
+.Nm
+framework provides methods usable for USB Ethernet drivers.
+The framework has support for these features:
+.Bl -bullet -offset 8n
+.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
+Network stack locking protocol
+.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.
+A 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 slots, 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 the first member of the device softc, 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 ,
+set up 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
+When bringing an interface up from
+.Xr if_init 9 ,
+which happens under
+.Xr IFNET_LOCK 9 ,
+.Nm
+will:
+.Bl -enum
+.It
+call
+.Dq uno_init
+to initialize the hardware for sending and receiving packets,
+.It
+open the USB pipes,
+.It
+allocate Rx and Tx buffers for transfers,
+.It
+call
+.Dq uno_mcast
+to initially program the hardware multicast filter, and finally
+.It
+start the Rx transfers so packets can be received.
+.El
+.Pp
+See the
+.Sx RECEIVE AND SEND
+section for details on using the chains.
+.Pp
+When bringing an interface down from
+.Xr if_stop 9 ,
+which happens under
+.Xr IFNET_LOCK 9 ,
+.Nm
+will:
+.Bl -enum
+.It
+abort the USB pipes,
+.It
+call
+.Dq uno_stop
+to stop the hardware from receiving packets (unless the device is
+detaching),
+.It
+free Rx and Tx buffers for transfers, and
+.It
+close the USB pipes.
+.El
+.Pp
+For interface ioctl, most of the handling is in the framework.
+While the interface is running, the optional
+.Dq uno_mcast
+callback is invoked after handling the
+.Dv SIOCADDMULTI
+and
+.Dv SIOCDELMULTI
+ioctl commands to update the hardware's multicast filter from the
+.Xr ethersubr 9
+lists.
+The optional
+.Dq uno_ioctl
+callback, which is invoked under
+.Xr IFNET_LOCK 9 ,
+can be used to program special settings like offload handling.
+.Pp
+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 sending packets, the
+.Dq uno_tx_prepare
+callback must be used to convert
+an mbuf into a chain buffer ready for transmission.
+.Pp
+For devices requiring MII handling there are callbacks for reading and
+writing registers, and for status change events.
+Access to all the MII functions is serialized by
+.Nm .
+.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_ifp un
+Returns pointer to this
+.Fa un Ns 's
+.Va struct ifnet .
+.It Fn usbnet_ec un
+Returns pointer to this
+.Fa un Ns 's
+.Va struct ethercom .
+.It Fn usbnet_mii un
+Returns pointer to this
+.Fa un Ns 's
+.Va struct mii_data .
+.It Fn usbnet_rndsrc un
+Returns pointer to this
+.Fa un Ns 's
+.Va krndsource_t .
+.It Fn usbnet_softc un
+Returns pointer to this
+.Fa un Ns 's
+device softc.
+.It Fn usbnet_havelink un
+Returns true if link is active.
+.It Fn usbnet_ispromisc un
+True if
+.Dv IFF_PROMISC
+is enabled, false if not.
+.Pp
+May be used only in
+.Dq uno_init
+and
+.Dq uno_mcast .
+.Pp
+Drivers must use this in
+.Dq uno_mcast
+instead of reading
+.Li ifp->if_flags .
+.It Fn usbnet_isdying un
+Returns true if device is dying (has been pulled or deactivated,
+pending detach).
+This should be used only to abort timeout loops early.
+.El
+.Pp
+Buffer enqueue handling for
+.Fa struct usbnet :
+.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.
+.Bl -tag -width 4n
+.It Fn usbnet_attach un
+Initial stage attach of a USB network device.
+Performs internal initialization and memory allocation only \(em
+nothing is published yet.
+.It Fn usbnet_attach_ifp un if_flags if_extflags unm
+Final stage attach of a USB network device.
+Publishes the network interface to the rest of the system.
+.Pp
+If the passed in
+.Fa unm
+is
+.Pf non- Dv NULL
+then an MII interface will be created using the values
+provided in the
+.Fa struct usbnet_mii
+structure, which has these members passed to
+.Fn mii_attach :
+.Bl -tag -width "un_mii_capmask"
+.It un_mii_flags
+Flags.
+.It un_mii_capmask
+Capability mask.
+.It un_mii_phyloc
+PHY location.
+.It un_mii_offset
+PHY offset.
+.El
+.Pp
+A default
+.Fa unm
+can be set using the
+.Fn USBNET_MII_DECL_DEFAULT
+macro.
+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.
+Stops all activity and frees memory.
+Usable as
+.Xr driver 9
+detach method.
+.It Fn usbnet_activate dev act
+Device activate (deactivate) method.
+Usable as
+.Xr driver 9
+activate method.
+.El
+.Sh AUTOCONFIGURATION
+The framework expects the usbnet structure to have these members
+filled in with valid values or functions:
+.Bl -tag -width 6n
+.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 Ft void Fn (*uno_stop) "struct ifnet *ifp" "int disable"
+Stop hardware activity
+.Pq optional .
+Called under
+.Xr IFNET_LOCK 9
+when bringing the interface down, but skipped when the device is
+detaching.
+.It Ft int Fn (*uno_ioctl) "struct ifnet *ifp" "u_long cmd" "void *data"
+Handle driver-specific ioctls
+.Pq optional .
+Called under
+.Xr IFNET_LOCK 9 .
+.It Ft void Fn (*uno_mcast) "struct ifnet *"
+Program hardware multicast filters from
+.Xr ethersubr 9
+lists
+.Pq optional .
+Called between, and not during,
+.Dq uno_init
+and
+.Dq uno_stop .
+.It Ft int Fn (*uno_override_ioctl) "struct ifnet *ifp" "u_long cmd" "void *data"
+Handle all ioctls, including standard ethernet ioctls normally handled
+internally by
+.Nm
+.Pq optional .
+May or may not be called under
+.Xr IFNET_LOCK 9 .
+.It Ft int Fn (*uno_init) "struct ifnet *ifp"
+Initialize hardware activity
+.Pq optional .
+Called under
+.Xr IFNET_LOCK 9
+when bringing the interface up.
+.It Ft int Fn (*uno_read_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t *val"
+Read MII register.
+Required with MII.
+Serialized with other MII functions, and only called after
+.Dq uno_init
+and before
+.Dq uno_stop .
+.It Ft int Fn (*uno_write_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t val"
+Write MII register.
+Required with MII.
+Serialized with other MII functions, and only called after
+.Dq uno_init
+and before
+.Dq uno_stop .
+.It Ft usbd_status Fn (*uno_statchg) "struct ifnet *ifp"
+Handle MII status change.
+Required with MII.
+Serialized with other MII functions, and only called after
+.Dq uno_init
+and before
+.Dq uno_stop .
+.It Ft unsigned Fn (*uno_tx_prepare) "struct usbnet *un" "struct mbuf *m" "struct usbnet_chain *c"
+Prepare an mbuf for transmit.
+Required.
+Called sequentially between, and not during,
+.Dq uno_init
+and
+.Dq uno_stop .
+.It Ft void Fn (*uno_rx_loop) "struct usbnet *un" "struct usbnet_chain *c" "uint32_t total_len"
+Prepare one or more chain for enqueue.
+Required.
+Called sequentially between, and not during,
+.Dq uno_init
+and
+.Dq uno_stop .
+.It Ft void Fn (*uno_intr) "struct usbnet *un" "usbd_status status"
+Process periodic interrupt
+.Pq optional .
+Called sequentially between, and not during,
+.Dq uno_init
+and
+.Dq uno_stop .
+.It Ft void Fn (*uno_tick) "struct usbnet *un"
+Called every second with USB task thread context
+.Pq optional .
+Called sequentially between, and not during,
+.Dq uno_init
+and
+.Dq uno_stop .
+.El
+.It un_intr
+Points to a
+.Va struct usbnet_intr
+structure which should have these members set:
+.Bl -tag -width 4n
+.It uni_buf
+If
+.Pf non- Dv 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_bufsz
+Size of interrupt pipe buffer.
+.It uni_interval
+Frequency of the interrupt in milliseconds.
+.El
+.It un_ed
+Array of endpoint descriptors.
+There indexes are provided:
+.Dv USBNET_ENDPT_RX ,
+.Dv USBNET_ENDPT_TX ,
+and
+.Dv USBNET_ENDPT_INTR .
+The Rx and Tx endpoints are required.
+.It un_phyno
+MII phy number.
+Not used by
+.Nm .
+.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
+.Fn usbd_setup_xfer
+for receiving packets.
+.It un_tx_xfer_flags
+Passed to
+.Fn 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 the
+.Va usbnet_cdata
+and
+.Va usbnet_chain
+structures, the
+.Dv un_ed ,
+.Dv un_rx_xfer_flags ,
+and
+.Dv un_tx_xfer_flags
+members, and the
+.Fn uno_init ,
+.Fn uno_tx_prepare ,
+.Fn uno_rx_loop ,
+and
+.Fn uno_stop
+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
+.Dv un_ed
+array 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
+.Fn uno_init
+callback enables the hardware, and if necessary reprograms the hardware
+multicast filter, before the framework initiates USB Tx/Rx transfers.
+All USB transfer setup is handled by the framework.
+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, called sequentially, 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 use
+.Fn if_input .
+(This currently relies upon the
+.Va struct ifnet
+having the
+.Dq _if_input
+member set as well, which is true for current consumers.)
+.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.
+Note that this callback must check that it is not attempting to copy
+more than the chain buffer size, as set in the
+.Va usbnet
+.Dq un_tx_bufsz
+member.
+This callback is only called once per packet, sequentially.
+.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
+After aborting all USB Tx/Rx transfers when bringing an interface down,
+the framework calls the optional
+.Fn uno_stop
+callback to disable the hardware.
+.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 standard
+.Xr errno 2 .
+Must initialize the result even on failure.
+.It uno_write_reg
+Write an MII register for a particular PHY.
+Returns standard
+.Xr errno 2 .
+.It uno_statchg
+Handle a status change event for this interface.
+.El
+.Sh INTERRUPT PIPE
+The interrupt-specific 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).
+The
+.Nm
+framework provides most of the interrupt handling and the callback
+simply inspects the returned buffer as necessary.
+To enable this callback point the
+.Va struct usbnet
+member
+.Dq un_intr
+to a
+.Va struct usbnet_intr
+structure with these members set:
+.Bl -tag -width 4n
+.It uni_buf
+Data buffer for interrupt status replies.
+.It uni_bufsz
+Size of the above buffer.
+.It uni_interval
+Interval in millieconds.
+.El
+.Pp
+These values will be passed to
+.Fn usbd_open_pipe_intr .
+.Sh CONVERTING OLD-STYLE DRIVERS
+The porting of an older driver to the
+.Nm
+framework is largely an effort in deleting code.
+The process involves making these changes:
+.Bl -tag -width 4n
+.It Headers
+Many headers are included in
+.Pa usbnet.h
+and can be removed from the driver, as well as headers no longer used,
+such as
+.Pa callout.h
+and
+.Pa rndsource.h ,
+etc.
+.It Device softc
+The majority of the driver's existing
+.Dq softc
+structure can likely be replaced with usage of
+.Va struct usbnet
+and its related functionality.
+This includes at least the device_t pointer, Ethernet address, the
+ethercom and mii_data structures, end point descriptors, usbd device,
+interface, and task and callout structures (both these probably go
+away entirely) and all the associated watchdog handling,
+timevals, list size, buffer size and xfer flags for
+both Rx, and Tx, and interrupt notices, interface flags, device link,
+PHY number, chain data, locks including Rx, Tx, and MII.
+There is a driver-only
+.Dq un_flags
+in the
+.Va usbnet
+structure available for drivers to use.
+.Pp
+Many drivers can use the
+.Va usbnet
+structure as the device private storage passed to
+.Dv CFATTACH_DECL_NEW .
+Many internal functions to the driver may look better if switched to
+operate on the device's
+.Va usbnet
+as, for example, the
+.Va usbd_device
+value is now available (and must be set by the driver) in the
+.Va usbnet ,
+which may be needed for any call to
+.Fn usbd_do_request .
+The standard endpoint values must be stored in the
+.Nm
+.Dq un_ed[]
+array.
+.Pp
+As
+.Nm
+manages xfer chains all code related to the opening, closing, aborting
+and transferring of data on pipes is performed by the framework based
+upon the buffer size and more provided in
+.Va subnet ,
+so all code related to them should be deleted.
+.It Interface setup
+The vast majority of interface-specific code should be deleted.
+For device-specific interface values, the
+.Va ifnet
+flags and exflags can be set, as well as the
+.Va ethercom
+.Dq ec_capabilities
+member, before calling
+.Fn usbnet_attach_ifp .
+All calls to
+.Fn ifmedia_init ,
+.Fn mii_attach ,
+.Fn ifmedia_add ,
+.Fn ifmedia_set ,
+.Fn if_attach ,
+.Fn ether_ifattach ,
+.Fn rnd_attach_source ,
+and
+.Fn usbd_add_drv_event
+should be eliminated.
+The device
+.Dq ioctl
+routine can use the default handling with a callback for additional
+device-specific programming (multicast filters, etc.), which can be
+empty, or, the override ioctl can be used for heavier requirements.
+The device
+.Dq stop
+routine is replaced with a simple call that turns off the
+device-specific transmitter and receiver if necessary, as the
+framework handles pipes and transfers and buffers.
+.It MII handling
+For devices with MII support the three normal callbacks
+.Pq read, write, and status change
+must be converted to
+.Va usbnet .
+Local
+.Dq link
+variables need to be replaced with accesses to
+.Fn usbnet_set_link
+and
+.Fn usbnet_havelink .
+Other ifmedia callbacks that were passed to
+.Fn ifmedia_init
+should be deleted and any work moved into
+.Dq uno_statchg .
+.It Receive and Transmit
+The
+.Nm
+framework handles the majority of handling of both network directions.
+The interface init routine should keep all of the device-specific setup
+but replace all pipe management with a call to
+.Fn usbnet_init_rx_tx .
+The typical receive handling will normally be replaced with a receive
+loop function that can accept one or more packets,
+.Dq uno_rx_loop ,
+which can use either
+.Fn usbnet_enqueue
+or
+.Fn usbnet_input
+to pass the packets up to higher layers.
+The typical interface
+.Dq if_start
+function and any additional functions used will normally be replaced
+with a relatively simple
+.Dq uno_tx_prepare
+function that simply converts an
+.Va mbuf
+into a
+.Va usbnet_chain
+useful for this device that will be passed onto
+.Fn usbd_transfer .
+The framework's handling of the Tx interrupt is all internal.
+.It Interrupt pipe handling
+For devices requiring special handling of the interrupt pipe (i.e.,
+they use the
+.Fn usbd_open_pipe_intr
+method), most of the interrupt handler should be deleted, leaving
+only code that inspects the result of the interrupt transfer.
+.It Common errors
+It's common to forget to set link active on devices with MII.
+Be sure to call
+.Fn usbnet_set_link
+during any status change event.
+.Pp
+Many locking issues are hidden without
+.Dv LOCKDEBUG ,
+including hard-hangs.
+It's highly recommended to develop with
+.Dv LOCKDEBUG .
+.Pp
+The
+.Va usbnet
+.Dq un_ed
+array is unsigned and should use
+.Dq 0
+as the no-endpoint value.
+.El
+.Sh SEE ALSO
+.Xr usb 4 ,
+.Xr driver 9 ,
+.Xr usbd_status 9 ,
+.Xr usbdi 9
+.Sh HISTORY
+This
+.Nm
+interface first appeared in
+.Nx 9.0 .
+Portions of the original design are based upon ideas from
+.An Nick Hudson Aq Mt skrll@NetBSD.org .
+.Sh AUTHORS
+.An Matthew R. Green Aq Mt mrg@eterna23.net