Flesh out a work in progress overview and protocol overview document
for net80211.
Details
Details
- Reviewers
bz - Group Reviewers
wireless - Commits
- rG490c53e9353f: net80211: add initial README.md and PROTOCOL.md
Diff Detail
Diff Detail
- Repository
- rG FreeBSD src repository
- Lint
Lint Skipped - Unit
Tests Skipped - Build Status
Buildable 72935 Build 69818: arc lint + arc unit
Event Timeline
Comment Actions
I stopped reading. I do not understand the PROTOCOL file for most of it. If you want an overview of the specification go and read a summary of the specification but that doesn't need to be in our tree.
The README really is at least a 70% copy of what's somehow still in our man pages without a single reference to them. I'd rather have us fix the man pages and link to them than have another duplicate copy in a 3rd markup format here.
| sys/net80211/PROTOCOL.md | ||
|---|---|---|
| 8 | None. You need an account in all cases. And it's 802.11-2024 by now. | |
| 21 | 802.11be, well, given you use "devices", it's 802.11bn but not to be outdated you better just say "and the latest generation devices" | |
Comment Actions
Consider an implementation from someone who has no knowledge of the stack. It appears as a giant wall of text. Where do you start? What's the equivalent of main() and how do the handlers interoperate?
I would benefit from a walkthrough of how the driver works:
- Step 1 - Hardware initialization and buffer allocation
- Step 2 - Creating a VAP layer
- Step 3 - Powering on
- Step 4 - State change
- Step 4 - Enabling the device to receive frames
- Step 5 - Processing frames
The interplay of the various handlers (_attach, _parent, _start, _transmit, _raw_xmit, _stop, etc) would be useful. I personally find the naming behind of _start a little confusing (seems to be more about the transmission of queued buffers). The crypto layers and key management.
What things go into the VAP layer versus the raw IC layer?
Also common idioms, such as the ring buffer, rxeof versus simple Rx, how partial frames are stored in an mbuf and processed.
A template driver would be good (I have this code: https://github.com/khanzf/i3e_driver). I also have sample dtrace scripts that might help with debugging.
On the theme of sample drivers, suggesting sample implementations from each driver to see a real-world example that keeps things simple to illustrate the point. Meaning, rtwn might not be the best, but rsu might be simpler/better.
| sys/net80211/DATAPATH_RECEIVE.md | ||
|---|---|---|
| 44 | I believe there is also validation that the rssi and nf are above a certain level. The ieee80211_add_rx_params would be good to mention here. I was having association rejected for this reason at one point. Could he mistaken... | |
| 131 | We could put what are those parameters and what are they used for? | |
| sys/net80211/DATAPATH_TRANSMIT.md | ||
| 271 | Very useful to me personally. Thank you!! | |
| 372 | Replace "actually" with "specifically", unless I am mistaken. | |
| sys/net80211/PROTOCOL.md | ||
| 18 | This raises the question of where to doesn't meet the spec and why. | |
| sys/net80211/README.md | ||
| 23 | There are some basic requirements, no? | |
| 38 | "This allows a single physical card to connect to multiple networks simultaneously by virtualizing the physical layer" or whatever more precise language | |
| sys/net80211/DATAPATH_TRANSMIT.md | ||
|---|---|---|
| 310 | Unnecessary detail. | |
| sys/net80211/README.md | ||
|---|---|---|
| 132 | FreeBSD WiFi drivers share a similar basic layout.ProbeThe goal of this stage is to determine if the driver is applicable to the device. The common idiom is to use drivername_probe(). The bus will provide the vendor and product ID to determine and it is very unlikely that the driver will need to interact with the device.
Note, this state does not "start" the device beyond what is needed to configure the device and make it ready for operations By convention, this function is named DRIVERNAME_attach. VAP ManagementThis is handled by two handlers:
These functions are used to create or delete a VAP, such as by running ifconfig wlan create wlandev rtwn or ifconfig wlan0 destroy. The driver will allocate or assign device-specific information necessary to manage multiple VAPs. Device State Changenet80211 has XXX state changes, which changes whether the state is.
By convention, these functions follow the naming convention DRIVERNAME_newstate(). Init and StopThe initialization function, typically with the naming convention DRIVERNAME_init, is used to turn the device on and notify the hardware to send new frames, either as USB URBs or DMA writes in PCI. By convention DRIVERNAME_init. The device driver should set a running variable or bit to true and, when true, allow new data traffic to be sent. Similarly, the stop method is used to stop the interface from an active state of sending new frames to the operating system. This might require telling the device to stop sending new frames, changing the power state, and clearing buffers. Note, this is not the same as shutting down the device power. By convention, this is named DRIVERNAME_stop. DetachmentThe detachment phase is called when the device is hardware removed, such as a USB unplug, or the kernel module is unloaded. The intention, where possible, is to leave the device in a working state ready for re-initialization as needed. The driver should power down the device, flush and free all buffers, delete the driver mutex and return. By convention, this function is named DRIVERNAME_detach. | |