Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src usbnet may be stable now. document it.
details: https://anonhg.NetBSD.org/src/rev/30dfdc77ae50
branches: trunk
changeset: 458790:30dfdc77ae50
user: mrg <mrg%NetBSD.org@localhost>
date: Sat Aug 10 20:35:35 2019 +0000
description:
usbnet may be stable now. document it.
diffstat:
distrib/sets/lists/comp/mi | 5 +-
share/man/man9/Makefile | 15 +-
share/man/man9/usbnet.9 | 663 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 675 insertions(+), 8 deletions(-)
diffs (truncated from 734 to 300 lines):
diff -r c8a6bb9cd0ca -r 30dfdc77ae50 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Sat Aug 10 20:33:01 2019 +0000
+++ b/distrib/sets/lists/comp/mi Sat Aug 10 20:35:35 2019 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2278 2019/07/24 14:07:16 joerg Exp $
+# $NetBSD: mi,v 1.2279 2019/08/10 20:35:35 mrg Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -11952,6 +11952,7 @@
./usr/share/man/cat9/uprintf.0 comp-sys-catman .cat
./usr/share/man/cat9/usbd_status.0 comp-sys-catman .cat
./usr/share/man/cat9/usbdi.0 comp-sys-catman .cat
+./usr/share/man/cat9/usbnet.0 comp-sys-catman .cat
./usr/share/man/cat9/useracc.0 comp-obsolete obsolete
./usr/share/man/cat9/userret.0 comp-sys-catman .cat
./usr/share/man/cat9/ustore.0 comp-sys-catman .cat
@@ -19839,6 +19840,7 @@
./usr/share/man/html9/uprintf.html comp-sys-htmlman html
./usr/share/man/html9/usbd_status.html comp-sys-htmlman html
./usr/share/man/html9/usbdi.html comp-sys-htmlman html
+./usr/share/man/html9/usbnet.html comp-sys-htmlman html
./usr/share/man/html9/userret.html comp-sys-htmlman html
./usr/share/man/html9/ustore.html comp-sys-htmlman html
./usr/share/man/html9/ustore_16.html comp-sys-htmlman html
@@ -27933,6 +27935,7 @@
./usr/share/man/man9/uprintf.9 comp-sys-man .man
./usr/share/man/man9/usbd_status.9 comp-sys-man .man
./usr/share/man/man9/usbdi.9 comp-sys-man .man
+./usr/share/man/man9/usbnet.9 comp-sys-man .man
./usr/share/man/man9/useracc.9 comp-obsolete obsolete
./usr/share/man/man9/userret.9 comp-sys-man .man
./usr/share/man/man9/ustore.9 comp-sys-man .man
diff -r c8a6bb9cd0ca -r 30dfdc77ae50 share/man/man9/Makefile
--- a/share/man/man9/Makefile Sat Aug 10 20:33:01 2019 +0000
+++ b/share/man/man9/Makefile Sat Aug 10 20:35:35 2019 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.437 2019/05/08 14:25:39 isaki Exp $
+# $NetBSD: Makefile,v 1.438 2019/08/10 20:35:35 mrg Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -53,17 +53,18 @@
SET.9 setbit.9 setjmp.9 shutdownhook_establish.9 \
signal.9 skpc.9 sockopt.9 softintr.9 spl.9 specificdata.9 \
spi.9 splraiseipl.9 \
+ store.9 \
suspendsched.9 \
sysctl.9 sysmon_envsys.9 sysmon_pswitch.9 sysmon_taskq.9 tc.9 \
tcp_congctl.9 threadpool.9 timecounter.9 time_second.9 todr.9 \
ts2timo.9 tvtohz.9 \
- ucas.9 uiomove.9 ucom.9 userret.9 \
+ ubc.9 ucas.9 ucom.9 ufetch.9 uiomove.9 \
+ usbd_status.9 usbdi.9 usbnet.9 \
+ userret.9 \
+ uvm.9 uvm_hotplug.9 uvm_km.9 uvm_map.9 \
vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
- video.9 vme.9 \
- vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \
- ubc.9 ufetch.9 usbd_status.9 usbdi.9 ustore.9 uvm.9 uvm_hotplug.9 \
- uvm_km.9 uvm_map.9 \
- vmem.9 wapbl.9 wdc.9 workqueue.9 \
+ video.9 vme.9 vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 vmem.9 \
+ wapbl.9 wdc.9 workqueue.9 \
wsbell.9 wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9 \
xcall.9
diff -r c8a6bb9cd0ca -r 30dfdc77ae50 share/man/man9/usbnet.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/usbnet.9 Sat Aug 10 20:35:35 2019 +0000
@@ -0,0 +1,663 @@
+.\" $NetBSD: usbnet.9,v 1.1 2019/08/10 20:35:35 mrg 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.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\"
+.\" 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 August 10, 2019
+.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 void
+.Fn usbnet_set_dying "struct usbnet *un" "bool dying"
+.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 bool
+.Fn usbnet_isdying "struct usbnet *un"
+.Ft void
+.Fn usbnet_lock "struct usbnet *un"
+.Ft void
+.Fn usbnet_unlock "struct usbnet *un"
+.Ft kmutex_t *
+.Fn usbnet_mutex "struct usbnet *un"
+.Ft void
+.Fn usbnet_isowned "struct usbnet *un"
+.Ft void
+.Fn usbnet_lock_rx "struct usbnet *un"
+.Ft void
+.Fn usbnet_unlock_rx "struct usbnet *un"
+.Ft kmutex_t *
+.Fn usbnet_mutex_rx "struct usbnet *un"
+.Ft void
+.Fn usbnet_isowned_rx "struct usbnet *un"
+.Ft void
+.Fn usbnet_lock_tx "struct usbnet *un"
+.Ft void
+.Fn usbnet_unlock_tx "struct usbnet *un"
+.Ft kmutex_t *
+.Fn usbnet_mutex_tx "struct usbnet *un"
+.Ft void
+.Fn usbnet_isowned_tx "struct usbnet *un"
+.Ft int
+.Fn usbnet_init_rx_tx "struct usbnet *un" "unsigned rxflags" "unsigned txflags"
+.Ft void
+.Fn usbnet_lock_mii "struct usbnet *un"
+.Ft void
+.Fn usbnet_lock_mii_un_locked "struct usbnet *un"
+.Ft void
+.Fn usbnet_unlock_mii "struct usbnet *un"
+.Ft void
+.Fn usbnet_unlock_mii_un_locked "struct usbnet *un"
+.Ft kmutex_t *
+.Fn usbnet_mutex_mii "struct usbnet *un"
+.Ft void
+.Fn usbnet_isowned_mii "struct usbnet *un"
+.Ft int
+.Fn usbnet_miibus_readreg "device_t dev" "int phy" "int reg" "uint16_t *val"
+.Ft int
+.Fn usbnet_miibus_writereg "device_t dev" "int phy" "int reg" "uint16_t val"
+.Ft void
+.Fn usbnet_miibus_statchg "struct ifnet *"
+.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" "const char *detname"
+.Ft void
+.Fn usbnet_attach_ifp "struct usbnet *un" "bool have_mii" "unsigned if_flags" "unsigned if_extflags" "int mii_flags"
+.Ft int
+.Fn usbnet_detach "device_t dev" "int flags"
+.Ft int
+.Fn usbnet_activate "device_t dev" "devact_t act"
+.Ft void
+.Fn usbnet_stop "struct usbnet *un" "struct ifnet *ifp" "int disable"
+.Sh DESCRIPTION
+The
+.Nm
+framework provides methods usable for USB ethernet drivers.
+The framework has support for these features:
+.Pp
+.Bl -tag -width "123456"
+.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
+MII bus locking
+.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.
+An 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
+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 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
+.Fn usbnet_attach ,
+setup 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
+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
+.Fn usbnet_init_rx_tx
+which will allocate chains, setup 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 .
+Both of
+.Fn usbnet_init_rx_tx
+and
+.Fn usbnet_stop
+must be called with the
+.Nm
+lock held, see
+.Fn usbnet_lock
+and
+.Fn usbnet_unlock .
+See the
+.Sx RECEIVE AND SEND
+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
+.Dq uno_init
+callback should perform any device specific initialisation and then call
+.Fn usbnet_init_rx_tx
+to finalise Rx and Tx queue initialisation.
+For interface ioctl, most of the handling is in the framework and the
+optional
+.Dq uno_ioctl
+callback should be used to program special settings
+like multicast filters or offload handling.
+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 interface start, the
+.Dq uno_tx_prepare
+callback must be used to convert
+an mbuf into a chain buffer ready for transmission.
+For interface stop, there is an optional
+.Dq uno_stop
+callback to turn off any chipset specific values if required.
+.Pp
+For devices requiring MII handling there are callbacks for reading and
+writing registers, and for status change events.
+The framework provides an MII-specific lock per interface which will be
Home |
Main Index |
Thread Index |
Old Index