Module Name: src
Committed By: mrg
Date: Thu Aug 15 08:33:14 UTC 2019
Modified Files:
src/share/man/man9: usbnet.9
Log Message:
- document locking requirements more
- expand uno_foo() docs to include return type and parameters
- expand uno_intr() docs
- add uno_tick()
- fix various typoes
To generate a diff of this commit:
cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/usbnet.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/usbnet.9
diff -u src/share/man/man9/usbnet.9:1.5 src/share/man/man9/usbnet.9:1.6
--- src/share/man/man9/usbnet.9:1.5 Mon Aug 12 00:01:23 2019
+++ src/share/man/man9/usbnet.9 Thu Aug 15 08:33:14 2019
@@ -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 @@ on PHY number
.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 @@ on PHY number
.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 @@ Points to a
.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 @@ structure which should have these member
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 @@ Frequency of the interrupt in millisecon
.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 @@ The optional
.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 @@ enqueued with the higher layers using ei
.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 @@ more than the chain buffer size, as set
.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 @@ Returns
.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 @@ using the
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 @@ into a
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
