[src/trunk]: src/share/man/man9 usbnet(9): Update man page.

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

details:   https://anonhg.NetBSD.org/src/rev/d9c83642011f
branches:  trunk
changeset: 362558:d9c83642011f
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Thu Mar 03 05:57:05 2022 +0000

description:
usbnet(9): Update man page.

diffstat:

 share/man/man9/usbnet.9 |  375 ++++++++++++++++++-----------------------------
 1 files changed, 145 insertions(+), 230 deletions(-)

diffs (truncated from 603 to 300 lines):

diff -r a572e799d0b6 -r d9c83642011f share/man/man9/usbnet.9
--- a/share/man/man9/usbnet.9   Thu Mar 03 05:56:58 2022 +0000
+++ b/share/man/man9/usbnet.9   Thu Mar 03 05:57:05 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbnet.9,v 1.14 2021/12/11 19:24:19 mrg Exp $
+.\"    $NetBSD: usbnet.9,v 1.15 2022/03/03 05:57:05 riastradh Exp $
 .\"
 .\" Copyright (c) 2019 Matthew R. Green
 .\" All rights reserved.
@@ -35,8 +35,6 @@
 .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 *
@@ -52,55 +50,17 @@
 .Ft bool
 .Fn usbnet_isdying "struct usbnet *un"
 .Ft void
-.Fn usbnet_lock_core "struct usbnet *un"
-.Ft void
-.Fn usbnet_unlock_core "struct usbnet *un"
-.Ft kmutex_t *
-.Fn usbnet_mutex_core "struct usbnet *un"
-.Ft void
-.Fn usbnet_isowned_core "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 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_busy "struct usbnet *un"
-.Ft void
-.Fn usbnet_unbusy "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" "const char *detname"
+.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"
-.Ft void
-.Fn usbnet_stop "struct usbnet *un" "struct ifnet *ifp" "int disable"
 .Sh DESCRIPTION
 The
 .Nm
@@ -160,42 +120,69 @@
 The device activate function should be set to
 .Fn usbnet_activate .
 .Pp
-To manage all Rx and Tx chains the
+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
-callback of
-.Va struct usbnet_ops
-should perform any device specific initialization and then call
-.Fn usbnet_init_rx_tx
-which will allocate chains, set up 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 .
+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
-The interface init, ioctl, start, and stop, routines are handled by the
-framework with callbacks for device-specific handling.
-For interface init (i.e., when bringing the interface up), the
-.Dq uno_init
-callback should perform any device specific initialization and then call
-.Fn usbnet_init_rx_tx
-to finalize Rx and Tx queue initialization.
-For interface ioctl, most of the handling is in the framework and the
-optional
+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 should be used to program special settings
-like multicast filters or offload handling.
+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
@@ -203,26 +190,15 @@
 ioctl handlers such as
 .Fn ether_ioctl
 as required.)
-For interface start, the
+For sending packets, 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 serializes MII access with the core lock, which will be
-held when calling these functions, and this lock should be used by
-internal code that also requires serialized access to registers with the
-.Fn usbnet_lock_core
-and
-.Fn usbnet_unlock_core
-functions.
-The MII callbacks handle device detach events safely; a reference count
-is taken and released around calls to the callbacks as the MII callbacks
-usually block.
+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.
@@ -245,101 +221,32 @@
 .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
+.Fa un Ns 's
 .Va struct ifnet .
 .It Fn usbnet_ec un
 Returns pointer to this
-.Fa un's
+.Fa un Ns 's
 .Va struct ethercom .
 .It Fn usbnet_mii un
 Returns pointer to this
-.Fa un's
+.Fa un Ns 's
 .Va struct mii_data .
 .It Fn usbnet_rndsrc un
 Returns pointer to this
-.Fa un's
+.Fa un Ns 's
 .Va krndsource_t .
 .It Fn usbnet_softc un
 Returns pointer to this
-.Fa un's
+.Fa un Ns 's
 device softc.
 .It Fn usbnet_havelink un
 Returns true if link is active.
 .It Fn usbnet_isdying un
 Returns true if device is dying (has been pulled or deactivated,
-pending detach.)
-.El
-.Pp
-Reference counting functions for
-.Fa struct usbnet :
-.Bl -tag -width 4n
-.It Fn usbnet_busy un
-Increases the reference count on the driver instance, preventing
-detach from occurring while the driver is blocked accessing the
-device.
-Must be called with the core lock held.
-.It Fn usbnet_unbusy un
-Decreases the reference count on the driver instance.
-Once the final reference has been dropped, if a detach event
-is pending, it is allowed to proceed.
-Must be called with the core lock held.
-.El
-.Pp
-Lock handling functions for
-.Fa struct usbnet :
-.Pp
-.Bl -tag -width 4n -compact
-.It Fn usbnet_lock_core un
-.It Fn usbnet_unlock_core un
-.It Fn usbnet_isowned_core 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
-These groups of three functions provide methods to lock,
-unlock, and assert ownership of one of the three locks provided by
-.Nm .
-The three locks are the
-.Dq core
-lock, the
-.Dq Tx
-lock, and the
-.Dq Rx
-lock.
-.El
-.Pp
-MII access functions for
-.Fa struct usbnet :
-.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 .
-Called with the core lock held.
-.It Fn usbnet_mii_writereg dev phy reg val
-Write register
-.Fa reg