docs/84961: [patch] Sync NDIS documentation with reality
Fredrik Lindberg
fli+freebsd at shapeshifter.se
Mon Aug 15 19:20:21 UTC 2005
>Number: 84961
>Category: docs
>Synopsis: [patch] Sync NDIS documentation with reality
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Aug 15 19:20:14 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator: Fredrik Lindberg
>Release: FreeBSD 7.0-CURRENT i386
>Organization:
>Environment:
System: FreeBSD biocandy.shapeshifter.se 7.0-CURRENT FreeBSD 7.0-CURRENT #2: Sun Aug 14 12:18:18 CEST 2005 root at biocandy.shapeshifter.se:/usr/obj/usr/src/sys/BIOCANDY-CURRENT i386
>Description:
The ndis section of the handbook is out-of-date, this patch syncs the docs
with reality.
1. Describe how to use ndisgen (the "old" way is not included).
2. The ndis documentation has been moved from the wireless section into
its own since it can be used with other cards than wireless once.
3. A reference has been added to the ndis section under
"26.3.3.6.3 802.11a & 802.11g Clients". (Not related to ndis, but I also
added references to iwi, ipw and ral in the same section, please remove
if they are inappropriate).
I've tried my best with the correctness regarding spelling and grammar, but
english is not my native language. Please proofread and correct grammar issues.
>How-To-Repeat:
>Fix:
Index: chapter.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v
retrieving revision 1.367
diff -r1.367 chapter.sgml
1086c1086
< <title>802.11a & 802.11g Clients</title>
---
> <title>802.11a & 802.11g Clients</title>
1088,1109c1088
< <para>The &man.ath.4; device driver supports 802.11a and 802.11g.
< If your card is based on an Atheros chipset, you may
< be able to use this driver.</para>
<
< <para>Unfortunately, there are still many vendors that do not
< provide schematics for their drivers to the open source
< community because they regard such information as trade
< secrets. Consequently, the developers of FreeBSD and other
< operating systems are left two choices: develop the drivers by
< a long and pain-staking process of reverse engineering or using
< the existing driver binaries available for the
< µsoft.windows; platforms. Most developers, including those
< involved with FreeBSD, have taken the latter approach.</para>
<
< <para>Thanks to the contributions of Bill Paul (wpaul), as of
< FreeBSD 5.3-RELEASE there is <quote>native</quote>
< support for the Network Driver Interface Specification
< (NDIS). The FreeBSD NDISulator (otherwise known as Project Evil)
< takes a &windows; driver binary and basically tricks it into
< thinking it is running on &windows;. This feature is still
< relatively new, but most test cases seem to work
< adequately.</para>
---
> <para>The following device drivers supports 802.11a and 802.11g.</para>
1110a1090,1118
> <para>The &man.ath.4; device driver supports many cards based on the
> Atheros chipset.</para>
>
> <para>The &man.iwi.4; device driver supports Intel PRO/Wireless 2200BG/2225BG/2915ABG based cards.</para>
>
> <para>The &man.ipw.4; device drivers supports Intel PRO/Wireless 2100 cards.</para>
> <para>The &man.ral.4; device drivers supports many cards based on the Ralink RT2500 chipset.</para>
>
> <para>In addition to this, support may be provided by the &man.ndis.4; driver, please see the <link linkend="network-ndis">NDIS</link> section of this handbook.</para>
>
> </sect4>
>
> </sect3>
> </sect2>
> </sect1>
>
> <sect1 id="network-ndis">
> <sect1info>
> <authorgroup>
> <author>
> <firstname>Fredrik</firstname>
> <surname>Lindberg</surname>
> <contrib>Written by </contrib>
> </author>
> </authorgroup>
> </sect1info>
> <title>NDIS Miniport Driver Wrapper</title>
>
> <indexterm><primary>NDIS miniport</primary></indexterm>
1122,1193c1130,1276
< <para>In order to use the NDISulator, you need three things:</para>
<
< <orderedlist>
< <listitem>
< <para>Kernel sources</para>
< </listitem>
< <listitem>
< <para>&windowsxp; driver binary
< (<filename>.SYS</filename> extension)</para>
< </listitem>
< <listitem>
< <para>&windowsxp; driver configuration file
< (<filename>.INF</filename> extension)</para>
< </listitem>
< </orderedlist>
<
< <para>You may need to compile the &man.ndis.4; mini port driver
< wrapper module. As <username>root</username>:</para>
<
< <screen>&prompt.root; <userinput>cd /usr/src/sys/modules/ndis</userinput>
< &prompt.root; <userinput>make && make install</userinput></screen>
<
< <para>Locate the files for your specific card. Generally, they can
< be found on the included CDs or at the vendors' websites. In the
< following examples, we will use
< <filename>W32DRIVER.SYS</filename> and
< <filename>W32DRIVER.INF</filename>.</para>
<
< <para>The next step is to compile the driver binary into a
< loadable kernel module. To accomplish this, as
< <username>root</username>, go into the
< <filename>if_ndis</filename> module directory and copy the
< &windows; driver files into it:</para>
<
< <screen>&prompt.root; <userinput>cd /usr/src/sys/modules/if_ndis</userinput>
< &prompt.root; <userinput>cp <replaceable>/path/to/driver/W32DRIVER.SYS</replaceable> ./</userinput>
< &prompt.root; <userinput>cp <replaceable>/path/to/driver/W32DRIVER.INF</replaceable> ./</userinput></screen>
<
< <para>We will now use the <command>ndiscvt</command> utility to
< create the driver definition header
< <filename>ndis_driver_data.h</filename> to build the
< module:</para>
<
< <screen>&prompt.root; <userinput>ndiscvt -i <replaceable>W32DRIVER.INF</replaceable> -s <replaceable>W32DRIVER.SYS</replaceable> -o ndis_driver_data.h</userinput></screen>
<
< <para>The <option>-i</option> and <option>-s</option> options specify
< the configuration and binary files, respectively. We use the
< <option>-o ndis_driver_data.h</option> option because the
< <filename>Makefile</filename> will be looking for this file when it
< comes time to build the module. </para>
<
< <note>
< <para>Some &windows; drivers require additional files to operate. You
< may include them with <command>ndiscvt</command> by using the
< <option>-f</option> option. Consult the &man.ndiscvt.8; manual page
< for more information.</para>
< </note>
<
< <para>Finally, we can build and install the driver module:</para>
<
< <screen>&prompt.root; <userinput>make && make install</userinput></screen>
<
< <para>To use the driver, you must load the appropriate modules:</para>
<
< <screen>&prompt.root; <userinput>kldload ndis</userinput>
< &prompt.root; <userinput>kldload if_ndis</userinput></screen>
<
< <para>The first command loads the NDIS miniport driver wrapper,
< the second loads the actual network interface. Check
< &man.dmesg.8; to see if there were any errors loading. If all
< went well, you should get output resembling the
< following:</para>
---
> <sect2>
> <title>Introduction</title>
> <para>The &man.ndis.4; device driver is a wrapper which allows binary
> µsoft.windows; NDIS (Network Driver Interface Specification) miniport
> network drivers to be used <quote>natively</quote> with FreeBSD. This will
> allow you to use existing network drivers to Windows 2000, Windows XP
> or Windows Server 2003 together with FreeBSD.</para>
>
> <para>The &man.ndis.4; driver works by providing an interface between
> the NDIS API and the networking subsystem in FreeBSD, essentially
> fooling the &windows; driver into thinking it is running on &windows;.
> Because the ndis driver is using a &windows; binary, it is only usable on
> i386 and amd64 systems.</para>
> </sect2>
>
> <sect2>
> <title>Using the ndis(4) driver</title>
> <para>To use the &man.ndis.4; device driver you will need a few things</para>
>
> <orderedlist>
> <listitem>
> <para>&windows; driver binary in Portable Executable (PE) format
> (<filename>.SYS</filename> extension)</para>
> </listitem>
> <listitem>
> <para>&windows; driver configuration file
> (<filename>.INF</filename> extension)</para>
> </listitem>
> <listitem>
> <para>A number of programs (which all are a part of the base system)</para>
> </listitem>
> </orderedlist>
>
> <para>You will need to locate the &windows; drivers to the network card you
> wish to use together with ndis. Drivers to &windows; 2000 should work,
> but drivers to &windows; XP or &windows; Server 2003 are prefered.
> Driver packages can usually be found on the CD that came bundled with your
> hardware. Another place to look at is the vendor's website, most vendors
> have drivers avaiable for download.
> </para>
>
> <note>
> <para>Some vendors carry their driver packages as self-extracting Zip
> archives (<filename>.EXE</filename> extension), these archives can
> usually be extracted with the <application>unzip</application> utility,
> which is avaiable as <filename role="package">archives/unzip</filename>
> port.
> </para>
> </note>
>
> <note>
> <para>You can not use a &windows;/i386 driver with FreeBSD/amd64, you must get a &windows;/amd64 driver to make it work properly.
> </para>
> </note>
>
> <para>When you have located the correct driver you should have one
> <filename>.INF</filename> file and one <filename>.SYS</filename> file.
> They usually have the same name.
> For example <filename>WIN32DRIVER.INF</filename> and
> <filename>WIN32DRIVER.SYS</filename>.
> </para>
>
> <para>
> The easiest way to generate a usable kernel module from these files is
> with the &man.ndisgen.8; utility, which is an interactive front-end to
> &man.ndiscvt.8;, &man.cc.1;, &man.ld.1; and &man.objcopy.1;.
> You do not need to concern yourself with these utilities,
> <command>ndisgen</command> will do everything for you, just follow
> the on-screen instructions and you should be fine. To begin, type:
> </para>
>
> <screen>&prompt.user; <userinput>ndisgen</userinput></screen>
>
> <para>You should now get a selection screen, type <keycap>3</keycap> and
> <keycap>Enter</keycap> to select <quote>Convert driver</quote>.
> </para>
>
> <para><command>ndisgen</command> will now ask you to supply the name of the
> <filename>.INI</filename> file. This file will now be validated and
> possibly converted from Unicode to ASCII.
> </para>
>
> <para>You will now be asked to specify your <filename>.SYS</filename> file.
> This file will also be verified to make sure it is a valid
> &windows; PE file.
> </para>
>
> <para>Once these files has been verified they will be converted
> into a &man.ndis.4; readable form by &man.ndiscvt.8;.
> The following message indicates a successful convertion:
> </para>
>
> <screen>Conversion was successful.
>
> Press enter to continue...
> </screen>
>
> <para>You will also be asked to load any additional firmware files which
> might be needed to make your card work properly. If your card
> requires firmware files they should be avaiable in the same packages
> as the drivers. Sometimes firmware files have the
> <filename>.BIN</filename> extension, but they can be named anything.
> </para>
>
> <para>
> <command>ndisgen</command> should now be ready to compile your driver and
> you should see something similar to this on your screen.
> </para>
>
> <screen>Press enter to compile the stub module and generate the driver
> module now:</screen>
>
> <para>Press <keycap>Enter</keycap>, the compilation should only take a few seconds on a modern computer.
> Now, if everything went well you should see a message similar to the following:
> </para>
>
> <screen>Generating Makefile... done.
> Building kernel module... done.
> Cleaning up... done.
>
> The file WIN32DRIVER_sys.ko has been successfully generated.
> You can kldload this module to get started.
>
> Press return to exit. </screen>
>
> <para>The file <filename>WIN32DRIVER_sys.ko</filename> is a loadable
> kernel module which can be loaded with &man.kldload.8;. To load the
> new module, type as <username>root</username>:
> </para>
>
> <screen>&prompt.root; <userinput>kldload ./WIN32DRIVER_sys.ko</userinput> </screen>
>
> <para>In addition to the generated kernel module you will also need to
> load the <filename>ndis.ko</filename> module and the
> <filename>if_ndis.ko</filename> module.
> This should be done automatically for you
> when you load any module that depends on &man.ndis.4;. If you need to
> load them manually:
> </para>
>
> <screen>&prompt.root; <userinput>kldload ndis</userinput>
> &prompt.root; <userinput>kldload if_ndis</userinput>
> </screen>
>
> <para>Now, check &man.dmesg.8; to see if there were any errors. If
> everything went well you should get an output resembeling the following:
> </para>
1195,1196c1278,1279
< <screen>ndis0: <Wireless-G PCI Adapter> mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1
< ndis0: NDIS API version: 5.0
---
> <screen>ndis0: <Wireless-G PCI Adapter< mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1
> ndis0: NDIS API version: 5.1
1198,1205c1281
< ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps
< ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen>
<
< <para>From here you can treat the <devicename>ndis0</devicename> device
< like any other wireless device (e.g. <devicename>wi0</devicename>) and
< consult the earlier sections of this chapter.</para>
<
< </sect4>
---
> </screen>
1207,1208c1283,1309
< </sect3>
< </sect2>
---
> <para>You can now treat <devicename>ndis0</devicename> as any other
> network interface and configure it with &man.ifconfig.8;.
> Please consult earlier chapters of this handbook if you need assistance
> with network interface configuration.
> </para>
>
> </sect2>
> <sect2>
> <title>Loading a NDIS module at boot</title>
> <para>Loading a NDIS module at boot is done in the same way as with any
> other module. First, copy your kernel module to <filename>/boot/modules</filename>.
> </para>
> <screen>&prompt.root; <userinput>cp WIN32DRIVER_sys.ko /boot/modules/</userinput></screen>
>
> <para>Alternatively, you can copy it to <filename>/boot/kernel</filename>. However, it will then be overwritten when you re-compile your kernel. </para>
> <note>
> <para>You should always re-compile all NDIS modules whenever you upgrade from one FreeBSD version to another, because of possible changes to networking and other related subsystems.</para>
> </note>
>
> <para>Next, add the following line to <filename>/boot/loader.conf</filename>
> </para>
> <screen>WIN32DRIVER_sys_load="YES"</screen>
>
> <para>Now you should be all set. Next time you reboot the NDIS driver should
> load automatically.
> </para>
> </sect2>
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list