home *** CD-ROM | disk | FTP | other *** search
/ minnie.tuhs.org / unixen.tar / unixen / PDP-11 / Trees / V7 / usr / doc / regen < prev    next >
Encoding:
Text File  |  1979-01-17  |  16.7 KB  |  548 lines

  1. .TL
  2. Regenerating System Software
  3. .AU
  4. Charles B. Haley
  5. .AU
  6. Dennis. M. Ritchie
  7. .MH
  8. .SH
  9. Introduction
  10. .PP
  11. This document discusses how to
  12. assemble or compile various parts of the
  13. .UX
  14. system software.
  15. This may be necessary because
  16. a command or library is accidentally
  17. deleted or otherwise
  18. destroyed;
  19. also, it may be desirable to install a modified
  20. version of some command or library routine.
  21. A few commands depend
  22. to some degree on the current configuration
  23. of the system;
  24. thus in any new system modifications to some commands
  25. are advisable.
  26. Most of the likely modifications
  27. relate to the standard disk devices contained
  28. in the system.
  29. For example, the df(1) (`disk free')
  30. command has built into it the names of
  31. the standardly present disk storage drives
  32. (e.g. `/dev/rf0', `/dev/rp0').
  33. Df(1) takes an argument to indicate which
  34. disk to examine, but it is convenient
  35. if its default argument is adjusted to
  36. reflect the ordinarily present devices.
  37. The companion document `Setting up UNIX'
  38. discusses which commands are likely to require
  39. changes.
  40. .SH
  41. Where Commands and Subroutines Live
  42. .PP
  43. The
  44. source files for commands and subroutines reside
  45. in several subdirectories
  46. of the directory /usr/src.
  47. These subdirectories, and a general
  48. description of their contents, are
  49. .IP cmd 12
  50. Source files for commands.
  51. .IP libc/stdio 12
  52. Source files making up the `standard i/o package'.
  53. .IP libc/sys 12
  54. Source files for the C system call interfaces.
  55. .IP libc/gen 12
  56. Source files for most of the remaining routines described
  57. in section 3 of the manual.
  58. .IP libc/crt 12
  59. Source files making up the C runtime support package, as
  60. in call save-return and long arithmetic.
  61. .IP libc/csu 12
  62. Source for the C startup routines.
  63. .IP games 12
  64. Source for (some of) the games.
  65. No great care has been taken to try to make it obvious how
  66. to compile these; treat it as a game.
  67. .IP libF77 12
  68. Source for the Fortran 77 runtime library, exclusive of IO.
  69. .IP libI77 12
  70. Source for the Fortran 77 IO runtime routines.
  71. .IP libdbm 12
  72. Source for the `data-base manager' package
  73. .I dbm
  74. (3).
  75. .IP libfpsim 12
  76. Source for the floating-point simulator routine.
  77. .IP libm 12
  78. Source for the mathematical library.
  79. .IP libplot 12
  80. Source for plotting routines.
  81. .SH
  82. Commands
  83. .PP
  84. The regeneration of most commands
  85. is straightforward.
  86. The `cmd' directory will contain either a source file
  87. for the command or a subdirectory containing the set
  88. of files that make up the command.
  89. If it is a single file the command
  90. .DS
  91. cd /usr/src/cmd
  92. cmake cmd_name
  93. .DE
  94. suffices. (Cmd_name is the name of the command you
  95. are playing with.)
  96. The result of the cmake command will be an executable version.
  97. If you type
  98. .DS
  99. cmake \-cp cmd_name
  100. .DE
  101. the result
  102. will be copied to /bin
  103. (or perhaps /etc or other places if appropriate).
  104. .PP
  105. If the source files are in a subdirectory there will be a `makefile'
  106. (see make(1)) to control the regeneration.
  107. After changing to the proper directory (cd(1)) you type one of the following:
  108. .IP "make all" 12
  109. The program is compiled and loaded; the executable is
  110. left in the current directory.
  111. .IP "make cp" 12
  112. The program is compiled and loaded, and the executable is
  113. installed.
  114. Everything is cleaned up afterwards;
  115. for example .o files are deleted.
  116. .IP "make cmp" 12
  117. The program is compiled and loaded, and the executable is compared
  118. against the one in /bin.
  119. .PP
  120. Some of the makefiles have other options. Print (cat(1)) the ones you
  121. are interested in to find out.
  122. .SH
  123. The Assembler
  124. .PP
  125. The assembler consists of two executable files:
  126. /bin/as and /lib/as2.
  127. The first is the 0-th pass:
  128. it reads the source program, converts it to
  129. an intermediate form in a temporary file `/tmp/atm0?',
  130. and estimates the final locations
  131. of symbols.
  132. It also makes two or three other temporary
  133. files which contain the ordinary symbol table,
  134. a table of temporary symbols (like 1:)
  135. and possibly an overflow intermediate file.
  136. The program /lib/as2
  137. acts as an ordinary multiple pass assembler
  138. with input taken from the files produced by /bin/as.
  139. .PP
  140. The source files for /bin/as
  141. are named `/usr/src/cmd/as/as1?.s'
  142. (there are 9 of them);
  143. /lib/as2 is produced
  144. from the source files
  145. `/usr/src/cmd/as/as2?.s';
  146. they likewise are 9 in number.
  147. Considerable care should be exercised
  148. in replacing either component of the
  149. assembler.
  150. Remember that if the assembler is lost,
  151. the only recourse is to replace it from some backup storage;
  152. a broken assembler cannot assemble itself.
  153. .SH
  154. The C Compiler
  155. .PP
  156. The C compiler consists of
  157. seven routines:
  158. `/bin/cc',
  159. which calls the phases of the compiler proper,
  160. the compiler control line expander `/lib/cpp',
  161. the assembler (`as'), and the loader (`ld').
  162. The phases of the C compiler are
  163. `/lib/c0', which is the first phase of the compiler;
  164. `/lib/c1', which is the second phase of the compiler;
  165. and `/lib/c2', which is the optional
  166. third phase optimizer.
  167. The loss of the C compiler is as serious
  168. as that of the assembler.
  169. .PP
  170. The source for /bin/cc
  171. resides in `/usr/src/cmd/cc.c'.
  172. Its loss alone (or that of c2) is not fatal.
  173. If needed,
  174. prog.c can be compiled by
  175. .DS
  176. /lib/cpp prog.c >temp0
  177. /lib/c0 temp0 temp1 temp2
  178. /lib/c1 temp1 temp2 temp3
  179. as \- temp3
  180. ld \-n /lib/crt0.o a.out \-lc
  181. .DE
  182. .PP
  183. The source for the compiler proper is in the
  184. directory /usr/src/cmd/c.
  185. The first phase (/lib/c0)
  186. is generated from the files c00.c, ..., c05.c,
  187. which must be compiled by the C compiler.
  188. There is also c0.h, a header file
  189. .I included
  190. by the C programs of the first phase.
  191. To make a new /lib/c0 use
  192. .DS
  193. make c0
  194. .DE
  195. Before installing the new c0, it is prudent to save the old one someplace.
  196. .PP
  197. The second phase of C (/lib/c1)
  198. is generated from the source files c10.c, ..., c13.c,
  199. the include-file c1.h, and a set
  200. of object-code tables combined into table.o.
  201. To generate a new second phase use
  202. .DS
  203. make c1
  204. .DE
  205. It is likewise prudent to save c1 before
  206. installing a new version.
  207. In fact in general it is wise to save the
  208. object files for the C compiler so that
  209. if disaster strikes C can be reconstituted
  210. without a working version of the compiler.
  211. .PP
  212. In a similar manner,
  213. the third phase of the C compiler
  214. (/lib/c2)
  215. is made up from the files
  216. c20.c and c21.c together with c2.h.
  217. Its loss is not critical since it is completely optional.
  218. .PP
  219. The set of tables mentioned above
  220. is generated from the file
  221. table.s.
  222. This `.s' file is not in fact assembler source;
  223. it must be converted by use of the 
  224. .I cvopt
  225. program, whose source and object are
  226. located in the C directory.
  227. Normally this is taken care of by make(1). You
  228. might want to look at the makefile to see what it does.
  229. .SH
  230. UNIX
  231. .PP
  232. The source and object programs for UNIX are kept in
  233. four subdirectories of
  234. .I /usr/sys.
  235. In the subdirectory 
  236. .I h
  237. there are several files ending in `.h';
  238. these are header files which are
  239. picked up (via `#include ...')
  240. as required by each system module.
  241. The subdirectory
  242. .I dev
  243. consists mostly of the device drivers
  244. together with a few other things.
  245. The subdirectory
  246. .I sys
  247. is the rest of the system.
  248. There are files of the form LIBx in the directories
  249. sys and dev. These are archives (ar(1)) which contain the
  250. object versions of the routines in the directory.
  251. .PP
  252. Subdirectory
  253. .I conf
  254. contains the files which control
  255. device configuration of the system.
  256. .I L.s
  257. specifies the
  258. contents of the interrupt vectors;
  259. .I c.c
  260. contains the tables which relate device numbers
  261. to handler routines.
  262. A third file,
  263. .I mch.s ,
  264. contains all the
  265. machine-language code in the system.
  266. A fourth file,
  267. .I mch0.s ,
  268. is generated by mkconf(1) and contains
  269. flags indicating what sort of tape drive is available
  270. for taking crash dumps.
  271. .PP
  272. There are two ways to recreate the system. Use
  273. .DS
  274. cd /usr/sys/conf
  275. make unix
  276. .DE
  277. if the libraries /usr/sys/dev/LIB2 and /usr/sys/sys/LIB1,
  278. and also c.o and l.o,
  279. are correct.
  280. Use
  281. .DS
  282. cd /usr/sys/conf
  283. make all
  284. .DE
  285. to recompile everything
  286. and recreate the libraries from scratch.
  287. This is needed, for example, when a header included
  288. in several source files is changed.
  289. See `Setting Up UNIX' for other information about configuration
  290. and such.
  291. .PP
  292. When the make is
  293. done, the new system is present in the
  294. current directory as `unix'.
  295. It should be tested before destroying the currently
  296. running `/unix', this is best done by doing something like
  297. .DS
  298. mv /unix /ounix
  299. mv unix /unix
  300. .DE
  301. If the new system doesn't work, you can still boot `ounix'
  302. and come up (see boot(8)).
  303. When you have satisfied yourself that the new system works,
  304. remove /ounix.
  305. .PP
  306. To install a new device driver,
  307. compile it and
  308. put it into its library.
  309. The best way to put it into
  310. the library is to use the command
  311. .DS
  312. ar uv LIB2 x.o
  313. .DE
  314. where x is the routine you just compiled.
  315. (All the device drivers distributed with
  316. the system are already in the library.)
  317. .PP
  318. Next, the device's interrupt vector must be entered in l.s.
  319. This is probably already done by the routine mkconf(1), but if the
  320. device is esoteric or nonstandard you will have to massage
  321. l.s by hand.
  322. This involves placing a pointer to a callout routine
  323. and the device's priority level in the vector.
  324. Use some other device (like the console) as a guide.
  325. Notice that the entries in l.s must be in order
  326. as the assembler does not permit moving the
  327. location counter `.' backwards.
  328. The assembler also does not permit assignation of
  329. an absolute number to `.', which is the
  330. reason for the `. = ZERO+100' subterfuge.
  331. If a constant smaller than 16(10) is added to the
  332. priority level,
  333. this number will be available as the first argument of the interrupt routine.
  334. This stratagem is used when
  335. several similar devices share the same interrupt routine
  336. (as in dl11's).
  337. .PP
  338. If you have to massage l.s, be sure to add the code
  339. to actually transfer to the interrupt routine. Again use
  340. the console as a guide. The apparent strangeness of this code
  341. is due to running the kernel in separate I&D space.
  342. The
  343. .I call
  344. routine
  345. saves registers as required and prepares a C-style
  346. call on the actual interrupt routine
  347. named after the `jmp' instruction.
  348. When the routine returns,
  349. .I call
  350. restores the registers and performs an
  351. rti instruction.
  352. As an aside, note that
  353. external names in C programs have an
  354. underscore (`_') prepended to them.
  355. .PP
  356. The second step which must be performed to add a 
  357. device unknown to mkconf is
  358. to add it to the configuration table
  359. /usr/sys/conf/c.c.
  360. This file contains two subtables,
  361. one for block-type devices, and one for character-type devices.
  362. Block devices include disks, DECtape, and magtape.
  363. All other devices are character devices.
  364. A line in each of these tables gives all the information
  365. the system needs to know about the device handler;
  366. the ordinal position of the line in the table implies
  367. its major device number, starting at 0.
  368. .PP
  369. There are four subentries per line in the block device table,
  370. which give its open routine, close routine, strategy routine, and
  371. device table.
  372. The open and close routines may be nonexistent,
  373. in which case the name `nulldev' is given;
  374. this routine merely returns.
  375. The strategy routine is called to do any I/O,
  376. and the device table contains status information for the device.
  377. .PP
  378. For character devices, each line in the table
  379. specifies a routine for open,
  380. close, read, and write, and one which sets and returns
  381. device-specific status (used, for example, for stty and gtty
  382. on typewriters).
  383. If there is no open or close routine, `nulldev' may
  384. be given; if there is no read, write, or status
  385. routine, `nodev' may be given.
  386. Nodev sets an error flag and returns.
  387. .PP
  388. The final step which must
  389. be taken to install a device is to make a special file for it.
  390. This is done by mknod(1), to which you must specify the
  391. device class (block or character),
  392. major device number (relative line in the configuration table)
  393. and minor device number
  394. (which is made available to the driver at appropriate times).
  395. .PP
  396. The documents
  397. `Setting up Unix' and
  398. `The Unix IO system'
  399. may aid in comprehending these steps.
  400. .SH
  401. The Library libc.a
  402. .PP
  403. The library /lib/libc.a is where most of the subroutines
  404. described in sections 2 and 3 of the manual are kept.
  405. This library
  406. can be remade using the following commands:
  407. .DS
  408. cd /usr/src/libc
  409. sh compall
  410. sh mklib
  411. mv libc.a /lib/libc.a
  412. .DE
  413. If single routines need to be recompiled and replaced, use
  414. .DS
  415. cc \-c \-O x.c
  416. ar vr /lib/libc.a x.o
  417. rm x.o
  418. .DE
  419. The above can also be used to put new items into the library.
  420. See ar(1), lorder(1), and tsort(1).
  421. .PP
  422. The routines in /usr/src/cmd/libc/csu (C start up) are not in
  423. libc.a. These are separately assembled and put into
  424. /lib. The commands to do this are
  425. .DS
  426. cd /usr/src/libc/csu
  427. as \- x.s
  428. mv a.out /lib/x
  429. .DE
  430. where x is the routine you want.
  431. .SH
  432. Other Libraries
  433. .PP
  434. Likewise,
  435. the directories containing the source for the other libraries
  436. have files compall (that recompiles everything)
  437. and mklib (that recreates the library).
  438. .SH
  439. System Tuning
  440. .PP
  441. There are several tunable parameters in the system. These set
  442. the size of various tables and limits. They are found in the
  443. file /usr/sys/h/param.h as manifests (`#define's).
  444. Their values are rather generous in the system as distributed.
  445. Our typical maximum number of users is about 20, but there are
  446. many daemon processes.
  447. .PP
  448. When any parameter is changed, it is prudent to recompile
  449. the entire system, as discussed above.
  450. A brief discussion of each follows:
  451. .IP NBUF 12
  452. This sets the size of the disk buffer cache. Each buffer is 512 bytes.
  453. This number should be around 25 plus NMOUNT,
  454. or as big as can be if the above number of
  455. buffers cause the system to not fit in memory.
  456. .IP NFILE 12
  457. This sets the maximum number of open files. An entry is made in
  458. this table every time a file is `opened' (see open(2), creat(2)).
  459. Processes share these table entries across forks (fork(2)). This number
  460. should be about the same size as NINODE below. (It can be a bit smaller.)
  461. .IP NMOUNT 12
  462. This indicates the maximum number of mounted file systems. Make it
  463. big enough that you don't run out at inconvenient times.
  464. .IP MAXMEM 12
  465. This sets an administrative limit on the amount of memory
  466. a process may have.
  467. It is set automatically if the amount of physical memory is small,
  468. and thus should not need to be changed.
  469. .IP MAXUPRC 12
  470. This sets the maximum number of processes that any one user can
  471. be running at any one time. This should be set just large enough
  472. that people can get work done but not so large that a user can
  473. hog all the processes available (usually by accident!).
  474. .IP NPROC 12
  475. This sets the maximum number of processes that can be
  476. active.
  477. It depends on the demand pattern of the typical user;
  478. we seem to need about 8 times the number
  479. of terminals.
  480. .DE
  481. .IP NINODE 12
  482. This sets the size of the inode table. There is one entry in the inode
  483. table for every open device, current working directory,
  484. sticky text segment,
  485. open file, and mounted device.
  486. Note that if two users have a file open there is still only one entry
  487. in the inode table. A reasonable rule of thumb for the size of
  488. this table is
  489. .DS
  490. NPROC + NMOUNT + (number of terminals)
  491. .DE
  492. .IP SSIZE 12
  493. The initial size of a process stack. This may be made bigger
  494. if commonly run processes have large data areas on the stack.
  495. .IP SINCR 12
  496. The size of the stack growth increment.
  497. .IP NOFILE 12
  498. This sets the maximum number of files that any one process can have
  499. open.
  500. 20 is plenty.
  501. .IP CANBSIZ 12
  502. This is the size of the typewriter canonicalization buffer. It is
  503. in this buffer that erase and kill processing is done. Thus this
  504. is the maximum size of an input typewriter line. 256 is usually
  505. plenty.
  506. .IP CMAPSIZ 12
  507. The number of fragments that memory can be broken into. This should
  508. be big enough that it never runs out.
  509. The theoretical maximum is twice the number of processes,
  510. but this is a vast overestimate in practice.
  511. 50 seems enough.
  512. .IP SMAPSIZ 12
  513. Same as CMAPSIZ except for secondary (swap) memory.
  514. .IP NCALL 12
  515. This is the size of the callout table. Callouts are entered in this
  516. table when some sort of internal system timing must be done, as in
  517. carriage return delays for terminals. The number must be big enough
  518. to handle all such requests.
  519. .IP NTEXT 12
  520. The maximum number of simultaneously executing pure programs. This
  521. should be big enough so as to not run out of space under heavy load.
  522. A reasonable rule of thumb is about
  523. .DS
  524. (number of terminals) + (number of sticky programs)
  525. .DE
  526. .IP NCLIST 12
  527. The number of clist segments. A clist segment is 6 characters.
  528. NCLIST should be big enough so that the list doesn't become exhausted
  529. when the machine is busy. The characters that have arrived from a terminal
  530. and are waiting to be given to a process live here. Thus enough space
  531. should be left so that every terminal can have at least one average
  532. line pending (about 30 or 40 characters).
  533. .IP TIMEZONE 12
  534. The number of minutes westward from Greenwich. See `Setting Up UNIX'.
  535. .IP DSTFLAG 12
  536. See `Setting Up UNIX' section on time conversion.
  537. .IP MSGBUFS 12
  538. The maximum number of characters of system error messages saved. This
  539. is used as a circular buffer.
  540. .IP NCARGS 12
  541. The maximum number of characters in an exec(2) arglist. This
  542. number controls how many arguments can be passed
  543. into a process.
  544. 5120 is practically infinite.
  545. .IP HZ 12
  546. Set to the frequency of the system clock (e.g., 50 for
  547. a 50 Hz. clock).
  548.