'\"!tbl | mmdoc
'\"macro stdmacro
.if n .pH g4.master @(#)master	40.10 of 1/17/90
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} master 4 "" "\&"
.if \nX=1 .ds x} master 4 ""
.if \nX=2 .ds x} master 4 "" "\&"
.if \nX=3 .ds x} master "" "" "\&"
.TH \*(x}
.SH NAME
\f4master\f1 \- master configuration database
.SH DESCRIPTION
The \f4master\fP
configuration database is a collection of files.
Each file contains configuration information for a device
or module that may be included in the system.
A file is named with the module name to which it applies.
This collection of files is maintained in a directory called
\f4/etc/master.d\f1.
Each file has an identical format.
For convenience, this collection of files will be referred to as
the \f4master\fP file,
as though it were a single file.
Treating the
\f4master\fP
file as a single file allows a reference to the
\f4master\fP file to be understood to mean the
individual file in the \f4master.d\f1 directory that
corresponds to the name of a device or module.
The file is used by the \f4mkboot\fP(1M)
program to obtain device information to generate the device
driver and configurable module files.
It is also used by the \f4sysdef\fP(1M) program to obtain
the names of supported devices.
\f4master\fP
consists of two parts;
they are separated by a line with a dollar sign (\f4$\fP)
in column 1.
Part 1 contains device information for both hardware and software devices,
and loadable modules.
Part 2 contains parameter declarations used in Part 1.
Any line with an asterisk (\(**) in column 1 is treated as a comment.
.SS Part 1. Description
Hardware devices,
software drivers
and loadable modules
are defined with a line containing the following information.
Field 1 must begin in the left-most position on the line.
Fields are separated by white space (tab or blank).
.PP
.RS
.PD 0
.TP 10
Field 1:
element characteristics:
.RS 16
.TP 8
\f4o\f1
specify only once
.TP
\f4r\f1
required device
.TP
\f4b\fP 
block device
.TP
\f4c\fP 
character device
.TP
\f4a\fP 
generate segment descriptor array
.TP
\f4t\fP 
initialize \f4cdevsw[].d_ttys\fP
.TP
\f4s\fP
software driver
.TP
\f4f\fP
\s-1STREAMS\s0 driver
.TP
\f4m\fP
\s-1STREAMS\s0 module
.TP
\f4x\fP
not a driver; a loadable module
.TP
\f4number\f1
first interrupt vector for an integral device
.TP
\f4none\f1
no flags for this driver or module
.RE
.TP 10
Field 2:
number of interrupt vectors required by a hardware device: "\f4\-\fP" if none.
.TP
Field 3:
handler prefix (4 characters maximum)
.TP
Field 4:
software driver external major number; "\f4\-\fP" if not a software driver,
or to be assigned during execution of \f4drvinstall\fP(1M)
.TP
Field 5:
number of sub-devices per device;
"\f4\-\fP" if none
.TP
Field 6:
interrupt priority level of the device;
"\f4\-\fP" if none
.TP
Field 7:
dependency list (optional);
this is a comma-separated list of other drivers or modules that must be present in the
configuration if this module is to be included
.PD
.RE
.PP
For each module,
two classes of information are required by
\f4mkboot\fP:
external routine references and variable definitions.
Routine and variable definition lines begin with
white space and immediately follow the initial module specification line.
These lines are free form,
thus they may be continued arbitrarily between non-blank tokens as long
as the first character of a line is white space.
.SS Part 1. Routine Reference Lines
If the
.SM UNIX
system kernel or other dependent module contains
external references to a module, but the module is not configured,
then these external references would be undefined.
Therefore, the
routine reference
lines are used to provide the information necessary to generate
appropriate dummy functions at boot time when the driver is not loaded.
The format of a routine reference is as follows:
.sp .25
.RS
\f2routine_name\f4()\f2action\f4\f1
.RE
.sp .25
The valid actions and their meanings are:
.RS
.PD 0
.TP 12
\f4{}\f1
\f2routine_name\f4(){}\f1
.TP
\f4{nosys}\f1
\f4{return nosys();\f1
.TP
\f4{nodev}\f1
\f4{return nodev();}\f1
.TP
\f4{false}\f1
\f4{return 0;}\f1
.TP
\f4{true}\f1
\f4{return 1;}\f1
.TP
\f4{nopkg}\f1
\f4{return nopkg();}\f1
.TP
\f4{noreach}\f1
panic the system
.PD
.RE
.SS Part 1. Variable Definition Lines
Variable definition lines
are used to generate all variables required by the module.
The variable generated may be of arbitrary size,
be initialized or not,
or be arrays containing an arbitrary number of elements.
Variable references
are defined as follows:
.RS
.TP 12
Field 1:
\f2variable_name\fP
.TP
Field 2:
\f4[ \f2expr\f4 ]\f1 \- optional field used to indicate array size
.TP
Field 3:
\f4(\f2length\f4)\f1 \- required field indicating the size of the variable
.TP
Field 4:
\f4={ \f2expr\f4,... }\f1 \- optional field used to initialize individual elements of
a variable
.RE
.PP
The
.I length
field is mandatory.
It is an arbitrary sequence of length specifiers,
each of which may be one of the following:
.RS
.PD 0
.TP 12
\f4%i\fP
an integer
.TP
\f4%l\fP
a long integer
.TP
\f4%s\fP
a short integer
.TP
\f4%c\fP
a single character
.TP
\f4%\f2number\f1
a field which is \f2number\f1 bytes long
.TP
\f4%\f2number\f4 c\f1
a character string which is \f2number\f1 bytes long
.RE
.PD
.P
For example,
the length field
.P
.RS
.ft 4
( %8c %l %0x58 %l %c %c )
.ft 1
.RE
.P
could be used to identify a variable consisting of a character string 8-bytes long,
a long integer,
a 0x58 byte structure of any type,
another long integer,
and two characters.
Appropriate alignment of each \f4%\fP specification
is performed (\f4%\f2number\f1 is word-aligned)
and the variable length is rounded up to the next
word boundary during processing.
.PP
The expressions for the optional array size and initialization
are infixed expressions
consisting of the usual operators for addition,
subtraction,
multiplication,
and division:
+, \-, \(**, and /.
Multiplication and division have the higher precedence,
but parentheses may be used to
override the default order.
The builtin functions
\f4min\fP
and
\f4max\fP
accept a pair of expressions,
and return the appropriate value.
The operands of the expression may be any mixture of the following:
.RS 3
.TP 10
\f4&\f2name\f1
address of
.IR name ,
where
.I name
is any symbol defined by the kernel,
any module loaded, or any variable definition line of any module loaded
.TP
\f4#\f2name\f1
\f4sizeof \f2name\f1 where
.I name
is any variable name defined by a variable definition for any module loaded;
the size is that of the individual variable\(emnot the size of an entire array
.TP
\f4#C\fP
number of controllers present;
this number is determined by the
.SM EDT
for hardware
devices,
or by the number provided in the system file for non-hardware drivers or modules
.TP
\f4#C(\f2name\f4)\f1
number of controllers present for the module
.IR name ;
this number is determined by the
.SM EDT
for hardware devices,
or by the number provided in the
system file for non-hardware drivers or modules
.TP
\f4#D\fP
number of devices per controller taken directly from the current master file entry
.TP
\f4#D(\f2name\f4)\f1
number of devices per controller taken directly from the master file
entry for the module
.I name
.TP
\f4#M\fP
the internal major number assigned to the current module if it
is a device driver;
zero of this module is not a device driver
.TP
\f4#M(\f2name\f4)\f1
the internal major number assigned to the module
.I name
if it is a device driver:
zero if that module is not a device driver
.TP
\f2name\fP
value of a parameter as defined in the second part of
\f4master\fP
.TP
\f2number\fP
arbitrary number (octal, decimal, or hex allowed)
.TP
\f2string\fP
a character string enclosed within double quotes (all of the character string
conventions supported by the C language are allowed);
this operand has a value which is the address of
a character array containing the
specified string
.RE
.P
When initializing a variable,
one initialization expression should be provided for each
\f4%i\fP, \f4%l\fP, \f4%s\fP, or
\f4%c\fP of the length field.
The only initializers allowed for a \f4%\f2number\f4 c\f1
are either a character string (the string may not be longer than
.IR number ),
or an explicit zero.
Initialization expressions must be separated by commas,
and variable initialization
proceeds element by element.
Note that \f4%\f2number\f1 specification
cannot be initialized\(emthey are set to zero.
Only the first element of an array can be initialized;
the other elements are set to zero.
If there are more initializers than size specifications,
it is an error and execution of the
\f4mkboot\fP
program is aborted.
If there are fewer initializations than size specifications,
zeros will be used to pad the variable.
For example:
.RS
.ft 4
={ "V2.L1", #C\(**#D, max(10,#D), #C(OTHER), #M(OTHER) }
.ft 1
.RE
.P
would be a possible initialization of the variable whose length field was
given in the preceding example.
.SS Part 2. Description
Parameter
declarations may be used to define a value symbolically.
Values can be associated with identifiers and these identifiers may be used
in the
.I "variable definition"
lines.
Parameters are defined as follows:
.sp .25
.RS
\f2identifier\f4 = \f2value\f1
.RE
.sp .25
The
.I identifier
may have a maximum of 8 characters.
The
.I value
may be a number (decimal, octal, or hex)
or a string.
.SH EXAMPLE
A sample \f4master\fP
file for a tty device driver would be named
\f4atty\f1
if the device appeared in the
.SM EDT
as \f4ATTY\f1.
The driver is a character device,
the driver prefix is
\f4at\f1,
two interrupt vectors are used,
and the interrupt priority is 6.
In addition,
another driver named \f4ATLOG\f1
is necessary for the correct operation of the software associated with this device.
.sp .25
.RS
.ft 4
.nf
\(**\|FLAG #VEC PREFIX SOFT #DEV IPL DEPENDENCIES/VARIABLES
 tca     2    at    \-    2   6  ATLOG
                                atpoint(){false}
                                at_tty[#C\(**#D] (%0x58)
                                at_cnt(%i) ={ #C\(**#D }
                                at_logmaj(%i) ={ #M(ATLOG) }
                                at_id(%8c) ={ ATID }
                                at_table(%i%l%31%s)
                                    ={ max(#C,ATMAX),
                                       &at_tty,
                                       #C }
$
ATID = "fred"
ATMAX = 6
.ft1
.fi
.RE
.sp .25
This \f4master\fP
file causes a routine named \f4atpoint\f1
to be generated by the boot program if the \f4ATTY\f1
driver is not loaded,
and there is a reference to this routine from any other module loaded.
When the driver is loaded,
the variables
\f4at_tty\fP,
\f4at_cnt\fP,
\f4at_logmaj\fP,
\f4at_id\fP,
and
\f4at_table\fP
are allocated and initialized as specified.
Because of the
\f4t\f1
flag, the
\f4d_ttys\fP
field
in the character
device switch table is initialized to point to
\f4at_tty\f1
(the first variable definition line contains the variable whose address will be stored 
in \f4d_ttys\f1).
The
\f4ATTY\fP
driver would reference these variables by coding:
.sp .25
.RS
.nf
.ft 4
extern struct tty at_tty[];
extern int at_cnt;
extern int at_logmaj;
extern char at_id[8];
extern struct {
        int member1;
        struct tty \(**member2;
        char junk[31];
        short member3;
        } at_table;
.ft
.fi
.RE
.SH FILES
\f4/etc/master.d/\(**\fP
.SH SEE ALSO
\f4drvinstall\fP(1M),
\f4mkboot\fP(1M),
\f4sysdef\fP(1M),
\f4system\fP(4)
