[src/trunk]: src/share/man/man9 minor rewording of a few places and add a new...

[mrg <mrg%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/49577f38173a
branches:  trunk
changeset: 964676:49577f38173a
user:      mrg <mrg%NetBSD.org@localhost>
date:      Sun Aug 11 21:33:08 2019 +0000

description:
minor rewording of a few places and add a new section to describe
the type of changes required to port a driver to usbnet interfaces.

diffstat:

 share/man/man9/usbnet.9 |  193 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 186 insertions(+), 7 deletions(-)

diffs (226 lines):

diff -r 245776b80514 -r 49577f38173a share/man/man9/usbnet.9
--- a/share/man/man9/usbnet.9   Sun Aug 11 20:26:33 2019 +0000
+++ b/share/man/man9/usbnet.9   Sun Aug 11 21:33:08 2019 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbnet.9,v 1.2 2019/08/11 08:26:46 wiz Exp $
+.\"    $NetBSD: usbnet.9,v 1.3 2019/08/11 21:33:08 mrg Exp $
 .\"
 .\" Copyright (c) 2019 Matthew R. Green
 .\" All rights reserved.
@@ -26,7 +26,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 10, 2019
+.Dd August 11, 2019
 .Dt USBNET 9
 .Os
 .Sh NAME
@@ -599,6 +599,11 @@
 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.
 .Pp
 The
@@ -638,16 +643,190 @@
 function (instead of the
 .Fn usbd_open_pipe
 function.)
-To enable the
-.Dq uno_intr
-callback the
+To enable the this callback point the
 .Va struct usbnet
 member
 .Dq un_intr
-must point to a
+to a
 .Va struct usbnet_intr
-structure that has the data buffer, size and interval to be passed to
+structure with these members set:
+.Bl -tag -width 4n
+.It uni_buf
+Data buffer for interrupt status relies.
+.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, MII, and the
+base softc lock.
+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 Device locking
+The
+.Nm
+framework provides four locks for the system: normal device/softc lock,
+receive and transmit locks, and the MII lock.  The normal locking order
+for these locks is ifnet lock -> usbnet lock -> usbnet rxlock -> usbne
+txlock, or, ifnet lock -> usbnet lock -> MII lock.
+.It MII handling
+For devices with MII support the three normal callbacks (read, write,
+and status change) must be converted to
+.Va usbnet .
+These functions are called with the MII lock is held (see
+.Dq Fn usbnet_isowned_mii ) ,
+and do not require any checking for running, or up, or dying devices
+unless they drop and retake the MII lock.
+Their return value is changed from
+.Fr int
+to
+.Fr usbd_status
+and should use
+.Dv USBD_NORMAL_COMPLETION
+for success.
+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 functions 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 upto higher layers.
+The typical interface
+.Dq if_start
+function and any additional functions used will normal 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 Common errors
+It's common to forget to set link active on devices with MII.
+Be sure to call
+.Fn usbent_set_link
+during any status change event.
+.Pp
+Many locking issues are hidden without LOCKDEBUG, including hard-hangs.
+It's highly recommended to develop with LOCKDEBUG.
+.Pp
+The
+.Va usbnet
+.Dq un_ed
+array is unsigned and should use
+.Dq 0
+as the no-endpoint value.
+.El
+.Pp
 .Sh SEE ALSO
 .Xr usb 4 ,
 .Xr driver 9 ,