Commit | Line | Data |
---|---|---|
9fdccade C |
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). |