diff options
Diffstat (limited to 'static/netbsd/man9/config.9')
| -rw-r--r-- | static/netbsd/man9/config.9 | 352 |
1 files changed, 352 insertions, 0 deletions
diff --git a/static/netbsd/man9/config.9 b/static/netbsd/man9/config.9 new file mode 100644 index 00000000..51a925df --- /dev/null +++ b/static/netbsd/man9/config.9 @@ -0,0 +1,352 @@ +.\" $NetBSD: config.9,v 1.30 2017/07/03 21:28:48 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.Dd March 3, 2010 +.Dt CONFIG 9 +.Os +.Sh NAME +.Nm config +.Nd the autoconfiguration framework +.Do +device definition +.Dc +language +.Sh DESCRIPTION +In +.Nx , +the +.Xr config 1 +program reads and verifies a machine description file (documented in +.Xr config 5 ) +that specifies the devices to include in the kernel. +A table is produced by +.Xr config 1 +which is used by the kernel during autoconfiguration (see +.Xr autoconf 9 ) +giving needed hints and details on matching hardware devices with +device drivers. +.Pp +Each device in the machine description file has: +.Bl -tag -width xxxxxx +.It A Name +The name is simply an alphanumeric string that ends in a unit number +(e.g., "sd0", "sd1", and so forth). +These unit numbers identify particular instances of a base device name; +the base name in turn maps directly to a device driver. +Device unit numbers are independent of hardware features. +.It A Parent +Every device must have a parent. +The pairing is denoted by "child at parent". +These pairings form the links in a directed graph. +The root device is the only exception, as it does not have a parent. +.It Locators +Locators are used to augment the parent/child pairings that locate +specific devices. +Each locator value is simply an integer that represents some sort of +device address on the parent bus or controller. +This can be a memory address, an I/O port, a driver number, or any +other value. +Locators can sometimes be wildcarded on devices that support direct +connection. +.It Attributes +An attribute describes the device's relationship with the code; it +then serves to constrain the device graph. +A +.Em plain attribute +describes some attribute of a device. +An +.Em interface attribute +describes a kind of +.Do +software interface +.Dc +and declares the device's ability to support other devices that use +that interface. +In addition, an interface attribute usually identifies additional locators. +.El +.Pp +During autoconfiguration, the directed graph is turned into a tree by +nominating one device as the root node and matching drivers with +devices by doing a depth-first traversal through the graph starting at +this root node. +.Pp +However, there must be constraints on the parent/child pairings that +are possible. +These constraints are embedded in the +.Do +device definition +.Dc +files. +The remainder of this page describes the +.Do +device definition +.Dc +language and how to use this language to add new functionality to the +.Nx +kernel. +.Sh DEVICE DEFINITION FILES +The device definition files are separated into machine-dependent and +machine-independent files. +The machine-dependent file is located in +.Pa sys/arch/<arch>/conf/files.<arch> , +where <arch> is the name of +.Nx +architecture. +The machine-independent file is located in +.Pa sys/conf/files . +It in turn includes files for the machine-independent drivers located +in +.Pa sys/dev/<bus>/files.<bus> , +where <bus> is the name of the machine-independent bus. +.Pp +These files define all legal devices and pseudo-devices. +They also define all attributes and interfaces, establishing the rules that +determine allowable machine descriptions, and list the source files +that make up the kernel. +.Pp +Each device definition file consists of a list of statements, +typically one per line. +Comments may be inserted anywhere using the +.Do +# +.Dc +character, and any line that begins with white space continues the +previous line. +Valid statements are: +.Bl -tag -width xxxxxx +.It cinclude filename +Conditionally include contents of file +.Ar filename +to currently processed configuration. +If the specified +.Ar filename +doesn't exist, a warning is printed, but the error +ignored. +.It defflag [filename] {options} +The space-separated list of pre-processor macros +.Em options +are defined in file +.Em filename . +This statement permits ``options FOO'' for FOO (i.e, without a value) +in the machine description file. +.Xr config 1 +will generate an error if a value is given. +If the filename field is not specified, it will be constructed based upon +the lower-case of the option name, ``opt_foo.h'' for example. +The +.Em option +is case-sensitive. +.It defparam [filename] {options} +The space-separated list of pre-processor macros +.Em options +are defined in file +.Em filename . +This statement permits ``options FOO=bar'' or ``option FOO="\e"com\e""'' +in the machine description file. +.Xr config 1 +will generate an error if a value is not given. +If the filename field is not specified, it will be constructed based upon +the lower-case of the option name, ``opt_foo.h'' for example. +The +.Em option +is case-sensitive. +.It defopt [filename] {options} +The space-separated list of pre-processor macros +.Em options +are defined in file +.Em filename . +This statement permits the syntax of either the defflag and defparam +statements and +.Xr config 1 +does not perform any checking of whether ``options FOO'' takes a +value. +Therefore, the use of the defopt statement is deprecated in +favour of the defflag and defparam statements. +If the filename field is not specified, it will be constructed based upon +the lower-case of the option name, ``opt_foo.h'' for example. +The +.Em option +is case-sensitive. +.It deffs name [[name] ...] +Define a filesystem +.Em name . +.It devclass name +Define a device class +.Em name . +A device class is similar to an attribute. +.It define name [{locators}] +The attribute +.Em name +is defined and device definitions can then refer to it. +If the attribute is an interface attribute and defines optional +.Em locators , +device attributes that refer to +.Em name +are assumed to share the interface and require the same locators. +.It device name [{locators}]: [attributes] +The device +.Em name +is defined and requires the optional comma-separated list of locators +.Em locators . +The optional +.Em attributes +define attribute dependencies. +.It attach name at interface [with ifname]: [attributes] +The device +.Em name +is defined and supports the interface +.Em interface . +If +.Em ifname +is specified, it is used to specify the interface to the driver for +device +.Em name +(see +.Xr driver 9 +for details). +The optional +.Em attributes +define attribute dependencies. +.It defpseudo name: [{locators}] +The pseudo-device +.Em name +is defined. +The optional +.Em locators +may be defined, but are largely pointless since no device can attach +to a pseudo-device. +.It file pathname [attributes [flags]] [rule] +The file +.Em pathname +is added to the list of files used to build the kernel. +If no attributes are specified, the file is always added to the kernel +compilation. +If any of the attributes are specified by other devices in the machine +description file, then the file is included in compilation, otherwise it +is omitted. +Valid values for the optional flags are: +.Bl -tag -width xxxxxx +.It needs-count +Specify that config should generate a file for each of the attributes +notifying the driver how many of some particular device or set of +devices are configured in the kernel. +This flag allows drivers to make calculations of driver used at compile time. +This option prevents autoconfiguration cloning. +.It needs-flag +This flag performs the same operation as +.Em needs-count +but only records if the number is nonzero. +Since the count is not exact, +.Em needs-flag +does not prevent autoconfiguration cloning. +.El +.It device-major name char [block] [attributes] +The character device switch +.Em name +associated with a character major device number is added to the list of +device switches used to build the kernel. +If +.Em block +is specified, the block device switch associated with a block major device +number is also added. +If all of attributes are specified by devices in the machine description +files, then device switches are added into the device switches' table of +the kernel in compilation, otherwise they are omitted. +.It include Ar filename +Include contents of file +.Ar filename +to currently processed configuration. +If the specified +.Ar filename +doesn't exist, +.Xr config 1 +exits with error. +.It package Ar filename +Changes prefix to directory of +.Ar filename , +processes contents of +.Ar filename , +and switches back to previous prefix. +This is syntactic sugar for: +.Bd -literal -compact -offset indent +.Li prefix Ar dirname(filename) +.Li include Ar basename(filename) +.Li prefix +.Ed +.It prefix Op Ar dirname +If +.Ar dirname +is specified, it is pushed on top of prefix stack. +Any further files specified via option +.Ar file +would have the prefix implicitly prepended before its +.Ar filename . +If +.Ar dirname +is not specified, pops (removes) a prefix from prefix stack. +.El +.Pp +To allow locators to be wildcarded in the machine description file, +their default value must be defined in the attribute definition. +To allow locators to be omitted entirely in the machine description file, +enclose the locator in square brackets. +This can be used when some locators do not make sense for some devices, +but the software interface requires them. +.Sh CODE REFERENCES +The device definition files are in +.Pa sys/conf/files , +.Pa sys/arch/<arch>/conf/files.<arch> , +and +.Pa sys/dev/<bus>/files.<bus> . +.Pp +The grammar for machine description files can be found in +.Xr config 1 , +in +.Pa usr.bin/config/gram.y . +.Sh SEE ALSO +.Xr config 1 , +.Xr config 5 , +.Xr autoconf 9 , +.Xr driver 9 +.Rs +.%T "Building 4.4 BSD Systems with Config" +.Re +.Rs +.%A Chris Torek +.%T "Device Configuration in 4.4BSD" +.%D 1992 +.Re +.Sh HISTORY +Autoconfiguration first appeared in +.Bx 4.1 . +The autoconfiguration framework was completely revised in +.Bx 4.4 . +It has been modified within +.Nx +to support bus-independent drivers and bus-dependent attachments. |