Project: Camphor

Quick note to say that I have the 3945 laptop for 1 week now, and marathon coding for next 6 days has started. By next Sunday 18 Oct, the driver will either work, or it will not work.

Please use this page for up-to-minute information.

Update 18 Oct 2009:

From the facebook page I hope people are aware that 65-70% of the driver is finished. However, there are issues with system freeze on repeated power on/off, and scanning for networks currently has some bugs according to the firmware. In other words, the driver is not functional by the deadline we had.

Thankfully though, I still have access to the laptop for 4-5 days further. So I shall continue working on the driver and see how far we get. I’m hoping at least unsecured connection is working by then! As usual, more up-to-the-minute updates are posted on the FB page linked above. Cheers!

It’s about time I consolidated the previous status updates into a blog entry of its own for those not following the facebook page.

Around 20% of the HAL is coded by now. Lots of support functions were first written, followed by code for uploading firmware and microcode to the card. A particularly nasty bug with VoodooWireless was also tracked down and fixed which was causing kernel panics on scans yielding no results.

What’s left now for completion of Stage 1 (i.e. firmware stage) is to finish implementing the allocation and initialization of Rx, Tx and command rings. Once this is done, the driver will be able to turn the card on or off, load the firmware and make it ready or action. Those following the project for 2200BG driver will remember that this was a major part of the work for that driver — once this was completed and working, the rest was simply a matter of time.

Comparison between 3945 and 2200

It’s interesting to compare the two cards to see what will be different for 3945 HAL compared to the experience of writing driver for 2200.

The 3945 is actually a 100% Intel-designed wireless card (partly to avoid licensing issues), so it differs in many ways from the 2200BG. Incidentally, although the Stage 1 code for 3945 is simpler than 2200, most of the things following that are more complicated. They moved a lot of work out of the hardware and put it into software - for example, to scan for networks, in 2200 you just prepared the scan parameters and channel list and sent the scan command to the hardware. In 3945 from what I can see so far, you have to manually create the actual probe request that is sent, then switch the channels manually to scan for each.

There are also some other changes - in 2200, the firmware automatically chose the best transmit rate so the driver didn’t have to do anything other than send the packet out. In 3945, the firmware doesn’t do this and the driver has to actually configure the tx data rates itself, mostly based on the adapter’s temperature checked every minute.

So all in all, the amount of code reduced in Stage 1 (firmware stage) is basically balanced (actually exceeded by a small amount) by the increase in code in Stage 2.

ETA

Currently we have clocked about 11 hours for the 3945 HAL. My expectation is that it will take around 40 to 50 hours to finish, which leaves at least around 30 more hours of work before it can go into beta.

Testing

In other news, fassl from Voodoo Labs, who worked on much of the Chameleon GUI, has offered to help his expertise in alpha-and-beta testing of the 3945 HAL. Since I am well aware of his expertise and prefer to keep things in-house, at least until stage 1 is done, I plan to work with him exclusively for testing. Afterwards we’ll use the loooong beta testers list I’ve compiled from your emails.

That’s all the updates for now. It is likely that Stage 1 will be completed in the next couple of days. News will be provided as and when it happens. Thanks for staying with me patiently.

Misc

The donation link is gone until 3945 HAL is finished. What would you guys’ opinion be on putting Google Ads on the blog?

Many people asked me to create twitter account so they could follow up-to-the-minute progress. So I created a facebook page instead because my twitter account is for personal use :P

The FB page offers more features like photo albums and discussion in addition to twitter-like short updates. Feel free to subscribe to it. This blog will contain only more major updates.

As for progress: firmware upload is still being worked upon, should be done today.

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.