master(4) — FILE FORMATS

NAME

master − master configuration database

DESCRIPTION

The master 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 /etc/master.d. Each file has an identical format. For convenience, this collection of files will be referred to as the master file, as though it were a single file. Treating the master file as a single file allows a reference to the master file to be understood to mean the individual file in the master.d directory that corresponds to the name of a device or module. The file is used by the mkboot(1M) program to obtain device information to generate the device driver and configurable module files. It is also used by the sysdef(1M) program to obtain the names of supported devices. master consists of two parts; they are separated by a line with a dollar sign ($) 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. Only two parts are supported in the master file, multiple uses of the ($) token are not allowed. Any line with an asterisk (∗) in column 1 is treated as a comment.

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).

Field 1: element characteristics:

b block device

c character device

d dispatch driver

e executable-type driver

f STREAMS driver

h hardware driver

j file-system driver

m STREAMS module

n new-style device driver

none no flags for this driver or module

o specify only once

r required device

s software driver

t initialize cdevsw[].d_ttys

x not a driver; a loadable module

M multi-threaded driver or module

[0-9] If this is a STREAMS driver or module (f or m) than this element defines the synchronization queue level used. See the following Note: for the complete description for synchronization queue levels. For all other drivers, this element defines the processor number for a statically bound driver

Field 2: handler prefix (4 characters maximum)

Field 3: hardware/software driver external major number; "−" if not a software/hardware driver, or to be assigned during execution of drvinstall(1M)

Field 4: number of sub-devices per device; "−" if none

Field 5: 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

Note:

Starting in R40V4.3, all STREAMS devices and modules will use the synchronization queue method to control the behavior of the device/module in a multiprocessor environment. An extension queue flag, QPROTECTED, has been added to the normal STREAMS framework to allow the safe access of a queue during interrupt context. If a driver uses getq(D3DK) during an interrupt, this extension should be enabled.

The synchronization queue (sync queue) method provides for a flexible way for a driver/module to establish MP safe operation. The definition of the sync queues allows for configuration from the individual queue level to a system wide synchronization. Included here is a short description of the available sync queue levels (SQLVL).

SQLVL_QUEUE
A queue associated with this module will acquire a sync queue for that queue before execution. Each queue may be run on any cpu, in concurrence with other queues in this module. This corresponds directly to option "M" in previous releases.

SQLVL_QUEUEPAIR
Each pair of queues, the read and write, jointly provide the synchronization. Any pair may be active on any cpu concurrently. This functionality is new.

SQLVL_MODULE
All queues in a module will acquire a single module sync queue before execution. The queue may run on any cpu. This corresponds to the "[no]M" (M not specified or cpu number) case.

SQLVL_GLOBAL
All queues in the module will acquire a system wide global sync queue before execution. The queues may be run on any cpu. This functionality is new.

SQLVL_CPU0
All queues in the modules will acquire the system wide sync queue for CPU0. Additionally, these queues will only be run on CPU 0. This corresponds to the earlier release "0" case.

The following mapping allows the STREAMS developer to select the type of configuration required.

option	SQLVL	QPROTECTED

M	SQLVL_QUEUE	off
[no]M	SQLVL_MODULE	on
0	SQLVL_CPU0	on
1	SQLVL_QUEUE	on
2	SQLVL_QUEUEPAIR	off
3	SQLVL_QUEUEPAIR	on
4	SQLVL_MODULE	off
5	SQLVL_GLOBAL	off
6	SQLVL_GLOBAL	on
7	SQLVL_CPU0	off

For each module, two classes of information are required by mkboot: 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.

Part 1. Routine Reference Lines

If the 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:

routine_name()action

The valid actions and their meanings are:

{} routine_name(){}

{nosys} {return nosys();

{nodev} {return nodev();}

{false} {return 0;}

{true} {return 1;}

{nopkg} {return nopkg();}

{noreach} panic the system

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 an array containing an arbitrary number of elements. Variable references are defined as follows:

Field 1: variable_name

Field 2: [ expr ] − optional field used to indicate array size

Field 3: (length) − required field indicating the size of the variable

Field 4: ={ expr,... } − optional field used to initialize individual elements of a variable

The length field is mandatory. It is an arbitrary sequence of length specifiers, each of which may be one of the following:

%i an integer

%l a long integer

%s a short integer

%c a single character

%number a field which is number bytes long

%number c a character string which is number bytes long

For example, the length field

( %8c %l %0x58 %l %c %c )

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 % specification is performed (%number
is word-aligned) and the variable length is rounded up to the next word boundary during processing.

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 min and max accept a pair of expressions, and return the appropriate value. The operands of the expression may be any mixture of the following:

&name address of name, where name is any symbol defined by the kernel, any module loaded, or any variable definition line of any module loaded

#name sizeof name where name is any variable name defined by a variable definition for any module loaded; the size is that of the individual variable—not the size of an entire array

#C number of controllers present; this number is determined by the EDT for hardware devices, or by the number provided in the system file for non-hardware drivers or modules

#C(name) number of controllers present for the module name; this number is determined by the EDT for hardware devices, or by the number provided in the system file for non-hardware drivers or modules

#D number of devices per controller taken directly from the current master file entry

#D(name) number of devices per controller taken directly from the master file entry for the module name

#M the internal major number assigned to the current module if it is a device driver; zero of this module is not a device driver

#M(name) the internal major number assigned to the module name if it is a device driver: zero if that module is not a device driver

name value of a parameter as defined in the second part of master

number arbitrary number (octal, decimal, or hex allowed)

string 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

When initializing a variable, one initialization expression should be provided for each %i, %l, %s, or %c of the length field. The only initializers allowed for a %number c are either a character string (the string may not be longer than number), or an explicit zero. Initialization expressions must be separated by commas, and variable initialization proceeds element by element. Note that %number specification cannot be initialized—they are set to zero. Multiple elements of an array may be initialized; uninitialized elements are set to zero. If there are more initializers than size specifications, it is an error and execution of the mkboot program is aborted. In the case of an array, mkboot will report an error only if the array’s dimension is a literal. C UNIX will report an error if the dimension is a symbol or expression and too many initializers are given. If there are fewer initializations than size specifications, zeros will be used to pad the variable. For example:

={ "V2.L1", #C∗#D, max(10,#D), #C(OTHER), #M(OTHER) }

would be a possible initialization of the variable whose length field was given in the preceding example.

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 variable definition lines. Parameters are defined as follows:

identifier = value

The identifier may have a maximum of 8 characters. The value may be a number (decimal, octal, or hex) or a string.

An optional extension can follow the parameter definition. This extension contains additional descriptive information, such as the brief descriptions, default (factory) values, suggested value ranges, recommended increments, and a flag indicating whether the parameter should be changed by the user.

This format of the extended information is the following:

identifier = value or string
{
description = string
default = value or string
range = string
tunable = true or false
}

The curly braces must reside on lines by themselves. The label tokens (e.g. description, default, etc.) and their values must reside on the same line with no carriage returns or line feeds separating them. All strings must be surrounded by double quotes. All the labels are optional. When no labels are used, the curly braces are also optional. It is recommended that the description string be limited to 55 characters or less. The default field should indicate the "factory" setting and should not be changed by the user. The range information contained in the range string is the suggested limits for the parameter and should not be taken as absolute limits. The increment information contained in the range string is the recommended increment for the parameter. The tunable flag indicates whether the user can safely change this parameter.

The format of the range string is the following:

"min value..max value(increment)"

Other possible range strings are:

"not applicable" or ""

min value and max value is one of the following:

parameter indicates the current value of parameter is the suggested minimum or maximum value; parameter can also be used in an arithmetic expression (e.g. must be twice NPROC: NPROC∗2).

UNKNOWN_MIN
no suggested minimum value currently exists

UNKNOWN_MAX
no suggested maximum value currently exists

~x x is an approximate minimum or maximum value

x x is a recommended minimum or maximum value

increment must be in the following form:

(+x) increments by x (x can be the token UNKNOWN)

(∗x) increments by multiples of x

(^x) increments in powers of x

The extended information is only provided to the user for description purposes only. No enforcement of the range, increment or tunable abilities are made by any system utilities.

EXAMPLE

A sample master file for a tty device driver would be named atty if the device appeared in the EDT as ATTY. The driver is a character device, the driver prefix is at. In addition, another driver named ATLOG is necessary for the correct operation of the software associated with this device.

∗FLAG PREFIX SOFT #DEV DEPENDENCIES/VARIABLES
tca    at    −    2     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"
{
description = "async tty identifier"
default = "fred"
tunable = false
}
ATMAX = 6
{
description = "maximum supported ttys"
default = 6
range = "1..8(+1)"
tunable = true
}

This master file causes a routine named atpoint to be generated by the boot program if the ATTY driver is not loaded, and there is a reference to this routine from any other module loaded. When the driver is loaded, the variables at_tty, at_cnt, at_logmaj, at_id, and at_table are allocated and initialized as specified. Because of the t flag, the d_ttys field in the character device switch table is initialized to point to at_tty (the first variable definition line contains the variable whose address will be stored in d_ttys). The ATTY driver would reference these variables by coding:

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;

FILES

/etc/master.d/∗

Museum

Related Articles