[src/uebayasi-xip]: src/share/man/man9 \\ -> \e

[joerg <joerg%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7fb9aac57e0f
branches:  uebayasi-xip
changeset: 751638:7fb9aac57e0f
user:      joerg <joerg%NetBSD.org@localhost>
date:      Mon Apr 05 19:27:17 2010 +0000

description:
\\ -> \e

diffstat:

 share/man/man9/config.9 |  359 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 359 insertions(+), 0 deletions(-)

diffs (truncated from 363 to 300 lines):

diff -r b4e23dea44db -r 7fb9aac57e0f share/man/man9/config.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/config.9   Mon Apr 05 19:27:17 2010 +0000
@@ -0,0 +1,359 @@
+.\"     $NetBSD: config.9,v 1.28.2.2 2010/04/05 19:27:17 joerg 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/\*[Lt]arch\*[Gt]/conf/files.\*[Lt]arch\*[Gt] ,
+where \*[Lt]arch\*[Gt] 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/\*[Lt]bus\*[Gt]/files.\*[Lt]bus\*[Gt] ,
+where \*[Lt]bus\*[Gt] 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: