net80211: add initial README.md and PROTOCOL.md

[adrian]

Summary

Flesh out a work in progress overview and protocol overview document
for net80211.

[bz]

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"

[adrian]

add MVP debug API section

[farhan_farhan.codes]

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.

[adrian]

Add some more transmit datapath overview documentation.

[adrian]

more stuff

[adrian]

finish my first pass at the transmit path overview

next up, receive

[adrian]

add some receive documentation

[farhan_farhan.codes]

sys/net80211/DATAPATH_RECEIVE.md

43

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...

130

We could put what are those parameters and what are they used for?

sys/net80211/DATAPATH_TRANSMIT.md

270

Very useful to me personally. Thank you!!

371

Replace "actually" with "specifically", unless I am mistaken.

sys/net80211/PROTOCOL.md

17

This raises the question of where to doesn't meet the spec and why.

sys/net80211/README.md

22

There are some basic requirements, no?

37

"This allows a single physical card to connect to multiple networks simultaneously by virtualizing the physical layer" or whatever more precise language

[farhan_farhan.codes]

sys/net80211/DATAPATH_TRANSMIT.md

309

Unnecessary detail.

[farhan_farhan.codes]

sys/net80211/DATAPATH_RECEIVE.md

72

This may be a me-thing because I have not gotten this far yet, but I do not know what the decap function does.

130

"Such as rssi, nf, timestamp".