From nobody@FreeBSD.org  Fri Oct 14 15:48:33 2005
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 5E7B916A41F
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 14 Oct 2005 15:48:33 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [216.136.204.117])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 206A043D45
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 14 Oct 2005 15:48:33 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.13.1/8.13.1) with ESMTP id j9EFmWZg097539
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 14 Oct 2005 15:48:33 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.13.1/8.13.1/Submit) id j9EFmWpB097536;
	Fri, 14 Oct 2005 15:48:32 GMT
	(envelope-from nobody)
Message-Id: <200510141548.j9EFmWpB097536@www.freebsd.org>
Date: Fri, 14 Oct 2005 15:48:32 GMT
From: Joe Rhett <jrhett@meer.net>
To: freebsd-gnats-submit@FreeBSD.org
Subject: comments for improvement of handbook/kernelconfig-config.html
X-Send-Pr-Version: www-2.3

>Number:         87445
>Category:       docs
>Synopsis:       comments for improvement of handbook/kernelconfig-config.html
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Oct 14 15:50:18 GMT 2005
>Closed-Date:    Sun Aug 03 14:41:26 UTC 2008
>Last-Modified:  Sun Aug  3 14:50:03 UTC 2008
>Originator:     Joe Rhett
>Release:        5.4
>Organization:
meer.net
>Environment:
>Description:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig-config.html

I'd like to offer some quick comments, after spending several hours reading and googling only to verify the fairly obvious but that wasn't spelled out.  My comments to improve this page are in the Fix sections below.


>How-To-Repeat:
              
>Fix:
1.  Start the beginning.  What does the kernel configuration file do?  If the following statement is true, let's put this (or something similar) somewhere near the top:

	"The kernel configuratioon file defines the modules which will be built statically into the kernel.  You would change this file to remove modules from your kernel, or to change some kernel options. It does not limit or prevent you from adding dynamically loadable modules later.  If you want to include a loadable module in your kernel, you don't need to rebuild your kernel configuration."

This appears to be true, and running several kernel builds appears to prove it, but just determining whether or not it was true was downright difficult.

2. Move the comment about NOTES/LINT to the bottom.  It's unlikely that your average kernel builder would care about most of this stuff, and they should read to the bottom anyway.  It's kindof "if we didn't talk about it here..." kind of comment anyway.  It certainly confuses the subject when you first hit this page.

3. Identify which modules are required for a kernel to boot.  Or have some discussion of this.  And in general -- what does it mean when I remove a module?  Can I remove plip from the kernel but have it installed as a .ko so that I can load it dynamically later on if by some reason I decide to use it?  What's the limitations of this approach?

And lastly, stop with the intertwined 4.x and 5.x (and soon 6.x) comments.  If there are different answers, put them in separate blocks.  Maybe color them separately.  It's incredibly frustrating to go through a paragraph and then hit an else near the end that makes you wonder just how many statements before the else are being negated.  An example of very clear documentation could be:

device   gif           # IPv6 and IPv4 tunneling

This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. Beginning with FreeBSD 4.4 the gif device is auto-cloning, and you should use the line pseudo-device gif. Earlier versions of FreeBSD 4.X require a number, for example pseudo-device gif 4.

Huh?  What?  Did I read this right?  Instead, why not:

FreeBSD 5/6:
device   gif           # IPv6 and IPv4 tunneling

FreeBSD 4.4 and above:
pseudo-device   gif           # IPv6 and IPv4 tunneling

FreeBSD 4.3 and earlier:
pseudo-device   gif   4        # the number of IPv6 and IPv4 tunneling interfaces

This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. Beginning with FreeBSD 4.4 the gif device is auto-cloning. Earlier versions of FreeBSD 4.X require a number, for example pseudo-device gif 4.

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Fri Oct 14 23:30:46 GMT 2005 
Responsible-Changed-Why:  
Grab.  I would really like to rewrite this chapter. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=87445 
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Wed Jun 7 06:58:14 UTC 2006 
State-Changed-Why:  
There have been many updates since this PR.  For instance: 
1: I cannot seem to find the first quoted sentence using 
several search strings. 

2: The 4.X/5.X/6.X intermix is pretty much gone.  There was 
and still is a big difference to the kernel options between 
4.X and 5.X/6.X.  But the 5.X/6.X stuff is extremely similar. 

3: NOTES must be introduced early on so the user knows where to 
look for all of the available options. 

4: Attempting to document every single part of the kernel that 
is required or not would take months.  What is required either 
has a note or will most likely cause a build failure. 

Switching to feedback for now because I want to know about the 
first (1 above) comment.  Am I just not seeing this sentence? 
Thanks! 

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

From: Jo Rhett <jrhett@svcolo.com>
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/87445: comments for improvement of handbook/kernelconfig-config.html
Date: Wed, 7 Jun 2006 09:26:03 -0700

 1.  No, that sentence doesn't exist.  It's an example of a sentence  
 that would make the page significantly easier to read.  (though I'm  
 not tied to that wording)
 
 The #1 problem is that the page starts halfway down the thought  
 process and then runs past the end to the beginning.  That's why my  
 comment: Start at the Beginning.
 
 Your numbered remarks don't match up to my numbered issues, so it's  
 confusing here.  But I'll use your numbers:
 
 3. The page appears to have been rewritten from top to bottom since I  
 posted this PR.  The original dense notes about LINT are not on the  
 page at all any more.
 
 4. I'm assuming you're replying to #3 above here.  Why did you reply  
 to the first question, and ignore the following paragraph that pretty  
 clearly explains what I mean?  There really is nothing to explain to  
 a person what commenting out a device does.  One would think it's not  
 available, but no - it's actually just turned into a .ko module.   
 Which you can load.  There is _zero_ explanation of this.
 
 If you're coming from Solaris, Linux, or any other platform where  
 loadable modules actually work (ie can be laoded dynamically at boot  
 time) then FreeBSD modules are very confusing in nature.  The kernel  
 building process should include documentation about this, otherwise  
 much foot shootage occurs.
 
 What do you mean by "has a note"?  What note?
 
 And I can guarantee you from deep experience, that very little that  
 is required for boot will cause a build failure.  Maybe commenting  
 out all possible CPUs?  But it's entirely possible to build a kernel  
 with no console and no bootable device drivers.
 
 -- 
 Jo Rhett
 senior geek
 Silicon Valley Colocation
 

From: Tom Rhodes <trhodes@FreeBSD.org>
To: Joe Rhett <jrhett@meer.net>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/87445: comments for improvement of
 handbook/kernelconfig-config.html
Date: Wed, 9 Apr 2008 04:16:28 -0400

 Hi Jo,
 
 My apologies for the confusion and lack of immediate response, in
 the first case I was hoping you could re-read the section/chapter
 and base further follow up on the current version.  The lack of
 response is completely my fault.  :)
 
 Anyway, from the previous comments, I have drafted the following
 diff for the chapter; however, I'm not completely sure it needs
 a section all on it's own.  Perhaps you could work with me on
 fleshing out something better which, after some review, we could
 put into the chapter itself.  Thanks,
 
 -- 
 Tom Rhodes
 
 Index: chapter.sgml
 ===================================================================
 RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml,v
 retrieving revision 1.180
 diff -u -u -r1.180 chapter.sgml
 --- chapter.sgml	27 Jan 2008 04:23:28 -0000	1.180
 +++ chapter.sgml	9 Apr 2008 08:12:10 -0000
 @@ -210,6 +210,54 @@
        a custom kernel should appear less daunting.</para>
    </sect1>
  
 +  <sect1 id="kernelconfig-modules">
 +    <title>Kernel Drivers, Subsystems, and Modules</title>
 +    <indexterm>
 +      <primary>kernel</primary>
 +      <secondary>drivers / modules / subsystems</secondary>
 +    </indexterm>
 +
 +    <para>Before building a custom kernel, consider the reasons for
 +      doing so.  If there is a need for specific hardware support,
 +      it may already exist as a module.</para>
 +
 +    <para>Kernel modules exist in the
 +      <filename role="directory">/boot/kernel</filename> directory
 +      and may be dynamically loaded into the running kernel using
 +      &man.kldload.8;.  Most, if not all kernel drivers have a
 +      specific module and manual page.  For example, the last section
 +      noted the <devicename>ath</devicename> wireless Ethernet driver.
 +      This device has the following information in its manual
 +      page:</para>
 +
 +    <programlisting>Alternatively, to load the driver as a module at boot time, place the
 +     following line in loader.conf(5):
 +
 +           if_ath_load="YES"</programlisting>
 +
 +    <para>As instructed, adding the <literal>if_ath_load="YES"</literal>
 +      line to the <filename>/boot/loader.conf</filename> file will
 +      activate loading this module dynamically at boot time.</para>
 +
 +    <para>In some cases; however, there is no associated module.  This
 +      is mostly true for certain subsystems and very important drivers,
 +      for instance, the fast file system (<acronym>FFS</acronym>) is a
 +      required option in the kernel.  As is network support (INET).
 +      Unfortunately the only way to tell if a driver is required is to
 +      check for the module itself.</para>
 +
 +    <warning>
 +      <para>It is considerably easy to pull built in support for a
 +	device or option and have a broken kernel.  For example, if
 +	the &man.ata.4; driver is pulled from the kernel configuration
 +	file, a system using <acronym>ATA</acronym> disk drivers may
 +	not boot without the line added to
 +	<filename>loader.conf</filename>.  When in doubt, check for
 +	the module and then just leave support in the kernel.</para>
 +    </warning>
 +
 +    <sect1>
 +
    <sect1 id="kernelconfig-building">
      <title>Building and Installing a Custom Kernel</title>
      <indexterm>
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Sun Aug 3 14:40:06 UTC 2008 
State-Changed-Why:  
Further changes to the kernel configuration chapter have 
been made, close this PR.  Thanks. 

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

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/87445: commit references a PR
Date: Sun,  3 Aug 2008 14:39:47 +0000 (UTC)

 trhodes     2008-08-03 14:39:40 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/handbook/kernelconfig chapter.sgml 
   Log:
   Add a section about using modules.
   
   PR:             87445
   Reviewed by:    brueffer, remko
   
   Revision  Changes    Path
   1.185     +47 -0     doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
