Bug 87445

Summary:	comments for improvement of handbook/kernelconfig-config.html
Product:	Documentation	Reporter:	Joe Rhett <jrhett>
Component:	Books & Articles	Assignee:	Tom Rhodes <trhodes>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Joe Rhett 2005-10-14 16:50:18 UTC

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.

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.

Comment 1 Tom Rhodes freebsd_committer

2005-10-15 00:30:46 UTC

Responsible Changed
From-To: freebsd-doc->trhodes

Grab.  I would really like to rewrite this chapter.

Comment 2 Tom Rhodes freebsd_committer

2006-06-07 07:58:14 UTC

State Changed
From-To: open->patched

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!

Comment 3 Jo Rhett 2006-06-07 17:26:03 UTC

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

Comment 4 Tom Rhodes freebsd_committer

2008-04-09 09:16:28 UTC

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>

Comment 5 dfilter service freebsd_committer

2008-08-03 15:39:47 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"

Comment 6 Tom Rhodes freebsd_committer

2008-08-03 15:40:06 UTC

State Changed
From-To: patched->closed

Further changes to the kernel configuration chapter have 
been made, close this PR.  Thanks.