BSD 3 development

[unix-history] / usr / doc / regen

.TL
REGENERATING SYSTEM SOFTWARE
.AU
For UNIX/32V

Thomas B. London
.AU
John F. Reiser
.HO
.SH
Introduction
.PP
This document discusses how to
assemble or compile various parts of the
.UX \s-2/32V\s0
system software.
This may be necessary because
a command or library is accidentally
deleted or otherwise
destroyed;
also, it may be desirable to install a modified
version of some command or library routine.
A few commands depend
to some degree on the current configuration
of the system;
thus in any new system modifications to some commands
are advisable.
Most of the likely modifications
relate to the standard disk devices contained
in the system.
For example, the df(1) (`disk free')
command has built into it the names of
the standardly present disk storage drives
(e.g. `/dev/rf0', `/dev/rp0').
Df(1) takes an argument to indicate which
disk to examine, but it is convenient
if its default argument is adjusted to
reflect the ordinarily present devices.
The companion document `Setting up UNIX'
discusses which commands are likely to require
changes.
.SH
Where Commands and Subroutines Live
.PP
The
source files for commands and subroutines reside
in several subdirectories
of the directory /usr/src.
These subdirectories, and a general
description of their contents, are
.IP cmd 12
Source files for commands.
.IP libc/stdio 12
Source files making up the `standard i/o package'.
.IP libc/sys 12
Source files for the C system call interfaces.
.IP libc/gen 12
Source files for most of the remaining routines described
in section 3 of the manual.
.IP libc/crt 12
Source files making up the C runtime support package, as
in call save-return and long arithmetic.
.IP libc/csu 12
Source for the C startup routines.
.IP games 12
Source for (some of) the games.
No great care has been taken to try to make it obvious how
to compile these; treat it as a game.
.IP libF77 12
Source for the Fortran 77 runtime library, exclusive of IO.
.IP libI77 12
Source for the Fortran 77 IO runtime routines.
.IP libdbm 12
Source for the `data-base manager' package
.I dbm
(3).
.IP libm 12
Source for the mathematical library.
.IP libnm 12
Source for the assembler language mathematical library.
.IP libplot 12
Source for plotting routines.
.SH
Commands
.PP
The regeneration of most commands
is straightforward.
The `cmd' directory will contain either a source file
for the command or a subdirectory containing the set
of files that make up the command.
If it is a single file the command
.DS
cd /usr/src/cmd/Admin
Mk cmd_name.c
.DE
suffices. (Cmd_name is the name of the command you
are playing with.)
The result of the Mk command will be an executable version,
copied to /bin
(or perhaps /etc or other places if appropriate).
If you want the result placed somewhere else, the command
.DS
cd /usr/src/cmd/Admin
DESTDIR=mydir Mk cmd_name.c
.DE
where mydir is a full pathname of some destination directory
(e.g. /usr/tbl/newcmds),
will compile the command and place the result in mydir/bin
(or perhaps mydir/etc or mydir/usr/bin, etc.).
.PP
If the source files are in a subdirectory there will be a `makefile'
(see make(1)) to control the regeneration.
After changing to the proper directory (cd(1)) you type one of the following:
.IP "make" 15
The program is compiled and loaded; the executable is
left in the current directory.
.IP "make install" 15
The program is compiled and loaded, and the executable is
installed.
.IP "make clean" 15
Everything is cleanup; for example .o files are deleted.
.PP
Some of the makefiles have other options. Print (cat(1)) the ones you
are interested in to find out.
.PP
Alternately, to compiler and install a subdirectory command, one may
perform the following
.DS
cd /usr/src/cmd/Admin
Mk cmd_name
.DE
which combines all three of the above make options.
.SH
The Assembler
.PP
The assembler consists of one executable file:
/bin/as.
The source files for /bin/as
are named `/usr/src/cmd/as/as?.c'.
Considerable care should be exercised
in replacing the
assembler.
Remember that if the assembler is lost,
the only recourse is to replace it from some backup storage;
a broken assembler cannot assemble itself.
.SH
The C Compiler
.PP
The C compiler consists of
six routines:
`/bin/cc',
which calls the phases of the compiler proper,
the compiler control line expander `/lib/cpp',
the assembler (`as'), and the loader (`ld').
The C compiler proper is `/lib/ccom';
`/lib/c2' is the optional
assembler-language optimizer.
The loss of the C compiler is as serious
as that of the assembler.
.PP
The source for /bin/cc
resides in `/usr/src/cmd/cc.c'.
Its loss alone (or that of c2) is not fatal.
If needed,
prog.c can be compiled by
.DS
/lib/cpp prog.c >temp0
/lib/ccom temp0 temp1
as temp3
ld /lib/crt0.o a.out \-lc
.DE
.PP
The source for the compiler proper is in the
directories /usr/src/cmd/mip and /usr/src/cmd/pcc.
The /usr/src/cmd/mip directory contains files which are 
(relatively) machine independent;
the machine dependent files reside in the
directory /usr/src/cmd/pcc.
The compiler is `made' by the makefile (see make(1))
in the directory /usr/src/cmd/pcc.
To make a new /lib/ccom use
.DS
cd /usr/src/cmd/pcc
make
.DE
which produces the compiler
(named /usr/src/cmd/pcc/comp).
Before installing the new compiler,
it is prudent to save the old one someplace.
.PP
In a similar manner,
the optimizer phase of the C compiler
(/lib/c2)
is made up from the files
c20.c, c21.c, and c22.c together with c2.h.
Its loss is not critical since it is completely optional.
.SH
UNIX
.PP
The source and object programs for UNIX are kept in
two subdirectories of
.I /usr/src/sys.
In the subdirectory 
.I h
there are several files ending in `.h';
these are header files which are
picked up (via `#include ...')
as required by each system module.
The subdirectory
.I sys
is the rest of the system.
.PP
The file
.I conf.c
contains the tables which control
device configuration of the system.
.I Locore.s
specifies the
contents of the interrupt vectors,
and all the
machine-language code in the system.
.PP
To recreate the system, use
.DS
cd /usr/src/sys/sys
make unix
.DE
See `Setting Up UNIX' for other information about configuration
and such.
.PP
When the make is
done, the new system is present in the
current directory as `unix'.
It should be tested before destroying the currently
running `/unix', this is best done by doing something like
.DS
mv /unix /ounix
mv unix /unix
.DE
If the new system doesn't work, you can still boot `ounix'
and come up (see boot(8)).
When you have satisfied yourself that the new system works,
remove /ounix.
.PP
To install a new device driver,
copy its source to /usr/src/sys/sys,
and edit the `makefile' and the file `loadall' if
necessary (see make(1)).
.PP
Next, the I/O interrupt fielding mechanism must be modified
to properly handle the new device.
If the device is connected via the UNIBUS, then one only
need add the device's interrupt handling routine address(s)
in the proper position in the table `UNIvec' in the
file /usr/src/sys/sys/univec.c.
`UNIvec'
should be modified
by placing a pointer to a callout routine
in the proper vector.
Use some other device (like the DZ11) as a guide.
Notice that the entries in `UNIvec' must be in order.
Bits 27-31 of the vector address
will be available as the first argument of the interrupt routine.
This stratagem is used when
several similar devices share the same interrupt routine
(as in dz11's).
.PP
If the device is connected via the MASSBUS,
then /usr/src/sys/sys/univec.c is not to be modifed.
Instead, code must be added to /usr/src/sys/sys/locore.s
to actually transfer to the interrupt routine.
Use the RP06 interrupt routine `Xmba0int' in locore.s as a guide.
As an aside, note that
external names in C programs have an
underscore (`_') prepended to them.
.PP
The second step which must be performed to add a new
device is
to add it to the configuration table
/usr/src/sys/sys/conf.c.
This file contains two subtables, `bdevsw' and `cdevsw',
one for block-type devices, and one for character-type devices.
Block devices include disks,  and magtape.
All other devices are character devices.
A line in each of these tables gives all the information
the system needs to know about the device handler;
the ordinal position of the line in the table implies
its major device number, starting at 0.
.PP
There are four subentries per line in the block device table,
which give its open routine, close routine, strategy routine, and
device table.
The open and close routines may be nonexistent,
in which case the name `nulldev' is given;
this routine merely returns.
The strategy routine is called to do any I/O,
and the device table contains status information for the device.
.PP
For character devices, each line in the table
specifies a routine for open,
close, read, and write, and one which sets and returns
device-specific status (used, for example, for stty and gtty
on typewriters).
If there is no open or close routine, `nulldev' may
be given; if there is no read, write, or status
routine, `nodev' may be given.
Nodev sets an error flag and returns.
.PP
The final step which must
be taken to install a device is to make a special file for it.
This is done by mknod(1), to which you must specify the
device class (block or character),
major device number (relative line in the configuration table)
and minor device number
(which is made available to the driver at appropriate times).
.PP
The documents
`Setting up Unix' and
`The Unix IO system'
may aid in comprehending these steps.
.SH
The Library libc.a
.PP
The library /lib/libc.a is where most of the subroutines
described in sections 2 and 3 of the manual are kept.
This library
can be remade using the following commands:
.DS
cd /usr/src/libc
make libc.a
make install
make clean
.DE
If single routines need to be recompiled and replaced, use
.DS
cc \-c \-O x.c
ar vr /lib/libc.a x.o
rm x.o
.DE
The above can also be used to put new items into the library.
See ar(1), lorder(1), and tsort(1).
.PP
The routines in /usr/src/cmd/libc/csu (C start up) are not in
libc.a. These are separately assembled and put into
/lib. The commands to do this are
.DS
cd /usr/src/libc
for i in csu/*.s
do
	j=`basename $i .s`
	as -o $j.o $i
	mv $j.o /lib
done
.DE
or, if you need only redo one routine,
.DS
cd /usr/src/libc/csu
as -o x.o x.s
mv x.o /lib
.DE
where x is the routine you want.
.SH
Other Libraries
.PP
Likewise,
the directories containing the source for the other libraries
have makefiles.
.SH
System Tuning
.PP
There are several tunable parameters in the system. These set
the size of various tables and limits. They are found in the
file /usr/sys/h/param.h as manifests (`#define's).
Their values are rather generous in the system as distributed.
Our typical maximum number of users is about 20, but there are
many daemon processes.
.PP
When any parameter is changed, it is prudent to recompile
the entire system, as discussed above.
A brief discussion of each follows:
.IP NBUF 12
This sets the size of the disk buffer cache. Each buffer is 512 bytes.
This number should be around 25 plus NMOUNT,
or as big as can be if the above number of
buffers cause the system to not fit in memory.
.IP NFILE 12
This sets the maximum number of open files. An entry is made in
this table every time a file is `opened' (see open(2), creat(2)).
Processes share these table entries across forks (fork(2)). This number
should be about the same size as NINODE below. (It can be a bit smaller.)
.IP NMOUNT 12
This indicates the maximum number of mounted file systems. Make it
big enough that you don't run out at inconvenient times.
.IP MAXMEM 12
This specifies the number of page-frames of real memory at this
installation.
It is currently set at 1024 (512K bytes), and should be increased
if you have more (otherwise the additional memory will not be utilized).
.IP MAXUMEM 12
This sets an administrative limit on the amount of memory
a process may have.
It is currently set at MAXMEM-128 (i.e. 896).
It will be increased automatically by increasing MAXMEM.
Note, however, that the current upper bound on MAXUMEM is 128*12
(i.e. 1536) which limits user process space to 768K bytes.
.IP PHYSPAGES 12
This indicates the number of pages which can be represented
on the memory freelist.
Its current value is 2048, and is sufficient for systems of
up to one megabyte.
If this value is too small (i.e. more memory than freelist)
then system will only use PHYSPAGES page frames.
.IP MAXUPRC 12
This sets the maximum number of processes that any one user can
be running at any one time. This should be set just large enough
that people can get work done but not so large that a user can
hog all the processes available (usually by accident!).
.IP NPROC 12
This sets the maximum number of processes that can be
active.
It depends on the demand pattern of the typical user;
we seem to need about 8 times the number
of terminals.
.DE
.IP NINODE 12
This sets the size of the inode table. There is one entry in the inode
table for every open device, current working directory,
sticky text segment,
open file, and mounted device.
Note that if two users have a file open there is still only one entry
in the inode table. A reasonable rule of thumb for the size of
this table is
.DS
NPROC + NMOUNT + (number of terminals)
.DE
.IP SSIZE 12
The initial size of a process stack. This may be made bigger
if commonly run processes have large data areas on the stack.
.IP SINCR 12
The size of the stack growth increment.
.IP NOFILE 12
This sets the maximum number of files that any one process can have
open.
20 is plenty.
.IP CANBSIZ 12
This is the size of the typewriter canonicalization buffer. It is
in this buffer that erase and kill processing is done. Thus this
is the maximum size of an input typewriter line. 256 is usually
plenty.
.IP SMAPSIZ 12
The number of fragments that secondary (swap) memory can be
broken into.
This should be big enough that it never runs out.
The theoretical maximum is twice the number of processes,
but this is a vast overestimate in practice.
70 seems enough.
.IP NCALL 12
This is the size of the callout table. Callouts are entered in this
table when some sort of internal system timing must be done, as in
carriage return delays for terminals. The number must be big enough
to handle all such requests.
.IP NTEXT 12
The maximum number of simultaneously executing pure programs. This
should be big enough so as to not run out of space under heavy load.
A reasonable rule of thumb is about
.DS
(number of terminals) + (number of sticky programs)
.DE
.IP NCLIST 12
The number of clist segments. A clist segment is 12 characters.
NCLIST should be big enough so that the list doesn't become exhausted
when the machine is busy. The characters that have arrived from a terminal
and are waiting to be given to a process live here. Thus enough space
should be left so that every terminal can have at least one average
line pending (about 30 or 40 characters).
.IP TIMEZONE 12
The number of minutes westward from Greenwich. See `Setting Up UNIX'.
.IP DSTFLAG 12
See `Setting Up UNIX' section on time conversion.
.IP MSGBUFS 12
The maximum number of characters of system error messages saved. This
is used as a circular buffer.
.IP NCARGS 12
The maximum number of characters in an exec(2) arglist. This
number controls how many arguments can be passed
into a process.
5120 is practically infinite.
.IP HZ 12
Set to the desired frequency of the system clock (e.g., 50 for
a 50 Hz. clock).
The current value is 60 (i.e. 60 Hz. clock).