Date: Sat, 13 Aug 2005 13:44:00 +0100 From: David Chisnall <theraven@sucs.org> To: freebsd-doc@freebsd.org Subject: Re: Project Evil Message-ID: <79496DBF-0BF7-4575-838E-72790FEB1519@sucs.org> In-Reply-To: <A597DC86-B3FD-44FC-AD79-300EF88F7B8E@sucs.org> References: <2C5B55DC-0FEA-45B6-AB05-2A47D651584E@sucs.org> <FBD0B16E-8C6E-4211-96C4-FD49474F4618@submonkey.net> <A597DC86-B3FD-44FC-AD79-300EF88F7B8E@sucs.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--Apple-Mail-4--399047763 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed On 13 Aug 2005, at 13:30, David Chisnall wrote: > I am happy to assign non-exclusive rights to distribute the article > in its entirety, in part, of in the form of derived works to the > FreeBSD doc project, and to any other entities selected by the doc > project, including the right to sub-license the content. > And here is a copy of the original version (i.e. before it was merged with all of Ping's layout). I haven't had a chance to fully get up to speed with DocBook yet, so it might be quicker for someone else to add the markup. Currently it's mainly in plain text, with some HTML snippets where I wanted to indicate formatting - hopefully a global search-and-replace can translate much of this. --Apple-Mail-4--399047763 Content-Transfer-Encoding: 7bit Content-Type: text/plain; x-unix-mode=0644; x-mac-hide-extension=yes; name="Project Evil.txt" Content-Disposition: attachment; filename="Project Evil.txt" Project Evil: Windows Network Drivers on FreeBSD ================================================ 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 <span class="file">.sys</span>. There is also a <span class="file">.inf</span> 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 <span class="file">.bin</span> 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 <span class="file">.sys</span>, <span class="file">.inf</span>, or <span class="file">.bin</span> extension to <span class="file">/sys/modules/if_ndis</span>. 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: <dl> <dt><span class="file">Fw1130.bin</span></dt> <dd>Network interface firmware.</dd> <dt><span class="file">FwRad16.bin</span></dt> <dd>Radio firmware.</dd> <dt><span class="file">TNET1130.INF</span></dt> <dd>Driver information file.</dd> <dt><span class="file">tnet1130.sys</span></dt> <dd>Driver binary.</dd> </dl> 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: <pre class="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 </pre> 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. <pre class="commands"> # kldload FwRad16.bin # kldload if_ndis </pre> The driver should now be loaded. The easiest way to configure the adapter is to run <span class="file">/stand/sysinstall</span> and follow the instructions. If you want your driver to load every time you reboot (which you probably do) you can add it to <span class="file">/boot/loader.conf</span>. You will need to add a line for each module, so you should end up with something that looks like this: <pre class="configFile"> FwRad16.bin_load="YES" if_ndis_load="YES" </pre> 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 <span class="file">ndisgen</span>. <pre class="commands"> # ndisgen </pre> 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 <span class="file">.ko</span> file. In my case, this was <span class="file">tnet1130_sys.ko</span>. You need to move this module to a location where it can be found by <span class="file">kldload</span>, and then load it. <pre class="commands"> # cp tnet1130_sys.ko /boot/kernel/ # kldload ndis # kldload if_ndis # kldload tnet1130_sys </pre> Note the order of the <span class="file">kldload</span> 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 <span class="file">/boot/loader.conf</span>. 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: <pre class="configFile"> ndis_load="YES" if_ndis_load="YES" tnet1130_sys_load="YES" </pre> You can now reboot and have your network card available at boot time. As before, use <span class="file">/stand/sysinstall</span> to set up the interface. --Apple-Mail-4--399047763 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII; format=flowed --Apple-Mail-4--399047763--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?79496DBF-0BF7-4575-838E-72790FEB1519>