[src/trunk]: src/share/man/man9 update for usbnet_mii and read/write reg retu...

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

details:   https://anonhg.NetBSD.org/src/rev/b1ce4df0ee11
branches:  trunk
changeset: 453691:b1ce4df0ee11
user:      mrg <mrg%NetBSD.org@localhost>
date:      Fri Aug 23 05:37:05 2019 +0000

description:
update for usbnet_mii and read/write reg return change.

diffstat:

 share/man/man9/usbnet.9 |  72 +++++++++++++++++++++++++++++++-----------------
 1 files changed, 46 insertions(+), 26 deletions(-)

diffs (153 lines):

diff -r dc6ee853b57b -r b1ce4df0ee11 share/man/man9/usbnet.9
--- a/share/man/man9/usbnet.9   Fri Aug 23 04:34:51 2019 +0000
+++ b/share/man/man9/usbnet.9   Fri Aug 23 05:37:05 2019 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbnet.9,v 1.7 2019/08/15 08:37:13 wiz Exp $
+.\"    $NetBSD: usbnet.9,v 1.8 2019/08/23 05:37:05 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 14, 2019
+.Dd August 22, 2019
 .Dt USBNET 9
 .Os
 .Sh NAME
@@ -104,7 +104,7 @@
 .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"
+.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
@@ -395,13 +395,31 @@
 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
+.It Fn usbnet_attach_ifp un if_flags if_extflags unm
 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.
+If the passed in
+.Fa unm
+is non-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 4n
+.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
@@ -449,19 +467,19 @@
 Required.
 Must call
 .Fn usbnet_rx_tx_init .
-.It Ft usbd_status Fn (*uno_read_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t *val"
+.It Ft int Fn (*uno_read_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t *val"
 Read MII register.
 Required with MII.
-.It Ft usbd_status Fn (*uno_write_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t val"
+.It Ft int Fn (*uno_write_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t val"
 Write MII register.
 Required with MII.
 .It Ft usbd_status Fn (*uno_statchg) "struct ifnet *ifp"
 Handle MII status change.
 Required with MII.
-.It Ft usbd_status Fn (*uno_tx_prepare) "struct usbnet *un" "struct mbuf *m" "struct usbnet_chain *c"
+.It Ft unsigned Fn (*uno_tx_prepare) "struct usbnet *un" "struct mbuf *m" "struct usbnet_chain *c"
 Prepare an mbuf for transmit.
 Required.
-.It Ft usbd_status Fn (*uno_rx_loop) "struct usbnet *un" "struct usbnet_chain *c" "uint32_t total_len"
+.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.
 .It Ft void Fn (*uno_intr) "struct usbnet *un" "usbd_status status"
@@ -495,6 +513,8 @@
 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
@@ -594,8 +614,13 @@
 .Fn usbnet_enqueue
 (for most devices) or
 .Fn usbnet_input
-for devices that currently use
-.Fn if_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.)
 The Rx lock will be held during this call, see
 .Fn usbnet_lock_rx
 and
@@ -637,12 +662,12 @@
 .Bl -tag -width 4n
 .It uno_read_reg
 Read an MII register for a particular PHY.
-Returns
-.Xr usbd_status 9 .
+Returns standard
+.Xr errno 2 .
 .It uno_write_reg
 Write an MII register for a particular PHY.
-Returns
-.Xr usbd_status 9 .
+Returns standard
+.Xr errno 2 .
 .It uno_statchg
 Handle a status change event for this interface.
 .El
@@ -789,13 +814,6 @@
 .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
-.Vt int
-to
-.Vt usbd_status
-and should use
-.Dv USBD_NORMAL_COMPLETION
-for success.
 Local
 .Dq link
 variables need to be replaced with accesses to
@@ -868,5 +886,7 @@
 .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@localhost .
 .Sh AUTHORS
 .An Matthew R. Green Aq Mt mrg%eterna.com.au@localhost