👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for config (netbsd section 5)

CONFIG(5)			     BSD File Formats Manual				CONFIG(5)

NAME
     config -- kernel configuration file syntax

DESCRIPTION
     The kernel configuration file specifies the way the kernel should be compiled by the rest of
     the toolchain.  It is processed by config(1) to produce a number of files that will allow
     the user to compile a possibly customised kernel.	One compilation can issue several kernel
     binaries, with different root and dump devices configurations, or with full debugging infor-
     mation.

     This manual page is intended to serve as a complete reference of all aspects of the syntax
     used in the many files processed by config(1).  The novice user will prefer looking at the
     examples given in config.samples(5) in order to understand better how the default configura-
     tion can be changed, and how all of its elements interact with each other.

     The kernel configuration file actually contains the description of all the options, drivers
     and source files involved in the kernel compilation, and the logic that binds them.  The
     machine statement, usually found in the std.${MACHINE} file, hides this from the user by
     automatically including all the descriptive files spread all around the kernel source tree,
     the main one being conf/files.

     Thus, the kernel configuration file contains two parts: the description of the compilation
     options, and the selection of those options.  However, it begins with a small preamble that
     controls a couple of options of config(1), and a few statements belong to any of the two
     sections.

     The user controls the options selection part, which is located in a file commonly referenced
     as the main configuration file or simply the kernel configuration file.  The developer is
     responsible for describing the options in the relevant files from the kernel source tree.

     Statements are separated by new-line characters.  However, new-line characters can appear in
     the middle of a given statement, with the value of a space character.

   OBJECTS AND NAMES
     config(1) is a rather complicated piece of software that tries to comply with any configura-
     tion the user might think of.  Quite a few different objects are manipulated through the
     kernel configuration file, therefore some definitions are needed.

   Options and attributes
     The basic objects driving the kernel compilation are options, and are called attributes in
     some contexts.  An attribute usually refers to a feature a given piece of hardware might
     have.  However, the scope of an attribute is rather wide and can just be a place holder to
     group some source files together.

     There is a special class of attribute, named interface attribute, which represents a hook
     that allows a device to attach to (i.e., be a child of) another device.  An interface
     attribute has a (possibly empty) list of locators to match the actual location of a device.
     For example, on a PCI bus, devices are located by a device number that is fixed by the
     wiring of the motherboard.  Additionally, each of those devices can appear through several
     interfaces named functions.  A single PCI device entity is a unique function number of a
     given device from the considered PCI bus.	Therefore, the locators for a pci(4) device are
     dev (for device), and function.

     A locator can either be a single integer value, or an array of integer values.  It can have
     a default value, in which case it can be wildcarded with a ``?'' in the options selection
     section of the configuration file.  A single locator definition can take one of the follow-
     ing forms:
	   1.	locator
	   2.	locator = value
	   3.	locator[length]
	   4.	locator[length] = {value, ...}
     The variants that specify a default value can be enclosed into square brackets, in which
     case the locator will not have to be specified later in the options selection section of the
     configuration file.

     In the options selection section, the locators are specified when declaring an instance as a
     space-separated list of ``<locator> <value>'' where value can be the ``?'' wildcard if the
     locator allows it.

   Devices, instances and attachments
     The main benefit of the kernel configuration file is to allow the user to avoid compiling
     some drivers, and wire down the configuration of some others.  We have already seen that
     devices attach to each other through interface attributes, but not everything can attach to
     anything.	Furthermore, the user has the ability to define precise instances for the
     devices.  An instance is simply the reality of a device when it is probed and attached by
     the kernel.

     Each driver has a name for its devices.  It is called the base device name and is found as
     base in this documentation.  An instance is the concatenation of a device name and a number.
     In the kernel configuration file, instances can sometimes be wildcarded (i.e., the number is
     replaced by a ``*'' or a ``?'') in order to match all the possible instances of a device.

     The usual ``*'' becomes a ``?'' when the instance name is used as an attachment name.  In
     the options selection part of the kernel configuration files, an attachment is an interface
     attribute concatenated with a number or the wildcard ``?''.

   Pseudo-devices
     Some components of the kernel behave like a device although they don't have any actual real-
     ity in the hardware.  For example, this is the case for special network devices, such as
     tun(4) and tap(4).  They are integrated in the kernel as pseudo-devices, and can have sev-
     eral instances and even children, just like normal devices.

   Dependencies
     The options description part of the kernel configuration file contains all the logic that
     ties the source files together, and it is done first through writing down dependencies
     between config(1) objects.

     In this documentation, the syntax for dependencies is a comma-separated list of options and
     attributes.

     For example, the use of an Ethernet network card requires the source files that handle the
     specificities of that protocol.  Therefore, all Ethernet network card drivers depend on the
     ether attribute.

   Conditions
     Finally, source file selection is possible through the help of conditionals, referred to as
     condition later in this documentation.  The syntax for those conditions uses well-known
     operators ( ``&'', ``|'' and ``!'') to combine options and attributes.

   CONTEXT NEUTRAL STATEMENTS
     version yyyymmdd
     Indicates the syntax version used by the rest of the file, or until the next version state-
     ment.  The argument is an ISO date.  A given config(1) binary might only be compatible with
     a limited range of version numbers.

     include path
     Includes a file.  The path is relative to the top of the kernel source tree, or the inner-
     most defined prefix.

     cinclude path
     Conditionally includes a file.  Contrary to include, it will not produce an error if the
     file does not exist.  The argument obeys the same rules as for include.

     prefix [path]
     If path is given, it pushes a new prefix for include and cinclude.  prefix statements act
     like a stack, and an empty path argument has the latest prefix popped out.  The path argu-
     ment is either absolute or relative to the current defined prefix, which defaults to the top
     of ther kernel source tree.

     ifdef attribute

     ifndef attribute

     elifdef attribute

     elifndef attribute

     else

     endif
     Conditionally interprets portions of the current file.  Those statements depend on whether
     or not the given attribute has been previously defined, through define or any other state-
     ment that implicitely defines attributes such as device.

   PREAMBLE
     In addition to include, cinclude, and prefix, the preamble may contain the following
     optional statements:

     build path
     Defines the build directory for the compilation of the kernel.  It replaces the default of
     ../compile/<config-file> and is superseded by the -b parameter of config(1).

     source path
     Defines the directory in which the source of the kernel lives.  It replaces the default of
     ../../../.. and is superseded by the -s parameter of config(1).

   OPTIONS DESCRIPTION
     The user will not usually have to use descriptive statements, as they are meant for the
     developer to tie a given piece of code to the rest of the kernel.	However, third parties
     may provide sources to add to the kernel compilation, and the logic that binds them to the
     NetBSD kernel will have to be added to the user-edited configuration file.

     devclass class
     Defines a special attribute, named device class.  A given device cannot belong to more than
     one device class.	config(1) translates that property by the rule that a device cannot
     depend on more than one device class, and will properly fill the configuration information
     file it generates according to that value.

     defflag [file] option [option [...]] [: dependencies]
     Defines a boolean option, that can either be selected or be un-selected by the user with the
     options statement.  The optional file argument names a header file that will contain the C
     pre-processor definition for the option.  If no file name is given, it will default to
     opt_<option>.h.  config(1) will always create the header file, but if the user choose not to
     select the option, it will be empty.  Several options can be combined in one header file,
     for convenience.  The header file is created in the compilation directory, making them
     directly accessible by source files.

     defparam [file] option [= value] [:= lint-value] [option [...]] [: dependencies]
     Behaves like defflag, except the defined option must have a value.  Such options are not
     typed: they can have either a numeric or a string value.  If a value is specified, it is
     treated as a default, and the option is always defined in the corresponding header file.  If
     a lint-value is specified, config(1) will use it as a value when generating a lint configu-
     ration with -L, and ignore it in all other cases.

     deffs name [name [...]]
     Defines a file-system name.  It is no more than a regular option, as defined by defflag, but
     it allows the user to select the file-systems to be compiled in the kernel with the
     file-system statement instead of the options statement.

     obsolete defflag [file] option [option [...]]

     obsolete defparam [file] option [option [...]]
     Those two statements are identical and mark the listed option names as obsolete.  If the
     user selects one of the listed options in the kernel configuration file, config(1) will emit
     a warning and ignore the option.  The optional file argument should match the original defi-
     nition of the option.

     define attribute [{locators}] [: dependencies]
     Defines an attribute.  The locators list is optional, and can be empty.  If the pair of
     brackets are present, the locator list is defined and the declared attribute becomes an
     interface attribute, on which devices can attach.

     maxpartitions number
     Defines the maximum number of partitions the disklabels for the considered architecture can
     hold.  This statement cannot be repeated and should only appear in the std.${ARCH} file.

     maxusers min default max
     Indicates the range of values that will later be accepted by config(1) for the maxusers
     statement in the options selection part of the configuration file.  In case the user doesn't
     include a maxusers statement in the configuration file, the value default is used instead.

     device base [{locators}] [: dependencies]
     Declares a device of name base.  The optional list of locators, which can also be empty,
     indicates the device can have children attached directly to it.  Internally, that means base
     becomes an interface attribute.  For every device the user selects, config(1) will add the
     matching CFDRIVER_DECL() statement to ioconf.c.  However, it is the responsibility of the
     developer to add the relevant CFATTACH_DECL() line to the source of the device's driver.

     attach base at attr [, attr [, ...]] [with name] [: dependencies]
     All devices must have at least one declared attachment.  Otherwise, they will never be found
     in the autoconf(9) process.  The attributes on which an instance of device base can attach
     must be interface attributes, or root in case the device is at the top-level, which is usu-
     ally the case of e.g., mainbus(4).  The instances of device base will later attach to one
     interface attribute from the specified list.

     Different attach definitions must use different names using the with option.  It is then
     possible to use the associated name as a conditional element in a file statement.

     defpseudo base [: dependencies]
     Declares a pseudo-device.	Those devices don't need an attachment to be declared, they will
     always be attached if they were selected by the user.

     defpseudodev base [{locators}] [: dependencies]
     Declares a pseudo-device.	Those devices don't need an attachment to be declared, they will
     always be attached if they were selected by the user.  This declaration should be used if
     the pseudodevice uses autoconf(9) functions to manage its instances or attach children.  As
     for normal devices, an optional list of locators can be defined, which implies an interface
     attribute named base, allowing the pseudo-device to have children.  Interface attributes can
     also be defined in the dependencies list.

     file path [condition] [needs-count] [needs-flag] [compile with rule]
     Adds a source file to the list of files to be compiled into the kernel, if the conditions
     are met.  The needs-count option indicates that the source file requires the number of all
     the countable objects it depends on (through the conditions) to be defined.  It is usually
     used for pseudo-devices whose number can be specified by the user in the pseudo-device
     statement.  Countable objects are devices and pseudo-devices.  For the former, the count is
     the number of declared instances.	For the latter, it is the number specified by the user,
     defaulting to 1.  The needs-flag options requires that a flag indicating the selection of an
     attribute to be created, but the precise number isn't needed.  This is useful for source
     files that only partly depend on the attribute, and thus need to add pre-processor state-
     ments for it.

     needs-count and needs-flag both produce a header file for each of the considered attributes.
     The name of that file is <attribute>.h.  It contains one pre-processor definition of
     NATTRIBUTE set to 0 if the attribute was not selected by the user, or to the number of
     instances of the device in the needs-count case, or to 1 in all the other cases.

     The rule argument specifies the make(1) rule that will be used to compile the source file.
     If it is not given, the default rule for the type of the file will be used.  For a given
     file, there can be more than one file statement, but not from the same configuration source
     file, and all later statements can only specify a rule argument, and no conditions or flags.
     This is useful when a file needs special consideration from one particular architecture.

     object path [condition]
     Adds an object file to the list of objects to be linked into the kernel, if the conditions
     are met.  This is most useful for third parties providing binary-only components.

     device-major base [char number] [block number] [condition]
     Associates a major device number with the device base.  A device can be a character device,
     a block device, or both, and can have different numbers for each.	The condition indicates
     when the relevant line should be added to ioconf.c, and works just like the file statement.

     makeoptions condition name+=value [, condition name+=value]
     Appends to a definition in the generated Makefile.

   OPTIONS SELECTION
     machine machine [arch [subarch [...]]]
     The machine statement should appear first in the kernel configuration file, with the excep-
     tion of context-neutral statements.  It makes config(1) include, in that order, the follow-
     ing files:
	   1.	conf/files
	   2.	arch/${ARCH}/conf/files.${ARCH} if defined
	   3.	arch/${SUBARCH}/conf/files.${SUBARCH} for each defined sub-architecture
	   4.	arch/${MACHINE}/conf/files.${MACHINE}
     It also defines an attribute for the machine, the arch and each of the subarch.

     package path
     Simpler version of:

	   prefix PATH
	   include FILE
	   prefix

     ident string
     Defines the indentification string of the kernel.	This statement is optional, and the name
     of the main configuration file will be used as a default value.

     maxusers number
     Despite its name, this statement does not limit the maximum number of users on the system.
     There is no such limit, actually.	However, some kernel structures need to be adjusted to
     accommodate with more users, and the maxusers parameter is used for example to compute the
     maximum number of opened files, and the maximum number of processes, which itself is used to
     adjust a few other parameters.

     options name [= value] [, name [= value], ...]
     Selects the option name, affecting it a value if the options requires it (see the defflag
     and defparam statements).

     If the option has not been declared in the options description part of the kernel configura-
     tion machinery, it will be added as a pre-processor definition when source files are com-
     piled.

     no options name [, name [, ...]]
     Un-selects the option name.  If option name has not been previously selected, the statement
     produces an error.

     [no] file-system name [, name [, ...]]
     Adds or removes support for all the listed file-systems.

     config name root on device [type fs] [dumps on device]
     Adds name to the list of kernel binaries to compile from the configuration file, using the
     specified root and dump devices information.

     Any of the device and fs parameters can be wildcarded with ``?'' to let the kernel automati-
     cally discover those values.

     At least one config statement must appear in the configuration file.

     no config name
     Removes name from the list of kernel binaries to compile from the configuration file.

     instance at attachment [locator specification]
     Configures an instance of a device attaching at a specific location in the device tree.  All
     parameters can be wildcarded, with a ``*'' for instance, and a ``?'' for attachment and the
     locators.

     no instance [at attachment]
     Removes the previously configured instances of a device that exactly match the given speci-
     fication.	If two instances differ only by their locators, both are removed.  If no
     attachment is specified, all matching instances are removed.

     If instance is a bare device name, all the previously defined instances of that device,
     regardless of the numbers or wildcard, are removed.

     no device at attachment
     Removes all previously configured instances that attach to the specified attachment.  If
     attachment ends with a ``*'', all instances attaching to all the variants of attachment are
     removed.

     pseudo-device device [number]
     Adds support for the specified pseudo-device.  The parameter number is passed to the ini-
     tialisation function of the pseudo-device, usually to indicate how many instances should be
     created.  It defaults to 1, and some pseudo-devices ignore that parameter.

     no pseudo-device name
     Removes support for the specified pseudo-device.

     makeoptions name=value [, name+=value [, ...]]
     Adds or appends to a definition in the generated Makefile.  A definition cannot be overri-
     den, it must be removed before it can be added again.

     no makeoptions name [, name [, ...]]
     Removes one or more definitions from the generated Makefile.

FILES
     The files are relative to the kernel source top directory (e.g., /usr/src/sys).

     arch/${MACHINE}/conf/std.${MACHINE}  Standard configuration for the given architecture.
					  This file should always be included.

     arch/${MACHINE}/conf/GENERIC	  Standard options selection file for the given architec-
					  ture.  Users should always start changing their main
					  kernel configuration file by editing a copy of this
					  file.

     conf/files 			  Main options description file.

EXAMPLES
     config.samples(5) uses several examples to cover all the practical aspects of writing or
     modifying a kernel configuration file.

SEE ALSO
     config(1), options(4), config.samples(5), config(9)

BSD					  March 3, 2010 				      BSD


All times are GMT -4. The time now is 03:31 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password