Module Name: src
Committed By: wiz
Date: Sun Aug 11 08:26:46 UTC 2019
Modified Files:
src/share/man/man9: usbnet.9
Log Message:
Various fixes: Pp cleanup, use more macros, sort sections,
fix typos, Americanize spelling (like other man pages), fix macro arguments.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 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.1 src/share/man/man9/usbnet.9:1.2
--- src/share/man/man9/usbnet.9:1.1 Sat Aug 10 20:35:35 2019
+++ src/share/man/man9/usbnet.9 Sun Aug 11 08:26:46 2019
@@ -1,4 +1,4 @@
-.\" $NetBSD: usbnet.9,v 1.1 2019/08/10 20:35:35 mrg Exp $
+.\" $NetBSD: usbnet.9,v 1.2 2019/08/11 08:26:46 wiz Exp $
.\"
.\" Copyright (c) 2019 Matthew R. Green
.\" All rights reserved.
@@ -31,7 +31,7 @@
.Os
.Sh NAME
.Nm usbnet
-.Nd common USB ethernet driver framework
+.Nd common USB Ethernet driver framework
.Sh SYNOPSIS
.In dev/usb/usbnet.h
.Ss Functions offered by usbnet.h
@@ -114,10 +114,9 @@
.Sh DESCRIPTION
The
.Nm
-framework provides methods usable for USB ethernet drivers.
+framework provides methods usable for USB Ethernet drivers.
The framework has support for these features:
-.Pp
-.Bl -tag -width "123456"
+.Bl -bullet -offset 8n
.It
Partial autoconf handling
.It
@@ -129,7 +128,7 @@ Generic handlers or support for several
.It
MII bus locking
.It
-Interrupt handling
+Interrupt handling
.El
.Pp
.Nm
@@ -139,7 +138,7 @@ members inside
.Va struct usbnet ,
which can be used directly as the device softc structure if
no additional storage is required.
-An structure exists for receive and transmit chain management,
+A structure exists for receive and transmit chain management,
.Va struct usbnet_chain ,
that tracks the metadata for each transfer descriptor available,
minimum of one each for Rx and Tx slot, and will be passed
@@ -157,9 +156,9 @@ is set to the device
.Fa dv_private ,
if it can not be used directly as the device softc, as well as set
up the necessary structure members, find end-points, find the
-ethernet address if relevant, call
+Ethernet address if relevant, call
.Fn usbnet_attach ,
-setup interface, ethernet, and MII capabilities, and finally call
+set up interface, Ethernet, and MII capabilities, and finally call
.Fn usbnet_attach_ifp .
The device detach routine should free any resources allocated
by attach and then call
@@ -177,9 +176,9 @@ To manage all Rx and Tx chains the
.Dq uno_init
callback of
.Va struct usbnet_ops
-should perform any device specific initialisation and then call
+should perform any device specific initialization and then call
.Fn usbnet_init_rx_tx
-which will allocate chains, setup and open pipes, and start the
+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 .
@@ -191,7 +190,7 @@ must be called with the
.Nm
lock held, see
.Fn usbnet_lock
-and
+and
.Fn usbnet_unlock .
See the
.Sx RECEIVE AND SEND
@@ -199,11 +198,11 @@ 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 (ie, when bringing the interface up), the
+For interface init (i.e., when bringing the interface up), the
.Dq uno_init
-callback should perform any device specific initialisation and then call
+callback should perform any device specific initialization and then call
.Fn usbnet_init_rx_tx
-to finalise Rx and Tx queue initialisation.
+to finalize Rx and Tx queue initialization.
For interface ioctl, most of the handling is in the framework and the
optional
.Dq uno_ioctl
@@ -228,11 +227,11 @@ For devices requiring MII handling there
writing registers, and for status change events.
The framework provides an MII-specific lock per interface which will be
held when calling these functions, and these locks should be used by
-internal code that also requires serialised access to registers with the
+internal code that also requires serialized access to registers with the
.Fn usbnet_lock_mii ,
.Fn usbnet_unlock_mii ,
.Fn usbnet_lock_mii_un_locked ,
-and
+and
.Fn usbnet_unlock_mii_un_locked
functions.
These functions handle device detach events safely, and as such take
@@ -252,7 +251,7 @@ the network frame up the stack via eithe
.Fn usbnet_enqueue
or
.Fn usbnet_input .
-Typically ethernet devices prefer
+Typically Ethernet devices prefer
.Fn usbnet_enqueue .
.Pp
General accessor functions for
@@ -295,11 +294,10 @@ Returns true if device is dying (has bee
pending detach.)
.El
.Pp
-
Lock handling functions for
.Fa struct usbnet :
.Pp
-.Bl -compact -tag -width 4n
+.Bl -tag -width 4n -compact
.It Fn usbnet_lock un
.It Fn usbnet_unlock un
.It Fn usbnet_isowned un
@@ -342,7 +340,6 @@ versions.
.Pp
MII access functions for
.Fa struct usbnet :
-.Pp
.Bl -tag -width 4n
.It Fn usbnet_mii_readreg dev phy reg valp
Read register
@@ -365,7 +362,6 @@ Trigger a status change update for inter
.Pp
Buffer enqueue handling for
.Fa struct usbnet :
-.Pp
.Bl -tag -width 4n
.It Fn usbnet_enqueue un buf buflen csum_flags csum_data mbuf_flags
Enqueue buffer
@@ -392,7 +388,6 @@ Autoconfiguration handling for
See the
.Sx AUTOCONFIGURATION
section for more details about these functions.
-.Pp
.Bl -tag -width 4n
.It Fn usbnet_attach un detachname
Initial stage attach of a usb network device.
@@ -419,11 +414,11 @@ Device activate (deactivate) method.
Usable as actual device method.
.It Fn usbnet_stop un ifp disable
Interface stop routine.
-.Pp
+.El
.Sh AUTOCONFIGURATION
The framework expects the usbnet structure to have these members
filled in with valid values or functions:
-.Bl -tag
+.Bl -tag -width 6n
.It un_sc
Real softc allocated by autoconf and provided to attach, should be
set to the usbnet structure if no device-specific softc is needed.
@@ -449,7 +444,7 @@ Simple ioctl callback (optional.)
.It uno_override_ioctl
Full ioctl callback (optional.)
.It uno_init
-Initialise (bring up) interface.
+Initialize (bring up) interface.
Required.
Must call
.Fn usbnet_rx_tx_init .
@@ -463,9 +458,11 @@ Required with MII.
Handle MII status change.
Required with MII.
.It uno_tx_prepare
-Prepare an mbuf for transmit. Required.
+Prepare an mbuf for transmit.
+Required.
.It uno_rx_loop
-Prepare one or more chain for enqueue. Required.
+Prepare one or more chain for enqueue.
+Required.
.It uno_intr
Process periodic interrupt (optional.)
.El
@@ -475,7 +472,9 @@ Points to a
structure which should have these members set:
.Bl -tag -width 4n
.It uni_intr_buf
-If non-NULL, points to a buffer passed to
+If
+.Pf non- Dv NULL ,
+points to a buffer passed to
Fn usbd_open_pipe_intr
in the device init callback, along with the size and interval.
.It uni_intr_bufsz
@@ -485,7 +484,7 @@ Frequency of the interrupt in millisecon
.El
.It un_ed
Array of endpoint descriptors.
-There indexes are provded:
+There indexes are provided:
.Dq USBNET_ENDPT_RX ,
.Dq USBNET_ENDPT_TX ,
and
@@ -494,18 +493,22 @@ The Rx and Tx endpoints are required.
.It un_phyno
MII phy number.
.It un_eaddr
-6 bytes of ethernet address that must be provided before calling
+6 bytes of Ethernet address that must be provided before calling
.Fn usbnet_attach_ifp
-if the device has ethernet.
+if the device has Ethernet.
.It un_flags
Device owned flags word.
The
.Nm
framework will not touch this value.
.It un_rx_xfer_flags
-Passed to usbd_setup_xfer() for receiving packets.
+Passed to
+.Fn usbd_setup_xfer
+for receiving packets.
.It un_tx_xfer_flags
-Passed to usbd_setup_xfer() for sending packets.
+Passed to
+.Fn usbd_setup_xfer
+for sending packets.
.It un_rx_list_cnt
Number of chain elements to allocate for Rx.
.It un_tx_list_cnt
@@ -534,11 +537,11 @@ Receive and send routines are structured
.Va usbnet_cdata
and
.Va usbnet_chain
-structures, then
+structures, the
.Dv un_ed ,
.Dv un_rx_xfer_flags ,
and
-.Dv un_tx_xfer_flags ,
+.Dv un_tx_xfer_flags
members, and the
.Fn uno_stop ,
.Fn uno_init ,
@@ -548,13 +551,13 @@ and
callbacks of
.Va usbnet_ops .
.Pp
-Typically, the device attach routine will fill in members of the
+Typically, the device attach routine will fill in members of the
.Va usbnet
structure, as listed in
.Sx AUTOCONFIGURATION .
The
.Fn un_ed
-should have the
+member should have the
.Dv USBNET_ENDPT_RX
and
.Dv USBNET_ENDPT_TX
@@ -571,13 +574,13 @@ The
.Fn uno_init
callback both performs device-specific enablement and then calls
.Fn usbnet_rx_tx_init ,
-which sets up the receieve, transmit, and, optionally, the interrupt
+which sets up the receive, transmit, and, optionally, the interrupt
pipes, as well as starting the receive pipes.
All USB transfer setup is handled internally to the framework, and
the driver callbacks merely copy data in or out of a chain entry using
what is typically a device-specific method.
.Pp
-.The
+The
.Fn uno_rx_loop
callback converts the provided
.Va usbnet_chain
@@ -587,7 +590,7 @@ enqueued with the higher layers using ei
(for most devices) or
.Fn usbnet_input
for devices that currently use
-.Fn if_input.
+.Fn if_input .
.Pp
The
.Fn uno_tx_prepare
@@ -609,7 +612,6 @@ It also contains pointers back to the ow
and the
.Va struct usbd_xfer
associated with this transfer.
-.Pp
.Sh MII
For devices that have MII support these callbacks in
.Fa struct usbnet_ops
@@ -618,18 +620,16 @@ must be provided:
.It uno_read_reg
Read an MII register for a particular PHY.
Returns
-.Fr usbd_status .
+.Xr usbd_status 9 .
.It uno_write_reg
Write an MII register for a particular PHY.
Returns
-.Fr usbd_status .
+.Xr usbd_status 9 .
.It uno_statchg
Handle a status change event for this interface.
.El
-.Pp
-.Pp
.Sh INTERRUPT PIPE
-The interrupt speicifc callback,
+The interrupt specific callback,
.Dq uno_intr ,
is an optional callback that can be called periodically, registered by
.Nm
@@ -648,16 +648,15 @@ must point to a
.Va struct usbnet_intr
structure that has the data buffer, size and interval to be passed to
.Fn usbd_open_pipe_intr .
-.Pp
.Sh SEE ALSO
.Xr usb 4 ,
-.Xr driver 9
+.Xr driver 9 ,
+.Xr usbd_status 9 ,
.Xr usbdi 9
-.Xr usbd_status 9
-.Sh AUTHORS
-.An Matthew R. Green Mt [email protected]
.Sh HISTORY
This
.Nm
interface first appeared in
.Nx 9.0 .
+.Sh AUTHORS
+.An Matthew R. Green Aq Mt [email protected]
