BSD 3 development

[unix-history] / usr / doc / regen

diff --git a/usr/doc/regen b/usr/doc/regen
index 452542a..101d88f 100644 (file)
--- a/usr/doc/regen
+++ b/usr/doc/regen
@@ -1,16 +1,18 @@
 .TL
 .TL

-Regenerating System Software
+REGENERATING SYSTEM SOFTWARE

 .AU
 .AU

-Charles B. Haley
+For UNIX/32V
+
+Thomas B. London

 .AU
 .AU

-Dennis. M. Ritchie
-.MH
+John F. Reiser
+.HO

 .SH
 Introduction
 .PP
 This document discusses how to
 assemble or compile various parts of the
 .SH
 Introduction
 .PP
 This document discusses how to
 assemble or compile various parts of the

-.UX
+.UX \s-2/32V\s0

 system software.
 This may be necessary because
 a command or library is accidentally
 system software.
 This may be necessary because
 a command or library is accidentally


@@ -72,10 +74,10 @@ Source for the Fortran 77 IO runtime routines.
 Source for the `data-base manager' package
 .I dbm
 (3).
 Source for the `data-base manager' package
 .I dbm
 (3).

-.IP libfpsim 12
-Source for the floating-point simulator routine.

 .IP libm 12
 Source for the mathematical library.
 .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
 .IP libplot 12
 Source for plotting routines.
 .SH


@@ -88,64 +90,55 @@ 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
 of files that make up the command.
 If it is a single file the command
 .DS

-cd /usr/src/cmd
-cmake cmd_name
+cd /usr/src/cmd/Admin
+Mk cmd_name.c

 .DE
 suffices. (Cmd_name is the name of the command you
 are playing with.)
 .DE
 suffices. (Cmd_name is the name of the command you
 are playing with.)

-The result of the cmake command will be an executable version.
-If you type
+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
 .DS

-cmake \-cp cmd_name
+cd /usr/src/cmd/Admin
+DESTDIR=mydir Mk cmd_name.c

 .DE
 .DE

-the result
-will be copied to /bin
-(or perhaps /etc or other places if appropriate).
+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:
 .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 all" 12
+.IP "make" 15

 The program is compiled and loaded; the executable is
 left in the current directory.
 The program is compiled and loaded; the executable is
 left in the current directory.

-.IP "make cp" 12
+.IP "make install" 15

 The program is compiled and loaded, and the executable is
 installed.
 The program is compiled and loaded, and the executable is
 installed.

-Everything is cleaned up afterwards;
-for example .o files are deleted.
-.IP "make cmp" 12
-The program is compiled and loaded, and the executable is compared
-against the one in /bin.
+.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
 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
 .SH
 The Assembler
 .PP

-The assembler consists of two executable files:
-/bin/as and /lib/as2.
-The first is the 0-th pass:
-it reads the source program, converts it to
-an intermediate form in a temporary file `/tmp/atm0?',
-and estimates the final locations
-of symbols.
-It also makes two or three other temporary
-files which contain the ordinary symbol table,
-a table of temporary symbols (like 1:)
-and possibly an overflow intermediate file.
-The program /lib/as2
-acts as an ordinary multiple pass assembler
-with input taken from the files produced by /bin/as.
-.PP
+The assembler consists of one executable file:
+/bin/as.

 The source files for /bin/as
 The source files for /bin/as

-are named `/usr/src/cmd/as/as1?.s'
-(there are 9 of them);
-/lib/as2 is produced
-from the source files
-`/usr/src/cmd/as/as2?.s';
-they likewise are 9 in number.
+are named `/usr/src/cmd/as/as?.c'.

 Considerable care should be exercised
 Considerable care should be exercised

-in replacing either component of the
+in replacing the

 assembler.
 Remember that if the assembler is lost,
 the only recourse is to replace it from some backup storage;
 assembler.
 Remember that if the assembler is lost,
 the only recourse is to replace it from some backup storage;


@@ -154,16 +147,14 @@ a broken assembler cannot assemble itself.
 The C Compiler
 .PP
 The C compiler consists of
 The C Compiler
 .PP
 The C compiler consists of

-seven routines:
+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').
 `/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 phases of the C compiler are
-`/lib/c0', which is the first phase of the compiler;
-`/lib/c1', which is the second phase of the compiler;
-and `/lib/c2', which is the optional
-third phase optimizer.
+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 loss of the C compiler is as serious
 as that of the assembler.
 .PP


@@ -174,64 +165,41 @@ If needed,
 prog.c can be compiled by
 .DS
 /lib/cpp prog.c >temp0
 prog.c can be compiled by
 .DS
 /lib/cpp prog.c >temp0

-/lib/c0 temp0 temp1 temp2
-/lib/c1 temp1 temp2 temp3
-as \- temp3
-ld \-n /lib/crt0.o a.out \-lc
+/lib/ccom temp0 temp1
+as temp3
+ld /lib/crt0.o a.out \-lc

 .DE
 .PP
 The source for the compiler proper is in the
 .DE
 .PP
 The source for the compiler proper is in the

-directory /usr/src/cmd/c.
-The first phase (/lib/c0)
-is generated from the files c00.c, ..., c05.c,
-which must be compiled by the C compiler.
-There is also c0.h, a header file
-.I included
-by the C programs of the first phase.
-To make a new /lib/c0 use
+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
 .DS

-make c0
+cd /usr/src/cmd/pcc
+make

 .DE
 .DE

-Before installing the new c0, it is prudent to save the old one someplace.
-.PP
-The second phase of C (/lib/c1)
-is generated from the source files c10.c, ..., c13.c,
-the include-file c1.h, and a set
-of object-code tables combined into table.o.
-To generate a new second phase use
-.DS
-make c1
-.DE
-It is likewise prudent to save c1 before
-installing a new version.
-In fact in general it is wise to save the
-object files for the C compiler so that
-if disaster strikes C can be reconstituted
-without a working version of the compiler.
+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,
 .PP
 In a similar manner,

-the third phase of the C compiler
+the optimizer phase of the C compiler

 (/lib/c2)
 is made up from the files
 (/lib/c2)
 is made up from the files

-c20.c and c21.c together with c2.h.
+c20.c, c21.c, and c22.c together with c2.h.

 Its loss is not critical since it is completely optional.
 Its loss is not critical since it is completely optional.

-.PP
-The set of tables mentioned above
-is generated from the file
-table.s.
-This `.s' file is not in fact assembler source;
-it must be converted by use of the 
-.I cvopt
-program, whose source and object are
-located in the C directory.
-Normally this is taken care of by make(1). You
-might want to look at the makefile to see what it does.

 .SH
 UNIX
 .PP
 The source and object programs for UNIX are kept in
 .SH
 UNIX
 .PP
 The source and object programs for UNIX are kept in

-four subdirectories of
-.I /usr/sys.
+two subdirectories of
+.I /usr/src/sys.

 In the subdirectory 
 .I h
 there are several files ending in `.h';
 In the subdirectory 
 .I h
 there are several files ending in `.h';


@@ -239,53 +207,24 @@ these are header files which are
 picked up (via `#include ...')
 as required by each system module.
 The subdirectory
 picked up (via `#include ...')
 as required by each system module.
 The subdirectory

-.I dev
-consists mostly of the device drivers
-together with a few other things.
-The subdirectory

 .I sys
 is the rest of the system.
 .I sys
 is the rest of the system.

-There are files of the form LIBx in the directories
-sys and dev. These are archives (ar(1)) which contain the
-object versions of the routines in the directory.

 .PP
 .PP

-Subdirectory
-.I conf
-contains the files which control
+The file
+.I conf.c
+contains the tables which control

 device configuration of the system.
 device configuration of the system.

-.I L.s
+.I Locore.s

 specifies the
 specifies the

-contents of the interrupt vectors;
-.I c.c
-contains the tables which relate device numbers
-to handler routines.
-A third file,
-.I mch.s ,
-contains all the
+contents of the interrupt vectors,
+and all the

 machine-language code in the system.
 machine-language code in the system.

-A fourth file,
-.I mch0.s ,
-is generated by mkconf(1) and contains
-flags indicating what sort of tape drive is available
-for taking crash dumps.

 .PP
 .PP

-There are two ways to recreate the system. Use
+To recreate the system, use

 .DS
 .DS

-cd /usr/sys/conf
+cd /usr/src/sys/sys

 make unix
 .DE
 make unix
 .DE

-if the libraries /usr/sys/dev/LIB2 and /usr/sys/sys/LIB1,
-and also c.o and l.o,
-are correct.
-Use
-.DS
-cd /usr/sys/conf
-make all
-.DE
-to recompile everything
-and recreate the libraries from scratch.
-This is needed, for example, when a header included
-in several source files is changed.

 See `Setting Up UNIX' for other information about configuration
 and such.
 .PP
 See `Setting Up UNIX' for other information about configuration
 and such.
 .PP


@@ -304,62 +243,44 @@ When you have satisfied yourself that the new system works,
 remove /ounix.
 .PP
 To install a new device driver,
 remove /ounix.
 .PP
 To install a new device driver,

-compile it and
-put it into its library.
-The best way to put it into
-the library is to use the command
-.DS
-ar uv LIB2 x.o
-.DE
-where x is the routine you just compiled.
-(All the device drivers distributed with
-the system are already in the library.)
+copy its source to /usr/src/sys/sys,
+and edit the `makefile' and the file `loadall' if
+necessary (see make(1)).

 .PP
 .PP

-Next, the device's interrupt vector must be entered in l.s.
-This is probably already done by the routine mkconf(1), but if the
-device is esoteric or nonstandard you will have to massage
-l.s by hand.
-This involves placing a pointer to a callout routine
-and the device's priority level in the vector.
-Use some other device (like the console) as a guide.
-Notice that the entries in l.s must be in order
-as the assembler does not permit moving the
-location counter `.' backwards.
-The assembler also does not permit assignation of
-an absolute number to `.', which is the
-reason for the `. = ZERO+100' subterfuge.
-If a constant smaller than 16(10) is added to the
-priority level,
-this number will be available as the first argument of the interrupt routine.
+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
 This stratagem is used when
 several similar devices share the same interrupt routine

-(as in dl11's).
+(as in dz11's).

 .PP
 .PP

-If you have to massage l.s, be sure to add the code
-to actually transfer to the interrupt routine. Again use
-the console as a guide. The apparent strangeness of this code
-is due to running the kernel in separate I&D space.
-The
-.I call
-routine
-saves registers as required and prepares a C-style
-call on the actual interrupt routine
-named after the `jmp' instruction.
-When the routine returns,
-.I call
-restores the registers and performs an
-rti instruction.
+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
 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 
-device unknown to mkconf is
+The second step which must be performed to add a new
+device is

 to add it to the configuration table
 to add it to the configuration table

-/usr/sys/conf/c.c.
-This file contains two subtables,
+/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.
 one for block-type devices, and one for character-type devices.

-Block devices include disks, DECtape, and magtape.
+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;
 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;


@@ -406,9 +327,9 @@ This library
 can be remade using the following commands:
 .DS
 cd /usr/src/libc
 can be remade using the following commands:
 .DS
 cd /usr/src/libc

-sh compall
-sh mklib
-mv libc.a /lib/libc.a
+make libc.a
+make install
+make clean

 .DE
 If single routines need to be recompiled and replaced, use
 .DS
 .DE
 If single routines need to be recompiled and replaced, use
 .DS


@@ -423,9 +344,19 @@ 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
 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
 cd /usr/src/libc/csu

-as \- x.s
-mv a.out /lib/x
+as -o x.o x.s
+mv x.o /lib

 .DE
 where x is the routine you want.
 .SH
 .DE
 where x is the routine you want.
 .SH


@@ -433,8 +364,7 @@ Other Libraries
 .PP
 Likewise,
 the directories containing the source for the other libraries
 .PP
 Likewise,
 the directories containing the source for the other libraries

-have files compall (that recompiles everything)
-and mklib (that recreates the library).
+have makefiles.

 .SH
 System Tuning
 .PP
 .SH
 System Tuning
 .PP


@@ -462,10 +392,24 @@ should be about the same size as NINODE below. (It can be a bit smaller.)
 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 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.
 This sets an administrative limit on the amount of memory
 a process may have.

-It is set automatically if the amount of physical memory is small,
-and thus should not need to be changed.
+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
 .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


@@ -503,14 +447,13 @@ 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.
 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 CMAPSIZ 12
-The number of fragments that memory can be broken into. This should
-be big enough that it never runs out.
+.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.
 The theoretical maximum is twice the number of processes,
 but this is a vast overestimate in practice.

-50 seems enough.
-.IP SMAPSIZ 12
-Same as CMAPSIZ except for secondary (swap) memory.
+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
 .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


@@ -524,7 +467,7 @@ A reasonable rule of thumb is about
 (number of terminals) + (number of sticky programs)
 .DE
 .IP NCLIST 12
 (number of terminals) + (number of sticky programs)
 .DE
 .IP NCLIST 12

-The number of clist segments. A clist segment is 6 characters.
+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
 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


@@ -543,5 +486,6 @@ number controls how many arguments can be passed
 into a process.
 5120 is practically infinite.
 .IP HZ 12
 into a process.
 5120 is practically infinite.
 .IP HZ 12

-Set to the frequency of the system clock (e.g., 50 for
+Set to the desired frequency of the system clock (e.g., 50 for

 a 50 Hz. clock).
 a 50 Hz. clock).

+The current value is 60 (i.e. 60 Hz. clock).