kern/110376: add some more explanations for the iwi/ipw firmware inclusion

[Eygene Ryabinkin]

>Number:         110376
>Category:       kern
>Synopsis:       add some more explanations for the iwi/ipw firmware inclusion
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-bugs
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Mar 16 07:10:06 GMT 2007
>Closed-Date:
>Last-Modified:
>Originator:     Eygene Ryabinkin
>Release:        FreeBSD 7.0-CURRENT i386
>Organization:
Code Labs
>Environment:
System: FreeBSD XXX 7.0-CURRENT FreeBSD 7.0-CURRENT #7: Tue Mar 13 16:56:09 MSK 2007 root at XXX:/usr/obj/usr/src/sys/XXX i386
>Description:
The inclusion of iwi/ipw firmware into the base system was a great
step. But the UPDATING and the iwi/ipw manual pages are saying
nothing about the need of inclusion of the iwifw/ipwfw modules
into the kernel configuration. And some people are building just
the restricted set of kernel modules, so they should know what they
will need to add to enable the system's firmware modules to be
built and installed into a proper place.

Also, manual pages iwi(4) and ipw(4) are specifying that the
license kenv tunable is license.intel_<name>.license_ack. Reading
the /sys/tools/fw_stub.awk I had a strong feeling that the right
name is license.<name>.license_ack as noted in the original commit
message and in the UPDATING.
>How-To-Repeat:
Look into the UPDATING and iwi/ipw manual pages: they are telling
nothing about the need of iwifw/ipwfw kernel modules. And the man
pages are telling about license.intel_{iwi,ipw}.license_ack.
>Fix:
The following patches will do the trick.

--- UPDATING.orig	Fri Mar 16 09:39:23 2007
+++ UPDATING	Fri Mar 16 10:04:48 2007
@@ -25,7 +25,8 @@
 	Firmwares for ipw(4) and iwi(4) are now included in the base tree.
 	In order to use them one must agree to the respective LICENSE in
 	share/doc/legal and define legal.<name>.license_ack=1 via
-	loader.conf(5) or kenv(1).
+	loader.conf(5) or kenv(1). Kernel module(s) <name>fw should be
+	built and installed to get the actual firmware.
 
 20070228:
 	The name resolution/mapping functions addr2ascii(3) and ascii2addr(3)

--- iwi.4.orig	Fri Mar 16 09:48:05 2007
+++ iwi.4	Fri Mar 16 10:03:39 2007
@@ -75,12 +75,15 @@
 .Xr ifconfig 8 .
 .Pp
 This driver requires firmware to be loaded before it will work.
+The firmware is installed by the kernel module
+.Nm iwifw .
+.Pp
 For the loaded firmware to work the license at
 .Pa /usr/share/doc/legal/intel_iwi/LICENSE
 must be agreed to and the following line be added to
 .Xr loader.conf 5 :
 .Pp
-.Dl "legal.intel_iwi.license_ack=1"
+.Dl "legal.iwi.license_ack=1"
 .Sh FILES
 .Bl -tag -width ".Pa /usr/share/doc/legal/intel_iwi/LICENSE" -compact
 .It Pa /usr/share/doc/legal/intel_iwi/LICENSE

--- ipw.4.orig	Fri Mar 16 09:57:56 2007
+++ ipw.4	Fri Mar 16 10:03:15 2007
@@ -75,12 +75,15 @@
 .Xr ifconfig 8 .
 .Pp
 This driver requires firmware to be loaded before it will work.
+The firmware is installed by the kernel module
+.Nm iwifw .
+.Pp
 For the loaded firmware to work the license at
 .Pa /usr/share/doc/legal/intel_ipw/LICENSE
 must be agreed to and the following line be added to
 .Xr loader.conf 5 :
 .Pp
-.Dl "legal.intel_ipw.license_ack=1"
+.Dl "legal.ipw.license_ack=1"
 .Sh FILES
 .Bl -tag -width ".Pa /usr/share/doc/legal/intel_ipw/LICENSE" -compact
 .It Pa /usr/share/doc/legal/intel_ipw/LICENSE
>Release-Note:
>Audit-Trail:
>Unformatted: