幽灵狼

Introducing Evil

One of the problems plaguing the Free Software community is the availability of device drivers. Unless an operating system has a significant market share, it does not make economic sense for a manufacturer to write device drivers for that system. Many manufacturers won't even provide documentation allowing open source drivers to be written, claiming that it would require disclosure of valuable intellectual property.

In the case of WiFi cards, this can be a problem. It is very difficult to tell in advance which chipset is used in a given card - some manufacturers change the hardware completely without changing the model number - and so finding a WiFi card compatible with your favourite OS can be difficult.

OpenBSD has a strong ideological attitude in this respect. If a manufacturer is not willing to release documentation, then they will not include closed-source drivers. This argument makes sense from a security point of view - if the drivers are closed then you can't audit them and so they may end up compromising the base system.

FreeBSD is more pragmatic. They include Project Evil, a partial implementation of the Windows driver API, which allows Windows drivers to be used for network cards. While not quite as useful as a native driver, they are a significant improvement over no driver at all.

How does it work?

Project Evil provides a set of basic functions commonly used by Windows network drivers. These functions are then translated internally to the FreeBSD driver model. To the driver, it appears that it is running in a normal Windows environment. To the OS, it appears that a native FreeBSD kernel module containing the driver is present.

On Windows, a WiFi driver comes in three components. The driver itself usually has the extension .sys. There is also a .inf file which contains information about the driver, such as the device ID of the hardware. Finally there is a copy of the driver firmware.

Traditionally, the firmware - software embedded in the device - for a network interface would be burned into ROM and shipped with the card. Then it was realised that the ability to update the firmware was desirable and so it was put in Flash, or similar. In modern, low budget, cards, the Flash is left off, and the firmware is stored in RAM. This means that the driver must load it before the card can be used.

To make matters more complicated, some drivers have separate firmware for the ethernet controller and radio portions of the firmware. Firmware files usually have the .bin extension.

Building the kernel modules

You will need a copy of the Windows driver. This will probably be on a CD included with your network card, or available from the manufacturer's web site. You should copy everything with a .sys, .inf, or .bin extension to /sys/modules/if_ndis.

I will use the file names of my driver for the rest of this tutorial, but you should substitute your own. The files supplied for my card are:

Fw1130.bin

Network interface firmware.

FwRad16.bin

Radio firmware.

TNET1130.INF

Driver information file.

tnet1130.sys

Driver binary.

The way of generating Project Evil kernel modules changed between FreeBSD 5.3 and FreeBSD 5.4, and unfortunately the documentation shipped with 5.4 still reflects the 5.3 method which no longer works. I will explain both methods.

It might be worth upgrading to -STABLE before you start, as work on Project Evil is constantly in progress - my interface wouldn't work with FreeBSD 5.3, but it would with a snapshot of -STABLE a couple of weeks after the release.

The old way

Before you start you will need to have the kernel sources for the release you are running installed.

The old way of installing a Project Evil module required you to build three different modules - the ndis stub driver, a specific driver for your card, and a module containing the firmware. This can be done with the following commands:

# cd /sys/modules/ndis
# make depend
...
# make
...
# make install
...
# cd ../if_ndis
# ndiscvt -i TNET1130.INF -s tnet1130.sys 
-f Fw1130.bin -o ndis_driver_data.h
...
# make depend
...
# make
...
# make install
# ndiscvt -f FwRad16.bin
# cp FwRad16.bin.ko /boot/kernel

The driver should now be installed. The next step is to test it. The driver will not work if it can't find the firmware, so the order in which these are loaded is important.

# kldload FwRad16.bin
# kldload if_ndis

The driver should now be loaded. The easiest way to configure the adapter is to run /stand/sysinstall and follow the instructions.

If you want your driver to load every time you reboot (which you probably do) you can add it to /boot/loader.conf. You will need to add a line for each module, so you should end up with something that looks like this:

FwRad16.bin_load="YES"
if_ndis_load="YES"

The new way

The new way doesn't require the kernel sources installed. The ndis and if_ndis kernel modules should already be installed. You will need to create one module for your card, which will contain the driver and the firmware. This is handled by an undocumented wizard called ndisgen.

# ndisgen

This will ask you for the location of your driver and firmware files. Note that they are case-sensitive and require full paths. At the end, it will create a single .ko file. In my case, this was tnet1130_sys.ko. You need to move this module to a location where it can be found by kldload, and then load it.

# cp tnet1130_sys.ko /boot/kernel/
# kldload ndis
# kldload if_ndis
# kldload tnet1130_sys

Note the order of the kldload statements. It is very important that they be performed in this order. Attempting to load the network card driver before the ndis stub driver can result in a kernel panic.

As with the old way, you load the driver at boot by adding it to /boot/loader.conf. You will need to add a line for each module of the three modules, so you should end up with something that looks like this:

ndis_load="YES"
if_ndis_load="YES"
tnet1130_sys_load="YES"

You can now reboot and have your network card available at boot time. As before, use /stand/sysinstall to set up the interface.

If you've found this article helpful, and would like to see similar tutorials on a particular topic, send your suggestions and requests to &#x66&#x65&#x61t&#x75&#x72es@p&#x69&#x6Egwal&#x65s&#x2E&#x63&#x6F.uk