Module Name: src Committed By: mrg Date: Sun Aug 11 21:33:09 UTC 2019
Modified Files: src/share/man/man9: usbnet.9 Log Message: 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. To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 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.2 src/share/man/man9/usbnet.9:1.3 --- src/share/man/man9/usbnet.9:1.2 Sun Aug 11 08:26:46 2019 +++ src/share/man/man9/usbnet.9 Sun Aug 11 21:33:08 2019 @@ -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 ,