| 1 | .TL |
| 2 | REGENERATING SYSTEM SOFTWARE |
| 3 | .AU |
| 4 | For UNIX/32V |
| 5 | |
| 6 | Thomas B. London |
| 7 | .AU |
| 8 | John F. Reiser |
| 9 | .HO |
| 10 | .SH |
| 11 | Introduction |
| 12 | .PP |
| 13 | This document discusses how to |
| 14 | assemble or compile various parts of the |
| 15 | .UX \s-2/32V\s0 |
| 16 | system software. |
| 17 | This may be necessary because |
| 18 | a command or library is accidentally |
| 19 | deleted or otherwise |
| 20 | destroyed; |
| 21 | also, it may be desirable to install a modified |
| 22 | version of some command or library routine. |
| 23 | A few commands depend |
| 24 | to some degree on the current configuration |
| 25 | of the system; |
| 26 | thus in any new system modifications to some commands |
| 27 | are advisable. |
| 28 | Most of the likely modifications |
| 29 | relate to the standard disk devices contained |
| 30 | in the system. |
| 31 | For example, the df(1) (`disk free') |
| 32 | command has built into it the names of |
| 33 | the standardly present disk storage drives |
| 34 | (e.g. `/dev/rf0', `/dev/rp0'). |
| 35 | Df(1) takes an argument to indicate which |
| 36 | disk to examine, but it is convenient |
| 37 | if its default argument is adjusted to |
| 38 | reflect the ordinarily present devices. |
| 39 | The companion document `Setting up UNIX' |
| 40 | discusses which commands are likely to require |
| 41 | changes. |
| 42 | .SH |
| 43 | Where Commands and Subroutines Live |
| 44 | .PP |
| 45 | The |
| 46 | source files for commands and subroutines reside |
| 47 | in several subdirectories |
| 48 | of the directory /usr/src. |
| 49 | These subdirectories, and a general |
| 50 | description of their contents, are |
| 51 | .IP cmd 12 |
| 52 | Source files for commands. |
| 53 | .IP libc/stdio 12 |
| 54 | Source files making up the `standard i/o package'. |
| 55 | .IP libc/sys 12 |
| 56 | Source files for the C system call interfaces. |
| 57 | .IP libc/gen 12 |
| 58 | Source files for most of the remaining routines described |
| 59 | in section 3 of the manual. |
| 60 | .IP libc/crt 12 |
| 61 | Source files making up the C runtime support package, as |
| 62 | in call save-return and long arithmetic. |
| 63 | .IP libc/csu 12 |
| 64 | Source for the C startup routines. |
| 65 | .IP games 12 |
| 66 | Source for (some of) the games. |
| 67 | No great care has been taken to try to make it obvious how |
| 68 | to compile these; treat it as a game. |
| 69 | .IP libF77 12 |
| 70 | Source for the Fortran 77 runtime library, exclusive of IO. |
| 71 | .IP libI77 12 |
| 72 | Source for the Fortran 77 IO runtime routines. |
| 73 | .IP libdbm 12 |
| 74 | Source for the `data-base manager' package |
| 75 | .I dbm |
| 76 | (3). |
| 77 | .IP libm 12 |
| 78 | Source for the mathematical library. |
| 79 | .IP libnm 12 |
| 80 | Source for the assembler language mathematical library. |
| 81 | .IP libplot 12 |
| 82 | Source for plotting routines. |
| 83 | .SH |
| 84 | Commands |
| 85 | .PP |
| 86 | The regeneration of most commands |
| 87 | is straightforward. |
| 88 | The `cmd' directory will contain either a source file |
| 89 | for the command or a subdirectory containing the set |
| 90 | of files that make up the command. |
| 91 | If it is a single file the command |
| 92 | .DS |
| 93 | cd /usr/src/cmd/Admin |
| 94 | Mk cmd_name.c |
| 95 | .DE |
| 96 | suffices. (Cmd_name is the name of the command you |
| 97 | are playing with.) |
| 98 | The result of the Mk command will be an executable version, |
| 99 | copied to /bin |
| 100 | (or perhaps /etc or other places if appropriate). |
| 101 | If you want the result placed somewhere else, the command |
| 102 | .DS |
| 103 | cd /usr/src/cmd/Admin |
| 104 | DESTDIR=mydir Mk cmd_name.c |
| 105 | .DE |
| 106 | where mydir is a full pathname of some destination directory |
| 107 | (e.g. /usr/tbl/newcmds), |
| 108 | will compile the command and place the result in mydir/bin |
| 109 | (or perhaps mydir/etc or mydir/usr/bin, etc.). |
| 110 | .PP |
| 111 | If the source files are in a subdirectory there will be a `makefile' |
| 112 | (see make(1)) to control the regeneration. |
| 113 | After changing to the proper directory (cd(1)) you type one of the following: |
| 114 | .IP "make" 15 |
| 115 | The program is compiled and loaded; the executable is |
| 116 | left in the current directory. |
| 117 | .IP "make install" 15 |
| 118 | The program is compiled and loaded, and the executable is |
| 119 | installed. |
| 120 | .IP "make clean" 15 |
| 121 | Everything is cleanup; for example .o files are deleted. |
| 122 | .PP |
| 123 | Some of the makefiles have other options. Print (cat(1)) the ones you |
| 124 | are interested in to find out. |
| 125 | .PP |
| 126 | Alternately, to compiler and install a subdirectory command, one may |
| 127 | perform the following |
| 128 | .DS |
| 129 | cd /usr/src/cmd/Admin |
| 130 | Mk cmd_name |
| 131 | .DE |
| 132 | which combines all three of the above make options. |
| 133 | .SH |
| 134 | The Assembler |
| 135 | .PP |
| 136 | The assembler consists of one executable file: |
| 137 | /bin/as. |
| 138 | The source files for /bin/as |
| 139 | are named `/usr/src/cmd/as/as?.c'. |
| 140 | Considerable care should be exercised |
| 141 | in replacing the |
| 142 | assembler. |
| 143 | Remember that if the assembler is lost, |
| 144 | the only recourse is to replace it from some backup storage; |
| 145 | a broken assembler cannot assemble itself. |
| 146 | .SH |
| 147 | The C Compiler |
| 148 | .PP |
| 149 | The C compiler consists of |
| 150 | six routines: |
| 151 | `/bin/cc', |
| 152 | which calls the phases of the compiler proper, |
| 153 | the compiler control line expander `/lib/cpp', |
| 154 | the assembler (`as'), and the loader (`ld'). |
| 155 | The C compiler proper is `/lib/ccom'; |
| 156 | `/lib/c2' is the optional |
| 157 | assembler-language optimizer. |
| 158 | The loss of the C compiler is as serious |
| 159 | as that of the assembler. |
| 160 | .PP |
| 161 | The source for /bin/cc |
| 162 | resides in `/usr/src/cmd/cc.c'. |
| 163 | Its loss alone (or that of c2) is not fatal. |
| 164 | If needed, |
| 165 | prog.c can be compiled by |
| 166 | .DS |
| 167 | /lib/cpp prog.c >temp0 |
| 168 | /lib/ccom temp0 temp1 |
| 169 | as temp3 |
| 170 | ld /lib/crt0.o a.out \-lc |
| 171 | .DE |
| 172 | .PP |
| 173 | The source for the compiler proper is in the |
| 174 | directories /usr/src/cmd/mip and /usr/src/cmd/pcc. |
| 175 | The /usr/src/cmd/mip directory contains files which are |
| 176 | (relatively) machine independent; |
| 177 | the machine dependent files reside in the |
| 178 | directory /usr/src/cmd/pcc. |
| 179 | The compiler is `made' by the makefile (see make(1)) |
| 180 | in the directory /usr/src/cmd/pcc. |
| 181 | To make a new /lib/ccom use |
| 182 | .DS |
| 183 | cd /usr/src/cmd/pcc |
| 184 | make |
| 185 | .DE |
| 186 | which produces the compiler |
| 187 | (named /usr/src/cmd/pcc/comp). |
| 188 | Before installing the new compiler, |
| 189 | it is prudent to save the old one someplace. |
| 190 | .PP |
| 191 | In a similar manner, |
| 192 | the optimizer phase of the C compiler |
| 193 | (/lib/c2) |
| 194 | is made up from the files |
| 195 | c20.c, c21.c, and c22.c together with c2.h. |
| 196 | Its loss is not critical since it is completely optional. |
| 197 | .SH |
| 198 | UNIX |
| 199 | .PP |
| 200 | The source and object programs for UNIX are kept in |
| 201 | two subdirectories of |
| 202 | .I /usr/src/sys. |
| 203 | In the subdirectory |
| 204 | .I h |
| 205 | there are several files ending in `.h'; |
| 206 | these are header files which are |
| 207 | picked up (via `#include ...') |
| 208 | as required by each system module. |
| 209 | The subdirectory |
| 210 | .I sys |
| 211 | is the rest of the system. |
| 212 | .PP |
| 213 | The file |
| 214 | .I conf.c |
| 215 | contains the tables which control |
| 216 | device configuration of the system. |
| 217 | .I Locore.s |
| 218 | specifies the |
| 219 | contents of the interrupt vectors, |
| 220 | and all the |
| 221 | machine-language code in the system. |
| 222 | .PP |
| 223 | To recreate the system, use |
| 224 | .DS |
| 225 | cd /usr/src/sys/sys |
| 226 | make unix |
| 227 | .DE |
| 228 | See `Setting Up UNIX' for other information about configuration |
| 229 | and such. |
| 230 | .PP |
| 231 | When the make is |
| 232 | done, the new system is present in the |
| 233 | current directory as `unix'. |
| 234 | It should be tested before destroying the currently |
| 235 | running `/unix', this is best done by doing something like |
| 236 | .DS |
| 237 | mv /unix /ounix |
| 238 | mv unix /unix |
| 239 | .DE |
| 240 | If the new system doesn't work, you can still boot `ounix' |
| 241 | and come up (see boot(8)). |
| 242 | When you have satisfied yourself that the new system works, |
| 243 | remove /ounix. |
| 244 | .PP |
| 245 | To install a new device driver, |
| 246 | copy its source to /usr/src/sys/sys, |
| 247 | and edit the `makefile' and the file `loadall' if |
| 248 | necessary (see make(1)). |
| 249 | .PP |
| 250 | Next, the I/O interrupt fielding mechanism must be modified |
| 251 | to properly handle the new device. |
| 252 | If the device is connected via the UNIBUS, then one only |
| 253 | need add the device's interrupt handling routine address(s) |
| 254 | in the proper position in the table `UNIvec' in the |
| 255 | file /usr/src/sys/sys/univec.c. |
| 256 | `UNIvec' |
| 257 | should be modified |
| 258 | by placing a pointer to a callout routine |
| 259 | in the proper vector. |
| 260 | Use some other device (like the DZ11) as a guide. |
| 261 | Notice that the entries in `UNIvec' must be in order. |
| 262 | Bits 27-31 of the vector address |
| 263 | will be available as the first argument of the interrupt routine. |
| 264 | This stratagem is used when |
| 265 | several similar devices share the same interrupt routine |
| 266 | (as in dz11's). |
| 267 | .PP |
| 268 | If the device is connected via the MASSBUS, |
| 269 | then /usr/src/sys/sys/univec.c is not to be modifed. |
| 270 | Instead, code must be added to /usr/src/sys/sys/locore.s |
| 271 | to actually transfer to the interrupt routine. |
| 272 | Use the RP06 interrupt routine `Xmba0int' in locore.s as a guide. |
| 273 | As an aside, note that |
| 274 | external names in C programs have an |
| 275 | underscore (`_') prepended to them. |
| 276 | .PP |
| 277 | The second step which must be performed to add a new |
| 278 | device is |
| 279 | to add it to the configuration table |
| 280 | /usr/src/sys/sys/conf.c. |
| 281 | This file contains two subtables, `bdevsw' and `cdevsw', |
| 282 | one for block-type devices, and one for character-type devices. |
| 283 | Block devices include disks, and magtape. |
| 284 | All other devices are character devices. |
| 285 | A line in each of these tables gives all the information |
| 286 | the system needs to know about the device handler; |
| 287 | the ordinal position of the line in the table implies |
| 288 | its major device number, starting at 0. |
| 289 | .PP |
| 290 | There are four subentries per line in the block device table, |
| 291 | which give its open routine, close routine, strategy routine, and |
| 292 | device table. |
| 293 | The open and close routines may be nonexistent, |
| 294 | in which case the name `nulldev' is given; |
| 295 | this routine merely returns. |
| 296 | The strategy routine is called to do any I/O, |
| 297 | and the device table contains status information for the device. |
| 298 | .PP |
| 299 | For character devices, each line in the table |
| 300 | specifies a routine for open, |
| 301 | close, read, and write, and one which sets and returns |
| 302 | device-specific status (used, for example, for stty and gtty |
| 303 | on typewriters). |
| 304 | If there is no open or close routine, `nulldev' may |
| 305 | be given; if there is no read, write, or status |
| 306 | routine, `nodev' may be given. |
| 307 | Nodev sets an error flag and returns. |
| 308 | .PP |
| 309 | The final step which must |
| 310 | be taken to install a device is to make a special file for it. |
| 311 | This is done by mknod(1), to which you must specify the |
| 312 | device class (block or character), |
| 313 | major device number (relative line in the configuration table) |
| 314 | and minor device number |
| 315 | (which is made available to the driver at appropriate times). |
| 316 | .PP |
| 317 | The documents |
| 318 | `Setting up Unix' and |
| 319 | `The Unix IO system' |
| 320 | may aid in comprehending these steps. |
| 321 | .SH |
| 322 | The Library libc.a |
| 323 | .PP |
| 324 | The library /lib/libc.a is where most of the subroutines |
| 325 | described in sections 2 and 3 of the manual are kept. |
| 326 | This library |
| 327 | can be remade using the following commands: |
| 328 | .DS |
| 329 | cd /usr/src/libc |
| 330 | make libc.a |
| 331 | make install |
| 332 | make clean |
| 333 | .DE |
| 334 | If single routines need to be recompiled and replaced, use |
| 335 | .DS |
| 336 | cc \-c \-O x.c |
| 337 | ar vr /lib/libc.a x.o |
| 338 | rm x.o |
| 339 | .DE |
| 340 | The above can also be used to put new items into the library. |
| 341 | See ar(1), lorder(1), and tsort(1). |
| 342 | .PP |
| 343 | The routines in /usr/src/cmd/libc/csu (C start up) are not in |
| 344 | libc.a. These are separately assembled and put into |
| 345 | /lib. The commands to do this are |
| 346 | .DS |
| 347 | cd /usr/src/libc |
| 348 | for i in csu/*.s |
| 349 | do |
| 350 | j=`basename $i .s` |
| 351 | as -o $j.o $i |
| 352 | mv $j.o /lib |
| 353 | done |
| 354 | .DE |
| 355 | or, if you need only redo one routine, |
| 356 | .DS |
| 357 | cd /usr/src/libc/csu |
| 358 | as -o x.o x.s |
| 359 | mv x.o /lib |
| 360 | .DE |
| 361 | where x is the routine you want. |
| 362 | .SH |
| 363 | Other Libraries |
| 364 | .PP |
| 365 | Likewise, |
| 366 | the directories containing the source for the other libraries |
| 367 | have makefiles. |
| 368 | .SH |
| 369 | System Tuning |
| 370 | .PP |
| 371 | There are several tunable parameters in the system. These set |
| 372 | the size of various tables and limits. They are found in the |
| 373 | file /usr/sys/h/param.h as manifests (`#define's). |
| 374 | Their values are rather generous in the system as distributed. |
| 375 | Our typical maximum number of users is about 20, but there are |
| 376 | many daemon processes. |
| 377 | .PP |
| 378 | When any parameter is changed, it is prudent to recompile |
| 379 | the entire system, as discussed above. |
| 380 | A brief discussion of each follows: |
| 381 | .IP NBUF 12 |
| 382 | This sets the size of the disk buffer cache. Each buffer is 512 bytes. |
| 383 | This number should be around 25 plus NMOUNT, |
| 384 | or as big as can be if the above number of |
| 385 | buffers cause the system to not fit in memory. |
| 386 | .IP NFILE 12 |
| 387 | This sets the maximum number of open files. An entry is made in |
| 388 | this table every time a file is `opened' (see open(2), creat(2)). |
| 389 | Processes share these table entries across forks (fork(2)). This number |
| 390 | should be about the same size as NINODE below. (It can be a bit smaller.) |
| 391 | .IP NMOUNT 12 |
| 392 | This indicates the maximum number of mounted file systems. Make it |
| 393 | big enough that you don't run out at inconvenient times. |
| 394 | .IP MAXMEM 12 |
| 395 | This specifies the number of page-frames of real memory at this |
| 396 | installation. |
| 397 | It is currently set at 1024 (512K bytes), and should be increased |
| 398 | if you have more (otherwise the additional memory will not be utilized). |
| 399 | .IP MAXUMEM 12 |
| 400 | This sets an administrative limit on the amount of memory |
| 401 | a process may have. |
| 402 | It is currently set at MAXMEM-128 (i.e. 896). |
| 403 | It will be increased automatically by increasing MAXMEM. |
| 404 | Note, however, that the current upper bound on MAXUMEM is 128*12 |
| 405 | (i.e. 1536) which limits user process space to 768K bytes. |
| 406 | .IP PHYSPAGES 12 |
| 407 | This indicates the number of pages which can be represented |
| 408 | on the memory freelist. |
| 409 | Its current value is 2048, and is sufficient for systems of |
| 410 | up to one megabyte. |
| 411 | If this value is too small (i.e. more memory than freelist) |
| 412 | then system will only use PHYSPAGES page frames. |
| 413 | .IP MAXUPRC 12 |
| 414 | This sets the maximum number of processes that any one user can |
| 415 | be running at any one time. This should be set just large enough |
| 416 | that people can get work done but not so large that a user can |
| 417 | hog all the processes available (usually by accident!). |
| 418 | .IP NPROC 12 |
| 419 | This sets the maximum number of processes that can be |
| 420 | active. |
| 421 | It depends on the demand pattern of the typical user; |
| 422 | we seem to need about 8 times the number |
| 423 | of terminals. |
| 424 | .DE |
| 425 | .IP NINODE 12 |
| 426 | This sets the size of the inode table. There is one entry in the inode |
| 427 | table for every open device, current working directory, |
| 428 | sticky text segment, |
| 429 | open file, and mounted device. |
| 430 | Note that if two users have a file open there is still only one entry |
| 431 | in the inode table. A reasonable rule of thumb for the size of |
| 432 | this table is |
| 433 | .DS |
| 434 | NPROC + NMOUNT + (number of terminals) |
| 435 | .DE |
| 436 | .IP SSIZE 12 |
| 437 | The initial size of a process stack. This may be made bigger |
| 438 | if commonly run processes have large data areas on the stack. |
| 439 | .IP SINCR 12 |
| 440 | The size of the stack growth increment. |
| 441 | .IP NOFILE 12 |
| 442 | This sets the maximum number of files that any one process can have |
| 443 | open. |
| 444 | 20 is plenty. |
| 445 | .IP CANBSIZ 12 |
| 446 | This is the size of the typewriter canonicalization buffer. It is |
| 447 | in this buffer that erase and kill processing is done. Thus this |
| 448 | is the maximum size of an input typewriter line. 256 is usually |
| 449 | plenty. |
| 450 | .IP SMAPSIZ 12 |
| 451 | The number of fragments that secondary (swap) memory can be |
| 452 | broken into. |
| 453 | This should be big enough that it never runs out. |
| 454 | The theoretical maximum is twice the number of processes, |
| 455 | but this is a vast overestimate in practice. |
| 456 | 70 seems enough. |
| 457 | .IP NCALL 12 |
| 458 | This is the size of the callout table. Callouts are entered in this |
| 459 | table when some sort of internal system timing must be done, as in |
| 460 | carriage return delays for terminals. The number must be big enough |
| 461 | to handle all such requests. |
| 462 | .IP NTEXT 12 |
| 463 | The maximum number of simultaneously executing pure programs. This |
| 464 | should be big enough so as to not run out of space under heavy load. |
| 465 | A reasonable rule of thumb is about |
| 466 | .DS |
| 467 | (number of terminals) + (number of sticky programs) |
| 468 | .DE |
| 469 | .IP NCLIST 12 |
| 470 | The number of clist segments. A clist segment is 12 characters. |
| 471 | NCLIST should be big enough so that the list doesn't become exhausted |
| 472 | when the machine is busy. The characters that have arrived from a terminal |
| 473 | and are waiting to be given to a process live here. Thus enough space |
| 474 | should be left so that every terminal can have at least one average |
| 475 | line pending (about 30 or 40 characters). |
| 476 | .IP TIMEZONE 12 |
| 477 | The number of minutes westward from Greenwich. See `Setting Up UNIX'. |
| 478 | .IP DSTFLAG 12 |
| 479 | See `Setting Up UNIX' section on time conversion. |
| 480 | .IP MSGBUFS 12 |
| 481 | The maximum number of characters of system error messages saved. This |
| 482 | is used as a circular buffer. |
| 483 | .IP NCARGS 12 |
| 484 | The maximum number of characters in an exec(2) arglist. This |
| 485 | number controls how many arguments can be passed |
| 486 | into a process. |
| 487 | 5120 is practically infinite. |
| 488 | .IP HZ 12 |
| 489 | Set to the desired frequency of the system clock (e.g., 50 for |
| 490 | a 50 Hz. clock). |
| 491 | The current value is 60 (i.e. 60 Hz. clock). |