From phil@bowens.cc  Mon Oct 11 20:31:45 2004
Return-Path: <phil@bowens.cc>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 6985C16A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 11 Oct 2004 20:31:45 +0000 (GMT)
Received: from sccimhc91.asp.att.net (sccimhc91.asp.att.net [63.240.76.165])
	by mx1.FreeBSD.org (Postfix) with ESMTP id DD81343D1F
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 11 Oct 2004 20:31:44 +0000 (GMT)
	(envelope-from phil@bowens.cc)
Received: from [192.168.1.101] (12-220-214-31.client.insightbb.com[12.220.214.31])
          by sccimhc91.asp.att.net (sccimhc91) with ESMTP
          id <20041011203133i91008j7sqe>; Mon, 11 Oct 2004 20:31:33 +0000
Message-Id: <416AEDB4.3080809@bowens.cc>
Date: Mon, 11 Oct 2004 16:31:48 -0400
From: Phil Bowens <phil@bowens.cc>
To: FreeBSD-gnats-submit@freebsd.org
Subject: [patch] [handbook] Update in Wireless Networking section for NDISulator
 in 5.3-*

>Number:         72545
>Category:       docs
>Synopsis:       [patch] [handbook] Update in Wireless Networking section for NDISulator
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Oct 11 20:40:09 GMT 2004
>Closed-Date:    Fri Mar 18 01:57:02 GMT 2005
>Last-Modified:  Fri Mar 18 01:57:02 GMT 2005
>Originator:     Phil Bowens
>Release:        FreeBSD 5.3-BETA7 i386
>Organization:
>Environment:
 System: FreeBSD hubble 5.3-BETA7 FreeBSD 5.3-BETA7 #2: Tue Oct 5 
 21:57:27 EDT 2004 pbowens@hubble:/usr/obj/usr/src/sys/HUBBLE i386

>Description:

 The Online FreeBSD handbook makes no mention of the NDISulator (Project 
 Evil) by
 wpaul. The patch below provides a quick how-to in the wireless 
 networking section
 of the advanced networking chapter in the handbook. Bassically covers 
 the ndiscvt
 utility etc to provide support for 802.11g (and presumably 802.11a, 
 802.11a+g)
 using existing Win32 binaries.
 
 This may be better suited for a FAQ entry.

>How-To-Repeat:
>Fix:

 Thorough review strongly requested.
 
 $FreeBSD: 
 doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 
 1.344 2004/09/22 19:47:39 ceri Exp $
 
 --- chapter.sgml.diff begins here ---
 --- chapter.sgml        Thu Oct  7 00:51:18 2004
 +++ chapter.new.sgml    Thu Oct  7 04:10:37 2004
 @@ -1075,7 +1075,7 @@
      </sect4>
 
      <sect4>
 -    <title>Clients</title>
 +    <title>802.11b Clients</title>
 
      <para>Almost all 802.11b wireless cards are currently supported
        under FreeBSD.  Most cards based on Prism, Spectrum24, Hermes,
 @@ -1083,8 +1083,113 @@
        IBSS (ad-hoc, peer-to-peer, and BSS) mode.</para>
 
      </sect4>
 -    </sect3>
 
 +    <sect4>
 +    <title>802.11a & 802.11g Clients</title>
 +
 +    <para>The &man.ath.4; device driver supports 802.11a and 802.11g.
 +      If your card is based 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 &microsoft.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
 +      <emphasis>FreeBSD 5.3-RELEASE</emphasis> there is "native" 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>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; cd /usr/src/sys/modules/ndis
 +&prompt.root; make && make install</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; ndiscvt -i 
 <replaceable>W32DRIVER.INF</replaceable> -s 
 <replaceable>W32DRIVER.SYS</replaceable> -o ndis_driver_data.h</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 an output 
 resembling
 +      the following:</para>
 +
 +    <screen>ndis0: &lt;Wireless-G PCI Adapter&gt; mem 
 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1
 +ndis0: NDIS API version: 5.0
 +ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5
 +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>
 +
 +    </sect3>
     </sect2>
    </sect1>
 
 --- chapter.sgml.diff ends here ---
>Release-Note:
>Audit-Trail:
Class-Changed-From-To: sw-bug->doc-bug 
Class-Changed-By: ceri 
Class-Changed-When: Tue Oct 12 15:19:11 GMT 2004 
Class-Changed-Why:  
This is a doc PR. 


Responsible-Changed-From-To: gnats-admin->freebsd-doc 
Responsible-Changed-By: ceri 
Responsible-Changed-When: Tue Oct 12 15:19:11 GMT 2004 
Responsible-Changed-Why:  
Reassign misfiled PR.  If the submitter is reading, note that your 
patch has wrapped quite nastily, and could do with being resubmitted as 
a followup to this PR (or just post it somewhere and send the URL as a 
followup). 

http://www.freebsd.org/cgi/query-pr.cgi?pr=72545 

From: Phil Bowens <phil@bowens.cc>
To: freebsd-gnats-submit@FreeBSD.org
Cc: phil@bowens.cc, freebsd-doc@freebsd.org
Subject: Re: docs/72545: [patch] [handbook] Update in Wireless Networking
 section for NDISulator
Date: Thu, 14 Oct 2004 09:56:21 -0400

 I apologize for the complications with the patch and PR classifications
 [this is my first PR, so bear with me.  :)  ]
 
 The patch can be found here:
    http://andromeda.moonside.org/freebsd-handbook/chapter.sgml.diff
 
State-Changed-From-To: open->feedback 
State-Changed-By: murray 
State-Changed-When: Wed Nov 10 23:47:54 GMT 2004 
State-Changed-Why:  
Thanks for the submission!  Your change has been committed with only 
minor whitespace changes.  It may take up to 24 hours for this change 
to be updated on the website. 

Do you think you could add some <indexterms> to this entry so that 
802.11a, NDIS, etc.. now appear in the index? 


http://www.freebsd.org/cgi/query-pr.cgi?pr=72545 
State-Changed-From-To: feedback->closed 
State-Changed-By: murray 
State-Changed-When: Fri Mar 18 01:56:37 GMT 2005 
State-Changed-Why:  
I added a few indexterms, so this PR is now closed.  Thanks for the 
submission! 


http://www.freebsd.org/cgi/query-pr.cgi?pr=72545 
>Unformatted:
