Getting the Netgear WN311T to work on PC-BSD/FreeBSD

Recently, I decided to try out PC-BSD. It's essentially FreeBSD with a desktop (KDE) and various other goodies. I'll talk about my experience with PC-BSD in another post. This one is about setting up the Netgear WN311T RangeMax NEXT Wireless Adapter to work with PC-BSD. I had heard that setting up wireless to work with FreeBSD or Linux can be quite an adventure and my experience was no different. These instructions should also work for regular FreeBSD. You can also use the following instructions to get other wireless cards working. But remember that each one will have its own quirks so you will probably have to scour the web looking for additional documentation. Remember, Google is your friend!

When I installed PC-BSD, I noticed that it wasn't able to recognize my Wireless Adapter. This wasn't a surprise, and for no fault of PC-BSD's. It's just that very few manufacturers make drivers for OSes other than Windows. Also, they are reluctant to release details for the adapters because they regard them as trade secrets. Hence, developers are left with the option to painstakingly reverse-engineer the adapters and write drivers for them. Anyway, before I could get my card to work, I needed to know what chipset it uses. To do this, you can use lspci, which lists devices on the PCI bus.

So first, open up a terminal window from Start->System->Konsole. Then do:

[vivin@tardis ~] su
Password:
[root@tardis /home/vivin]# pkg_add -r pciutils
Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.1-release/Latest/pciutils.tbz... Done
[root@tardis /home/vivin]# lspci
00:00.0 Host bridge: Intel Corporation 82875P/E7210 Memory Controller Hub (rev 02)
00:01.0 PCI bridge: Intel Corporation 82875P Processor to AGP Controller (rev 02)
00:03.0 PCI bridge: Intel Corporation 82875P/E7210 Processor to PCI to CSA Bridge (rev 02)
00:1d.0 USB Controller: Intel Corporation 82801EB/ER (ICH5/ICH5R) USB UHCI Controller #1 (rev 02)
00:1d.1 USB Controller: Intel Corporation 82801EB/ER (ICH5/ICH5R) USB UHCI Controller #2 (rev 02)
00:1d.2 USB Controller: Intel Corporation 82801EB/ER (ICH5/ICH5R) USB UHCI Controller #3 (rev 02)
00:1d.3 USB Controller: Intel Corporation 82801EB/ER (ICH5/ICH5R) USB UHCI Controller #4 (rev 02)
00:1d.7 USB Controller: Intel Corporation 82801EB/ER (ICH5/ICH5R) USB2 EHCI Controller (rev 02)
00:1e.0 PCI bridge: Intel Corporation 82801 PCI Bridge (rev c2)
00:1f.0 ISA bridge: Intel Corporation 82801EB/ER (ICH5/ICH5R) LPC Interface Bridge (rev 02)
00:1f.1 IDE interface: Intel Corporation 82801EB/ER (ICH5/ICH5R) IDE Controller (rev 02)
00:1f.2 IDE interface: Intel Corporation 82801EB (ICH5) SATA Controller (rev 02)
00:1f.3 SMBus: Intel Corporation 82801EB/ER (ICH5/ICH5R) SMBus Controller (rev 02)
01:00.0 VGA compatible controller: nVidia Corporation NV31 [GeForce FX 5600] (rev a1)
02:01.0 Ethernet controller: Intel Corporation 82547EI Gigabit Ethernet Controller (LOM)
03:01.0 Ethernet controller: Marvell Technology Group Ltd. Unknown device 2a02 (rev 03)
03:02.0 Serial controller: 3Com Corp, Modem Division 56K FaxModem Model 5610 (rev 01)
03:03.0 Multimedia audio controller: Creative Labs SB Audigy (rev 03)
03:03.1 Input device controller: Creative Labs SB Audigy MIDI/Game port (rev 03)
03:03.2 FireWire (IEEE 1394): Creative Labs SB Audigy FireWire Port
03:04.0 Multimedia controller: Sigma Designs, Inc. REALmagic Hollywood Plus DVD Decoder (rev 02)

As you can see, the wireless controller has a Marvell chipset. Unfortunately, FreeBSD doesn't have a driver for Marvell chipsets. This is where the amazing piece of software known as ndiswrapper comes in. FreeBSD doesn't have ndiswrapper per se, instead it has something similar called ndisulator (also known as Project Evil). This nifty piece of software creates a kernel module by making a wrapper around the Windows driver (using the SYS and INF files). You can then load this kernel module and FreeBSD will be able to recognize your wireless card.

Before you can run ndisulator, you need access to your hardware's driver files and the kernel source files. For PC-BSD, you can get the source files here. You will need to copy this from /Programs to /usr and extract it. For FreeBSD, run /stand/sysinstall and then download the src distribution. I think it's somewhere under "Configure".

As far as the driver files, you can usually get this from your installation CD. However, in some cases (such as this one), the driver files are packed into an executable and there's no way you can get it unless you actually install the program. If this is the case, you can probably search the web to be able to find the driver files. What I did was install Wine and then run the latest driver from Netgear's site. If you don't have X running, then this is a problem. Anyway, I have made it easier for you and I have the bzipped and gzipped tarballs available for download. Now once you have extracted the files to a directory, you will need to run ndisgen on these files. If you notice, there are two SYS files. I built modules for both, and I use both on my system. It seems to work if you load either one. Using ndisgen is simple. However, there are a few caveats. When you first run ndisgen you may get a "Conversion failed" error with a syntax error on line 998 (or something to that effect). The reason is that the INF file parser on FreeBSD is not as forgiving as the one on Windows. It'll trip up on DOS-style EOL characters (\r\n) and on some other weird characters as well. Often, the file itself has some other weird syntax errors as well. Anyway, to fix the the EOL character problem, you have to change the DOS-style EOL characters to Unix. Some systems have a dos2unix and unix2dos command. If you don't have it (I didn't) you can use the sed command:

[root@tardis /home/vivin/wn311t]# sed -i -e 's,^M,,g' NetMW14x.inf

The ^M is not just the caret sign and the capital letter M. To get it, you have to press CTRL+V and then CTRL+M. This command will convert all DOS-style EOL's to UNIX-style EOL's. Now we need to try converting the files to kernel modules. Unfortunately, when I did this first, I got the following error:

[root@tardis /home/vivin/wn311t]# ndisgen NetMW14x.inf netmw145.sys
        ==================================================================
        ------------------ Windows(r) driver converter -------------------
        ==================================================================

                        Kernel module generation


        The script will now try to generate the kernel driver module.
        This is the last step. Once this module is generated, you should
        be able to load it just like any other FreeBSD driver module.

        Press enter to compile the stub module and generate the driver
        module now: 

        Generating Makefile... done.
        Building kernel module... In file included from /usr/share/misc/windrv_stub.c:57:
./windrv.h:150:4: unknown escape sequence '\p'
./windrv.h:150:4: unknown escape sequence '\H'
./windrv.h:318:4: unknown escape sequence '\p'
./windrv.h:318:4: unknown escape sequence '\H'
build failed. Exiting.

This is problem is due to un-escaped backslashes in windrv.h. I went ahead and fixed the file, but then realized that when I ran ndisgen again, my changes would be overwritten. So I copied my changes to another file called windrv2.h. I ran ndisgen again, and at the prompt where it tells you that it is going to build the kernel module, I opened up another terminal window and copied windrv2.h over windrv.h. This time the conversion process went through without a hitch. After you convert both SYS files, you will be looking at two .ko files; netmw143_sys.ko and netmw145_sys.ko. You need to kldload these modules:

[root@tardis /home/vivin/wn311t]# kldload netmw145_sys.ko
[root@tardis /home/vivin/wn311t]# kldload netmw143_sys.ko
[root@tardis /home/vivin/wn311t]# kldstat
Id Refs Address    Size     Name
 1   23 0xc0400000 753dc8   kernel
 3    2 0xc0b5f000 1af50    linux.ko
 4    1 0xc0b7a000 75650    netmw143_sys.ko
 5    4 0xc0bf0000 1753c    ndis.ko
 6    3 0xc0c08000 c9e0     if_ndis.ko
 7    1 0xc0c15000 757d0    netmw145_sys.ko
 8    1 0xc0c8b000 58554    acpi.ko
 9    1 0xc57ff000 6000     snd_emu10k1.ko
10    1 0xc5805000 1c000    sound.ko
11    1 0xc5872000 6000     linprocfs.ko
12    1 0xc588f000 4000     logo_saver.ko

Note that I took this output from my machine where I automatically load the modules at startup (more on that later), which is why they are in lower memory locations. Anyway, the highlighted modules are the ones you need to worry about. If all goes well, these modules should be visible. If you do an ifconfig you should now be able to see the ndis0 interface:

[root@tardis /home/vivin/wn311t]# ifconfig ndis0
ndis0: flags=8843 mtu 1500
        inet6 fe80::218:4dff:fe1f:f432%ndis0 prefixlen 64 scopeid 0x7 
        inet 0.0.0.0 netmask 0xffffff00 broadcast 255.255.255.255
        ether 00:18:4d:1f:f4:32
        media: IEEE 802.11 Wireless Ethernet autoselect
        status: no carrier
        ssid "" channel 1
        authmode OPEN privacy OFF txpowmax 100 protmode CTS

This is good, because FreeBSD now recognizes your card. The next hurdle is getting your card associated to a wireless network. This is where I had the most difficulty. Scanning for networks didn't seem to work for me. KDE's wireless tools were unable to find anything and I was also unable to find anything from the terminal. I figured I could still try and connect to the network by providing my SSID. Since I use WPA, I was going to use wpa_supplicant to connect to my wireless network. This proved to be easier said than done. I set up my wpa_supplicant.conf file in /etc like this:

eapol_version=1
ap_scan=1
fast_reauth=1

network={
           ssid="" 
           # 'RSN' == 'WPA2'
           proto=RSN WPA
           key_mgmt=WPA-PSK
           pairwise=CCMP TKIP
           group=CCMP TKIP
           psk=
        }

After that:

[root@tardis /home/vivin/wn311t]# wpa_supplicant -i ndis0 -c /etc/wpa_supplicant.conf
ioctl[SIOCG80211, op 24, len 24576]: No space left on device
ioctl[SIOCG80211, op 24, len 24576]: No space left on device
ioctl[SIOCG80211, op 24, len 24576]: No space left on device
ioctl[SIOCG80211, op 24, len 24576]: No space left on device
ioctl[SIOCG80211, op 24, len 24576]: No space left on device

As you can see, things didn't go too well. I spent hours scouring the web and message boards. I found someone with exactly the same error message, but they had received no responses to their queries. Finally after about another hour of searching, I had enough information to put it all together. Instead of using the wpa_supplicant binary, you need to use FreeBSD's wpa_supplicant script together with dhclient:

[root@tardis /home/vivin/wn311t]# /etc/rc.d/wpa_supplicant forcestart ndis0
[root@tardis /home/vivin/wn311t]# dhclient ndis0

If all goes well, your wireless card should be able to authenticate with your wireless router and receive an IP address:

[root@tardis /home/vivin/wn311t]# ifconfig ndis0
ndis0: flags=8843 mtu 1500
        inet6 fe80::218:4dff:fe1f:f432%ndis0 prefixlen 64 scopeid 0x7 
        inet 10.0.1.197 netmask 0xffffff00 broadcast 10.0.1.255
        ether 00:18:4d:1f:f4:32
        media: IEEE 802.11 Wireless Ethernet autoselect
        status: associated
        ssid "" channel 1
        authmode OPEN privacy OFF txpowmax 100 protmode CTS

This is fine and dandy. But now you need to make sure that all these steps are done automatically when you startup your machine. First, you need to ensure that your new kernel modules are loaded up when you start your machine. To do that, copy your kernel object files to /boot/kernel. Then, add the following lines to /boot/loader.conf

[root@tardis /home/vivin/wn311t]# grep net /boot/loader.conf
netmw143_sys_load="yes"
netmw145_sys_load="yes"

These changes will ensure that your wireless adapter drivers are loaded up on startup. Finally, you need to add two lines to /etc/rc.conf to let FreeBSD know that your wireless adapter needs to be configured through wpa_supplicant:

# Enable wpa_supplicant
if_ndis0="WPA DHCP"
wpa_supplicant_enable="YES"

I have read that the second line is superfluous because apparently the "WPA" option tells FreeBSD to use wpa_supplicant, but it didn't seem to hurt anything so I left it in there. Once you have done all this, go ahead and restart your machine. Your WN311T Wireless Adapter should now be able to connect to the wireless network. You can verify that wpa_supplicant is running by doing the following:

[root@tardis /home/vivin/wn311t]# ps x | grep wpa
 1368  ??  Ss     0:56.72 /usr/sbin/wpa_supplicant -B -q -i ndis0 -c /etc/wpa_supplicant.conf -D ndis -P /var/run/wpa_supplicant/ndis0.pid

In some cases, wpa_supplicant still won't start. I have had this problem before. In that case, you will have to run wpa_supplicant and dhclient manually (like I showed before) to get your card to work. I am not sure why this happens.

These instructions deal with using WPA for your Wireless Security. I believe wpa_supplicant can be configured to use WEP as well.

So there you have it. I hope this writeup is helpful and saves you hours of frustration!