minor rewording of a few places and add a new section to describe
the type of changes required to port a driver to usbnet interfaces.
This commit is contained in:
mrg
parent
04ad65d955
commit
fc57de4558
|
|
@ -1,4 +1,4 @@
|
|||
.\" $NetBSD: usbnet.9,v 1.2 2019/08/11 08:26:46 wiz Exp $
|
||||
.\" $NetBSD: usbnet.9,v 1.3 2019/08/11 21:33:08 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 10, 2019
|
||||
.Dd August 11, 2019
|
||||
.Dt USBNET 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
|
@ -599,6 +599,11 @@ callback must convert the provided
|
|||
into the provided
|
||||
.Va struct usbnet_chain
|
||||
performing any device-specific padding, checksum, header or other.
|
||||
Note that this callback must check that it is not attempting to copy
|
||||
more than the chain buffer size, as set in the
|
||||
.Va usbnet
|
||||
.Dq un_tx_bufsz
|
||||
member.
|
||||
This callback is only called once per packet.
|
||||
.Pp
|
||||
The
|
||||
|
|
@ -638,16 +643,190 @@ using the
|
|||
function (instead of the
|
||||
.Fn usbd_open_pipe
|
||||
function.)
|
||||
To enable the
|
||||
.Dq uno_intr
|
||||
callback the
|
||||
To enable the this callback point the
|
||||
.Va struct usbnet
|
||||
member
|
||||
.Dq un_intr
|
||||
must point to a
|
||||
to a
|
||||
.Va struct usbnet_intr
|
||||
structure that has the data buffer, size and interval to be passed to
|
||||
structure with these members set:
|
||||
.Bl -tag -width 4n
|
||||
.It uni_buf
|
||||
Data buffer for interrupt status relies.
|
||||
.It uni_bufsz
|
||||
Size of the above buffer.
|
||||
.It uni_interval
|
||||
Interval in millieconds.
|
||||
.El
|
||||
.Pp
|
||||
These values will be passed to
|
||||
.Fn usbd_open_pipe_intr .
|
||||
.Sh CONVERTING OLD-STYLE DRIVERS
|
||||
The porting of an older driver to the
|
||||
.Nm
|
||||
framework is largely an effort in deleting code.
|
||||
The process involves making these changes:
|
||||
.Bl -tag -width 4n
|
||||
.It Headers
|
||||
Many headers are included in
|
||||
.Pa usbnet.h
|
||||
and can be removed from the driver, as well as headers no longer used,
|
||||
such as
|
||||
.Pa callout.h
|
||||
and
|
||||
.Pa rndsource.h ,
|
||||
etc.
|
||||
.It Device softc
|
||||
The majority of the driver's existing
|
||||
.Dq softc
|
||||
structure can likely be replaced with usage of
|
||||
.Va struct usbnet
|
||||
and its related functionality.
|
||||
This includes at least the device_t pointer, ethernet address, the
|
||||
ethercom and mii_data structures, end point descriptors, usbd device,
|
||||
interface, and task and callout structures (both these probably go
|
||||
away entirely) and all the associated watchdog handling,
|
||||
timevals, list size, buffer size and xfer flags for
|
||||
both Rx, and Tx, and interrupt notices, interface flags, device link,
|
||||
PHY number, chain data, locks including Rx, Tx, MII, and the
|
||||
base softc lock.
|
||||
There is a driver-only
|
||||
.Dq un_flags
|
||||
in the
|
||||
.Va usbnet
|
||||
structure available for drivers to use.
|
||||
.Pp
|
||||
Many drivers can use the
|
||||
.Va usbnet
|
||||
structure as the device private storage passed to
|
||||
.Dv CFATTACH_DECL_NEW .
|
||||
Many internal functions to the driver may look better if switched to
|
||||
operate on the device's
|
||||
.Va usbnet
|
||||
as, for example, the
|
||||
.Va usbd_device
|
||||
value is now available (and must be set by the driver) in the
|
||||
.Va usbnet ,
|
||||
which may be needed for any call to
|
||||
.Fn usbd_do_request .
|
||||
The standard endpoint values must be stored in the
|
||||
.Nm
|
||||
.Dq un_ed[]
|
||||
array.
|
||||
.Pp
|
||||
As
|
||||
.Nm
|
||||
manages xfer chains all code related to the opening, closing, aborting
|
||||
and transferring of data on pipes is performed by the framework based
|
||||
upon the buffer size and more provided in
|
||||
.Va subnet ,
|
||||
so all code related to them should be deleted.
|
||||
.It Interface setup
|
||||
The vast majority of interface specific code should be deleted.
|
||||
For device-specific interface values, the
|
||||
.Va ifnet
|
||||
flags and exflags can be set, as well as the
|
||||
.Va ethercom
|
||||
.Dq ec_capabilities
|
||||
member, before calling
|
||||
.Fn usbnet_attach_ifp .
|
||||
All calls to
|
||||
.Fn ifmedia_init ,
|
||||
.Fn mii_attach ,
|
||||
.Fn ifmedia_add ,
|
||||
.Fn ifmedia_set ,
|
||||
.Fn if_attach ,
|
||||
.Fn ether_ifattach ,
|
||||
.Fn rnd_attach_source ,
|
||||
and
|
||||
.Fn usbd_add_drv_event
|
||||
should be eliminated.
|
||||
The device
|
||||
.Dq ioctl
|
||||
routine can use the default handling with a callback for additional
|
||||
device specific programming (multicast filters, etc.), which can be
|
||||
empty, or, the override ioctl can be used for heavier requirements.
|
||||
The device
|
||||
.Dq stop
|
||||
routine is replaced with a simple call that turns off the
|
||||
device-specific transmitter and receiver if necessary, as the
|
||||
framework handles pipes and transfers and buffers.
|
||||
.It Device locking
|
||||
The
|
||||
.Nm
|
||||
framework provides four locks for the system: normal device/softc lock,
|
||||
receive and transmit locks, and the MII lock. The normal locking order
|
||||
for these locks is ifnet lock -> usbnet lock -> usbnet rxlock -> usbne
|
||||
txlock, or, ifnet lock -> usbnet lock -> MII lock.
|
||||
.It MII handling
|
||||
For devices with MII support the three normal callbacks (read, write,
|
||||
and status change) must be converted to
|
||||
.Va usbnet .
|
||||
These functions are called with the MII lock is held (see
|
||||
.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
|
||||
.Fr int
|
||||
to
|
||||
.Fr usbd_status
|
||||
and should use
|
||||
.Dv USBD_NORMAL_COMPLETION
|
||||
for success.
|
||||
Local
|
||||
.Dq link
|
||||
variables need to be replaced with accesses to
|
||||
.Fn usbnet_set_link
|
||||
and
|
||||
.Fn usbnet_havelink .
|
||||
Other ifmedia callbacks that were passed to
|
||||
.Fn ifmedia_init
|
||||
should be deleted and any work moved into
|
||||
.Dq uno_statchg .
|
||||
.It Receive and Transmit
|
||||
The
|
||||
.Nm
|
||||
framework handles the majority of handling of both network directions.
|
||||
The interface init routine should keep all of the device specific setup
|
||||
but replace all pipe management with a call to
|
||||
.Fn usbnet_init_rx_tx .
|
||||
The typical receive handling will normally be replaced with a receive
|
||||
loop functions that can accept one or more packets,
|
||||
.Dq uno_rx_loop ,
|
||||
which can use either
|
||||
.Fn usbnet_enqueue
|
||||
or
|
||||
.Fn usbnet_input
|
||||
to pass the packets upto higher layers.
|
||||
The typical interface
|
||||
.Dq if_start
|
||||
function and any additional functions used will normal be replaced
|
||||
with a relatively simple
|
||||
.Dq uno_tx_prepare
|
||||
function that simply converts an
|
||||
.Va mbuf
|
||||
into a
|
||||
.Va usbnet_chain
|
||||
useful for this device that will be passed onto
|
||||
.Fn usbd_transfer .
|
||||
The framework's handling of the Tx interrupt is all internal.
|
||||
.It Common errors
|
||||
It's common to forget to set link active on devices with MII.
|
||||
Be sure to call
|
||||
.Fn usbent_set_link
|
||||
during any status change event.
|
||||
.Pp
|
||||
Many locking issues are hidden without LOCKDEBUG, including hard-hangs.
|
||||
It's highly recommended to develop with LOCKDEBUG.
|
||||
.Pp
|
||||
The
|
||||
.Va usbnet
|
||||
.Dq un_ed
|
||||
array is unsigned and should use
|
||||
.Dq 0
|
||||
as the no-endpoint value.
|
||||
.El
|
||||
.Pp
|
||||
.Sh SEE ALSO
|
||||
.Xr usb 4 ,
|
||||
.Xr driver 9 ,
|
||||
|
|
|
|||
Loading…
Reference in New Issue