From eb0c627c629527f9e9686a27b1c2aa39ebaf53dd Mon Sep 17 00:00:00 2001 From: Alice Wyan Date: Tue, 12 May 2020 21:56:33 +0200 Subject: [PATCH] Update documentation on rebuilding ITS - Add a couple details on the build process - Improve formatting --- doc/NITS.md | 92 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 53 insertions(+), 39 deletions(-) diff --git a/doc/NITS.md b/doc/NITS.md index 3152571e..be6fe440 100644 --- a/doc/NITS.md +++ b/doc/NITS.md @@ -1,20 +1,29 @@ -### Assembling a new ITS +# Assembling a new ITS -Note: $ means typing the Altmode or Escape key. - -Note: `XX` means the name of the ITS you are building. - -0. Here are manuals for all programs mentioned below: +Note: $ means typing the Altmode or Escape key. `XX` refers to the name of the ITS you are building. +## Step 0. Preliminaries +Here are manuals for all programs mentioned below: - [MIDAS](info/midas.26) - [SALV](kshack/nsalv.order) - [DSKDMP](sysdoc/dskdmp.order) - [DDT](_info_/ddtord.1462) - [LOCK](_info_/lock.order) -1. First examine SYSTEM; CONFIG > for changes you want to make. Look for the text `IFE MCOND XX,[` to find the section for the machine named XX. +## Step 1. Machine configuration +First examine `SYSTEM; CONFIG >` for changes you want to make. Look for the text `IFE MCOND XX,[` to find the section for the machine named `XX`. There are already preconfigured machines for several simulators. - KA10 options you may want to consider: +If you are building a machine with a new name, make sure to read [Victor's guide](https://its.victor.se/wiki/rename) first, as well as [this issue](https://github.com/PDP-10/its/issues/441). + +If you want to connect your machine to a network, this is also where you define its network address. + + Common options you may want to consider: + - NQS, the number of disk drives. + - IMPP, whether there's an IMP interface. + - IMPUS3, the machine's **IP address**. + - NCPP, INETP, CHAOSP, network protocols. + + KA10-specific options: - DC10P, RP10P the kind of tape drives. - TM10A or TM10B, the kind of tape drive. - NUNITS and NEWDTP, number and kind of DECtape drives. @@ -23,21 +32,18 @@ Note: `XX` means the name of the ITS you are building. - TK10P, DPKPP, MTYP, terminal ports. - CH10P or T11CHP, the kind of Chaosnet interface. - KS10 options: + KS10-specific options: - RM03P, RM80P, RP06P, RP07P, the kind of disk drive. - DZ11P, terminal ports. - CH11P, Chaosnet interface. - Common options: - - NQS, the number of disk drives. - - IMPP, whether there's an IMP interface. - - NCPP, INETP, CHAOSP, network protocols. - - To change properties for terminals, edit the file SYSTEM; TTYTYP >. - Look for the section headed `MCONDX XX,{` + To change properties for terminals, edit the file `SYSTEM; TTYTYP >`. + Look for the section headed `MCONDX XX,{` or create it based on an existing one. +If you are creating a new machine name, you will have to add it to the terminal database too. -2. If you changed the disk configuration, you should probably reassemble (N)SALV and DSKDMP too. +## Step 2. Disk re-configuration (optional) +If you changed the disk configuration, you should probably reassemble (N)SALV and DSKDMP too. SALV is used on the KA10 to check the disks, and is merged with ITS later. NSALV is the corresponding program for the KS10. DSKDMP is used for booting the machine, reading a program from disk, and starting it. @@ -45,7 +51,7 @@ Note: `XX` means the name of the ITS you are building. For DSKDMP, use one of the default configurations, or use ASK and enter values for all parameters. - On a KA10, use the HRIFLG switch to make a new DSKDMP paper tape to boot from. - - On a KS10, use the BOOTSW switch to make a new DSKDMP boot block and save it as `.; BT BIN` Then write it to the front end file system: + - On a KS10, use the BOOTSW switch to make a new DSKDMP boot block and save it as `.; BT BIN`. Then write it to the front end file system: ``` :KSFEDR !WRITE @@ -55,14 +61,17 @@ Note: `XX` means the name of the ITS you are building. !QUIT ``` -3. Assemble ITS. It's prudent to store the binary in the `.` directory with a new name. E.g. +## Step 3. Assemble ITS +It's prudent to store the binary in the `.` directory with a new name. E.g. - `:MIDAS DSK0:.;NITS BIN_SYSTEM; ITS` + :MIDAS DSK0:.;NITS BIN_SYSTEM; ITS - Answer the question `MACHINE NAME = ` with `XX`. - Forgetting to specify `DSK0:` may later cause `FNF` and `PKNMTD` errors on `DKSDMP` during steps 5 and 6. +Answer the question `MACHINE NAME =` with `XX`. -4. If you made a change to (N)SALV, you should update @ (N)SALV. The latter is just (N)SALV dumped with its symbol table and DDT in the core image. +Forgetting to specify `DSK0:` may later cause `FNF` and `PKNMTD` errors on `DKSDMP` during steps 5 and 6 if the ITS binary ends up on a disk pack other than the first one. + +## Step 4. Update (N)SALV (optional) +If you made a change to (N)SALV, you should update @ (N)SALV. The latter is just (N)SALV dumped with its symbol table and DDT in the core image. ``` L$DDT @@ -71,27 +80,32 @@ Note: `XX` means the name of the ITS you are building. D$(N)SALV ``` -5. Merge the ITS binary with DDT and (N)SALV. +## Step 5. Merge the ITS binary with DDT and (N)SALV There are two options for doing this. The normal way is to reboot and do it in DSKDMP. The other way is to do it in timesharing DDT. - - DSKDMP method. Use this unless you have a good reason not to. +### DSKDMP method +Use this unless you have a good reason not to. - 1. Shut down ITS with LOCK. Reboot into DSKDMP. Use the new DSKDMP if you made one above. - 2. Load DDT: L$DDT - 3. Give ITS and its symbols to DDT: T$NITS BIN - 4. You're now in DDT. Exit back to DSKDMP: $U - 5. Merge in (N)SALV. For KA10: M$SALV BIN For KS10: M$NSALV BIN - 6. Write the result to disk: D$NITS Again, it's prudent to invent a new file name here. Use F$ for a file listing. + 1. Shut down ITS with LOCK. Reboot into DSKDMP. Use the new DSKDMP if you made one above. + 2. Load DDT: L$DDT + 3. Give ITS and its symbols to DDT: T$NITS BIN + 4. You're now in DDT. Exit back to DSKDMP: $U + 5. Merge in (N)SALV. For KA10: M$SALV BIN For KS10: M$NSALV BIN + 6. Write the result to disk: D$NITS Again, it's prudent to invent a new file name here. Use F$ for a file listing. - - Timesharing DDT method. +If you forgot to specify `DSK0:` in Step 2, or the disk order has changed, you might get `FNF` (FileNotFound) and `PKNMTD` (PacKNotMounTeD) errors. You can mount (load) the other disk packs using the L$n$ command (with `n` the disk pack to load) and then retry. - 1. Make a new job: ITS$J - 2. Load DDT without symbols: $1L .; @ DDT - 3. Merge in (N)SALV without symbols. For KA10: $$1L .; @ SALV For KS10: $$1L .; NSALV BIN - 4. Merge in ITS with symbols: $$L .; NITS BIN - 5. Write the result to disk: $Y .; @ NITS +### Timesharing DDT method. -6. If you're in DSKDMP and want to run ITS right away after dumping it, type G$. You're now in DDT. You can examine ITS, set breakpoints, etc. Type $G to start ITS. + 1. Make a new job: ITS$J + 2. Load DDT without symbols: $1L .; @ DDT + 3. Merge in (N)SALV without symbols. For KA10: $$1L .; @ SALV For KS10: $$1L .; NSALV BIN + 4. Merge in ITS with symbols: $$L .; NITS BIN + 5. Write the result to disk: $Y .; @ NITS -7. When the new ITS has passed testing, rename the old `.; @ ITS` to `.; @ OITS`. Rename the new ITS to `.; @ ITS`. +## Step 6 +If you're in DSKDMP and want to run ITS right away after dumping it, type G$. You're now in DDT. You can examine ITS, set breakpoints, etc. Type $G to start ITS. + +## Step 7 +When the new ITS has passed testing, rename the old `.; @ ITS` to `.; @ OITS`. Rename the new ITS to `.; @ ITS`.