File:  [NetBSD Developer Wiki] / wikisrc / tutorials / converting_usb_drivers_to_usbwifi__40__9__41__.mdwn
Revision 1.3: download - view: text, annotated - select for diffs
Thu Aug 26 17:39:30 2021 UTC (4 months, 3 weeks ago) by wiki
Branches: MAIN
CVS tags: HEAD
web commit by martin: Add driver matrix reference

    1: Before starting a driver conversion, you should have read the general instructions at [[Converting drivers to the new wifi stack]]. Many items there are marked as "not for usbwifi" though, so instead of a big list with lots of things to skip here is a todo list when converting a usb wifi driver from the old stack to usbwifi and the new stack.
    3: Note that the usbwifi(9) manual is only available in the hg branch sources!
    5: Similar to usbnet(9) the usb wifi driver to usbwifi(9) conversion is mostly an excercise in cleanup and deleting. Here is what is needed to be done:
    7:  * Rearrange the softc so `struct usbwifi` is the first member.
    9:  * Remove all parts of softc that are now in `struct usbwifi` and fixup references to them.
   10:    This typically includes the common IEEE 802.11 ic strucuture, usb device and interface
   11:    pointer.
   13:  * Initialize the members of `struct usbwifi`, setup a `struct usbwifi_ops` (see below) and
   14:    simplify the device attach function, detach function and driver declaration as described
   15:    in the AUTOCONFIGURATION section in the usbwifi(9) manual page. Besides the pointer
   16:    forward and backward referencing (`uw_sc`, `uw_dev`, `uw_udev`) make sure to setup
   17:    buffer sizes and counts as well as usb transfer flags (`uw_*_xfer_flags`, `uw_*_bufsz`,
   18:    `uw_*_list_cnt`).
   20:  * The most tricky part of the step above is getting the endpoint handling correct. Fill the
   21:    `uw_ed` array with the endpoint numbers properly sorted: all TX endpoints first (many
   22:    wifi chips offer multiple TX endpoints), sorted by priority (highest quality of service
   23:    first). Let the RX endpoints follow this. If there is an interrupt endpoint, it goes
   24:    last and you need to setup a `struct usbwifi_intr` and set its `uwi_index` entry to the
   25:    index of the interrupt endpoint in the `uw_ed` array. Next you need to assign TX indices
   26:    to the uw_ac2id array. If your chipset only has a single TX queue, all indices in this
   27:    array will be 0, if there are multiple QOS you can make some use queues/endpoints with
   28:    lower priority. All WME QOS levels need to have a valid index (which happens by default,
   29:    everything will use the first queue with highest priority). Pass the number of TX and RX
   30:    queues to `usbwifi_ic_attach` (the second stage of the usbwifi attachment).
   32:  * Overwrite the default implementations for `uw_ic` callbacks that got setup by the
   33:    framework in `usbwifi_ic_attach` where needed. At least `ic_getradiocaps` needs to be
   34:    implemented individually. When done, finish autoconfig attachment by a call to
   35:    `usbwifi_attach_finalize`.
   37:  * Remove all cargo cult locking found in most drivers. Replace by `usbwifi_lock_core`,
   38:    `usbwifi_lock_rx` and `usbwifi_lock_tx`. Think twice if you are tempted to use more locks.
   40:  * Create the callbacks needed for `struct usbwifi_ops`
   41:    * `uwo_stop` is optional. It is used to power down the radio.
   42:    * `uwo_init` brings up the radio starts the RX path. It needs to call `usbwifi_rx_tx_init`
   43:       to get the rx/tx queues initialized.
   44:    * `uwo_rx_loop` if the core part of the RX handling (everything else will be handled
   45:      by the framework). It gets passed `struct usbwifi_chain *c` as the main work item
   46:      and `len` as the amount of data in the chain. It decodes the chip specific data,
   47:      optionally updates the RX radio tap header with current data (if `uw_ic.ic_flags_ext`
   48:      has the `IEEE80211_FEXT_BPF` bit set) and passes each packet found in the chain
   49:      to the framework via a call to `usbwifi_enqueue`.
   50:    * `uwo_tx_prepare` is called for each packet transmitted. Like `uwo_rx_loop` it gets
   51:      a `struct usbwifi_chain *c` as main work item, which includes (slightly unobvious)
   52:      the mbuf to encode as `uwc_mbuf`, the target of the transmission as `uwc_ni` and
   53:      additionally is passed the "raw" priority/QOS as `qid` (one of the WME_AC_* constants).
   54:      The function encapsulates the data as needed and copies it (with any
   55:      padding and checksums needed) to `c->uwc_buf` and returns the number of bytes
   56:      copied into the chain.
   58: Look at one of the converted usb drivers on the branch (see [[Driver state matrix]] for a list of usbwifi(9) drivers and their state.)

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb