Master(4) Master(4)
NAME
Master - generic configuration information for a kernel module
SYNOPSIS
Master
DESCRIPTION
The Master file is one of the Installable Driver/Tunable
Parameters kernel configuration files and it describes a
kernel module that can potentially be configured into the
system. For configuration information for individual kernel
modules see System(4).
When the Master component of a module's Driver Software
Package (DSP) is installed, idinstall(1M) stores the module's
Master file information in /etc/conf/mdevice.d/module-name,
where the file module-name is the name of the module being
installed. Package scripts should never access
/etc/conf/mdevice.d/module-name files directly; instead use
the idinstall(1M) and idtune(1M) commands.
Blank lines in Master files and lines beginning with `#' or
`*' are considered comments and are ignored.
The first non-comment line should be:
$version 2
Older Master file versions are also supported by idinstall
(see Compatibility Considerations).
Following the $version line should be one or more of the
following lines, in any sequence:
$contact contact-information
$depend module-name-list
$entry entry-point-list
$interface interface-name interface-version-list
$magic magic-number-list
$modtype loadable-module-type-name
$name visible-name
$oversion original-version-number
The description of each line follows:
Copyright 1994 Novell, Inc. Page 1
Master(4) Master(4)
$contact
User-readable contact information for the driver
provider. One or more $contact lines, with arbitrary
text, can be supplied. If there is a problem or
potential problem configuring the module, this contact
information might be printed in a warning or error
message.
$depend For dynamically loadable kernel modules only,
specifies the names of the loadable modules (if any)
that contain symbols referenced by this loadable
module. One or more $depend lines can be used to
specify the module names. If a single $depend line
specifies more than one module name, the names must be
separated by white space.
The preferred method for showing dependencies is to
use the $depend line(s) in an Interface_ID(4) file,
which is referenced by a $interface line, rather than
placing $depend line(s) directly in the Master file.
$entry Specifies the names of the entry point routines
included in the module. One or more $entry lines can
be used to specify the entry point names. If a single
$entry line specifies more than one entry point name,
the names must be separated by white space.
The function names are created by appending the entry
point name to the module's prefix. Only functions
explicitly listed on $entry lines are called directly
by the kernel. The following entry points are built
into idbuild(1M) (note that some of these entry points
apply only to certain module types):
_init chpoll close core devinfo exec init intr ioctl
mmap msgio open read segmap size strategy textinfo write
Other entry points are defined by Ftab(4) files.
Entry points that may be used by device drivers are
described in sections D2 and D2I of the book Device
Driver Reference.
Note that open and close routines for STREAMS drivers
and modules are not considered entry points for
$entry, since they are called indirectly through the
module's streamtab structure, not directly.
Similarly, _load, _unload, and _verify routines used
by loadable modules are not listed with $entry since
they are referenced indirectly through a module's
wrapper.
Copyright 1994 Novell, Inc. Page 2
Master(4) Master(4)
$interface
Specifies to which well-defined interface or
interfaces, if any, the module conforms. For example,
you can specify that a DDI/DKI device driver conforms
to a specific version of the ddi interface. This
allows the system to support the use of functions or
variables within well-defined interfaces.
The interface-version-list for each $interface line
consists of one or more version strings. If multiple
versions are specified, the module will work with more
than one version of the specified interface.
Every Master file must contain at least one $interface
line. To be accepted by the system, each interface
line must contain an interface name and version that
is supported by this release of the operating system.
For loadable modules, this evaluation is done when the
module is loaded; for static modules, this is done at
idbuild time.
All external symbol references from a module must be
to symbols defined in one of its specified interfaces,
or to symbols defined in a module for which it has a
$depend line.
The special $interface line $interface base (with no
version strings) can be used by base system modules to
allow symbol references outside of defined interfaces.
For add-on modules, the $interface line $interface
nonconforming can be used to achieve the same effect;
however, this should be avoided since compatibility
support cannot be guaranteed. Modules with $interface
nonconforming may no longer work when the operating
system is upgraded; they may have to be replaced or
deconfigured.
$magic Specifies the magic numbers supported by the exec
module. A leading 0 indicates the base is 8. A
leading 0X or 0x indicates the base is 16.
If wildcard is specified, an additional entry is
generated for the module, following the entries for
the explicit magic numbers. This additional entry has
a NULL magic number pointer that instructs the system
to call the handler regardless of the magic number.
Copyright 1994 Novell, Inc. Page 3
Master(4) Master(4)
If a non-exec module specifies this line or there are
multiple iterations of this line for an exec module,
it is an error.
$modtype
For dynamically loadable kernel modules only,
specifies the character string (maximum of 40
characters, including white space characters) used in
error messages to identify the type of this module.
$name Specifies a visible-name to use instead of module-name
for user-visible aspects of the module, such as the
name for a filesystem as given to the mount(1M)
command.
$oversion
Specifies the original version number (from $version)
of a file that was converted to the current version by
idinstall. This line is automatically appended by
idinstall and is not added manually.
The last non-comment line of the Master file contains the
following six fields:
module-name prefix characteristics order bmaj cmaj
A value must be specified for each field; the fields are
separated by white space.
module-name Specifies the internal name of the module (maximum
of 14 characters). The first character must be
alphabetic; the remaining characters can be
letters, digits or underscores.
prefix Specifies the character string prefixed to all
entry-point routines and variable names associated
with this module (maximum of 8 characters).
During the kernel build process, an all upper-case
version of this string is used to construct the
#define symbolic constants accessible to the
module's Space.c file [see idbuild(1M)].
If the module has no entry-points or special
variables, this field can contain a dash; then, no
#define symbols are generated.
Copyright 1994 Novell, Inc. Page 4
Master(4) Master(4)
characteristics
Defines a set of flags that identify the
characteristics of the module. If none of the
characteristics listed below apply to the module,
the characteristics field must contain a dash.
Valid field values are:
b The module is a ``block'' device driver.
c The module is a (STREAMS or non-STREAMS)
character device driver.
d The module is a dispatcher class module.
e The module is an exec module.
h The module controls hardware or requires
access to hardware I/O resources (for
example, interrupts or bus addresses). This
flag must be used for any module that
specifies resources (including interrupts)
in its System file.
k Keep majors flag. This flag is intended for
device drivers supplied with the base system
only. It indicates that idinstall should
use the major numbers specified by the bmaj
and cmaj fields in the module's Master file,
instead of automatically assigning major
numbers to the module. These reserved major
numbers must be specified in the res_major
file [see res_major(4)].
l The module contains loadable stubs
(Modstub.o). This should be used only by
base system modules. Add-on drivers cannot
use loadable stubs.
m The module is a STREAMS module.
o The module may have only one System file
entry.
u The module is a device driver that requires
identical block major numbers and character
major numbers. Note that both the b and c
Copyright 1994 Novell, Inc. Page 5
Master(4) Master(4)
flags must be set when using this flag; if
they are not set, the u flag is ignored.
C The module contains console driver support
and the variable pfxconssw that defines the
console (indirect) entry points. Such a
module is referred to as console-capable.
D The module is a hardware module that can
share its DMA channel(s) with other drivers.
F The module is a VFS file system module.
K Keep nodes flag. This flag prevents
idmknod(1M) from removing device nodes for
this device (as determined by the major
number(s) in the Master file).
L Loadable module flag. The driver module is
a loadable module; however, if the System
file contains $static, then this entry
overrides the flag and the module is
statically linked.
M The CMA range of this device can overlap
that of another device.
O The IOA range of this device can overlap
that of another device.
S The module is a STREAMS driver, a STREAMS
module, or both.
order Specifies a decimal numeric value used to control
the sequence in which the module's init and start
routines are called, and the sequence of execsw
entries for exec modules. Higher-numbered values
are first. For most modules, the sequence is
unimportant, and this field should be 0.
All the execsw entries are processed in the sequence
specified in this field, calling the appropriate
handlers if the magic number matches, until one
returns 0 for success or an error other than
ENOEXEC.
Copyright 1994 Novell, Inc. Page 6
Master(4) Master(4)
bmaj When the b flag is set, specifies the block major
number(s) for this module. Typically, drivers do
not specify the actual major number(s). Instead,
this field is a placeholder that is modified by
idinstall(1M) when the driver is installed;
idinstall(1M) assigns an unused major number to this
driver.
For most drivers, bmaj is a single decimal number.
When the driver needs multiple major numbers, this
entry is a range: the first and last number of the
range, separated by a dash. For example, to request
four major numbers, a driver can set bmaj to 0-3,
and this entry will be changed to an assigned range
of major numbers.
When the k flag is set, the original value of bmaj
is unchanged by idinstall(1M). Note that this flag
is intended for installations with the base system
only.
cmaj When the c flag is set, the cmaj entry is processed
as described for bmaj except that cmaj applies to
character major number(s) rather than block major
number(s).
USAGE
Specifying STREAMS Devices and Modules
STREAMS modules and drivers are treated in a slightly
different way from other drivers, and their configuration
reflects this difference. To specify a STREAMS device driver,
its Master file should specify both an S and a c flag in the
characteristics field. This indicates that it is a STREAMS
driver and that it requires an entry in the cdevsw table,
where STREAMS drivers typically are configured into the
system.
A STREAMS module that is not a device driver, such as a line
discipline module, requires both an S and an m flag in the
characteristics field of its Master file; it should not
specify a c flag, as a device driver does.
In cases where a module contains both a STREAMS module and a
STREAMS driver, the S, c and m flags should all be specified.
Copyright 1994 Novell, Inc. Page 7
Master(4) Master(4)
Warnings
Package scripts should never access /etc/conf/mdevice.d files
directly; only the idinstall(1M) and idcheck(1M) commands
should be used.
NOTICES
Compatibility Considerations
For compatibility with existing add-on DSP packages, idinstall
accepts the old (version 0 and version 1) Master file formats,
and converts them to the current version 2 format.
Version 0 format:
Version 0 Master files are not supported for exec modules.
The version 0 format is a single non-comment line that
contains the following nine fields:
name funcs characteristics prefix bmaj cmaj min_unit max_unit dmachan
When converting version 0 mdevice files to the current format:
The funcs field is converted into $entry lines.
The following characteristics flags are obsolete and
ignored: a, i, n, r, s, t, G, H, M, N, R (the f flag in
the version 0 mdevice file will still be recognized, but
should not be used in a version 2 Master file).
The min_unit and max_unit fields are obsolete and
ignored.
The dmachan field is moved to the System file.
$interface lines are generated. These are deduced from
external symbol references in the Driver.o and from old
$dversion lines and p flags that are removed. Because
of this, a version 0 Master cannot be converted to
version 2 unless both a System file and a Driver.o are
present.
Version 1 format:
The version 1 format is closer to the current version 2
format, except that the last line can have an optional seventh
field that is the cpu field used to bind the driver to a
specific processor.
Copyright 1994 Novell, Inc. Page 8
Master(4) Master(4)
The cpu field is moved to the System file for version 2.
The following characteristics flags are obsolete and
ignored: a, i, n, p, r, s, t, G, H, M, N, R; the old Q
flag is converted to the new C flag.
$interface lines are generated. These are deduced from
external symbol references in the Driver.o and from old
$dversion lines and p flags that are removed. Because
of this, a version 1 Master cannot be converted to
version 2 unless both a System file and a Driver.o are
present.
mfsys files:
The idinstall(1M) command accepts obsolete mfsys files and
converts them to version 2 Master file format.
REFERENCES
Ftab(4), idbuild(1M), idcheck(1M), idinstall(1M),
Interface_ID(4), Master(4), modadmin(1M), res_major(4),
Space.c(4), System(4)
Copyright 1994 Novell, Inc. Page 9