- 1 -
Building Berkeley UNIX* Kernels with Config
Samuel J. Leffler and Michael J. Karels
Computer Systems Research Group
Department of Electrical Engineering and Computer Science
University of California, Berkeley
Berkeley, California 94720
ABSTRACT
This document describes the use of config(8) to
configure and create bootable 4.3BSD system images. It
discusses the structure of system configuration files
and how to configure systems with non-standard hardware
configurations. Sections describing the preferred way
to add new code to the system and how the system's
autoconfiguration process operates are included. An
appendix contains a summary of the rules used by the
system in calculating the size of system data struc-
tures, and also indicates some of the standard system
size limitations (and how to change them). Other confi-
guration options are also listed.
Revised April 17, 1991
1. INTRODUCTION
Config is a tool used in building 4.3BSD system images (the
UNIX kernel). It takes a file describing a system's tunable
parameters and hardware support, and generates a collection of
files which are then used to build a copy of UNIX appropriate to
that configuration. Config simplifies system maintenance by iso-
lating system dependencies in a single, easy to understand, file.
This document describes the content and format of system
configuration files and the rules which must be followed when
creating these files. Example configuration files are
_________________________
*UNIX is a Trademark of Bell Laboratories.
April 27, 2013
SMM:2-2 Building Kernels with Config
constructed and discussed.
Later sections suggest guidelines to be used in modifying
system source and explain some of the inner workings of the auto-
configuration process. Appendix D summarizes the rules used in
calculating the most important system data structures and indi-
cates some inherent system data structure size limitations (and
how to go about modifying them).
2. CONFIGURATION FILE CONTENTS
A system configuration must include at least the following
pieces of information:
+ machine type
+ cpu type
+ system identification
+ timezone
+ maximum number of users
+ location of the root file system
+ available hardware
Config allows multiple system images to be generated from a
single configuration description. Each system image is config-
ured for identical hardware, but may have different locations for
the root file system and, possibly, other system devices.
2.1. Machine type
The machine type indicates if the system is going to operate
on a DEC VAX-11- computer, or some other machine on which 4.3BSD
operates. The machine type is used to locate certain data files
which are machine specific, and also to select rules used in con-
structing the resultant configuration files.
2.2. Cpu type
The cpu type indicates which, of possibly many, cpu's the
system is to operate on. For example, if the system is being con-
figured for a VAX-11, it could be running on a VAX 8600, VAX-
11/780, VAX-11/750, VAX-11/730 or MicroVAX II. (Other VAX cpu
types, including the 8650, 785 and 725, are configured using the
cpu designation for compatible machines introduced earlier.)
Specifying more than one cpu type implies that the system should
_________________________
- DEC, VAX, UNIBUS, MASSBUS and MicroVAX are trademarks
of Digital Equipment Corporation.
April 27, 2013
Building Kernels with Config SMM:2-3
be configured to run on any of the cpu's specified. For some
types of machines this is not possible and config will print a
diagnostic indicating such.
2.3. System identification
The system identification is a moniker attached to the sys-
tem, and often the machine on which the system is to run. For
example, at Berkeley we have machines named Ernie (Co-VAX), Kim
(No-VAX), and so on. The system identifier selected is used to
create a global C ``#define'' which may be used to isolate system
dependent pieces of code in the kernel. For example, Ernie's
Varian driver used to be special cased because its interrupt vec-
tors were wired together. The code in the driver which under-
stood how to handle this non-standard hardware configuration was
conditionally compiled in only if the system was for Ernie.
The system identifier ``GENERIC'' is given to a system which
will run on any cpu of a particular machine type; it should not
otherwise be used for a system identifier.
2.4. Timezone
The timezone in which the system is to run is used to define
the information returned by the gettimeofday(2) system call.
This value is specified as the number of hours east or west of
GMT. Negative numbers indicate a value east of GMT. The timezone
specification may also indicate the type of daylight savings time
rules to be applied.
2.5. Maximum number of users
The system allocates many system data structures at boot
time based on the maximum number of users the system will sup-
port. This number is normally between 8 and 40, depending on the
hardware and expected job mix. The rules used to calculate sys-
tem data structures are discussed in Appendix D.
2.6. Root file system location
When the system boots it must know the location of the root
of the file system tree. This location and the part(s) of the
disk(s) to be used for paging and swapping must be specified in
order to create a complete configuration description. Config uses
many rules to calculate default locations for these items; these
are described in Appendix B.
When a generic system is configured, the root file system is
left undefined until the system is booted. In this case, the
root file system need not be specified, only that the system is a
generic system.
April 27, 2013
SMM:2-4 Building Kernels with Config
2.7. Hardware devices
When the system boots it goes through an autoconfiguration
phase. During this period, the system searches for all those
hardware devices which the system builder has indicated might be
present. This probing sequence requires certain pieces of infor-
mation such as register addresses, bus interconnects, etc. A
system's hardware may be configured in a very flexible manner or
be specified without any flexibility whatsoever. Most people do
not configure hardware devices into the system unless they are
currently present on the machine, expect them to be present in
the near future, or are simply guarding against a hardware
failure somewhere else at the site (it is often wise to configure
in extra disks in case an emergency requires moving one off a
machine which has hardware problems).
The specification of hardware devices usually occupies the
majority of the configuration file. As such, a large portion of
this document will be spent understanding it. Section 6.3 con-
tains a description of the autoconfiguration process, as it
applies to those planning to write, or modify existing, device
drivers.
2.8. Pseudo devices
Several system facilities are configured in a manner like
that used for hardware devices although they are not associated
with specific hardware. These system options are configured as
pseudo-devices. Some pseudo devices allow an optional parameter
that sets the limit on the number of instances of the device that
are active simultaneously.
2.9. System options
Other than the mandatory pieces of information described
above, it is also possible to include various optional system
facilities or to modify system behavior and/or limits. For exam-
ple, 4.3BSD can be configured to support binary compatibility for
programs built under 4.1BSD. Also, optional support is provided
for disk quotas and tracing the performance of the virtual memory
subsystem. Any optional facilities to be configured into the
system are specified in the configuration file. The resultant
files generated by config will automatically include the neces-
April 27, 2013
Building Kernels with Config SMM:2-5
sary pieces of the system.
3. SYSTEM BUILDING PROCESS
In this section we consider the steps necessary to build a
bootable system image. We assume the system source is located in
the ``/sys'' directory and that, initially, the system is being
configured from source code.
Under normal circumstances there are 5 steps in building a
system.
1) Create a configuration file for the system.
2) Make a directory for the system to be constructed in.
3) Run config on the configuration file to generate the files
required to compile and load the system image.
4) Construct the source code interdependency rules for the con-
figured system with makedepend using make(1).
5) Compile and load the system with make.
Steps 1 and 2 are usually done only once. When a system
configuration changes it usually suffices to just run config on
the modified configuration file, rebuild the source code depen-
dencies, and remake the system. Sometimes, however, configura-
tion dependencies may not be noticed in which case it is neces-
sary to clean out the relocatable object files saved in the
system's directory; this will be discussed later.
3.1. Creating a configuration file
Configuration files normally reside in the directory
``/sys/conf''. A configuration file is most easily constructed by
copying an existing configuration file and modifying it. The
4.3BSD distribution contains a number of configuration files for
machines at Berkeley; one may be suitable or, in worst case, a
copy of the generic configuration file may be edited.
The configuration file must have the same name as the direc-
tory in which the configured system is to be built. Further, con-
fig assumes this directory is located in the parent directory of
the directory in which it is run. For example, the generic sys-
tem has a configuration file ``/sys/conf/GENERIC'' and an accom-
panying directory named ``/sys/GENERIC''. Although it is not
required that the system sources and configuration files reside
in ``/sys,'' the configuration and compilation procedure depends
on the relative locations of directories within that hierarchy,
as most of the system code and the files created by config use
pathnames of the form ``../''. If the system files are not
located in ``/sys,'' it is desirable to make a symbolic link
there for use in installation of other parts of the system that
April 27, 2013
SMM:2-6 Building Kernels with Config
share files with the kernel.
When building the configuration file, be sure to include the
items described in section 2. In particular, the machine type,
cpu type, timezone, system identifier, maximum users, and root
device must be specified. The specification of the hardware
present may take a bit of work; particularly if your hardware is
configured at non-standard places (e.g. device registers located
at funny places or devices not supported by the system). Section
4 of this document gives a detailed description of the configura-
tion file syntax, section 5 explains some sample configuration
files, and section 6 discusses how to add new devices to the sys-
tem. If the devices to be configured are not already described
in one of the existing configuration files you should check the
manual pages in section 4 of the UNIX Programmers Manual. For
each supported device, the manual page synopsis entry gives a
sample configuration line.
Once the configuration file is complete, run it through con-
fig and look for any errors. Never try and use a system which
config has complained about; the results are unpredictable. For
the most part, config's error diagnostics are self explanatory.
It may be the case that the line numbers given with the error
messages are off by one.
A successful run of config on your configuration file will
generate a number of files in the configuration directory. These
files are:
+ A file to be used by make(1) in compiling and loading the sys-
tem, Makefile.
+ One file for each possible system image for this machine,
swapxxx.c, where xxx is the name of the system image, which
describes where swapping, the root file system, and other mis-
cellaneous system devices are located.
+ A collection of header files, one per possible device the sys-
tem supports, which define the hardware configured.
+ A file containing the I/O configuration tables used by the
system during its autoconfiguration phase, ioconf.c.
+ An assembly language file of interrupt vectors which connect
interrupts from the machine's external buses to the main sys-
tem path for handling interrupts, and a file that contains
counters and names for the interrupt vectors.
Unless you have reason to doubt config, or are curious how
the system's autoconfiguration scheme works, you should never
have to look at any of these files.
April 27, 2013
Building Kernels with Config SMM:2-7
3.2. Constructing source code dependencies
When config is done generating the files needed to compile
and link your system it will terminate with a message of the form
``Don't forget to run make depend''. This is a reminder that you
should change over to the configuration directory for the system
just configured and type ``make depend'' to build the rules used
by make to recognize interdependencies in the system source code.
This will insure that any changes to a piece of the system source
code will result in the proper modules being recompiled the next
time make is run.
This step is particularly important if your site makes
changes to the system include files. The rules generated specify
which source code files are dependent on which include files.
Without these rules, make will not recognize when it must rebuild
modules due to the modification of a system header file. The
dependency rules are generated by a pass of the C preprocessor
and reflect the global system options. This step must be repeated
when the configuration file is changed and config is used to
regenerate the system makefile.
3.3. Building the system
The makefile constructed by config should allow a new system
to be rebuilt by simply typing ``make image-name''. For example,
if you have named your bootable system image ``vmunix'', then
``make vmunix'' will generate a bootable image named ``vmunix''.
Alternate system image names are used when the root file system
location and/or swapping configuration is done in more than one
way. The makefile which config creates has entry points for each
system image defined in the configuration file. Thus, if you have
configured ``vmunix'' to be a system with the root file system on
an ``hp'' device and ``hkvmunix'' to be a system with the root
file system on an ``hk'' device, then ``make vmunix hkvmunix''
will generate binary images for each. As the system will gen-
erally use the disk from which it is loaded as the root filesys-
tem, separate system images are only required to support dif-
ferent swap configurations.
Note that the name of a bootable image is different from the
system identifier. All bootable images are configured for the
same system; only the information about the root file system and
paging devices differ. (This is described in more detail in sec-
tion 4.)
The last step in the system building process is to rearrange
certain commonly used symbols in the symbol table of the system
image; the makefile generated by config does this automatically
for you. This is advantageous for programs such as netstat(1) and
vmstat(1), which run much faster when the symbols they need are
located at the front of the symbol table. Remember also that many
programs expect the currently executing system to be named
``/vmunix''. If you install a new system and name it something
April 27, 2013
SMM:2-8 Building Kernels with Config
other than ``/vmunix'', many programs are likely to give strange
results.
3.4. Sharing object modules
If you have many systems which are all built on a single
machine there are at least two approaches to saving time in
building system images. The best way is to have a single system
image which is run on all machines. This is attractive since it
minimizes disk space used and time required to rebuild systems
after making changes. However, it is often the case that one or
more systems will require a separately configured system image.
This may be due to limited memory (building a system with many
unused device drivers can be expensive), or to configuration
requirements (one machine may be a development machine where disk
quotas are not needed, while another is a production machine
where they are), etc. In these cases it is possible for common
systems to share relocatable object modules which are not confi-
guration dependent; most of the modules in the directory
``/sys/sys'' are of this sort.
To share object modules, a generic system should be built.
Then, for each system configure the system as before, but before
recompiling and linking the system, type ``make links'' in the
system compilation directory. This will cause the system to be
searched for source modules which are safe to share between sys-
tems and generate symbolic links in the current directory to the
appropriate object modules in the directory ``../GENERIC''. A
shell script, ``makelinks'' is generated with this request and
may be checked for correctness. The file ``/sys/conf/defines''
contains a list of symbols which we believe are safe to ignore
when checking the source code for modules which may be shared.
Note that this list includes the definitions used to condition-
ally compile in the virtual memory tracing facilities, and the
trace point support used only rarely (even at Berkeley). It may
be necessary to modify this file to reflect local needs. Note
further that interdependencies which are not directly visible in
the source code are not caught. This means that if you place
per-system dependencies in an include file, they will not be
recognized and the shared code may be selected in an unexpected
fashion.
3.5. Building profiled systems
It is simple to configure a system which will automatically
collect profiling information as it operates. The profiling data
may be collected with kgmon(8) and processed with gprof(1) to
obtain information regarding the system's operation. Profiled
systems maintain histograms of the program counter as well as the
number of invocations of each routine. The gprof command will
also generate a dynamic call graph of the executing system and
propagate time spent in each routine along the arcs of the call
graph (consult the gprof documentation for elaboration). The pro-
gram counter sampling can be driven by the system clock, or if
April 27, 2013
Building Kernels with Config SMM:2-9
you have an alternate real time clock, this can be used. The
latter is highly recommended, as use of the system clock will
result in statistical anomalies, and time spent in the clock rou-
tine will not be accurately attributed.
To configure a profiled system, the -p option should be sup-
plied to config. A profiled system is about 5-10% larger in its
text space due to the calls to count the subroutine invocations.
When the system executes, the profiling data is stored in a
buffer which is 1.2 times the size of the text space. The over-
head for running a profiled system varies; under normal load we
see anywhere from 5-25% of the system time spent in the profiling
code.
Note that systems configured for profiling should not be
shared as described above unless all the other shared systems are
also to be profiled.
4. CONFIGURATION FILE SYNTAX
In this section we consider the specific rules used in writ-
ing a configuration file. A complete grammar for the input
language can be found in Appendix A and may be of use if you
should have problems with syntax errors.
A configuration file is broken up into three logical pieces:
+ configuration parameters global to all system images specified
in the configuration file,
+ parameters specific to each system image to be generated, and
+ device specifications.
4.1. Global configuration parameters
The global configuration parameters are the type of machine,
cpu types, options, timezone, system identifier, and maximum
users. Each is specified with a separate line in the configura-
tion file.
machine type
The system is to run on the machine type specified. No more
than one machine type can appear in the configuration file.
Legal values are vax and sun.
cpu ``type''
This system is to run on the cpu type specified. More than
one cpu type specification can appear in a configuration
file. Legal types for a vax machine are VAX8600, VAX780,
VAX750, VAX730 and VAX630 (MicroVAX II). The 8650 is listed
as an 8600, the 785 as a 780, and a 725 as a 730.
options optionlist
April 27, 2013
SMM:2-10 Building Kernels with Config
Compile the listed optional code into the system. Options in
this list are separated by commas. Possible options are
listed at the top of the generic makefile. A line of the
form ``options FUNNY,HAHA'' generates global ``#define''s
-DFUNNY -DHAHA in the resultant makefile. An option may be
given a value by following its name with ``='', then the
value enclosed in (double) quotes. The following are major
options are currently in use: COMPAT (include code for com-
patibility with 4.1BSD binaries), INET (Internet communica-
tion protocols), NS (Xerox NS communication protocols), and
QUOTA (enable disk quotas). Other kernel options controlling
system sizes and limits are listed in Appendix D; options
for the network are found in Appendix E. There are addi-
tional options which are associated with certain peripheral
devices; those are listed in the Synopsis section of the
manual page for the device.
makeoptions optionlist
Options that are used within the system makefile and
evaluated by make are listed as makeoptions. Options are
listed with their values with the form ``makeoptions
name=value,name2=value2.'' The values must be enclosed in
double quotes if they include numerals or begin with a dash.
timezone number [ dst [ number ] ]
Specifies the timezone used by the system. This is measured
in the number of hours your timezone is west of GMT. EST is
5 hours west of GMT, PST is 8. Negative numbers indicate
hours east of GMT. If you specify dst, the system will
operate under daylight savings time. An optional integer or
floating point number may be included to specify a particu-
lar daylight saving time correction algorithm; the default
value is 1, indicating the United States. Other values are:
2 (Australian style), 3 (Western European), 4 (Middle Euro-
pean), and 5 (Eastern European). See gettimeofday(2) and
ctime(3) for more information.
ident name
This system is to be known as name. This is usually a cute
name like ERNIE (short for Ernie Co-Vax) or VAXWELL (for
Vaxwell Smart). This value is defined for use in conditional
compilation, and is also used to locate an optional list of
source files specific to this system.
maxusers number
The maximum expected number of simultaneously active user on
this system is number. This number is used to size several
system data structures.
4.2. System image parameters
Multiple bootable images may be specified in a single confi-
guration file. The systems will have the same global configura-
tion parameters and devices, but the location of the root file
April 27, 2013
Building Kernels with Config SMM:2-11
system and other system specific devices may be different. A
system image is specified with a ``config'' line:
config sysname config-clauses
The sysname field is the name given to the loaded system image;
almost everyone names their standard system image ``vmunix''.
The configuration clauses are one or more specifications indicat-
ing where the root file system is located and the number and
location of paging devices. The device used by the system to pro-
cess argument lists during execve(2) calls may also be specified,
though in practice this is almost always selected by config using
one of its rules for selecting default locations for system dev-
ices.
A configuration clause is one of the following
root [ on ] root-device
swap [ on ] swap-device [ and swap-device ] ...
dumps [ on ] dump-device
args [ on ] arg-device
(the ``on'' is optional.) Multiple configuration clauses are
separated by white space; config allows specifications to be con-
tinued across multiple lines by beginning the continuation line
with a tab character. The ``root'' clause specifies where the
root file system is located, the ``swap'' clause indicates swap-
ping and paging area(s), the ``dumps'' clause can be used to
force system dumps to be taken on a particular device, and the
``args'' clause can be used to specify that argument list pro-
cessing for execve should be done on a particular device.
The device names supplied in the clauses may be fully speci-
fied as a device, unit, and file system partition; or underspeci-
fied in which case config will use builtin rules to select
default unit numbers and file system partitions. The defaulting
rules are a bit complicated as they are dependent on the overall
system configuration. For example, the swap area need not be
specified at all if the root device is specified; in this case
the swap area is placed in the ``b'' partition of the same disk
where the root file system is located. Appendix B contains a
complete list of the defaulting rules used in selecting system
configuration devices.
The device names are translated to the appropriate major and
minor device numbers on a per-machine basis. A file,
``/sys/conf/devices.machine'' (where ``machine'' is the machine
type specified in the configuration file), is used to map a dev-
ice name to its major block device number. The minor device
number is calculated using the standard disk partitioning rules:
on unit 0, partition ``a'' is minor device 0, partition ``b'' is
minor device 1, and so on; for units other than 0, add 8 times
the unit number to get the minor device.
April 27, 2013
SMM:2-12 Building Kernels with Config
If the default mapping of device name to major/minor device
number is incorrect for your configuration, it can be replaced by
an explicit specification of the major/minor device. This is done
by substituting
major x minor y
where the device name would normally be found. For example,
config vmunix root on major 99 minor 1
Normally, the areas configured for swap space are sized by
the system at boot time. If a non-standard size is to be used
for one or more swap areas (less than the full partition), this
can also be specified. To do this, the device name specified for
a swap area should have a ``size'' specification appended. For
example,
config vmunix root on hp0 swap on hp0b size 1200
would force swapping to be done in partition ``b'' of ``hp0'' and
the swap partition size would be set to 1200 sectors. A swap
area sized larger than the associated disk partition is trimmed
to the partition size.
To create a generic configuration, only the clause ``swap
generic'' should be specified; any extra clauses will cause an
error.
4.3. Device specifications
Each device attached to a machine must be specified to con-
fig so that the system generated will know to probe for it during
the autoconfiguration process carried out at boot time. Hardware
specified in the configuration need not actually be present on
the machine where the generated system is to be run. Only the
hardware actually found at boot time will be used by the system.
The specification of hardware devices in the configuration
file parallels the interconnection hierarchy of the machine to be
configured. On the VAX, this means that a configuration file
must indicate what MASSBUS and UNIBUS adapters are present, and
to which nexi they might be connected.* Similarly, devices and
controllers must be indicated as possibly being connected to one
or more adapters. A device description may provide a complete
definition of the possible configuration parameters or it may
leave certain parameters undefined and make the system probe for
all the possible values. The latter allows a single device con-
figuration list to match many possible physical configurations.
_________________________
* While VAX-11/750's and VAX-11/730 do not actually
have nexi, the system treats them as having simulated
nexi to simplify device configuration.
April 27, 2013
Building Kernels with Config SMM:2-13
For example, a disk may be indicated as present at UNIBUS adapter
0, or at any UNIBUS adapter which the system locates at boot
time. The latter scheme, termed wildcarding, allows more flexi-
bility in the physical configuration of a system; if a disk must
be moved around for some reason, the system will still locate it
at the alternate location.
A device specification takes one of the following forms:
master device-name device-info
controller device-name device-info [ interrupt-spec ]
device device-name device-info interrupt-spec
disk device-name device-info
tape device-name device-info
A ``master'' is a MASSBUS tape controller; a ``controller'' is a
disk controller, a UNIBUS tape controller, a MASSBUS adapter, or
a UNIBUS adapter. A ``device'' is an autonomous device which
connects directly to a UNIBUS adapter (as opposed to something
like a disk which connects through a disk controller). ``Disk''
and ``tape'' identify disk drives and tape drives connected to a
``controller'' or ``master.''
The device-name is one of the standard device names, as
indicated in section 4 of the UNIX Programmers Manual, con-
catenated with the logical unit number to be assigned the device
(the logical unit number may be different than the physical unit
number indicated on the front of something like a disk; the logi-
cal unit number is used to refer to the UNIX device, not the phy-
sical unit number). For example, ``hp0'' is logical unit 0 of a
MASSBUS storage device, even though it might be physical unit 3
on MASSBUS adapter 1.
The device-info clause specifies how the hardware is con-
nected in the interconnection hierarchy. On the VAX, UNIBUS and
MASSBUS adapters are connected to the internal system bus through
a nexus. Thus, one of the following specifications would be used:
controller mba0 at nexus x
controller uba0 at nexus x
To tie a controller to a specific nexus, ``x'' would be supplied
as the number of that nexus; otherwise ``x'' may be specified as
``?'', in which case the system will probe all nexi present look-
ing for the specified controller.
The remaining interconnections on the VAX are:
+ a controller may be connected to another controller (e.g. a
disk controller attached to a UNIBUS adapter),
+ a master is always attached to a controller (a MASSBUS
adapter),
April 27, 2013
SMM:2-14 Building Kernels with Config
+ a tape is always attached to a master (for MASSBUS tape
drives),
+ a disk is always attached to a controller, and
+ devices are always attached to controllers (e.g. UNIBUS con-
trollers attached to UNIBUS adapters).
The following lines give an example of each of these interconnec-
tions:
controller hk0 at uba0 ...
master ht0 at mba0 ...
disk hp0 at mba0 ...
tape tu0 at ht0 ...
disk rk1 at hk0 ...
device dz0 at uba0 ...
Any piece of hardware which may be connected to a specific con-
troller may also be wildcarded across multiple controllers.
The final piece of information needed by the system to con-
figure devices is some indication of where or how a device will
interrupt. For tapes and disks, simply specifying the slave or
drive number is sufficient to locate the control status register
for the device. Drive numbers may be wildcarded on MASSBUS dev-
ices, but not on disks on a UNIBUS controller. For controllers,
the control status register must be given explicitly, as well the
number of interrupt vectors used and the names of the routines to
which they should be bound. Thus the example lines given above
might be completed as:
controller hk0 at uba0 csr 0177440vector rkintr
master ht0 at mba0 drive 0
disk hp0 at mba0 drive ?
tape tu0 at ht0 slave 0
disk rk1 at hk0 drive 1
device dz0 at uba0 csr 0160100vector dzrint dzxint
Certain device drivers require extra information passed to
them at boot time to tailor their operation to the actual
hardware present. The line printer driver, for example, needs to
know how many columns are present on each non-standard line
printer (i.e. a line printer with other than 80 columns). The
drivers for the terminal multiplexors need to know which lines
are attached to modem lines so that no one will be allowed to use
them unless a connection is present. For this reason, one last
parameter may be specified to a device, a flags field. It has
the syntax
flags number
and is usually placed after the csr specification. The number is
passed directly to the associated driver. The manual pages in
April 27, 2013
Building Kernels with Config SMM:2-15
section 4 should be consulted to determine how each driver uses
this value (if at all). Communications interface drivers commonly
use the flags to indicate whether modem control signals are in
use.
The exact syntax for each specific device is given in the
Synopsis section of its manual page in section 4 of the manual.
4.4. Pseudo-devices
A number of drivers and software subsystems are treated like
device drivers without any associated hardware. To include any of
these pieces, a ``pseudo-device'' specification must be used. A
specification for a pseudo device takes the form
pseudo-device device-name [ howmany ]
Examples of pseudo devices are pty, the pseudo terminal
driver (where the optional howmany value indicates the number of
pseudo terminals to configure, 32 default), and loop, the
software loopback network pseudo-interface. Other pseudo devices
for the network include imp (required when a CSS or ACC imp is
configured) and ether (used by the Address Resolution Protocol on
10 Mb/sec Ethernets). More information on configuring each of
these can also be found in section 4 of the manual.
5. SAMPLE CONFIGURATION FILES
In this section we will consider how to configure a sample
VAX-11/780 system on which the hardware can be reconfigured to
guard against various hardware mishaps. We then study the rules
needed to configure a VAX-11/750 to run in a networking environ-
ment.
5.1. VAX-11/780 System
Our VAX-11/780 is configured with hardware recommended in
the document ``Hints on Configuring a VAX for 4.2BSD'' (this is
one of the high-end configurations). Table 1 lists the pertinent
hardware to be configured.
April 27, 2013
SMM:2-16 Building Kernels with Config
__________________________________________________________________
|Item | Vendor | Connection| Name | Reference|
|____________________|_________|____________|________|___________|
|cpu | DEC | | VAX780| |
|MASSBUS controller | Emulex | nexus ? | mba0 | hp(4) |
|disk | Fujitsu| mba0 | hp0 | |
|disk | Fujitsu| mba0 | hp1 | |
|MASSBUS controller | Emulex | nexus ? | mba1 | |
|disk | Fujitsu| mba1 | hp2 | |
|disk | Fujitsu| mba1 | hp3 | |
|UNIBUS adapter | DEC | nexus ? | | |
|tape controller | Emulex | uba0 | tm0 | tm(4) |
|tape drive | Kennedy| tm0 | te0 | |
|tape drive | Kennedy| tm0 | te1 | |
|terminal multiplexor| Emulex | uba0 | dh0 | dh(4) |
|terminal multiplexor| Emulex | uba0 | dh1 | |
|terminal multiplexor| Emulex | uba0 | dh2 | |
|____________________|_________|____________|________|___________|
Table 1. VAX-11/780 Hardware support.
We will call this machine ANSEL and construct a configuration
file one step at a time.
The first step is to fill in the global configuration param-
eters. The machine is a VAX, so the machine type is ``vax''. We
will assume this system will run only on this one processor, so
the cpu type is ``VAX780''. The options are empty since this is
going to be a ``vanilla'' VAX. The system identifier, as men-
tioned before, is ``ANSEL,'' and the maximum number of users we
plan to support is about 40. Thus the beginning of the confi-
guration file looks like this:
#
# ANSEL VAX (a picture perfect machine)
#
machine vax
cpu VAX780
timezone 8 dst
ident ANSEL
maxusers 40
To this we must then add the specifications for three system
images. The first will be our standard system with the root on
``hp0'' and swapping on the same drive as the root. The second
will have the root file system in the same location, but swap
space interleaved among drives on each controller. Finally, the
third will be a generic system, to allow us to boot off any of
the four disk drives.
April 27, 2013
Building Kernels with Config SMM:2-17
config vmunix root on hp0
config hpvmunix root on hp0 swap on hp0 and hp2
config genvmunix swap generic
Finally, the hardware must be specified. Let us first just
try transcribing the information from Table 1.
controller mba0 at nexus ?
disk hp0 at mba0 disk 0
disk hp1 at mba0 disk 1
controller mba1 at nexus ?
disk hp2 at mba1 disk 2
disk hp3 at mba1 disk 3
controller uba0 at nexus ?
controller tm0 at uba0 csr 0172520vector tmintr
tape te0 at tm0 drive 0
tape te1 at tm0 drive 1
device dh0 at uba0 csr 0160020vector dhrint dhxint
device dm0 at uba0 csr 0170500vector dmintr
device dh1 at uba0 csr 0160040vector dhrint dhxint
device dh2 at uba0 csr 0160060vector dhrint dhxint
(Oh, I forgot to mention one panel of the terminal multiplexor
has modem control, thus the ``dm0'' device.)
This will suffice, but leaves us with little flexibility.
Suppose our first disk controller were to break. We would like
to recable the drives normally on the second controller so that
all our disks could still be used without reconfiguring the sys-
tem. To do this we wildcard the MASSBUS adapter connections and
also the slave numbers. Further, we wildcard the UNIBUS adapter
connections in case we decide some time in the future to purchase
another adapter to offload the single UNIBUS we currently have.
The revised device specifications would then be:
controller mba0 at nexus ?
disk hp0 at mba? disk ?
disk hp1 at mba? disk ?
controller mba1 at nexus ?
disk hp2 at mba? disk ?
disk hp3 at mba? disk ?
controller uba0 at nexus ?
controller tm0 at uba? csr 0172520vector tmintr
tape te0 at tm0 drive 0
tape te1 at tm0 drive 1
device dh0 at uba? csr 0160020vector dhrint dhxint
device dm0 at uba? csr 0170500vector dmintr
device dh1 at uba? csr 0160040vector dhrint dhxint
device dh2 at uba? csr 0160060vector dhrint dhxint
April 27, 2013
SMM:2-18 Building Kernels with Config
The completed configuration file for ANSEL is shown in Appendix
C.
5.2. VAX-11/750 with network support
Our VAX-11/750 system will be located on two 10Mb/s Ethernet
local area networks and also the DARPA Internet. The system will
have a MASSBUS drive for the root file system and two UNIBUS
drives. Paging is interleaved among all three drives. We have
sold our standard DEC terminal multiplexors since this machine
will be accessed solely through the network. This machine is not
intended to have a large user community, it does not have a great
deal of memory. First the global parameters:
#
# UCBVAX (Gateway to the world)
#
machine vax
cpu "VAX780"
cpu "VAX750"
ident UCBVAX
timezone 8 dst
maxusers 32
options INET
options NS
The multiple cpu types allow us to replace UCBVAX with a
more powerful cpu without reconfiguring the system. The value of
32 given for the maximum number of users is done to force the
system data structures to be over-allocated. That is desirable
on this machine because, while it is not expected to support many
users, it is expected to perform a great deal of work. The
``INET'' indicates that we plan to use the DARPA standard Inter-
net protocols on this machine, and ``NS'' also includes support
for Xerox NS protocols. Note that unlike 4.2BSD configuration
files, the network protocol options do not require corresponding
pseudo devices.
The system images and disks are configured next.
April 27, 2013
Building Kernels with Config SMM:2-19
config vmunix root on hp swap on hp and rk0 and rk1
config upvmunix root on up
config hkvmunix root on hk swap on rk0 and rk1
controller mba0 at nexus ?
controller uba0 at nexus ?
disk hp0 at mba? drive 0
disk hp1 at mba? drive 1
controller sc0 at uba? csr 0176700vector upintr
disk up0 at sc0 drive 0
disk up1 at sc0 drive 1
controller hk0 at uba? csr 0177440 vector rkintr
disk rk0 at hk0 drive 0
disk rk1 at hk0 drive 1
UCBVAX requires heavy interleaving of its paging area to
keep up with all the mail traffic it handles. The limiting fac-
tor on this system's performance is usually the number of disk
arms, as opposed to memory or cpu cycles. The extra UNIBUS con-
troller, ``sc0'', is in case the MASSBUS controller breaks and a
spare controller must be installed (most of our old UNIBUS con-
trollers have been replaced with the newer MASSBUS controllers,
so we have a number of these around as spares).
Finally, we add in the network devices. Pseudo terminals are
needed to allow users to log in across the network (remember the
only hardwired terminal is the console). The software loopback
device is used for on-machine communications. The connection to
the Internet is through an IMP, this requires yet another
pseudo-device (in addition to the actual hardware device used by
the IMP software). And, finally, there are the two Ethernet dev-
ices. These use a special protocol, the Address Resolution Proto-
col (ARP), to map between Internet and Ethernet addresses. Thus,
yet another pseudo-device is needed. The additional device
specifications are show below.
pseudo-device pty
pseudo-device loop
pseudo-device imp
device acc0 at uba? csr 0167600vector accrint accxint
pseudo-device ether
device ec0 at uba? csr 0164330vector ecrint eccollide ecxint
device il0 at uba? csr 0164000vector ilrint ilcint
The completed configuration file for UCBVAX is shown in Appendix
C.
5.3. Miscellaneous comments
It should be noted in these examples that neither system was
configured to use disk quotas or the 4.1BSD compatibility mode.
April 27, 2013
SMM:2-20 Building Kernels with Config
To use these optional facilities, and others, we would probably
clean out our current configuration, reconfigure the system, then
recompile and relink the system image(s). This could, of course,
be avoided by figuring out which relocatable object files are
affected by the reconfiguration, then reconfiguring and recompil-
ing only those files affected by the configuration change. This
technique should be used carefully.
6. ADDING NEW SYSTEM SOFTWARE
This section is not for the novice, it describes some of the
inner workings of the configuration process as well as the per-
tinent parts of the system autoconfiguration process. It is
intended to give those people who intend to install new device
drivers and/or other system facilities sufficient information to
do so in the manner which will allow others to easily share the
changes.
This section is broken into four parts:
+ general guidelines to be followed in modifying system code,
+ how to add non-standard system facilities to 4.3BSD,
+ how to add a device driver to 4.3BSD, and
+ how UNIBUS device drivers are autoconfigured under 4.3BSD on
the VAX.
6.1. Modifying system code
If you wish to make site-specific modifications to the sys-
tem it is best to bracket them with
#ifdef SITENAME
...
#endif
to allow your source to be easily distributed to others, and also
to simplify diff(1) listings. If you choose not to use a source
code control system (e.g. SCCS, RCS), and perhaps even if you do,
it is recommended that you save the old code with something of
the form:
#ifndef SITENAME
...
#endif
We try to isolate our site-dependent code in individual files
which may be configured with pseudo-device specifications.
Indicate machine-specific code with ``#ifdef vax'' (or other
machine, as appropriate). 4.2BSD underwent extensive work to make
it extremely portable to machines with similar architectures- you
April 27, 2013
Building Kernels with Config SMM:2-21
may someday find yourself trying to use a single copy of the
source code on multiple machines.
Use lint periodically if you make changes to the system. The
4.3BSD kernel has only two lines of lint in it. It is very sim-
ple to lint the kernel. Use the LINT configuration file,
designed to pull in as much of the kernel source code as possi-
ble, in the following manner.
$ cd /sys/conf
$ mkdir ../LINT
$ config LINT
$ cd ../LINT
$ make depend
$ make assym.s
$ make -k lint > linterrs 2>&1 &
(or for users of csh(1))
% make -k >& linterrs
This takes about an hour on a lightly loaded VAX-11/750, but is
well worth it.
6.2. Adding non-standard system facilities
This section considers the work needed to augment config's
data base files for non-standard system facilities. Config uses a
set of files that list the source modules that may be required
when building a system. The data bases are taken from the direc-
tory in which config is run, normally /sys/conf. Three such files
may be used: files, files.machine, and files.ident. The first is
common to all systems, the second contains files unique to a sin-
gle machine type, and the third is an optional list of modules
for use on a specific machine. This last file may override
specifications in the first two. The format of the files file has
grown somewhat complex over time. Entries are normally of the
form
dir/source.c type option-list modifiers
for example,
vaxuba/foo.c optional foo device-driver
The type is one of standard or Files marked as standard are
included in all system configurations. Optional file specifica-
tions include a list of one or more system options that together
require the inclusion of this module. The options in the list may
be either names of devices that may be in the configuration file,
or the names of system options that may be defined. An optional
file may be listed multiple times with different options; if all
of the options for any of the entries are satisfied, the module
is included.
If a file is specified as a device-driver, any special
April 27, 2013
SMM:2-22 Building Kernels with Config
compilation options for device drivers will be invoked. On the
VAX this results in the use of the -i option for the C optimizer.
This is required when pointer references are made to memory loca-
tions in the VAX I/O address space.
Two other optional keywords modify the usage of the file.
Config understands that certain files are used especially for
kernel profiling. These files are indicated in the files files
with a profiling-routine keyword. For example, the current pro-
filing subroutines are sequestered off in a separate file with
the following entry:
sys/subr_mcount.c optional profiling-routine
The profiling-routine keyword forces config not to compile the
source file with the -pg option.
The second keyword which can be of use is the config-
dependent keyword. This causes config to compile the indicated
module with the global configuration parameters. This allows
certain modules, such as machdep.c to size system data structures
based on the maximum number of users configured for the system.
6.3. Adding device drivers to 4.3BSD
The I/O system and config have been designed to easily allow
new device support to be added. The system source directories are
organized as follows:
/sys/h machine independent include files
/sys/sys machine-independent system source files
/sys/conf site configuration files and basic templates
/sys/net network-protocol-independent, but network-related code
/sys/netinet DARPA Internet code
/sys/netimp IMP support code
/sys/netns Xerox NS code
/sys/vax VAX-specific mainline code
/sys/vaxif VAX network interface code
/sys/vaxmba VAX MASSBUS device drivers and related code
/sys/vaxuba VAX UNIBUS device drivers and related code
Existing block and character device drivers for the VAX
reside in ``/sys/vax'', ``/sys/vaxmba'', and ``/sys/vaxuba''.
Network interface drivers reside in ``/sys/vaxif''. Any new dev-
ice drivers should be placed in the appropriate source code
directory and named so as not to conflict with existing devices.
Normally, definitions for things like device registers are placed
in a separate file in the same directory. For example, the
``dh'' device driver is named ``dh.c'' and its associated include
file is named ``dhreg.h''.
April 27, 2013
Building Kernels with Config SMM:2-23
Once the source for the device driver has been placed in a
directory, the file ``/sys/conf/files.machine'', and possibly
``/sys/conf/devices.machine'' should be modified. The files
files in the conf directory contain a line for each C source or
binary-only file in the system. Those files which are machine
independent are located in ``/sys/conf/files,'' while machine
specific files are in ``/sys/conf/files.machine.'' The
``devices.machine'' file is used to map device names to major
block device numbers. If the device driver being added provides
support for a new disk you will want to modify this file (the
format is obvious).
In addition to including the driver in the files file, it
must also be added to the device configuration tables. These are
located in ``/sys/vax/conf.c'', or similar for machines other
than the VAX. If you don't understand what to add to this file,
you should study an entry for an existing driver. Remember that
the position in the device table specifies the major device
number. The block major number is needed in the
``devices.machine'' file if the device is a disk.
With the configuration information in place, your configura-
tion file appropriately modified, and a system reconfigured and
rebooted you should incorporate the shell commands needed to
install the special files in the file system to the file
``/dev/MAKEDEV'' or ``/dev/MAKEDEV.local''. This is discussed in
the document ``Installing and Operating 4.3BSD on the VAX''.
6.4. Autoconfiguration on the VAX
4.3BSD requires all device drivers to conform to a set of
rules which allow the system to:
1) support multiple UNIBUS and MASSBUS adapters,
2) support system configuration at boot time, and
3) manage resources so as not to crash when devices request
resources which are unavailable.
In addition, devices such as the RK07 which require everyone else
to get off the UNIBUS when they are running need cooperation from
other DMA devices if they are to work. Since it is unlikely that
you will be writing a device driver for a MASSBUS device, this
section is devoted exclusively to describing the I/O system and
autoconfiguration process as it applies to UNIBUS devices.
Each UNIBUS on a VAX has a set of resources:
+ 496 map registers which are used to convert from the 18-bit
UNIBUS addresses into the much larger VAX memory address
space.
+ Some number of buffered data paths (3 on an 11/750, 15 on an
April 27, 2013
SMM:2-24 Building Kernels with Config
11/780, 0 on an 11/730) which are used by high speed devices
to transfer data using fewer bus cycles.
There is a structure of type struct uba_hd in the system per
UNIBUS adapter used to manage these resources. This structure
also contains a linked list where devices waiting for resources
to complete DMA UNIBUS activity have requests waiting.
There are three central structures in the writing of drivers
for UNIBUS controllers; devices which do not do DMA I/O can often
use only two of these structures. The structures are struct
uba_ctlr, the UNIBUS controller structure, struct uba_device the
UNIBUS device structure, and struct uba_driver, the UNIBUS driver
structure. The uba_ctlr and uba_device structures are in one-to-
one correspondence with the definitions of controllers and dev-
ices in the system configuration. Each driver has a struct
uba_driver structure specifying an internal interface to the rest
of the system.
Thus a specification
controller sc0 at uba0 csr 0176700 vector upintr
would cause a struct uba_ctlr to be declared and initialized in
the file ioconf.c for the system configured from this descrip-
tion. Similarly specifying
disk up0 at sc0 drive 0
would declare a related uba_device in the same file. The up.c
driver which implements this driver specifies in its declara-
tions:
int upprobe(), upslave(), upattach(), updgo(), upintr();
struct uba_ctlr *upminfo[NSC];
struct uba_device *updinfo[NUP];
u_short upstd[] = { 0776700, 0774400, 0776300, 0 };
struct uba_driver scdriver =
{ upprobe, upslave, upattach, updgo, upstd, "up", updinfo, "sc", upminfo };
initializing the uba_driver structure. The driver will support
some number of controllers named sc0, sc1, etc, and some number
of drives named up0, up1, etc. where the drives may be on any of
the controllers (that is there is a single linear name space for
devices, separate from the controllers.)
We now explain the fields in the various structures. It may
help to look at a copy of vaxuba/ubareg.h, vaxuba/ubavar.h and
drivers such as up.c and dz.c while reading the descriptions of
the various structure fields.
uba_driver structure
One of these structures exists per driver. It is
April 27, 2013
Building Kernels with Config SMM:2-25
initialized in the driver and contains functions used by the con-
figuration program and by the UNIBUS resource routines. The
fields of the structure are:
ud_probe
A routine which, given a caddr_t address as argument, should
attempt to determine that the device is present at that
address in virtual memory, and should cause an interrupt
from the device. When probing controllers, two additional
arguments are supplied: the controller index, and a pointer
to the uba_ctlr structure. Device probe routines receive a
pointer to the uba_device structure as second argument. Both
of these structures are described below. Neither is normally
used, but devices that must record status or device type
information from the probe routine may require them.
The autoconfiguration routine attempts to verify that the
specified address responds before calling the probe routine. How-
ever, the device may not actually exist or may be of a different
type, and therefore the probe routine should use delays (via the
DELAY(n) macro which delays for n microseconds) rather than wait-
ing for specific events to occur. The routine must not declare
its argument as a register parameter, but must declare
register int br, cvec;
as local variables. At boot time the system takes special meas-
ures that these variables are ``value-result'' parameters. The
br is the IPL of the device when it interrupts, and the cvec is
the interrupt vector address on the UNIBUS. These registers are
actually filled in in the interrupt handler when an interrupt
occurs.
As an example, here is the up.c probe routine:
upprobe(reg)
caddr_t reg;
{
register int br, cvec;
#ifdef lint
br = 0; cvec = br; br = cvec; upintr(0);
#endif
((struct updevice *)reg)->upcs1 = UP_IE|UP_RDY;
DELAY(10);
((struct updevice *)reg)->upcs1 = 0;
return (sizeof (struct updevice));
}
The definitions for lint serve to indicate to it that the br
and cvec variables are value-result. The call to the inter-
rupt routine satisfies lint that the interrupt handler is
used. The cod here enable interrupts on the device and write
the ready bit UP_RDY. The 10 microsecond delay insures that
April 27, 2013
SMM:2-26 Building Kernels with Config
the interrupt enable will not be canceled before the inter-
rupt can be posted. The return of ``sizeof (struct updev-
ice)'' here indicates that the probe routine is satisfied
that the device is present (the value returned is not
currently used, but future plans dictate that you should
return the amount of space in the device's register bank).
A probe routine may use the function ``badaddr'' to see if
certain other addresses are accessible on the UNIBUS
(without generating a machine check), or look at the con-
tents of locations where certain registers should be. If
the registers contents are not acceptable or the addresses
don't respond, the probe routine can return 0 and the device
will not be considered to be there.
One other thing to note is that the action of different
VAXen when illegal addresses are accessed on the UNIBUS may
differ. Some of the machines may generate machine checks
and some may cause UNIBUS errors. Such considerations are
handled by the configuration program and the driver writer
need not be concerned with them.
It is also possible to write a very simple probe routine for
a one-of-a-kind device if probing is difficult or impossi-
ble. Such a routine would include statements of the form:
br = 0x15;
cvec = 0200;
for instance, to declare that the device ran at UNIBUS br5
and interrupted through vector 0200 on the UNIBUS.
ud_slave
This routine is called with a uba_device structure (yet to
be described) and the address of the device controller. It
should determine whether a particular slave device of a con-
troller is present, returning 1 if it is and 0 if it is not.
As an example here is the slave routine for up.c.
upslave(ui, reg)
struct uba_device *ui;
caddr_t reg;
{
register struct updevice *upaddr = (struct updevice *)reg;
upaddr->upcs1 = 0; /* conservative */
upaddr->upcs2 = ui->ui_slave;
if (upaddr->upcs2 & UPCS2_NED) {
upaddr->upcs1 = UP_DCLR | UP_GO;
return (0);
}
return (1);
}
Here the code fetches the slave (disk unit) number from the
April 27, 2013
Building Kernels with Config SMM:2-27
ui_slave field of the uba_device structure, and sees if the
controller responds that that is a non-existent driver
(NED). If the drive is not present, a drive clear is issued
to clean the state of the controller, and 0 is returned
indicating that the slave is not there. Otherwise a 1 is
returned.
ud_attach
The attach routine is called after the autoconfigure code
and the driver concur that a peripheral exists attached to a
controller. This is the routine where internal driver state
about the peripheral can be initialized. Here is the attach
routine from the up.c driver:
upattach(ui)
register struct uba_device *ui;
{
register struct updevice *upaddr;
if (upwstart == 0) {
timeout(upwatch, (caddr_t)0, hz);
upwstart++;
}
if (ui->ui_dk >= 0)
dk_mspw[ui->ui_dk] = .0000020345;
upip[ui->ui_ctlr][ui->ui_slave] = ui;
up_softc[ui->ui_ctlr].sc_ndrive++;
ui->ui_type = upmaptype(ui);
}
The attach routine here performs a number of functions. The
first time any drive is attached to the controller it starts
the timeout routine which watches the disk drives to make
sure that interrupts aren't lost. It also initializes, for
devices which have been assigned iostat numbers (when ui-
>ui_dk >= 0), the transfer rate of the device in the array
dk_mspw, the fraction of a second it takes to transfer 16
bit word. It then initializes an inverting pointer in the
array upip which will be used later to determine, for a par-
ticular up controller and slave number, the corresponding
uba_device. It increments the count of the number of dev-
ices on this controller, so that search commands can later
be avoided if the count is exactly 1. It then attempts to
decipher the actual type of drive attached to the controller
in a controller-specific way. On the EMULEX SC-21 it may
ask for the number of tracks on the device and use this to
decide what the drive type is. The drive type is used to
setup disk partition mapping tables and other device
specific information.
ud_dgo
This is the routine which is called by the UNIBUS resource
management routines when an operation is ready to be started
(because the required resources have been allocated). The
April 27, 2013
SMM:2-28 Building Kernels with Config
routine in up.c is:
updgo(um)
struct uba_ctlr *um;
{
register struct updevice *upaddr = (struct updevice *)um->um_addr;
upaddr->upba = um->um_ubinfo;
upaddr->upcs1 = um->um_cmd|((um->um_ubinfo>>8)&0x300);
}
This routine uses the field um_ubinfo of the uba_ctlr struc-
ture which is where the UNIBUS routines store the UNIBUS map
allocation information. In particular, the low 18 bits of
this word give the UNIBUS address assigned to the transfer.
The assignment to upba in the go routine places the low 16
bits of the UNIBUS address in the disk UNIBUS address regis-
ter. The next assignment places the disk operation command
and the extended (high 2) address bits in the device
control-status register, starting the I/O operation. The
field um_cmd was initialized with the command to be stuffed
here in the driver code itself before the call to the ubago
routine which eventually resulted in the call to updgo.
ud_addr
This is a zero-terminated list of the conventional addresses
for the device control registers in UNIBUS space. This
information is used by the system to look for instances of
the device supported by the driver. When the system probes
for the device it first checks for a control-status register
located at the address indicated in the configuration file
(if supplied), then uses the list of conventional addresses
pointed to be ud_addr.
ud_dname
This is the name of a device supported by this controller;
thus the disks on a SC-21 controller are called up0, up1,
etc. That is because this field contains up.
ud_dinfo
This is an array of back pointers to the uba_device struc-
tures for each device attached to the controller. Each
driver defines a set of controllers and a set of devices.
The device address space is always one-dimensional, so that
the presence of extra controllers may be masked away (e.g.
by pattern matching) to take advantage of hardware redun-
dancy. This field is filled in by the configuration pro-
gram, and used by the driver.
ud_mname
The name of a controller, e.g. sc for the up.c driver. The
first SC-21 is called sc0, etc.
ud_minfo
April 27, 2013
Building Kernels with Config SMM:2-29
The backpointer array to the structures for the controllers.
ud_xclu
If non-zero specifies that the controller requires exclusive
use of the UNIBUS when it is running. This is non-zero
currently only for the RK611 controller for the RK07 disks
to map around a hardware problem. It could also be used if
6250bpi tape drives are to be used on the UNIBUS to insure
that they get the bandwidth that they need (basically the
whole bus).
ud_ubamem
This is an optional entry point to the driver to configure
UNIBUS memory associated with a device. If this field in the
driver structure is null, it is ignored. Otherwise, it is
called before beginning to probe for devices when configura-
tion of a UNIBUS is begun. The driver must probe for the
existence of its memory, and is then responsible for allo-
cating the map registers corresponding to the device memory
addresses so that the registers are not used for other pur-
poses. The ud_ubamem returns 0 on success and -1 on failure.
A return value of 1 indicates that the memory exists, and
that there is no further configuration required for the dev-
ice.
uba_ctlr structure
One of these structures exists per-controller. The fields
link the controller to its UNIBUS adapter and contain the state
information about the devices on the controller. The fields are:
um_driver
A pointer to the struct uba_device for this driver, which
has fields as defined above.
um_ctlr
The controller number for this controller, e.g. the 0 in
sc0.
um_alive
Set to 1 if the controller is considered alive; currently,
always set for any structure encountered during normal
operation. That is, the driver will have a handle on a
uba_ctlr structure only if the configuration routines set
this field to a 1 and entered it into the driver tables.
um_intr
The interrupt vector routines for this device. These are
generated by config and this field is initialized in the
ioconf.c file.
um_hd
A back-pointer to the UNIBUS adapter to which this con-
troller is attached.
April 27, 2013
SMM:2-30 Building Kernels with Config
um_cmdA place for the driver to store the command which is to be
given to the device before calling the routine ubago with
the devices uba_device structure. This information is then
retrieved when the device go routine is called and stuffed
in the device control status register to start the I/O
operation.
um_ubinfo
Information about the UNIBUS resources allocated to the dev-
ice. This is normally only used in device driver go routine
(as updgo above) and occasionally in exceptional condition
handling such as ECC correction.
um_tabThis buffer structure is a place where the driver hangs the
device structures which are ready to transfer. Each driver
allocates a buf structure for each device (e.g. updtab in
the up.c driver) for this purpose. You can think of this
structure as a device-control-block, and the buf structures
linked to it as the unit-control-blocks. The code for deal-
ing with this structure is stylized; see the rk.c or up.c
driver for the details. If the ubago routine is to be used,
the structure attached to this buf structure must be:
+ A chain of buf structures for each waiting device on this
controller.
+ On each waiting buf structure another buf structure which
is the one containing the parameters of the I/O opera-
tion.
uba_device structure
One of these structures exist for each device attached to a
UNIBUS controller. Devices which are not attached to controllers
or which perform no buffered data path DMA I/O may have only a
device structure. Thus dz and dh devices have only uba_device
structures. The fields are:
ui_driver
A pointer to the struct uba_driver structure for this device
type.
ui_unit
The unit number of this device, e.g. 0 in up0, or 1 in dh1.
ui_ctlr
The number of the controller on which this device is
attached, or -1 if this device is not on a controller.
ui_ubanum
The number of the UNIBUS on which this device is attached.
ui_slave
The slave number of this device on the controller which it
April 27, 2013
Building Kernels with Config SMM:2-31
is attached to, or -1 if the device is not a slave. Thus a
disk which was unit 2 on a SC-21 would have ui_slave 2; it
might or might not be up2, that depends on the system confi-
guration specification.
ui_intr
The interrupt vector entries for this device, copied into
the UNIBUS interrupt vector at boot time. The values of
these fields are filled in by config to small code segments
which it generates in the file ubglue.s.
ui_addr
The control-status register address of this device.
ui_dk
The iostat number assigned to this device. Numbers are
assigned to disks only, and are small nonnegative integers
which index the various dk_* arrays in <sys/dk.h>.
ui_flags
The optional ``flags xxx'' parameter from the configuration
specification was copied to this field, to be interpreted by
the driver. If flags was not specified, then this field will
contain a 0.
ui_alive
The device is really there. Presently set to 1 when a dev-
ice is determined to be alive, and left 1.
ui_type
The device type, to be used by the driver internally.
ui_physaddr
The physical memory address of the device control-status
register. This is typically used in the device dump rou-
tines.
ui_mi
A struct uba_ctlr pointer to the controller (if any) on
which this device resides.
ui_hd
A struct uba_hd pointer to the UNIBUS on which this device
resides.
UNIBUS resource management routines
UNIBUS drivers are supported by a collection of utility rou-
tines which manage UNIBUS resources. If a driver attempts to
bypass the UNIBUS routines, other drivers may not operate prop-
erly. The major routines are: uballoc to allocate UNIBUS
resources, ubarelse to release previously allocated resources,
and ubago to initiate DMA. When allocating UNIBUS resources you
may request that you
April 27, 2013
SMM:2-32 Building Kernels with Config
NEEDBDP
if you need a buffered data path,
HAVEBDP
if you already have a buffered data path and just want new
mapping registers (and access to the UNIBUS),
CANTWAIT
if you are calling (potentially) from interrupt level, and
NEED16if the device uses only 16 address bits, and thus requires
map registers from the first 64K of UNIBUS address space.
If the presentation here does not answer all the questions you
may have, consult the file /sys/vaxuba/uba.c
Autoconfiguration requirements
Basically all you have to do is write a ud_probe and a
ud_attach routine for the controller. It suffices to have a
ud_probe routine which just initializes br and cvec, and a
ud_attach routine which does nothing. Making the device fully
configurable requires, of course, more work, but is worth it if
you expect the device to be in common usage and want to share it
with others.
If you managed to create all the needed hooks, then make
sure you include the necessary header files; the ones included by
vaxuba/ct.c are nearly minimal. Order is important here, don't
be surprised at undefined structure complaints if you order the
includes incorrectly. Finally, if you get the device configured
in, you can try bootstrapping and see if configuration messages
print out about your device. It is a good idea to have some mes-
sages in the probe routine so that you can see that it is being
called and what is going on. If it is not called, then you prob-
ably have the control-status register address wrong in the system
configuration. The autoconfigure code notices that the device
doesn't exist in this case, and the probe will never be called.
Assuming that your probe routine works and you manage to
generate an interrupt, then you are basically back to where you
would have been under older versions of UNIX. Just be sure to use
the ui_ctlr field of the uba_device structures to address the
device; compiling in funny constants will make your driver only
work on the CPU type you have (780, 750, or 730).
Other bad things that might happen while you are setting up
the configuration stuff:
+ You get ``nexus zero vector'' errors from the system. This
will happen if you cause a device to interrupt, but take away
the interrupt enable so fast that the UNIBUS adapter cancels
the interrupt and confuses the processor. The best thing to
do it to put a modest delay in the probe code between the
April 27, 2013
Building Kernels with Config SMM:2-33
instructions which should cause and interrupt and the clearing
of the interrupt enable. (You should clear interrupt enable
before you leave the probe routine so the device doesn't
interrupt more and confuse the system while it is configuring
other devices.)
+ The device refuses to interrupt or interrupts with a ``zero
vector''. This typically indicates a problem with the hardware
or, for devices which emulate other devices, that the emula-
tion is incomplete. Devices may fail to present interrupt
vectors because they have configuration switches set wrong, or
because they are being accessed in inappropriate ways. Incom-
plete emulation can cause ``maintenance mode'' features to not
work properly, and these features are often needed to force
device interrupts.
April 27, 2013
SMM:2-34 Building Kernels with Config
APPENDIX A. CONFIGURATION FILE GRAMMAR
The following grammar is a compressed form of the actual
yacc(1) grammar used by config to parse configuration files. Ter-
minal symbols are shown all in upper case, literals are embol-
dened; optional clauses are enclosed in brackets, ``['' and
``]''; zero or more instantiations are denoted with ``*''.
Configuration ::= [ Spec ; ]*
Spec ::= Config_spec
| Device_spec
| trace
| /* lambda */
/* configuration specifications */
Config_spec ::= machine ID
| cpu ID
| options Opt_list
| ident ID
| System_spec
| timezone [ - ] NUMBER [ dst [ NUMBER ] ]
| timezone [ - ] FPNUMBER [ dst [ NUMBER ] ]
| maxusers NUMBER
/* system configuration specifications */
System_spec ::= config ID System_parameter [ System_parameter ]*
System_parameter ::= swap_spec | root_spec | dump_spec | arg_spec
swap_spec ::= swap [ on ] swap_dev [ and swap_dev ]*
swap_dev ::= dev_spec [ size NUMBER ]
root_spec ::= root [ on ] dev_spec
dump_spec ::= dumps [ on ] dev_spec
arg_spec ::= args [ on ] dev_spec
dev_spec ::= dev_name | major_minor
major_minor ::= major NUMBER minor NUMBER
dev_name ::= ID [ NUMBER [ ID ] ]
/* option specifications */
Opt_list ::= Option [ , Option ]*
Option ::= ID [ = Opt_value ]
April 27, 2013
Building Kernels with Config SMM:2-35
Opt_value ::= ID | NUMBER
Mkopt_list ::= Mkoption [ , Mkoption ]*
Mkoption ::= ID = Opt_value
/* device specifications */
Device_spec ::= device Dev_name Dev_info Int_spec
| master Dev_name Dev_info
| disk Dev_name Dev_info
| tape Dev_name Dev_info
| controller Dev_name Dev_info [ Int_spec ]
| pseudo-device Dev [ NUMBER ]
Dev_name ::= Dev NUMBER
Dev ::= uba | mba | ID
Dev_info ::= Con_info [ Info ]*
Con_info ::= at Dev NUMBER
| at nexus NUMBER
Info ::= csr NUMBER
| drive NUMBER
| slave NUMBER
| flags NUMBER
Int_spec ::= vector ID [ ID ]*
| priority NUMBER
Lexical Conventions
The terminal symbols are loosely defined as:
ID
One or more alphabetics, either upper or lower case, and
underscore, ``_''.
NUMBER
Approximately the C language specification for an integer
number. That is, a leading ``0x'' indicates a hexadecimal
value, a leading ``0'' indicates an octal value, otherwise
the number is expected to be a decimal value. Hexadecimal
numbers may use either upper or lower case alphabetics.
FPNUMBER
A floating point number without exponent. That is a number
of the form ``nnn.ddd'', where the fractional component is
optional.
In special instances a question mark, ``?'', can be substituted
April 27, 2013
SMM:2-36 Building Kernels with Config
for a ``NUMBER'' token. This is used to effect wildcarding in
device interconnection specifications.
Comments in configuration files are indicated by a ``#'' charac-
ter at the beginning of the line; the remainder of the line is
discarded.
A specification is interpreted as a continuation of the previous
line if the first character of the line is tab.
April 27, 2013
Building Kernels with Config SMM:2-37
APPENDIX B. RULES FOR DEFAULTING SYSTEM DEVICES
When config processes a ``config'' rule which does not fully
specify the location of the root file system, paging area(s),
device for system dumps, and device for argument list processing
it applies a set of rules to define those values left unspeci-
fied. The following list of rules are used in defaulting system
devices.
1) If a root device is not specified, the swap specification must
indicate a ``generic'' system is to be built.
2) If the root device does not specify a unit number, it defaults
to unit 0.
3) If the root device does not include a partition specification,
it defaults to the ``a'' partition.
4) If no swap area is specified, it defaults to the ``b'' parti-
tion of the root device.
5) If no device is specified for processing argument lists, the
first swap partition is selected.
6) If no device is chosen for system dumps, the first swap parti-
tion is selected (see below to find out where dumps are placed
within the partition).
The following table summarizes the default partitions
selected when a device specification is incomplete, e.g. ``hp0''.
Type Partition
_________________
root ``a''
swap ``b''
args ``b''
dumps ``b''
Multiple swap/paging areas
When multiple swap partitions are specified, the system
treats the first specified as a ``primary'' swap area which is
always used. The remaining partitions are then interleaved into
the paging system at the time a swapon(2) system call is made.
This is normally done at boot time with a call to swapon(8) from
the /etc/rc file.
System dumps
System dumps are automatically taken after a system crash,
April 27, 2013
SMM:2-38 Building Kernels with Config
provided the device driver for the ``dumps'' device supports
this. The dump contains the contents of memory, but not the swap
areas. Normally the dump device is a disk in which case the
information is copied to a location at the back of the partition.
The dump is placed in the back of the partition because the pri-
mary swap and dump device are commonly the same device and this
allows the system to be rebooted without immediately overwriting
the saved information. When a dump has occurred, the system
variable dumpsize is set to a non-zero value indicating the size
(in bytes) of the dump. The savecore(8) program then copies the
information from the dump partition to a file in a ``crash''
directory and also makes a copy of the system which was running
at the time of the crash (usually ``/vmunix''). The offset to
the system dump is defined in the system variable dumplo (a sec-
tor offset from the front of the dump partition). The savecore
program operates by reading the contents of dumplo, dumpdev, and
dumpmagic from /dev/kmem, then comparing the value of dumpmagic
read from /dev/kmem to that located in corresponding location in
the dump area of the dump partition. If a match is found,
savecore assumes a crash occurred and reads dumpsize from the
dump area of the dump partition. This value is then used in
copying the system dump. Refer to savecore(8) for more informa-
tion about its operation.
The value dumplo is calculated to be
dumpdev-size - memsize
where dumpdev-size is the size of the disk partition where system
dumps are to be placed, and memsize is the size of physical
memory. If the disk partition is not large enough to hold a full
dump, dumplo is set to 0 (the start of the partition).
April 27, 2013
Building Kernels with Config SMM:2-39
APPENDIX C. SAMPLE CONFIGURATION FILES
The following configuration files are developed in section
5; they are included here for completeness.
#
# ANSEL VAX (a picture perfect machine)
#
machine vax
cpu VAX780
timezone 8 dst
ident ANSEL
maxusers 40
config vmunix root on hp0
config hpvmunix root on hp0 swap on hp0 and hp2
config genvmunix swap generic
controller mba0 at nexus ?
disk hp0 at mba? disk ?
disk hp1 at mba? disk ?
controller mba1 at nexus ?
disk hp2 at mba? disk ?
disk hp3 at mba? disk ?
controller uba0 at nexus ?
controller tm0 at uba? csr 0172520vector tmintr
tape te0 at tm0 drive 0
tape te1 at tm0 drive 1
device dh0 at uba? csr 0160020vector dhrint dhxint
device dm0 at uba? csr 0170500vector dmintr
device dh1 at uba? csr 0160040vector dhrint dhxint
device dh2 at uba? csr 0160060vector dhrint dhxint
April 27, 2013
SMM:2-40 Building Kernels with Config
#
# UCBVAX - Gateway to the world
#
machine vax
cpu "VAX780"
cpu "VAX750"
ident UCBVAX
timezone 8 dst
maxusers 32
options INET
options NS
config vmunix root on hp swap on hp and rk0 and rk1
config upvmunix root on up
config hkvmunix root on hk swap on rk0 and rk1
controller mba0 at nexus ?
controller uba0 at nexus ?
disk hp0 at mba? drive 0
disk hp1 at mba? drive 1
controller sc0 at uba? csr 0176700vector upintr
disk up0 at sc0 drive 0
disk up1 at sc0 drive 1
controller hk0 at uba? csr 0177440vector rkintr
disk rk0 at hk0 drive 0
disk rk1 at hk0 drive 1
pseudo-device pty
pseudo-device loop
pseudo-device imp
device acc0 at uba? csr 0167600vector accrint accxint
pseudo-device ether
device ec0 at uba? csr 0164330vector ecrint eccollide ecxint
device il0 at uba? csr 0164000vector ilrint ilcint
April 27, 2013
Building Kernels with Config SMM:2-41
APPENDIX D. VAX KERNEL DATA STRUCTURE SIZING RULES
Certain system data structures are sized at compile time
according to the maximum number of simultaneous users expected,
while others are calculated at boot time based on the physical
resources present, e.g. memory. This appendix lists both sets of
rules and also includes some hints on changing built-in limita-
tions on certain data structures.
Compile time rules
The file /sys/conf/param.c contains the definitions of
almost all data structures sized at compile time. This file is
copied into the directory of each configured system to allow
configuration-dependent rules and values to be maintained. (Each
copy normally depends on the copy in /sys/conf, and global modif-
ications cause the file to be recopied unless the makefile is
modified.) The rules implied by its contents are summarized below
(here MAXUSERS refers to the value defined in the configuration
file in the ``maxusers'' rule). Most limits are computed at com-
pile time and stored in global variables for use by other
modules; they may generally be patched in the system binary image
before rebooting to test new values.
nproc
The maximum number of processes which may be running at any
time. It is referred to in other calculations as NPROC and
is defined to be
20 + 8 * MAXUSERS
ntext
The maximum number of active shared text segments. The con-
stant is intended to allow for network servers and common
commands that remain in the table. It is defined as
36 + MAXUSERS.
ninode
The maximum number of files in the file system which may be
active at any time. This includes files in use by users, as
well as directory files being read or written by the system
and files associated with bound sockets in the UNIX IPC
domain. It is defined as
(NPROC + 16 + MAXUSERS) + 32
nfile
The number of ``file table'' structures. One file table
structure is used for each open, unshared, file descriptor.
April 27, 2013
SMM:2-42 Building Kernels with Config
Multiple file descriptors may reference a single file table
entry when they are created through a dup call, or as the
result of a fork. This is defined to be
16 * (NPROC + 16 + MAXUSERS) / 10 + 32
ncallout
The number of ``callout'' structures. One callout structure
is used per internal system event handled with a timeout.
Timeouts are used for terminal delays, watchdog routines in
device drivers, protocol timeout processing, etc. This is
defined as
16 + NPROC
nclist
The number of ``c-list'' structures. C-list structures are
used in terminal I/O, and currently each holds 60 charac-
ters. Their number is defined as
60 + 12 * MAXUSERS
nmbclusters
The maximum number of pages which may be allocated by the
network. This is defined as 256 (a quarter megabyte of
memory) in /sys/h/mbuf.h. In practice, the network rarely
uses this much memory. It starts off by allocating 8 kilo-
bytes of memory, then requesting more as required. This
value represents an upper bound.
nquota
The number of ``quota'' structures allocated. Quota struc-
tures are present only when disc quotas are configured in
the system. One quota structure is kept per user. This is
defined to be
(MAXUSERS * 9) / 7 + 3
ndquot
The number of ``dquot'' structures allocated. Dquot struc-
tures are present only when disc quotas are configured in
the system. One dquot structure is required per user, per
active file system quota. That is, when a user manipulates a
file on a file system on which quotas are enabled, the
information regarding the user's quotas on that file system
must be in-core. This information is cached, so that not
all information must be present in-core all the time. This
is defined as
NINODE + (MAXUSERS * NMOUNT) / 4
April 27, 2013
Building Kernels with Config SMM:2-43
where NMOUNT is the maximum number of mountable file sys-
tems.
In addition to the above values, the system page tables (used to
map virtual memory in the kernel's address space) are sized at
compile time by the SYSPTSIZE definition in the file
/sys/vax/vmparam.h. This is defined to be
20 + MAXUSERS
pages of page tables. Its definition affects the size of many
data structures allocated at boot time because it constrains the
amount of virtual memory which may be addressed by the running
system. This is often the limiting factor in the size of the
buffer cache, in which case a message is printed when the system
configures at boot time.
Run-time calculations
The most important data structures sized at run-time are
those used in the buffer cache. Allocation is done by allocating
physical memory (and system virtual memory) immediately after the
system has been started up; look in the file /sys/vax/machdep.c.
The amount of physical memory which may be allocated to the
buffer cache is constrained by the size of the system page
tables, among other things. While the system may calculate a
large amount of memory to be allocated to the buffer cache, if
the system page table is too small to map this physical memory
into the virtual address space of the system, only as much as can
be mapped will be used.
The buffer cache is comprised of a number of ``buffer
headers'' and a pool of pages attached to these headers. Buffer
headers are divided into two categories: those used for swapping
and paging, and those used for normal file I/O. The system tries
to allocate 10% of the first two megabytes and 5% of the remain-
ing available physical memory for the buffer cache (where avail-
able does not count that space occupied by the system's text and
data segments). If this results in fewer than 16 pages of memory
allocated, then 16 pages are allocated. This value is kept in the
initialized variable bufpages so that it may be patched in the
binary image (to allow tuning without recompiling the system), or
the default may be overridden with a configuration-file option.
For example, the option options BUFPAGES="3200" causes 3200 pages
(3.2M bytes) to be used by the buffer cache. A sufficient number
of file I/O buffer headers are then allocated to allow each to
hold 2 pages each. Each buffer maps 8K bytes. If the number of
buffer pages is larger than can be mapped by the buffer headers,
the number of pages is reduced. The number of buffer headers
allocated is stored in the global variable nbuf, which may be
patched before the system is booted. The system option options
NBUF="1000" forces the allocation of 1000 buffer headers. Half as
many swap I/O buffer headers as file I/O buffers are allocated,
but no more than 256.
April 27, 2013
SMM:2-44 Building Kernels with Config
System size limitations
As distributed, the sum of the virtual sizes of the core-
resident processes is limited to 256M bytes. The size of the
text segment of a single process is currently limited to 6M
bytes. It may be increased to no greater than the data segment
size limit (see below) by redefining MAXTSIZ. This may be done
with a configuration file option, e.g. options
MAXTSIZ="(10*1024*1024)" to set the limit to 10 million bytes.
Other per-process limits discussed here may be changed with simi-
lar options with names given in parentheses. Soft, user-
changeable limits are set to 512K bytes for stack (DFLSSIZ) and
6M bytes for the data segment (DFLDSIZ) by default; these may be
increased up to the hard limit with the setrlimit(2) system call.
The data and stack segment size hard limits are set by a system
configuration option to one of 17M, 33M or 64M bytes. One of
these sizes is chosen based on the definition of MAXDSIZ; with no
option, the limit is 17M bytes; with an option options
MAXDSIZ="(32*1024*1024)" (or any value between 17M and 33M), the
limit is increased to 33M bytes, and values larger than 33M
result in a limit of 64M bytes. You must be careful in doing this
that you have adequate paging space. As normally configured , the
system has 16M or 32M bytes per paging area, depending on disk
size. The best way to get more space is to provide multiple,
thereby interleaved, paging areas. Increasing the virtual memory
limits results in interleaving of swap space in larger sections
(from 500K bytes to 1M or 2M bytes).
By default, the virtual memory system allocates enough
memory for system page tables mapping user page tables to allow
256 megabytes of simultaneous active virtual memory. That is, the
sum of the virtual memory sizes of all (completely- or
partially-) resident processes can not exceed this limit. If the
limit is exceeded, some process(es) must be swapped out. To
increase the amount of resident virtual space possible, you can
alter the constant USRPTSIZE (in /sys/vax/vmparam.h). Each page
of system page tables allows 8 megabytes of user virtual memory.
Because the file system block numbers are stored in page
table pg_blkno entries, the maximum size of a file system is lim-
ited to 2^24 1024 byte blocks. Thus no file system can be larger
than 8 gigabytes.
The number of mountable file systems is set at 20 by the
definition of NMOUNT in /sys/h/param.h. This should be suffi-
cient; if not, the value can be increased up to 255. If you have
many disks, it makes sense to make some of them single file sys-
tems, and the paging areas don't count in this total.
The limit to the number of files that a process may have
open simultaneously is set to 64. This limit is set by the NOFILE
definition in /sys/h/param.h. It may be increased arbitrarily,
with the caveat that the user structure expands by 5 bytes for
each file, and thus UPAGES (/sys/vax/machparam.h) must be
April 27, 2013
Building Kernels with Config SMM:2-45
increased accordingly.
The amount of physical memory is currently limited to 64 Mb
by the size of the index fields in the core-map (/sys/h/cmap.h).
The limit may be increased by following instructions in that file
to enlarge those fields.
April 27, 2013
SMM:2-46 Building Kernels with Config
APPENDIX E. NETWORK CONFIGURATION OPTIONS
The network support in the kernel is self-configuring
according to the protocol support options (INET and NS) and the
network hardware discovered during autoconfiguration. There are
several changes that may be made to customize network behavior
due to local restrictions. Within the Internet protocol routines,
the following options set in the system configuration file are
supported:
GATEWAY
The machine is to be used as a gateway. This option
currently makes only minor changes. First, the size of the
network routing hash table is increased. Secondly, machines
that have only a single hardware network interface will not
forward IP packets; without this option, they will also
refrain from sending any error indication to the source of
unforwardable packets. Gateways with only a single interface
are assumed to have missing or broken interfaces, and will
return ICMP unreachable errors to hosts sending them packets
to be forwarded.
TCP_COMPAT_42
This option forces the system to limit its initial TCP
sequence numbers to positive numbers. Without this option,
4.3BSD systems may have problems with TCP connections to
4.2BSD systems that connect but never transfer data. The
problem is a bug in the 4.2BSD TCP; this option should be
used during the period of conversion to 4.3BSD.
IPFORWARDING
Normally, 4.3BSD machines with multiple network interfaces
will forward IP packets received that should be resent to
another host. If the line ``options IPFORWARDING="0"'' is in
the system configuration file, IP packet forwarding will be
disabled.
IPSENDREDIRECTS
When forwarding IP packets, 4.3BSD IP will note when a
packet is forwarded using the same interface on which it
arrived. When this is noted, if the source machine is on the
directly-attached network, an ICMP redirect is sent to the
source host. If the packet was forwarded using a route to a
host or to a subnet, a host redirect is sent, otherwise a
network redirect is sent. The generation of redirects may be
inhibited with the configuration option ``options IPSEN-
DREDIRECTS="0".''
SUBNETSARELOCAL
TCP calculates a maximum segment size to use for each con-
nection, and sends no datagrams larger than that size. This
size will be no larger than that supported on the outgoing
interface. Furthermore, if the destination is not on the
April 27, 2013
Building Kernels with Config SMM:2-47
local network, the size will be no larger than 576 bytes.
For this test, other subnets of a directly-connected subnet-
ted network are considered to be local unless the line
``options SUBNETSARELOCAL="0"'' is used in the system confi-
guration file.
COMPAT_42
This option, intended as a catchall for 4.2BSD compatibility
options, has only a single function thus far. It disables
the checking of UDP input packet checksums. As the calcula-
tion of UDP packet checksums was incorrect in 4.2BSD, this
option allows a 4.3BSD system to receive UDP packets from a
4.2BSD system.
The following options are supported by the Xerox NS protocols:
NSIP
This option allows NS IDP datagrams to be encapsulated in
Internet IP packets for transmission to a collaborating NSIP
host. This may be used to pass IDP packets through IP-only
link layer networks. See nsip(4P) for details.
THREEWAYSHAKE
The NS Sequenced Packet Protocol does not require a three-
way handshake before considering a connection to be in the
established state. (A three-way handshake consists of a con-
nection request, an acknowledgement of the request along
with a symmetrical opening indication, and then an ack-
nowledgement of the reciprocal opening packet.) This option
forces a three-way handshake before data may be transmitted
on Sequenced Packet sockets.
April 27, 2013
Generated on 2013-04-27 00:20:00 by $MirOS: src/scripts/roff2htm,v 1.77 2013/01/01 20:49:09 tg Exp $
These manual pages and other documentation are copyrighted by their respective writers;
their source is available at our CVSweb,
AnonCVS, and other mirrors. The rest is Copyright © 2002‒2013 The MirOS Project, Germany.
This product includes material
provided by Thorsten Glaser.
This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.