diff options
Diffstat (limited to 'static/netbsd/man9/usbnet.9')
| -rw-r--r-- | static/netbsd/man9/usbnet.9 | 827 |
1 files changed, 827 insertions, 0 deletions
diff --git a/static/netbsd/man9/usbnet.9 b/static/netbsd/man9/usbnet.9 new file mode 100644 index 00000000..f87f2a0f --- /dev/null +++ b/static/netbsd/man9/usbnet.9 @@ -0,0 +1,827 @@ +.\" $NetBSD: usbnet.9,v 1.23 2026/01/26 00:19:29 gutteridge Exp $ +.\" +.\" Copyright (c) 2019 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 15, 2020 +.Dt USBNET 9 +.Os +.Sh NAME +.Nm usbnet +.Nd common USB Ethernet driver framework +.Sh SYNOPSIS +.In dev/usb/usbnet.h +.Ss Functions offered by usbnet.h +.Ft void +.Fn usbnet_set_link "struct usbnet *un" "bool link" +.Ft struct ifnet * +.Fn usbnet_ifp "struct usbnet *un" +.Ft struct ethercom * +.Fn usbnet_ec "struct usbnet *un" +.Ft struct mii_data * +.Fn usbnet_mii "struct usbnet *un" +.Ft krndsource_t * +.Fn usbnet_rndsrc "struct usbnet *un" +.Ft void * +.Fn usbnet_softc "struct usbnet *un" +.Ft bool +.Fn usbnet_havelink "struct usbnet *un" +.Ft int +.Fn usbnet_ispromisc "struct usbnet *un" +.Ft bool +.Fn usbnet_isdying "struct usbnet *un" +.Ft void +.Fn usbnet_enqueue "struct usbnet *un" "uint8_t *buf" "size_t buflen" "int csum_flags" "uint32_t csum_data" "int mbuf_flags" +.Ft void +.Fn usbnet_input "struct usbnet *un" "uint8_t *buf" "size_t buflen" +.Ft void +.Fn usbnet_attach "struct usbnet *un" +.Ft void +.Fn usbnet_attach_ifp "struct usbnet *un" "unsigned if_flags" "unsigned if_extflags" "const struct usbnet_mii *unm" +.Ft int +.Fn usbnet_detach "device_t dev" "int flags" +.Ft int +.Fn usbnet_activate "device_t dev" "devact_t act" +.Sh DESCRIPTION +The +.Nm +framework provides methods usable for USB Ethernet drivers. +The framework has support for these features: +.Bl -bullet -offset 8n +.It +Partial autoconf handling +.It +USB endpoint pipe handling +.It +Rx and Tx chain handling +.It +Generic handlers or support for several struct ifnet callbacks +.It +Network stack locking protocol +.It +Interrupt handling +.El +.Pp +.Nm +provides many or all of the traditional +.Dq softc +members inside +.Va struct usbnet , +which can be used directly as the device softc structure if +no additional storage is required. +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 slots, and will be passed +to the Rx and Tx callbacks. +.Pp +There is a +.Va struct usbnet_ops +structure that provides a number of optional and required callbacks +that will be described below. +.Pp +For autoconfiguration the device attach routine is expected to +ensure that this device's +.Va struct usbnet +is the first member of the device softc, 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 +.Fn usbnet_attach , +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 +.Fn usbnet_detach , +possibly directly using +.Fn usbnet_detach +as most consumers have no additional resources not owned and +released by the +.Nm +framework itself. +The device activate function should be set to +.Fn usbnet_activate . +.Pp +When bringing an interface up from +.Xr if_init 9 , +which happens under +.Xr IFNET_LOCK 9 , +.Nm +will: +.Bl -enum +.It +call +.Dq uno_init +to initialize the hardware for sending and receiving packets, +.It +open the USB pipes, +.It +allocate Rx and Tx buffers for transfers, +.It +call +.Dq uno_mcast +to initially program the hardware multicast filter, and finally +.It +start the Rx transfers so packets can be received. +.El +.Pp +See the +.Sx RECEIVE AND SEND +section for details on using the chains. +.Pp +When bringing an interface down from +.Xr if_stop 9 , +which happens under +.Xr IFNET_LOCK 9 , +.Nm +will: +.Bl -enum +.It +abort the USB pipes, +.It +call +.Dq uno_stop +to stop the hardware from receiving packets (unless the device is +detaching), +.It +free Rx and Tx buffers for transfers, and +.It +close the USB pipes. +.El +.Pp +For interface ioctl, most of the handling is in the framework. +While the interface is running, the optional +.Dq uno_mcast +callback is invoked after handling the +.Dv SIOCADDMULTI +and +.Dv SIOCDELMULTI +ioctl commands to update the hardware's multicast filter from the +.Xr ethersubr 9 +lists. +The optional +.Dq uno_ioctl +callback, which is invoked under +.Xr IFNET_LOCK 9 , +can be used to program special settings like offload handling. +.Pp +If ioctl handling requires capturing device-specific ioctls then the +.Dq uno_override_ioctl +callback may be used instead to replace the framework's +ioctl handler completely (i.e., the replacement should call any generic +ioctl handlers such as +.Fn ether_ioctl +as required). +For sending packets, the +.Dq uno_tx_prepare +callback must be used to convert +an mbuf into a chain buffer ready for transmission. +.Pp +For devices requiring MII handling there are callbacks for reading and +writing registers, and for status change events. +Access to all the MII functions is serialized by +.Nm . +.Pp +As receive must handle the case of multiple packets in one buffer, +the support is split between the driver and the framework. +A +.Dq uno_rx_loop +callback must be provided that loops over the incoming +packet data found in a chain, performs necessary checking, and passes +the network frame up the stack via either +.Fn usbnet_enqueue +or +.Fn usbnet_input . +Typically Ethernet devices prefer +.Fn usbnet_enqueue . +.Pp +General accessor functions for +.Fa struct usbnet : +.Bl -tag -width 4n +.It Fn usbnet_set_link un link +Set the link status for this +.Fa un +to +.Fa link . +.It Fn usbnet_ifp un +Returns pointer to this +.Fa un Ns 's +.Va struct ifnet . +.It Fn usbnet_ec un +Returns pointer to this +.Fa un Ns 's +.Va struct ethercom . +.It Fn usbnet_mii un +Returns pointer to this +.Fa un Ns 's +.Va struct mii_data . +.It Fn usbnet_rndsrc un +Returns pointer to this +.Fa un Ns 's +.Va krndsource_t . +.It Fn usbnet_softc un +Returns pointer to this +.Fa un Ns 's +device softc. +.It Fn usbnet_havelink un +Returns true if link is active. +.It Fn usbnet_ispromisc un +True if +.Dv IFF_PROMISC +is enabled, false if not. +.Pp +May be used only in +.Dq uno_init +and +.Dq uno_mcast . +.Pp +Drivers must use this in +.Dq uno_mcast +instead of reading +.Li ifp->if_flags . +.It Fn usbnet_isdying un +Returns true if device is dying (has been pulled or deactivated, +pending detach). +This should be used only to abort timeout loops early. +.El +.Pp +Buffer enqueue handling for +.Fa struct usbnet : +.Bl -tag -width 4n +.It Fn usbnet_enqueue un buf buflen csum_flags csum_data mbuf_flags +Enqueue buffer +.Fa buf +for length +.Fa buflen +with higher layers, using the provided +.Fa csum_flags , +and +.Fa csum_data , +which are written directly to the mbuf packet header, and +.Fa mbuf_flags , +which is or-ed into the mbuf flags for the created mbuf. +.It Fn usbnet_input un buf buflen +Enqueue buffer +.Fa buf +for length +.Fa buflen +with higher layers. +.El +.Pp +Autoconfiguration handling for +.Fa struct usbnet . +See the +.Sx AUTOCONFIGURATION +section for more details about these functions. +.Bl -tag -width 4n +.It Fn usbnet_attach un +Initial stage attach of a USB network device. +Performs internal initialization and memory allocation only \(em +nothing is published yet. +.It Fn usbnet_attach_ifp un if_flags if_extflags unm +Final stage attach of a USB network device. +Publishes the network interface to the rest of the system. +.Pp +If the passed in +.Fa unm +is +.Pf non- Dv NULL +then an MII interface will be created using the values +provided in the +.Fa struct usbnet_mii +structure, which has these members passed to +.Fn mii_attach : +.Bl -tag -width "un_mii_capmask" +.It un_mii_flags +Flags. +.It un_mii_capmask +Capability mask. +.It un_mii_phyloc +PHY location. +.It un_mii_offset +PHY offset. +.El +.Pp +A default +.Fa unm +can be set using the +.Fn USBNET_MII_DECL_DEFAULT +macro. +The +.Fa if_flags +and +.Fa if_extflags +will be or-ed into the interface flags and extflags. +.It Fn usbnet_detach dev flags +Device detach. +Stops all activity and frees memory. +Usable as +.Xr driver 9 +detach method. +.It Fn usbnet_activate dev act +Device activate (deactivate) method. +Usable as +.Xr driver 9 +activate method. +.El +.Sh AUTOCONFIGURATION +The framework expects the usbnet structure to have these members +filled in with valid values or functions: +.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. +.It un_dev +device_t saved in attach, used for messages mostly. +.It un_iface +The USB iface handle for data interactions, see +.Fn usbd_device2interface_handle +for more details. +.It un_udev +The struct usbd_device for this device, provided as the usb_attach_arg's +.Va uaa_device +member. +.It un_ops +Points to a +.Va struct usbnet_ops +structure which contains these members: +.Bl -tag -width 4n +.It Ft void Fn (*uno_stop) "struct ifnet *ifp" "int disable" +Stop hardware activity +.Pq optional . +Called under +.Xr IFNET_LOCK 9 +when bringing the interface down, but skipped when the device is +detaching. +.It Ft int Fn (*uno_ioctl) "struct ifnet *ifp" "u_long cmd" "void *data" +Handle driver-specific ioctls +.Pq optional . +Called under +.Xr IFNET_LOCK 9 . +.It Ft void Fn (*uno_mcast) "struct ifnet *" +Program hardware multicast filters from +.Xr ethersubr 9 +lists +.Pq optional . +Called between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.It Ft int Fn (*uno_override_ioctl) "struct ifnet *ifp" "u_long cmd" "void *data" +Handle all ioctls, including standard ethernet ioctls normally handled +internally by +.Nm +.Pq optional . +May or may not be called under +.Xr IFNET_LOCK 9 . +.It Ft int Fn (*uno_init) "struct ifnet *ifp" +Initialize hardware activity +.Pq optional . +Called under +.Xr IFNET_LOCK 9 +when bringing the interface up. +.It Ft int Fn (*uno_read_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t *val" +Read MII register. +Required with MII. +Serialized with other MII functions, and only called after +.Dq uno_init +and before +.Dq uno_stop . +.It Ft int Fn (*uno_write_reg) "struct usbnet *un" "int phy" "int reg" "uint16_t val" +Write MII register. +Required with MII. +Serialized with other MII functions, and only called after +.Dq uno_init +and before +.Dq uno_stop . +.It Ft usbd_status Fn (*uno_statchg) "struct ifnet *ifp" +Handle MII status change. +Required with MII. +Serialized with other MII functions, and only called after +.Dq uno_init +and before +.Dq uno_stop . +.It Ft unsigned Fn (*uno_tx_prepare) "struct usbnet *un" "struct mbuf *m" "struct usbnet_chain *c" +Prepare an mbuf for transmit. +Required. +Called sequentially between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.It Ft void Fn (*uno_rx_loop) "struct usbnet *un" "struct usbnet_chain *c" "uint32_t total_len" +Prepare one or more chain for enqueue. +Required. +Called sequentially between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.It Ft void Fn (*uno_intr) "struct usbnet *un" "usbd_status status" +Process periodic interrupt +.Pq optional . +Called sequentially between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.It Ft void Fn (*uno_tick) "struct usbnet *un" +Called every second with USB task thread context +.Pq optional . +Called sequentially between, and not during, +.Dq uno_init +and +.Dq uno_stop . +.El +.It un_intr +Points to a +.Va struct usbnet_intr +structure which should have these members set: +.Bl -tag -width 4n +.It uni_buf +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_bufsz +Size of interrupt pipe buffer. +.It uni_interval +Frequency of the interrupt in milliseconds. +.El +.It un_ed +Array of endpoint descriptors. +There indexes are provided: +.Dv USBNET_ENDPT_RX , +.Dv USBNET_ENDPT_TX , +and +.Dv USBNET_ENDPT_INTR . +The Rx and Tx endpoints are required. +.It un_phyno +MII phy number. +Not used by +.Nm . +.It un_eaddr +6 bytes of Ethernet address that must be provided before calling +.Fn usbnet_attach_ifp +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 +.Fn usbd_setup_xfer +for receiving packets. +.It un_tx_xfer_flags +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 +Number of chain elements to allocate for Tx. +.It un_rx_bufsz +Rx buffer size. +.It un_tx_bufsz +Tx buffer size. +.El +.Pp +The device detach and activate callbacks can typically be set to +.Fn usbnet_detach +and +.Fn usbnet_activate +unless device-specific handling is required, in which case, they +can be called before or after such handling. +.Pp +The capabilities described in both +.Va struct ifp +and +.Va struct ethercom +must be set before calling +.Fn usbnet_attach_ifp . +.Sh RECEIVE AND SEND +Receive and send routines are structured around the +.Va usbnet_cdata +and +.Va usbnet_chain +structures, the +.Dv un_ed , +.Dv un_rx_xfer_flags , +and +.Dv un_tx_xfer_flags +members, and the +.Fn uno_init , +.Fn uno_tx_prepare , +.Fn uno_rx_loop , +and +.Fn uno_stop +callbacks of +.Va usbnet_ops . +.Pp +Typically, the device attach routine will fill in members of the +.Va usbnet +structure, as listed in +.Sx AUTOCONFIGURATION . +The +.Dv un_ed +array should have the +.Dv USBNET_ENDPT_RX +and +.Dv USBNET_ENDPT_TX +array entries filled in, and optionally the +.Dv USBNET_ENDPT_INTR +entry filled in if applicable. +.Pp +The +.Fn uno_init +callback enables the hardware, and if necessary reprograms the hardware +multicast filter, before the framework initiates USB Tx/Rx transfers. +All USB transfer setup is handled by the framework. +The driver callbacks merely copy data in or out of a chain entry using +what is typically a device-specific method. +.Pp +The +.Fn uno_rx_loop +callback, called sequentially, converts the provided +.Va usbnet_chain +data and length into a series (one or more) of packets that are +enqueued with the higher layers using either +.Fn usbnet_enqueue +(for most devices) or +.Fn usbnet_input +for devices that use +.Fn if_input . +(This currently relies upon the +.Va struct ifnet +having the +.Dq _if_input +member set as well, which is true for current consumers.) +.Pp +The +.Fn uno_tx_prepare +callback must convert the provided +.Va struct mbuf +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, sequentially. +.Pp +The +.Fa struct usbnet_chain +structure which contains a +.Dq unc_buf +member which has the chain buffer allocated where data should be +copied to or from for receive or transmit operations. +It also contains pointers back to the owning +.Fa struct usbnet , +and the +.Va struct usbd_xfer +associated with this transfer. +.Pp +After aborting all USB Tx/Rx transfers when bringing an interface down, +the framework calls the optional +.Fn uno_stop +callback to disable the hardware. +.Sh MII +For devices that have MII support these callbacks in +.Fa struct usbnet_ops +must be provided: +.Bl -tag -width 4n +.It uno_read_reg +Read an MII register for a particular PHY. +Returns standard +.Xr errno 2 . +Must initialize the result even on failure. +.It uno_write_reg +Write an MII register for a particular PHY. +Returns standard +.Xr errno 2 . +.It uno_statchg +Handle a status change event for this interface. +.El +.Sh INTERRUPT PIPE +The interrupt-specific callback, +.Dq uno_intr , +is an optional callback that can be called periodically, registered by +.Nm +using the +.Fn usbd_open_pipe_intr +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 this callback point the +.Va struct usbnet +member +.Dq un_intr +to a +.Va struct usbnet_intr +structure with these members set: +.Bl -tag -width 4n +.It uni_buf +Data buffer for interrupt status replies. +.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, and MII. +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 MII handling +For devices with MII support the three normal callbacks +.Pq read, write, and status change +must be converted to +.Va usbnet . +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 function 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 up to higher layers. +The typical interface +.Dq if_start +function and any additional functions used will normally 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 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 +.Fn usbnet_set_link +during any status change event. +.Pp +Many locking issues are hidden without +.Dv LOCKDEBUG , +including hard-hangs. +It's highly recommended to develop with +.Dv LOCKDEBUG . +.Pp +The +.Va usbnet +.Dq un_ed +array is unsigned and should use +.Dq 0 +as the no-endpoint value. +.El +.Sh SEE ALSO +.Xr usb 4 , +.Xr driver 9 , +.Xr usbd_status 9 , +.Xr usbdi 9 +.Sh HISTORY +This +.Nm +interface first appeared in +.Nx 9.0 . +Portions of the original design are based upon ideas from +.An Nick Hudson Aq Mt skrll@NetBSD.org . +.Sh AUTHORS +.An Matthew R. Green Aq Mt mrg@eterna23.net |