Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Minor updates - I've attempted to catch the most glaringly outdated 

statements but haven't made any effort yet to rewrite the main content.
This commit is contained in:
dholland 2014-07-06 05:16:18 +00:00
parent c8a2e91d5f
commit 75eb1ae2e9
6 changed files with 89 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
share/doc/smm/config/0.t
View File

@ -1,4 +1,4 @@
.\" $NetBSD: 0.t,v 1.1 2007/12/18 03:35:51 garbled Exp $
.\" $NetBSD: 0.t,v 1.2 2014/07/06 05:16:18 dholland Exp $
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@ -50,14 +50,16 @@
\fB\\$1\fP\\$2
..
.TL
Building 4.4BSD Kernels with Config
Building NetBSD Kernels with Config
.AU
Samuel J. Leffler and Michael J. Karels
.\" (uncomment this once there are substantive changes)
.\" Updated for NetBSD by David A. Holland
.AI
Computer Systems Research Group
Department of Electrical Engineering and Computer Science
University of California, Berkeley
Berkeley, California 94720
.\" Computer Systems Research Group
.\" Department of Electrical Engineering and Computer Science
.\" University of California, Berkeley
.\" Berkeley, California 94720
.de IR
\fI\\$1\fP\\$2
..
@ -67,8 +69,8 @@ Berkeley, California 94720
.AB
.PP
This document describes the use of
\fIconfig\fP\|(8) to configure and create bootable
4.4BSD system images.
\fIconfig\fP\|(1) to configure and create bootable
NetBSD system images.
It discusses the structure of system
configuration files and how to configure
systems with non-standard hardware configurations.
@ -78,12 +80,14 @@ process operates are included. An appendix
contains a summary of the rules used by the system
in calculating the size of system data structures,
and also indicates some of the standard system size
limitations (and how to change them).
limitations and how to change them.
Other configuration options are also listed.
.sp
.LP
Revised July 5, 1993
.LP
Revised for NetBSD beginning July 5, 2014
.AE
.LP
.OH 'Building 4.4BSD Kernels with Config''SMM:2-%'
.EH 'SMM:2-%''Building 4.4BSD Kernels with Config'
.OH 'Building NetBSD Kernels with Config''Command Reference Documents'
.EH 'Command Reference Documents''Building NetBSD Kernels with Config'

10
share/doc/smm/config/1.t
View File

@ -1,4 +1,4 @@
.\" $NetBSD: 1.t,v 1.1 2007/12/18 03:35:51 garbled Exp $
.\" $NetBSD: 1.t,v 1.2 2014/07/06 05:16:18 dholland Exp $
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@ -39,10 +39,10 @@
INTRODUCTION
.PP
.I Config
is a tool used in building 4.4BSD 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
is a tool used in building BSD kernel images.
It takes a file describing the tunable parameter settings, features,
and drivers to include, and generates a collection
of files which are then used to build a copy of the kernel appropriate
to that configuration.
.I Config
simplifies system maintenance by isolating system dependencies

8
share/doc/smm/config/2.t
View File

@ -1,4 +1,4 @@
.\" $NetBSD: 2.t,v 1.1 2007/12/18 03:35:52 garbled Exp $
.\" $NetBSD: 2.t,v 1.2 2014/07/06 05:16:18 dholland Exp $
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@ -69,7 +69,7 @@ indicates if the system is going to operate on a DEC VAX-11\(dg computer,
\(dg DEC, VAX, UNIBUS, MASSBUS and MicroVAX are trademarks of Digital
Equipment Corporation.
.FE
or some other machine on which 4.4BSD operates. The machine type
or some other machine on which NetBSD operates. The machine type
is used to locate certain data files which are machine specific, and
also to select rules used in constructing the resultant
configuration files.
@ -179,8 +179,8 @@ 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 example, 4.4BSD can be configured to support binary compatibility for
programs built under 4.3BSD. Also, optional support is provided
For example, NetBSD can be configured to support binary compatibility for
programs built under Linux and FreeBSD. 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

62
share/doc/smm/config/3.t
View File

@ -1,4 +1,4 @@
.\" $NetBSD: 3.t,v 1.1 2007/12/18 03:35:52 garbled Exp $
.\" $NetBSD: 3.t,v 1.2 2014/07/06 05:16:18 dholland Exp $
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@ -38,7 +38,7 @@
SYSTEM BUILDING PROCESS
.PP
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
image. We assume the system source is located in the ``/usr/src'' directory
and that, initially, the system is being configured from source code.
.PP
Under normal circumstances there are 5 steps in building a system.
@ -54,11 +54,11 @@ to compile and load the system image.
.IP 4)
Construct the source code interdependency rules for the
configured system with
.I make depend
.I "make depend"
using
.IR make (1).
.IP 5)
Compile and load the system with
Compile and link the system with
.IR make .
.PP
Steps 1 and 2 are usually done only once. When a system configuration
@ -67,36 +67,38 @@ changes it usually suffices to just run
on the modified configuration file, rebuild the source code dependencies,
and remake the system. Sometimes,
however, configuration dependencies may not be noticed in which case
it is necessary to clean out the relocatable object files saved
it is necessary to clean out the object files saved
in the system's directory; this will be discussed later.
.NH 2
Creating a configuration file
.PP
Configuration files normally reside in the directory ``/sys/conf''.
Configuration files normally reside in the directory ``conf'' in the
architecture-specific subtree of the kernel for the machine type in
use.
(For example, configuration files for 64-bit x86 machines live in
``/usr/src/sys/arch/amd64/conf''.)
A configuration file is most easily constructed by copying an
existing configuration file and modifying it. The 4.4BSD 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.
existing configuration file and modifying it. The NetBSD distribution
contains assorted standard configuration files for different machine
types and varieties. Start with ``GENERIC'' if no other is more
appropriate.
.PP
The configuration file must have the same name as the directory in
which the configured system is to be built.
Further,
.I config
assumes this directory is located in the parent directory of
the directory in which it
is run. For example, the generic
system has a configuration file ``/sys/conf/GENERIC'' and an accompanying
directory named ``/sys/GENERIC''.
assumes this directory is located under the ``compile'' directory at
the same level as the ``conf'' directory in which it
is run. For example, the generic 64-bit x86
system has a configuration file ``/usr/src/sys/arch/amd64/conf/GENERIC''
and an accompanying
directory named ``/usr/src/sys/arch/amd64/compile/GENERIC''.
Although it is not required that the system sources and configuration
files reside in ``/sys,'' the configuration and compilation procedure
files reside in ``/usr/src,'' 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
.I 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 share files with the kernel.
.PP
When building the configuration file, be sure to include the items
described in section 2. In particular, the machine type,
@ -110,7 +112,7 @@ section 5 explains some sample configuration files, and
section 6 discusses how to add new devices to
the system. 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
the section 4 manual pages. For each
supported device, the manual page synopsis entry gives a
sample configuration line.
.PP
@ -194,18 +196,17 @@ Building the system
.PP
The makefile constructed by
.I 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 ``kernel'',
then ``make kernel''
will generate a bootable image named ``kernel''. Alternate system image names
should allow a new system to be rebuilt by simply typing ``make''.
.\" XXX is this still supported?
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
.I config
creates has entry points for each system image defined in
the configuration file.
Thus, if you have configured ``kernel'' to be a system with the root file
system on an ``hp'' device and ``hkkernel'' to be a system with the root
file system on an ``hk'' device, then ``make kernel hkkernel'' will generate
Thus, if you have configured ``netbsd'' to be a system with the root file
system on an ``hp'' device and ``hknetbsd'' to be a system with the root
file system on an ``hk'' device, then ``make netbsd hknetbsd'' will generate
binary images for each.
As the system will generally use the disk from which it is loaded
as the root filesystem, separate system images are only required
@ -226,8 +227,8 @@ This is advantageous for programs such as
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 ``/kernel''. If you install
a new system and name it something other than ``/kernel'', many programs
the currently executing system to be named ``/netbsd''. If you install
a new system and name it something other than ``/netbsd'', many programs
are likely to give strange results.
.NH 2
Sharing object modules
@ -244,8 +245,7 @@ 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
configuration dependent; most of the modules in the directory ``/sys/sys''
are of this sort.
configuration dependent.
.PP
To share object modules, a generic system should be built. Then, for
each system configure the system as before, but before recompiling and

4
share/doc/smm/config/4.t
View File

@ -1,4 +1,4 @@
.\" $NetBSD: 4.t,v 1.1 2007/12/18 03:35:52 garbled Exp $
.\" $NetBSD: 4.t,v 1.2 2014/07/06 05:16:18 dholland Exp $
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@ -151,7 +151,7 @@ with a ``config'' line:
The
.I sysname
field is the name given to the loaded system image; almost everyone
names their standard system image ``kernel''. The configuration clauses
names their standard system image ``netbsd''. The configuration clauses
are one or more specifications indicating where the root file system
is located and the number and location of paging devices.
The device used by the system to process argument lists during

70
share/doc/smm/config/6.t
View File

@ -1,4 +1,4 @@
.\" $NetBSD: 6.t,v 1.1 2007/12/18 03:35:53 garbled Exp $
.\" $NetBSD: 6.t,v 1.2 2014/07/06 05:16:18 dholland Exp $
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@ -49,9 +49,9 @@ This section is broken into four parts:
.IP \(bu 3
general guidelines to be followed in modifying system code,
.IP \(bu 3
how to add non-standard system facilities to 4.4BSD,
how to add non-standard system facilities to NetBSD, and
.IP \(bu 3
how to add a device driver to 4.4BSD, and
how to add a device driver to NetBSD.
.NH 2
Modifying system code
.PP
@ -63,9 +63,7 @@ it is best to bracket them with
#endif
.DE
to allow your source to be easily distributed to others, and
also to simplify \fIdiff\fP\|(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
also to simplify \fIdiff\fP\|(1) listings. It is
recommended that you save the old code with something
of the form:
.DS
@ -73,15 +71,11 @@ of the form:
\&...
#endif
.DE
We try to isolate our site-dependent code in individual files
which may be configured with pseudo-device specifications.
.PP
Indicate machine-specific code with ``#ifdef vax'' (or other machine,
as appropriate).
4.4BSD underwent extensive work to make it extremely portable to
machines with similar architectures\- you may someday find
yourself trying to use a single copy of the source code on
multiple machines.
Machine-specific code should be placed in existing machine-specific
files, or added as new files in machine-specific source
directories.
The use of machine-specific preprocessor conditionals is discouraged.
.NH 2
Adding non-standard system facilities
.PP
@ -91,9 +85,8 @@ data base files for non-standard system facilities.
.I 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 directory in which
.I config
is run, normally /sys/conf.
The data bases are taken from standard locations in the system source
tree, normally ``/usr/src/sys/conf''.
Three such files may be used:
.IR files ,
.IR files .machine,
@ -176,7 +169,7 @@ parameters. This allows certain modules, such as
to size system data structures based on the maximum number
of users configured for the system.
.NH 2
Adding device drivers to 4.4BSD
Adding device drivers to NetBSD
.PP
The I/O system and
.I config
@ -185,38 +178,39 @@ The system source directories are organized as follows:
.DS
.TS
lw(1.0i) l.
/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
/usr/src/sys/sys machine independent include files
/usr/src/sys/kern machine-independent system source files
/usr/src/sys/conf machine-independent configuration data
/usr/src/sys/net network-protocol-independent, but network-related code
/usr/src/sys/netinet DARPA Internet code
/usr/src/sys/dev machine-independent device drivers
/usr/src/sys/arch machine-dependent code
/usr/src/sys/arch/amd64 machine-dependent code for 64-bit x86
/usr/src/sys/arch/i386 machine-dependent code for 32-bit x86
/usr/src/sys/arch/x86 machine-dependent code shared between x86 types
/usr/src/sys/arch/amd64/conf site configuration files and basic templates
(and so on)
.TE
.DE
.PP
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 device
reside in ``/usr/src/sys/dev''. Any new device
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''.
a separate file in the same directory. For example, the ``auixp''
device driver is named ``auixp.c'' and its associated include file is
named ``auixpreg.h''. There is also an ``auixpvar.h'' which contains
data structures and other external declarations that the driver needs
to expose.
.PP
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
the file ``/usr/src/sys/conf/files'' should be modified. The
.I 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
located in ``/usr/src/sys/conf/files,'' while machine specific files for
the ``foo'' port are in ``/usr/src/sys/arch/foo/conf/files.foo.'' The ``devices.foo'' 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).