kern/113670: wrong advertising of default value for HZ in sys/conf/NOTES

[Bruce Evans]

The following reply was made to PR misc/113670; it has been noted by GNATS.

From: Bruce Evans <brde at optusnet.com.au>
To: Ighighi <ighighi at gmail.com>
Cc: freebsd-gnats-submit at FreeBSD.org, freebsd-bugs at FreeBSD.org
Subject: Re: kern/113670: wrong advertising of default value for HZ in
 sys/conf/NOTES
Date: Thu, 14 Jun 2007 17:24:52 +1000 (EST)

 On Thu, 14 Jun 2007, Ighighi wrote:
 
 >> Description:
 > The current src/sys/conf/NOTES (v1.1432) states that:
 >
 > -8<--------------------------------------
 >
 > # CLOCK OPTIONS
 >
 > # The granularity of operation is controlled by the kernel option HZ whose
 > # default value (100) means a granularity of 10ms (1s/HZ).
 >
 > [...]
 > options         HZ=100
 
 NOTES (LINT) is supposed to give a non-default value, so that non-default
 values get tested.
 
 So 100 in the above options directive was a bug when the default was
 100 (I used 101 in NOTES then), but is now correct, while the comment that
 gives the default was correct but is now wrong.
 
 Before this, attached to the options directive for DUMMYNET, is a comment
 that suggests using "optionz HZ=1000", but this is the default.  Similarly
 for DEVICE_POLLING in the MD NOTES.
 
 Reasons why HZ shouldn't be set to 1000 are still in the [...] part
 of the above comment.  These reasons still apply, but on fast machines
 the loss is closer to 0.5% than 5% or 50% so most users don't notice.
 
 > -8<--------------------------------------
 >
 > I guess the real value is 10x that quantity for 4 of the "main" platforms,
 > as defined in src/sys/kern/subr_param.c
 >
 > -8<--------------------------------------
 >
 > #ifndef HZ
 > #  if defined(__amd64__) || defined(__i386__) || defined(__ia64__) || defined(__sparc64__)
 > #    define     HZ 1000
 > #  else
 > #    define     HZ 100
 > #  endif
 > #endif
 >
 > -8<--------------------------------------
 >
 > By looking at the CVS log available at:
 > http://www.FreeBSD.org/cgi/cvsweb.cgi/sys/kern/subr_param.c
 > it can be seen that it has been that way since 6.0-RELEASE, with a just a few
 > platforms being added earlier, and with no mention of it in their respective
 > GENERIC files, thus being the "real thing".
 >
 > I just find it a bit misleading when compiling a new kernel and copy/pasting from NOTES.
 
 Don't copy/paste values from NOTES.  This should give bizarre values.
 Copy values from GENERIC and adjust them according to comments in
 NOTES, but beware that NOTES is likely to be out of date and/or not
 cover all machine dependencies.  E.g., strictly, to match the above ifdef,
 it is a bug for the MI NOTES to have any options for HZ.  It just has
 options that are several years out of date for HZ.  More obscure options
 may be more out of date.
 
 Bruce