[src/trunk]: src/share/man/man9 - document locking requirements more

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

details:   https://anonhg.NetBSD.org/src/rev/93617b7ed722
branches:  trunk
changeset: 458891:93617b7ed722
user:      mrg <mrg%NetBSD.org@localhost>
date:      Thu Aug 15 08:33:14 2019 +0000

description:
- document locking requirements more
- expand uno_foo() docs to include return type and parameters
- expand uno_intr() docs
- add uno_tick()
- fix various typoes

diffstat:

 share/man/man9/usbnet.9 |  64 +++++++++++++++++++++++++++++++++++-------------
 1 files changed, 47 insertions(+), 17 deletions(-)

diffs (176 lines):

diff -r 6fe11b04676f -r 93617b7ed722 share/man/man9/usbnet.9
--- a/share/man/man9/usbnet.9   Thu Aug 15 08:30:19 2019 +0000
+++ b/share/man/man9/usbnet.9   Thu Aug 15 08:33:14 2019 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbnet.9,v 1.5 2019/08/12 00:01:23 mrg Exp $
+.\"    $NetBSD: usbnet.9,v 1.6 2019/08/15 08:33:14 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 11, 2019
+.Dd August 14, 2019
 .Dt USBNET 9
 .Os
 .Sh NAME
@@ -346,6 +346,7 @@
 .Fa phy
 and return the value in
 .Fa valp .
+Called with the MII lock held.
 .It Fn usbnet_mii_writereg dev phy reg val
 Write register
 .Fa reg
@@ -353,9 +354,11 @@
 .Fa phy
 with
 .Fa val .
+Called with the MII lock held.
 .It Fn usbnet_mii_statchg ifp
 Trigger a status change update for interface
-.Fa ifp
+.Fa ifp .
+Unlike register access, called with the MII lock not held.
 .El
 .Pp
 Buffer enqueue handling for
@@ -435,34 +438,36 @@
 .Va struct usbnet_ops
 structure which contains these members:
 .Bl -tag -width 4n
-.It uno_stop
+.It Ft void Fn (*uno_stop) "struct ifnet *ifp" "int disable"
 Stop interface (optional.)
-.It uno_ioctl
+.It Ft int Fn (*uno_ioctl) "struct ifnet *ifp" "u_long cmd" "void *data"
 Simple ioctl callback (optional.)
-.It uno_override_ioctl
+.It Ft int Fn (*uno_override_ioctl "struct ifnet *ifp" "u_long cmd" "void *data"
 Full ioctl callback (optional.)
-.It uno_init
+.It Ft int Fn (*uno_init) "struct ifnet *ifp"
 Initialize (bring up) interface.
 Required.
 Must call
 .Fn usbnet_rx_tx_init .
-.It uno_read_reg
+.It Ft usbd_status Fn (*uno_read_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t *val"
 Read MII register.
 Required with MII.
-.It uno_write_reg
+.It Ft usbd_status Fn (*uno_write_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t val"
 Write MII register.
 Required with MII.
-.It uno_statchg
+.It Ft usbd_status Fn (*uno_statchg) "struct ifnet *ifp"
 Handle MII status change.
 Required with MII.
-.It uno_tx_prepare
+.It Ft usbd_status Fn (*uno_tx_prepare) "struct usbnet *un" "struct mbuf *m" "struct usbnet_chain *c"
 Prepare an mbuf for transmit.
 Required.
-.It uno_rx_loop
+.It Ft usbd_status Fn (*uno_rx_loop) "struct usbnet *un" "struct usbnet_chain *c" "uint32_t total_len"
 Prepare one or more chain for enqueue.
 Required.
-.It uno_intr
+.It Ft void Fn (*uno_intr) "struct usbnet *un" "usbd_status status"
 Process periodic interrupt (optional.)
+.It Ft void Fn (*uno_tick) "struct usbnet *un"
+Called every second with USB task thread context (optional.)
 .El
 .It un_intr
 Points to a
@@ -473,7 +478,7 @@
 If
 .Pf non- Dv NULL ,
 points to a buffer passed to
-Fn usbd_open_pipe_intr
+.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.
@@ -483,10 +488,10 @@
 .It un_ed
 Array of endpoint descriptors.
 There indexes are provided:
-.Dq USBNET_ENDPT_RX ,
-.Dq USBNET_ENDPT_TX ,
+.Dv USBNET_ENDPT_RX ,
+.Dv USBNET_ENDPT_TX ,
 and
-.Dq USBNET_ENDPT_INTR .
+.Dv USBNET_ENDPT_INTR .
 The Rx and Tx endpoints are required.
 .It un_phyno
 MII phy number.
@@ -567,6 +572,8 @@
 .Fn uno_stop
 callback performs device-specific operations to shutdown the
 transmit or receive handling.
+.Fn uno_stop
+will be called with the usbnet lock held.
 .Pp
 The
 .Fn uno_init
@@ -589,6 +596,10 @@
 .Fn usbnet_input
 for devices that currently use
 .Fn if_input .
+The Rx lock will be held during this call, see
+.Xr Fn usbnet_lock_rx
+and
+.Xr Fn usbnet_unlock_rx .
 .Pp
 The
 .Fn uno_tx_prepare
@@ -603,6 +614,10 @@
 .Dq un_tx_bufsz
 member.
 This callback is only called once per packet.
+The Tx lock will be held during this call, see
+.Xr Fn usbnet_lock_tx
+and
+.Xr Fn usbnet_unlock_tx .
 .Pp
 The
 .Fa struct usbnet_chain
@@ -631,6 +646,11 @@
 .It uno_statchg
 Handle a status change event for this interface.
 .El
+The read and write callbacks are called with the MII lock held.
+See
+.Xr usbnet_lock_mii
+and
+.Xr usbnet_unlock_mii .
 .Sh INTERRUPT PIPE
 The interrupt specific callback,
 .Dq uno_intr ,
@@ -641,6 +661,10 @@
 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 the this callback point the
 .Va struct usbnet
 member
@@ -809,6 +833,12 @@
 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