Project: Camphor

Just got done with creating the 3945 HAL template based on VoodooWireless. There is barely any hardware-specific code in it right now, but the kext project and the subclassed functions are there with a few basic (getHardwareInfo() etc.) functions implemented. Firmware is converted. From here on, it’s a lot of mechanical work with a little bit of careful thinking and added technique, to finish implementing the remaining 10 or so hardware-specific functions.

This is gonna be one hell of a ride because I can’t test anything until I finish coding all of it, and even then it’ll be external testers. Exciting! :-D Expecting to finish it in a few days (depending on any difficulties encountered during the course, and how busy I am), and then beta testing can begin. (Alert: beta testers who sent me an email, you might receive a beta driver from me this week.)

NOTE: For the umpteenth time, please do NOT send me ANY MORE emails asking to be a beta tester. Every day I get a few emails, and right now I must have like 60-70 people on the list, maybe more. Out of those I have chosen only 3 or 4 who will participate in the test initially, based on their credentials. As the hardware is going to be the same for all, I don’t need 200 testers during this phase. So the rest of the list is “reserve.”

Updates will continue during the next few days of heavy-weight coding, of course.

As everyone probably knows, VoodooWireless is the major component which allows a hardware abstraction layer for a card to talk with OS X. This layer implements a nano-sized 802.11 (Wifi) stack and handles all Airport-related stuff. Few weeks ago I posted that this part was completed, and I’m trying to fix some bugs in it.

Today the bug with packet transmission was fixed (it was an incorrectly copied BSSID address in the wifi header - Apple’s association requests typically zero out the BSSID and the driver must scan for that on its own). Once that was fixed, the 2200 HAL was able to get an IP address and small packets were flowing.

But larger packets weren’t, and so web surfing or any non-trivial network activity wasn’t working. Further testing showed a very peculiar behaviour : Packets up to length 168 were being transmitted fine, but those from length 169 onwards were not. Turns out to be a problem in Apple networking stack (I think so), where the larger packets are not coalesced into one mbuf before being sent to VoodooWireless.

So those are the updates for now - currently trying to fix the problem with un-coalesced packets. After this, there is one little To-Do left with the scan results handling part.

UPDATE (40min later): OK, the large-packet coalesce bug is fixed. Had to manually coalesce the mbuf chain, but it works. I’m now online via the totally rewritten VoodooWireless + 2200BG HAL architecture! :-)

So now I’ll make the small scan-handling change and then 3945 is probably only a few days away.

Hey guys, sorry for the lack of activity recently. I’m out of town these days. Progress update will come when there’s something worthwhile to report. 3945 target is still within this month I hope.

And two reminders —

1. I am not looking for any more beta testers!

2. I am not looking for a 3945 card because it is incompatible with my laptop!

Oh and one more thing: All the early donators deserve another big thank you — my laptop screen’s hinge got broken a few days ago and it’s literally just hanging on one hinge. But thanks to the donations I was able to immediately order a replacement set which should arrive by the time I get home [this weekend] so no interruption in coding :) Thank you all.

I now have enough interested testers. Even if you didn’t get a reply directly, if you’ve emailed me, you are added to the pool of testers. There are some who I have contacted directly, who are first in line to get any beta versions when required. If they disappear or are otherwise unable to test, others from the pool will be contacted.

Progress

As a test case I’ve ported the 2200BG driver to VoodooWireless — the hardware-specific driver code is now a paltry 1550 lines of code! This is the smallest out of all existing drivers for this wireless adapter — less than half of the size of the FreeBSD driver, and 10% the size of the Linux driver! Adding support for Ad-Hoc mode should take no more than 200 lines of code in the HAL (and some more in VoodooWireless). WEP and WPA support can theoretically be added without modifying the HAL at all.

Unfortunately there are some bugs remaining in VoodooWireless. The scanning part is working well but there is some bug with transmission of packets. I’m currently trying to debug those.

3945 HAL is currently blocked on this, as the bug with packet Tx could be either in VoodooWireless or the 2200 HAL.

In any case, I’m moving towards having a working 3945 driver this month:)

Testing still remains, but the coding part is done.

Some statistics:

• Lines of Code — Total: 2736, VoodooWireless only: 2200, VoodooWireless Ciphers only: 536 (WEP encryption only right now, decryption and WPA to be added later)

• Time taken: 58 hr 45 min

• Lines of code / hour = about 46

The API is basically finalized and I don’t envision any changes immediately, except of course when new features like WPA, hardware crypto, .11n or Ad-Hoc mode are added. For a first version I decided to only implement .11b/g (.11a will come soon) connections with WEP in Infrastructure mode. This should cover a lot of users already.

A clipping of the eight (8) hardware-specific functions that HAL writers will need to implement —

Next in line are:

1. Port over the existing 2200BG driver to VoodooWireless and make sure no bugs remain in it. Now I know people will be up in arms about this, but there is no other way to test that the VoodooWireless code actually works. This might take a day or two.

2. When I’m convinced the code works, I’ll port over the FreeBSD wpi driver for the 3945ABG card. This will probably take 4 or 5 days.

Looking for 3945 testers

Now, something important. The inevitable has happened and I no longer have access to the 3945 card anymore. That means I’ll need to code it blind and rely on external testers. Coding part shouldn’t be that difficult anymore (I hope), but the testing probably will be so.

I’m looking for 2 or 3 experienced testers for 3945. The criterion is that you should have a good understanding of how OS X works, how wireless networks work, and how to debug driver issues (e.g. I will not tell you how to load the test drivers, or what to do when you get a kernel panic, or how to change your router settings). The second criterion is that you must be available and able to respond to emails and send test results fast. I’m talking 10 test versions of the driver a day, or something in its vicinity. I usually test drivers 20 times a day! If I rely on external testers, I don’t want to be waiting all day for a test report.

If you think you fit the criteria, and want to help with testing, write me an email at voodoo@mercurysquad.com. I am expecting a lot of messages; so to help me pick, please include any past testing/coding experience or similar information.

NOTE: Just to stay clear, there is NO alpha or beta driver for 3945 yet! The coding/testing will run in parallel all this week.

Just a quick update.

The hardware-independent part of VoodooWireless framework is almost completed. What remains is handling of scan results, and handling the various apple80211Request() function calls and mapping relevant ones to hardware-dependent functions.

Out of these the first part is somewhat complicated as a lot of decisions need to be taken on which results to store, for how long, when to renew them, which ones to send to Airport, which ones to choose while associating, and so on. The second part is more mechanical work, as there are something like 25-30 message types to respond to (or map to hardware-dependent function calls).

Once these are done, the hardware-dependent parts of the HAL (for 3945) will be written. I’ve gone through the FreeBSD wpi driver already during my trip last week, and have a somewhat clear idea of how this card works. It is different than 2200BG in many respects, but also similar in many other respects. Some things that the 2200BG firmware handled for us, need to be handled in software for the 3945 (like manually creating probe request frames for scanning). But other things are more streamlined that 2200BG.

All in all, it should be an interesting experience. Let’s see how long it takes to complete.

Total time logged so far is 336 hours, out of which 46 hours have been spent working on the “new” architecture.

I’m publishing here an early preview of the API used to create wireless device HALs for VoodooWireless.

There have been many big changes from the initial API that I designed. The most important change is that the HALs will no longer be a provider nub for the VoodooAirportBridge client — that design got way too complicated, for both development and testing, from the client’s as well as the provider’s points of view.

The simplified design is a ‘superclass’ which derives from IO80211Controller. HALs will need to derive from this subclass and implement some hardware-specific functions. HALs will need to call some functions provided by the superclass when events happen (like card is turned off, scanning is completed, or data is received).

Most of the hard work will be handled by the VoodooWirelessDevice superclass, and HALs will typically only need to implement hardware-specific code. For example, driver writers will not need to worry about parsing probe responses to get scan results and network information — they simply pass the incoming packets up to the superclass which will take care of the rest.

Given below is source code of most header files that will be used during development of HALs. Hope this is useful to those who are planning to help write HALs for cards like 4965 or 5100.

IMPORTANT: All this source code is made available for preview/academic purpose only and the copyright remains with me (the author).

Click to view the source code

Note that it is not always possible to finalize the APIs before starting to use it. So, big and small changes are expected. To repeat myself: this is only a preview designed to give prospective developers an idea of how the final API might look like.

I am back now and work on 3945 has started.

No other updates currently, it’s still in very early stages.

A slightly updated and bug-fixed version of the 2200BG® driver is available from the Download page now.

It has many small and big fixes which I don’t have time to describe in detail now, but in brief:

1. Fixed bug in setting antenna sensitivity to large dBm values. Connections should be more stable now. Also changed antenna to “auto” (firmware selects best antenna) instead of “slow diversity” - should provide better reception in weak signal.

2. Fixed some transmit queue related problems: freeing mbufs and transmitting mbufs is now more robust in laggy connections.

3. Now using just the first Tx queue instead of all four: to try to get rid of firmware resets during heavy transfer while using WEP.

4. Changes in background scan watchdog, but it doesn’t work well yet.

5. Misc fixes..

Estimate time of availability for 3945 driver and WPA support

ETA for 3945: this is a blind guess but I’m hoping to get it working with WEP by the end of the month.

ETA for WPA: this will take more time that I had thought, so it’s postponed until 3945+WEP is working. (Note: WPA support will be common to all drivers so it only needs to be written once).

Getting debug logs

If you want to investigate any problems with the 2200bg kext, you can get extended debug logs in your Console by setting a sysctl key as follows (in Terminal):

sudo sysctl -w debug.voodoowireless=xx

Replace xx with any sum of the following values to selectively display debug messages:

    dbgUnused   = 1,        // (currently unused)
    dbgFatal    = 2,        // Fatal/abort errors
    dbgWarning  = 4,        // Warning messages
    dbgInfo     = 8,        // General informational messages
    dbgIoctl    = 16,       // apple80211request messages
    dbgRxTx     = 32,       // Rx/tx of packets
    dbgBeacons  = 64,       // incoming beacons
    dbgEntryExit    = 128,      // Function entry and exit logs
    dbgDump     = 256,      // rx/tx packet dumps
    dbgEverything   = 0xFFFFFFFF    // All levels of debugging

The most useful value is 14 (ie. display Fatal errors, warnings and useful information).

That said, I won’t be available for the next few days, so no updates or responses to comments. Have a good week everyone.

I have uploaded beta version 04 of the driver for 2200BG. Everyone is advised to update.

This version fixes a very important bug in previous versions which was preventing the card from connecting in 11g and working at full speeds.

It is available from the Downloads page.

Note that in WEP networks during long transfers at high speeds, I have experienced frequent firmware errors resulting in the driver shutting down the card. If this happens with you, either lower the maximum connection speed in your access point’s configuration, or use the debug.wirelessmode sysctl key to force the driver to always connect at 11b speeds only.

By default the driver prefers 11g mode if available.