Bug 70674

Attach patch since URL's makes PR's difficult to work with.

-- 
Joel

On Fri, Aug 20, 2004 at 04:50:32PM +0000, Joel Dahl wrote:
>  --- chapter.sgml	Thu Aug 19 16:05:42 2004
>  +++ new.chapter.sgml	Thu Aug 19 21:16:12 2004


Great going!  A rewrite (or at least a retouch) of the kernel config
section is indeed needed, thanks for taking the time to do it!
But... :) see below for a couple of comments.

>  @@ -426,19 +426,18 @@
>         some related keywords have been grouped together in a single section
>         (such as Networking) even though they are actually scattered
>         throughout the <filename>GENERIC</filename> file.  <anchor

[snip]
>  +      id="kernelconfig-options"> An exhaustive list of architecure
>  +      dependent options and more detailed explanations of the device lines
>  +      is present in the <filename>NOTES</filename> configuration file,
>  +      located in the same directory as <filename>GENERIC</filename>. If you
>  +      are in doubt as to the purpose or necessity of a line, check first in
>  +      <filename>NOTES</filename>. Architecure independent options are
>  +      stored in <filename>/usr/src/sys/conf/NOTES</filename>.</para>
>  +
>  +    <note><para>In &os; 4.X and earlier <filename>NOTES</filename> is
>  +      non-existent. Instead, see the <filename>LINT</filename> file for
>  +      detailed explanations of options in <filename>GENERIC</filename>.
>  +      </para></note>


Actually, just substituting NOTES for LINT is not quite (or at least not
completely) correct.  It is true that the sys/conf/NOTES and
sys/<arch>/conf/NOTES files are the place one should look when choosing
kernel options to include (or remove) when building a custom kernel
config, so that much is correct.  However, there is a bit more to be
said about the NOTES vs LINT issue, and it might need a little detour
into history :)

The purpose of the LINT kernel config in FreeBSD 4.x and earlier was
actually twofold: to provide a reference for choosing kernel options
when building a custom kernel, *and* to provide a kernel configuration
file with as much drivers/options included as possible and as many
tweakable knobs tweaked to non-default values as possible.  The idea was
that such a kernel config should (and does) help a lot in checking
whether new code or changes to existing code will cause conflicts with
other parts of the kernel.

Then, about 4 years ago, Peter Wemm borrowed Poul-Henning Kamp's axe and
took it to the kernel configuration framework, almost turning the thing
inside out :)  The part of this change that interests us most is the
fact that the driver configuration options that were so far stored in
the kernel config (e.g. 'device ppc0 at isa? irq 7') were moved to a
so-called 'hints' file, so that they could be changed and loaded
dynamically at boot time.  Among other things, this meant that the LINT
file could no longer contain those hints (since the syntax had changed
to just 'device ppc' and a separate line *in a separate file*), so for
this and other reasons, the file-formerly-known-as-LINT was renamed to
(nope, not 'Symbol') NOTES and retained mostly the first reason for its
existence: documenting the available options for user convenience.
However, the second reason - building a kernel with all the bells and
whistles and seeing which of those do not play nice with each other -
was (and is) still very, very important, so in the same change 4 years
ago Peter Wemm also created sys/<arch>/conf/Makefile with the sole
purpose of taking sys/<arch>/conf/NOTES and sys/conf/NOTES and
converting them into a buildable kernel config file named - yep, you
guessed it - LINT.

So basically, it's not so much that NOTES doesn't exist in 4.x, it's
more like LINT turned to NOTES in 5.x, but you can still generate a
buildable LINT:

  # cd /sys/i386/conf && make LINT

...and you can later build the LINT kernel:

  # cd /usr/src && make KERNCONF=LINT NO_MODULES=yes buildkernel

(the NO_MODULES part serves two purposes: first, pretty much all the
code is *in* the LINT kernel, and second, nobody in their right mind
would actually try to *boot* the thing :)

Soooo... do you think you could somehow integrate some of those mindless
ravings of mine (rewording where necessary :) into your changes?  And
it's okay if you don't want to - sometimes I amaze myself when I look at
things I've written a couple of months ago and wonder just how could I
have been so dumb and/or unclear :)

G'luck,
Peter

-- 
Peter Pentchev	roam@ringlet.net    roam@cnsys.bg    roam@FreeBSD.org
PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
If this sentence didn't exist, somebody would have invented it.

>  Soooo... do you think you could somehow integrate some of those
mindless
>  ravings of mine (rewording where necessary :) into your changes?

Yes, one way or another. ;)

I've also spotted some minor errors in my patch, so I'll try to submit a
better one in a few days, as a follow-up to this one.
 
>  G'luck,
>  Peter

Thanks,
Joel

Comment 4 Ceri Davies 2004-08-26 11:37:10 UTC

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

Take this.

This updated patch fixes a few minor errors and adds some descriptions.
Any thoughts on this? Good or bad?

As a side note, I did not put my name in the "updated by" section at the
top of chapter 8.1 (Synopsis). I don't know if this is necessary.

-- 
Joel

Two late comments:

#1
SCHED_4BSD will replace SCHED_ULE in RELENG_5. SCHED_ULE is described in
the patch, so we need to change this.

#2
PFIL_HOOKS has been removed from GENERIC in HEAD (a while ago). I don't
know if this is going to be MFC'd.

Comment 7 Ceri Davies 2004-09-10 20:13:31 UTC

State Changed
From-To: open->closed

Committed in revision 1.135; thanks very much!