Joshua Oreman: 802.11 wireless development

Banged out the rtl8180 driver today, based on the Linux code, and tweaked things that came up while doing it.

• [drivers 802.11] Initial import Realtek 8180/8185 driver from Linux
• [nvs] Add init function for Atmel 93C66 EEPROM
• [802.11] Tweaks to API for clarity and practicality
• [drivers rtl8180] First shot at an rtl8180/8185 driver
• [drivers rtl8180] Fix the main rtl8180 driver filename

It doesn't link yet, because the 802.11 MAC layer code hasn't been written, but it does compile.

This driver was actually surprisingly painless to work on. Like most Realtek cards, it does almost everything in the simplest way possible. The EEPROM on the card is a larger version of one already supported by gPXE's bitbasher, and the driver hasn't been in the Linux kernel long enough to accumulate cruft, so there wasn't too much for me to excise. The Linux support for this card is almost as barebones as gPXE's will be. Code for the driver excluding the variable RF part weighs in at about 3k.

For the record, the 8180 is an 802.11b-only card, and the 8185 is 802.11b/g; the programming interfaces are almost identical.

One complicating factor for this chipset is that it can be bundled with any of four RF chips, three for the 8180 and one for the 8185. So far I've implemented these using gPXE's linker tables, so the user can compile in the ones they want, e.g.

  make bin/rtl8180--rtl8180_rtl8225.lkrn

for the 802.11g card. The make syntax is a bit ugly, and there may be a way to make it nicer - perhaps the RF chip can be guessed by the PCI ID? Or we could have e.g. a rtl8185.c file that just REQUIRE_OBJECT()s rtl8180 and rtl8180_rtl8225.

The RF code for the 802.11g card is quite bulky due to an unholy number of constants that must be used to initialize the chip; it's about 8k. The 802.11b RF modules are 1k or less each.

The Linux driver shared some code with a driver supporting rtl8187 - that's the “rtl818x” that shows up some places. I'll port over the rtl8187 driver if I get some hardware that uses the chipset.

Made some pretty good progress on coding the MAC layer:

• [netdevice] Add netdev argument to ll_protocol::push, pull
• [802.11] The 802.11 MAC layer, first big commit

So far I've implemented the basic structure of everything (including a framework to fill in for crypto), link-layer encapsulation, net_device wrapping, and rx defragmentation. I still need to handle received management frames, especially those involved in associating with a network, and write said association code. The beacons received during association also need to be used to construct the lists of channels and rates on which the device can communicate, and those lists need to be freed at the appropriate time.

gPXE with the rtl8180 driver now builds cleanly, because I've stubbed the necessary 802.11 functions that haven't been implemented. If you run it it will probably time out waiting for “link-up” (which is how I've chosen to represent association to the network stack) because there's nothing going on to get the association in place.

Tomorrow I work on management frame parsing, and maybe get to test all this stuff.

More work on the MAC layer, to fill in the gaping “insert association functionality here” hole. No commits today, since I got to a state where the code had a dozen half-finished parts and I should be able to clean it up tomorrow. I realized I hadn't fully mapped out how the association process should work, so I took a break from the coding to do that; the notes are in my design notes page. I figure the association will be managed by a process that's created whenever it's needed. My goal is to have it appear to higher layers like the “link up” on a wired Ethernet link, so it needs to happen asynchronously - netdev_open() returns right away, and some time later the NETDEV_LINK_UP flag is automagically set (assuming everything works properly).

The association process will be able to be invoked by an “auto-association” method, which takes parameters from gPXE settings and is used on initial device open, and a “associate to specified” method for command-line use. The auto-associate method can just call associate-to-specified with appropriate parameters, so there's no code bloat introduced by having both, and the latter will be useful for debugging. Either of those methods starts the association process, which handles the four steps of 802.11 association in turn: set up parameters, send authentication, send association, cryptographic handshaking. The net80211_device will include a state field to report information about which parts of this have been done, so e.g. if we receive a disassociation packet from the AP we know we only need to redo the last two steps.

Weekly meeting tomorrow.

(I'm working Saturday and Sunday this week because I missed Tuesday and Wednesday.)

Notes from weekly meeting:

• Association should be triggered via a settings applicator, on netX/ssid. That setting can be handled as a netX-scoped struct setting. mcb30 gave a great explanation of how the settings system works.
• Code review of 8d60d...: The netdev argument to push/pull needs “Network device” instead of “Network device pointer” in its doxygen comments.
• Coding style issues: spaces around parentheses in non-driver code, proper Doxygen-style comments on things (row of stars down the second column) and use of @v and @ret lines for function documentation.
• Datasheet question: it'd be a good idea to email the authors of the rtl8180 drivers for Linux and/or FreeBSD and ask if they've got a sheet.
• Milestone for next week: get the MAC layer usable by Wednesday, spend remainder of time testing and bugfixing rtl8180 boot, hopefully have working boot by end of week.
• Hardware purchase issues: we found a rtl8185 card

Commits for today:

• [802.11] The 802.11 MAC layer, second big commit
• [drivers rtl8180] Updated rtl8180 driver for API changes
• [aesthetic] Adjust parenthesis spacing on net80211.[ch] to fit gPXE style

I'm almost done with the initial coding for the MAC layer; all I have left to write is the network scanning function, net80211_probe(). It looks like I should be able to start testing bug-hunting on Monday if not tomorrow.

I did some packet sniffing on my home wireless network today, and found that ordinary 2.4GHz-band consumer-grade networks generally don't even include the IEEE country information element that I had assumed we'd be able to use to set regulatory parameters. It may be possible to get at them with a probe packet, but if not, we're left guessing about maximum TX power - we'd have to use 20 dBm (maximum value for Europe and Japan) even in the US where a higher-range 27 dBm is allowable. For now I'm leaving it fixed at 20 always.

Finished the initial required MAC layer functionality, and started testing on hardware. Commits:

• [802.11] Fix sequence number fields in ieee80211.h
• [802.11] MAC layer: Add probe functionality, other small improvements
• [drivers rtl8180] Fix a couple bugs, add a bunch of debugging

If we want to support site survey (“show me a list of networks”), most of the code in net80211_probe() can be factored out into a separate function that's called from either probe() or scan(). For now I've left scan() unimplemented.

I doubt net80211.c is going to be getting much bigger; most of the remaining code bulk will be in encryption, which I plan on making separable from the main MAC layer (so you can just compile in the encryption methods you use). Currently the code size for 802.11 is 5.8k, which IMO is not so bad.

With a couple obvious bugfixes, the rtl8180 card initializes and starts receiving packets. The first serious problem I ran into involves receiving packets of at least 85 bytes (maybe lower, but more than 64): the card signals a DMA error. Everything is aligned more than required (to 1k where the card needs 256b), all DMA is using physical addresses, the rx buffer size is set to 2356, I dunno what could be going wrong. Tomorrow I'll scrutinize my changes from the Linux driver and make sure I didn't inadvertently introduce something stupid.

It does receive a great many probe request packets from my TiVo just fine, which I think is a small victory.