docs/97229: [patch] Handbook contains obsolete instructions on NDIS

[Gavin Atkinson]

>Number:         97229
>Category:       docs
>Synopsis:       [patch] Handbook contains obsolete instructions on NDIS
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat May 13 21:40:23 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator:     Gavin Atkinson
>Release:        FreeBSD 6.1-RC i386
>Organization:
http://www.mod3.co.uk/
>Environment:
System: FreeBSD buffy.york.ac.uk 6.1-RC FreeBSD 6.1-RC #8: Fri May 5 16:37:33 BST 2006 root at buffy.york.ac.uk:/usr/obj/usr/src/sys/BUFFY i386

>Description:
	The instructions at
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-wireless.html
are wrong with regards to creating an NDIS kernel module under FreeBSD 5.5,
6.0 and later.  The "old" way detailed in the handbook is deprecated and is
not guaranteed to work (and indeed, doesn't, for me...)

>How-To-Repeat:
	Try following the example with the standard Intel 3945ABG driver
>Fix:
	Note that as this is a new laptop, I don't currently have the
infrastructure to compile-test this patch: please check it doesn't break
the build before committing it.

--- ndis.diff begins here ---
Index: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
===================================================================
RCS file: /usr/cvs/doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v
retrieving revision 1.365
diff -u -r1.365 chapter.sgml
--- doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml	18 Mar 2005 01:56:06 -0000	1.365
+++ doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml	13 May 2006 21:19:08 -0000
@@ -1135,18 +1135,31 @@
      </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>In &os; 5.5, &os; 6.0 and later, a kernel module is created
+        with &man.ndisgen.8; as <username>root</username>:</para>
+
+    <screen>&prompt.root; <userinput>ndisgen <replaceable>/path/to/W32DRIVER.INF</replaceable> <replaceable>/path/to/W32DRIVER.SYS</replaceable></userinput></screen>
+
+      <para>The &man.ndisgen.8; utility is interactive and will prompt
+        for any extra information it requires; it will produce a kernel
+        module in the current directory which can be loaded as follows:</para>
+      <screen>&prompt.root; <userinput>kldload <replaceable>./W32DRIVER.ko</replaceable></userinput>
+
+      <para>Under &os; 5.4 and before, the process of creating the kernel
+        module is more involved, and is detailed next.</para>
+
+	<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>The next step is to compile the driver binary into a
       loadable kernel module. To accomplish this, as
       <username>root</username>, go into the
--- ndis.diff ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted: