[review request] New config.5 manual page

[Joseph Koshy]

The attached manual page documents the syntax for the kernel configuration
files as understood by the config(8) program in 5-CURRENT.  This syntax has 
diverged from the syntax understood by the original 4.4BSD config(8) program,
and it is perhaps time for a new manual page.

This manual entry is to be added to section 5 (file formats) of the 
FreeBSD manual.

Could you please review and send in your comments?


Joseph Koshy   <[EMAIL PROTECTED]>
Developer, The FreeBSD Project http://people.freebsd.org/~jkoshy/
.\" Copyright (c) 2003  Joseph Koshy
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"notice, this list of conditions and the following disclaimer in the
.\"documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man5/quota.user.5,v 1.3 2002/12/12 17:25:57 ru Exp 
$
.\"
.Dd June 03, 2003
.Dt CONFIG 5
.Os
.Sh NAME
.Nm config
.Nd kernel configuration file format
.Sh DESCRIPTION
A kernel configuration file specifies the configuration of a
.Fx
kernel.
It is processed by
.Xr config 8
to create a build environment where a kernel may be built using
.Xr make 1 .
.Sh LEXICAL STRUCTURE
A kernel configuration file comprises a sequence of specification
directives.
.Pp
A specification directive starts with a keyword at the beginning
of the line and is followed by additional parameters.
.Pp
A specification directive may be terminated by a semicolon
.Ql \&;
or by a newline.
Long input lines may be broken into shorter lines by
starting the second and subsequent lines with a white
space character.
.Pp
Case is significant,
.Ql machine
and
.Ql MACHINE
are different tokens.
.Pp
A double quote character
.Ql \&\*q
starts a quoted string.
All characters up to the next quote character form the value
of the quoted string.
A
.Ql \&\*q
character may be inserted into a quoted string by
using the sequence
.Ql \e\*q .
.Pp
Number are specified using
.Li C Ns No -style
syntax.
.Pp
A
.Ql #
character starts a comment; all characters from the
.Ql #
character till end of line are ignored.
.Pp
Whitespace between tokens is ignored, except inside quoted strings.
Whitespace following a comment line is ignored.
.Sh CONFIGURATION DIRECTIVES
Kernel configuration directives may appear in any order
in a kernel configuration file.
Directives are processed in order of appearance with subsequent
directive lines overriding the effect of prior ones.
.Pp
The list of keywords and their meanings are as follows:
.Bl -tag -width "makeoptions"
.\"  CPU 
.It Cm cpu Ar cputype
Specify the CPU this kernel will run on.
There can be more than one
.Li cpu
directives in a configuration file.
The allowed list of cpu names is architecture specific and is
defined in the file
.Pa "sys/conf/options." Ns Ar arch .
.\"  DEVICE 
.It Cm device Ar name Op count
Configures device
.Ar name
for inclusion into the kernel image.
If
.Ar count
is specified, the device is configured for
.Ar count
instances.
The list of valid device names is architecture specific and are
defined in the files
.Pa "sys/conf/files"
and
.Pa "sys/conf/files." Ns Ar arch .
.\"  ENV 
.It Cm env Ar filename
Specifies a filename containing a kernel environment definition.
The kernel normally uses an environment prepared for it at boot time
by
.Xr loader 8 .
This directive makes the kernel ignore the boot environment and use
the compiled in environment instead.
.Pp
This directive is useful for setting kernel tunables in
embedded environments that do not start from
.Xr loader 8 .
.\"  HINTS 
.It Cm hints Ar filename
Specifies a file to load a static device configuration specification
from.
From
.Fx 5.0
onwards, the kernel picks up the device configuration at boot time
(see
.Xr device.hints 5 Ns ).
This directive configures the kernel to use the static device configura

Re: [review request] New config.5 manual page

[John]

Dealing with maxusers can be a bit confusing depending upon
the approach taken.  You may want to add a bit of additional
information:

 maxusers number
  This optional directive is used to configure the size of
  some kernel data structures.  number should be an integer
  between 2 and 512, or can be 0.  From FreeBSD 4.5 onwards,
  the kernel will automatically size its tables according to
  the available physical memory if maxusers is not specified
  or is specified to be 0.  As explained in tuning(7), this
  tunable can also be set on a running kernel using sysctl(8).


  When maxusers is not specified and thus automatically
  sized, the default maximum is 384. To increase maxusers
  beyond 384 requires either a config entry or boot time
  override. As noted above, the config entry for maxusers
  is limited to 512. If a maxusers of 1024 is desired, an
  entry in /boot/loader.conf is required.


   If the maxusers can be specified in multiple locations, the limits
placed on the value should be similar/identical. Any differences in the
way the value is treated should be well documented (or fixed).  As we
move into larger memory systems our current limitations need to be either
removed or increased.
  
   Hope this helps.

-John

___
[EMAIL PROTECTED] mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-current
To unsubscribe, send any mail to "[EMAIL PROTECTED]"

Re: [review request] New config.5 manual page

[Joseph Koshy]

> placed on the value should be similar/identical. Any differences in the
> way the value is treated should be well documented (or fixed).  As we
> move into larger memory systems our current limitations need to be either
> removed or increased.

Yes, you are right.  It doesn't make sense to restrict the value of maxusers 
at configuration time, when the kernel can be configured to use larger values
at boot time.

I think it makes sense to remove the maximum bound on a statically
configured 'maxusers' value.  The lower bound could be retained
as a sanity check.

Something like this?

Index: mkoptions.c
===
RCS file: /cvs/FreeBSD/src/usr.sbin/config/mkoptions.c,v
retrieving revision 1.30
diff -u -r1.30 mkoptions.c
--- mkoptions.c 15 Feb 2003 02:26:13 -  1.30
+++ mkoptions.c 5 Jul 2003 04:42:44 -
@@ -52,11 +52,7 @@
 #include "config.h"
 #include "y.tab.h"
 
-static struct users {
-   int u_default;
-   int u_min;
-   int u_max;
-} users= { 8, 2, 512 };
+#define U_MIN 2
 
 static char *lower(char *);
 static void read_options(void);
@@ -79,13 +75,10 @@
SLIST_INSERT_HEAD(&opt, op, op_next);
}   
 
-   if (maxusers == 0) {
-   /* printf("maxusers not specified; will auto-size\n"); */
-   } else if (maxusers < users.u_min) {
-   printf("minimum of %d maxusers assumed\n", users.u_min);
-   maxusers = users.u_min;
-   } else if (maxusers > users.u_max)
-   printf("warning: maxusers > %d (%d)\n", users.u_max, maxusers);
+   if (maxusers && maxusers < U_MIN) {
+   printf("minimum of %d maxusers assumed\n", U_MIN);
+   maxusers = U_MIN;
+   }
 
/* Fake MAXUSERS as an option. */
op = (struct opt *)malloc(sizeof(*op));


-- 
Joseph Koshy   <[EMAIL PROTECTED]>
Developer, The FreeBSD Project http://people.freebsd.org/~jkoshy/



___
[EMAIL PROTECTED] mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-current
To unsubscribe, send any mail to "[EMAIL PROTECTED]"