[src-draft/trunk]: src/sys/dev/usb Add usbwifi(9) - similar to usbnet(9) but ...

[Martin Husemann <martin%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src-all/rev/e8bbca9d3ed1
branches:  trunk
changeset: 1027518:e8bbca9d3ed1
user:      Martin Husemann <martin%NetBSD.org@localhost>
date:      Fri Sep 03 17:52:14 2021 +0200

description:
Add usbwifi(9) - similar to usbnet(9) but for ieee80211 drivers

diffstat:

 distrib/sets/lists/comp/mi |     3 +
 share/man/man9/Makefile    |     2 +-
 share/man/man9/usbwifi.9   |   533 ++++++++++++++++
 sys/dev/usb/files.usb      |     4 +
 sys/dev/usb/usbwifi.c      |  1430 ++++++++++++++++++++++++++++++++++++++++++++
 sys/dev/usb/usbwifi.h      |   341 ++++++++++
 6 files changed, 2312 insertions(+), 1 deletions(-)

diffs (truncated from 2376 to 300 lines):

diff -r 84715943496d -r e8bbca9d3ed1 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Thu Jun 10 20:20:06 2021 +0200
+++ b/distrib/sets/lists/comp/mi        Fri Sep 03 17:52:14 2021 +0200
@@ -12627,6 +12627,7 @@
 ./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/usbwifi.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
@@ -20796,6 +20797,7 @@
 ./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/usbwifi.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
@@ -29172,6 +29174,7 @@
 ./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/usbwifi.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 84715943496d -r e8bbca9d3ed1 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Thu Jun 10 20:20:06 2021 +0200
+++ b/share/man/man9/Makefile   Fri Sep 03 17:52:14 2021 +0200
@@ -60,7 +60,7 @@
        tcp_congctl.9 thmap.9 threadpool.9 timecounter.9 time_second.9 todr.9 \
        ts2timo.9 tvtohz.9 \
        ubc.9 ucas.9 ucom.9 ufetch.9 uiomove.9 \
-       usbd_status.9 usbdi.9 usbnet.9 \
+       usbd_status.9 usbdi.9 usbnet.9 usbwifi.9 \
        userret.9 ustore.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 \
diff -r 84715943496d -r e8bbca9d3ed1 share/man/man9/usbwifi.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/usbwifi.9  Fri Sep 03 17:52:14 2021 +0200
@@ -0,0 +1,533 @@
+.\"    $NetBSD: usbnet.9,v 1.13 2020/08/28 16:07:49 fcambus Exp $
+.\"
+.\" Copyright (c) 2021 Martin Husemann
+.\" 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 August 21, 2021
+.Dt USBWIFI 9
+.Os
+.Sh NAME
+.Nm usbwifi
+.Nd common USB wlan driver framework
+.Sh SYNOPSIS
+.In dev/usb/usbwifi.h
+.Ss Functions offered by usbwifi.h
+.Ft void
+.Fn usbwifi_set_dying "struct usbwifi *uw" "bool dying"
+.Ft void *
+.Fn usbwifi_softc "struct usbwifi *uw"
+.Ft bool
+.Fn usbwifi_isdying "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_lock_core "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_unlock_core "struct usbwifi *uw"
+.Ft kmutex_t *
+.Fn usbwifi_mutex_core "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_isowned_core "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_busy "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_unbusy "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_lock_rx "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_unlock_rx "struct usbwifi *uw"
+.Ft kmutex_t *
+.Fn usbwifi_mutex_rx "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_isowned_rx "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_lock_tx "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_unlock_tx "struct usbwifi *uw"
+.Ft kmutex_t *
+.Fn usbwifi_mutex_tx "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_isowned_tx "struct usbwifi *uw"
+.Ft int
+.Fn usbwifi_init_rx_tx "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_enqueue "struct usbwifi *uw" "uint8_t *buf" "size_t buflen" "int rssi" "int csum_flags" "uint32_t csum_data" "int mbuf_flags"
+.Ft void
+.Fn usbwifi_attach "struct usbwifi *uw" "const char *detname"
+.Ft void
+.Fn usbwifi_ic_attach "struct usbwifi *uw" "int num_tx_chains" "int num_rx_chains" "int flags"
+.Ft void
+.Fn usbwifi_attach_finalize "struct usbwifi *uw"
+.Ft int
+.Fn usbwifi_detach "device_t self" "int flags"
+.Ft int
+.Fn usbwifi_activate "device_t self" "devact_t act"
+.Ft void
+.Fn usbwifi_stop "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_start "struct usbwifi *uw"
+.Ft void
+.Fn usbwifi_parent "struct ieee80211com *"
+.Sh DESCRIPTION
+The
+.Nm
+framework provides methods usable for USB wlan 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 net80211 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 usbwifi ,
+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 usbwifi_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 usbwifi_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 usbwifi
+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 MAC address, call
+.Fn usbwifi_attach ,
+set up additional callbacks, call
+.Fn usbwifi_ic_attach ,
+complete softc setup and finally call
+.Fn usbwifi_attach_finalize .
+The device detach routine should free any resources allocated
+by attach and then call
+.Fn usbwifi_detach ,
+possibly directly using
+.Fn usbwifi_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 usbwifi_activate .
+.Pp
+.Pp
+To manage all Rx and Tx chains the
+.Dq uwo_init
+callback of
+.Va struct usbwifi_ops
+should perform any device specific initialization and then call
+.Fn usbwifi_init_rx_tx
+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 usbwifi_stop .
+Both of
+.Fn usbwifi_init_rx_tx
+and
+.Fn usbwifi_stop
+must be called with the
+.Nm
+lock held, see
+.Fn usbwifi_lock
+and
+.Fn usbwifi_unlock .
+See the
+.Sx RECEIVE AND SEND
+section for details on using the chains.
+For interface start, the
+.Dq uwo_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 uwo_stop
+callback to turn off any chipset specific values if required.
+.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 uwo_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 usbwifi_enqueue .
+.Pp
+General accessor functions for
+.Fa struct usbwifi :
+.Bl -tag -width 4n
+.It Fn usbwifi_set_dying uw dying
+Set the dying status for this
+.Fa uw
+to
+.Fa dying .
+.It Fn usbwifi_softc uw
+Returns pointer to this
+.Fa uw's
+device softc.
+.It Fn usbwifi_isdying uw
+Returns true if device is dying (has been pulled or deactivated,
+pending detach.)
+.El
+.Pp
+Reference counting functions for
+.Fa struct usbwifi :
+.Bl -tag -width 4n
+.It Fn usbwifi_busy uw
+Increases the reference count on the driver instance, preventing
+detach from occurring while the driver is blocked accessing the
+device.
+Must be called with the core lock held.
+.It Fn usbwifi_unbusy uw
+Decreases the reference count on the driver instance.
+Once the final reference has been dropped, if a detach event
+is pending, it is allowed to proceed.
+Must be called with the core lock held.
+.El
+.Pp
+Lock handling functions for
+.Fa struct usbwifi :
+.Pp
+.Bl -tag -width 4n -compact
+.It Fn usbwifi_lock_core un
+.It Fn usbwifi_unlock_core un
+.It Fn usbwifi_isowned_core un
+.It Fn usbwifi_lock_rx un
+.It Fn usbwifi_unlock_rx un
+.It Fn usbwifi_isowned_rx un
+.It Fn usbwifi_lock_tx un
+.It Fn usbwifi_unlock_tx un
+.It Fn usbwifi_isowned_tx un
+These groups of three functions provide methods to lock,
+unlock, and assert ownership of one of the three locks provided by
+.Nm .
+The three locks are the
+.Dq core
+lock, the
+.Dq Tx
+lock, and the
+.Dq Rx
+lock.
+.El
+.Pp
+Buffer enqueue handling for
+.Fa struct usbwifi :
+.Bl -tag -width 4n
+.It Fn usbwifi_enqueue uw buf buflen rssi csum_flags csum_data mbuf_flags
+Enqueue buffer
+.Fa buf
+for length
+.Fa buflen
+with higher layers, using the provided