Document how to make new ITS installation

[larsbrinkhoff]

@jwbrase wrote to the PiDP-11 mailing list:

I was looking for good instructions for a manual install, but the instructions I was able to find either created a very minimal system, without a lot of the seemingly standard utilities that I was seeing in documentation for the usage (rather than installation) of ITS, or else assumed that you were bringing up a simh resurrection of a historical host (seemingly there are hostnames hard coded into the source code or something?) without giving much information on how a new site would have installed ITS back in the day (presumably the host has to be defined somewhere?).

This is indeed something that would be good do document. There is NITS.md, but it's only part of the puzzle. Additional topics would be:

• Defining the disk geometries.
• Making DSKDMP and (N)SALV to suit.
• Updating source code with a new ITS name.
• Making tapes for bootstrapping.
• Building the basic tools, dragons, etc.

[jwbrase]

A few comments:  For disk geometries, it would probably be best to document the setup process for a specified set of simulated hardware. The standard hardware might or might not correspond to a historical configuration, but it would be a known quantity. Then we could have a footnote saying "if you want to use a different disk setup, follow the instructions in this supplement". As for the NITS document, users that have never seen ITS before will need to know what decisions they'll be making, what the technical context is, what the historical context is, what the consequences of each decision will be for the build process (will some options require significantly more work than others), etc. Some of the programs mentioned in the NITS document might need some clarification of what they actually do. The SALV documentation, for example,  describes what its individual functions do better than it explains the program as a whole, and basically provides one line of info for each function. The DDT documentation,  OTOH is excellent, and while I haven't looked through it closely, the MIDAS documentation looks to be good as well. 

[larsbrinkhoff]

Thanks, good points!

[techfury90]

I dabbled with this a bit back in December and finally dusted it off this morning. See branch techfury90/ka-tf-its for an example of mods I made to generate a KA ITS named TF. I don't doubt that it probably still needs changes on top of what I made.

Edit: Oh, and my idea of "works" was "successfully completes build from source". The rest, of course, is almost all untested.

[larsbrinkhoff]

That looks fine to me. Does it boot without complaints?

There's like 50 places in the sources that have a list of ITS machine names, that we know of. But they are mostly optional.

[larsbrinkhoff]

One thing that's very easy to miss, is adding a new section in SYSTEM; TTYTYP > and also make it match the number of terminal lines in CONFIG. That number is the sum of NOTYS, NNTYS, NDPTYS, NSTTYS, and maybe a few more.

If you get this wrong, ITS will just crash.

[larsbrinkhoff]

Even though it was not what @jwbrase had in mind, I'd like to add some text about configuring the number of disk packs. Or adding more. It's not very obvious and involves reassembling SALV, and ITS, and running obscure SALV commands.

[techfury90]

That looks fine to me. Does it boot without complaints?

DSKDMP
its
$G
SALVAGER.316

IT IS NOW  2:09:34 PM EST, FRIDAY, FEB 7,2020

TF ITS 1648 IN OPERATION AT 14:09:34
TF ITS 1648 SYSTEM JOB USING THIS CONSOLE.
TV 11 WENT DOWN -- 14:09:34
 LOGIN  TARAKA 0 14:09:35
TOP LEVEL INTERRUPT 200 DETACHED JOB # 3, USR:COMSAT IV     14:09:36

TF ITS.1648. DDT.1547.
TTY 0
You're all alone, Fair share = 92%
Welcome to ITS!

For brief information, type ?
For a list of colon commands, type :? and press Enter.
For the full info system, type :INFO and Enter.

Happy hacking!

There's like 50 places in the sources that have a list of ITS machine names, that we know of. But they are mostly optional.

I believe it. The changes I made here were basically just enough to get the automated build to succeed, although it does appear to be more or less usable at a glance.

One thing that's very easy to miss, is adding a new section in SYSTEM; TTYTYP > and also make it match the number of terminal lines in CONFIG. That number is the sum of NOTYS, NNTYS, NDPTYS, NSTTYS, and maybe a few more.

Yes! I remember running into this :) I took the lazy way out and just cloned all of KA's sections for things like CONFIG and TTYTYP, renaming them to TF.

I also modified the emulator configuration a bit... changed port numbers and IMP configuration, mainly so I could run it alongside a regular KA instance on the same host.

[techfury90]

Even though it was not what @jwbrase had in mind, I'd like to add some text about configuring the number of disk packs. Or adding more. It's not very obvious and involves reassembling SALV, and ITS, and running obscure SALV commands.

I'd be interested in this. Also curious about what's involved in generating a system with a different disk type... (say, where are we on DC10 support for KA these days?)

[larsbrinkhoff]

DC10 works well enough that I consider switching the KA ITS configuration to it. To get that authentic AI lab feel. See #1645. But first I should have it running on my own machine a few months or so.

[larsbrinkhoff]

Here's a comment that can be used in the document: https://github.com/PDP-10/its/issues/1645#issuecomment-510965790

[eswenson1]

I've been meaning to write up the steps for adding new disk packs to an existing ITS and for changing the disk type. I've done both of these processes multiple times. Trouble is, I've never written anything down and would have to go through the process again -- taking notes this time -- in order to do the writeup. That said, here are some partial notes that I wrote down -- they may not be complete.

1. Update SALV or NSALV to adjust NDRIVE, NUNITS, and LASTPK. Rebuild, and put copy of binary in . directory.
2. Update ITS to know about second disk. Update NQS, to reflect number of disks. Assemble, and put new version in "." directory - give it name NITS (or something that doesn't conflict with your working ITS)
3. Update emulator to know about second disk/pack.
4. Reboot emulator and load new NSALV/SALV (boot to DSKDMP, l$DDT, T$NSALV (or SALV)
5. Format new disk pack with MARK$G, specify new pack number, verify, and set swapping allocation to correct value (3000). Give pack an ID (string).
6. Copy user directories from pack 0 to new pack. UCOP$G and specify from and to units.
7. Then run CHKR$G to check the pack(s). Provide, say, "01", if there are two packs where before there was one. Specify to use MFD from original pack 0, Same with where user directories are.
8. Make a new bootable ITS image from DSKDMP. Use commands similar to this:

l$ddt
t$nits bin
$U
 DSKDMP
m$nnsalv bin
d$nits

10. Boot your new ITS from DSKDMP: g$
11. Verify with :DSKUSE # command. Should see new pack.

Again, I have not tested these recently, but it should be close. When I get a chance, I'll try the steps out and make any adjustments, but don't hold your breath.

[jwbrase]

Even though it was not what @jwbrase had in mind, I'd like to add some text about configuring the number of disk packs. Or adding more. It's not very obvious and involves reassembling SALV, and ITS, and running obscure SALV commands.

Oh, I have no objection to including such information. I'd like to see the installation procedure documented all the way through for some default hardware configuration, but that doesn't mean there can't be sections dealing with alternate configurations. Nor does it mean that the default configuration can't be one that requires making changes to the sources we're starting with, with a note "If you're using alternate configuration abc, skip step n", just as long as there is a default configuration for which the entire process is documented.

[larsbrinkhoff]

@eswenson1, you don't need to verify your notes. The steps to add disk packs are scripted in build/ka10/include.tcl.

On purpose, the KA10 ITS build is starting from ML ITS with two RP03 packs. During the bootstrap process, ITS/SALV/DSKDMP are assembled for KA ITS with four packs. Rather than updating the initial boostrap binary I kept it like this to ensure the process is tested.

But I see now I overestimated the value of scripting as documentation.

[larsbrinkhoff]

876 has some information that would fit here.

[eswenson1]

I realize that we already do this in that particular build (I don't think we do that for the KLH10 build). In any case, the script is a lousy way to document this -- since people who run real ITS systems will need to do this every so often. (I've expanded ES three times since I brought it up in 2015). We should have this documented in my new INFO; TIPS > as well as in an .md file outside of ITS.

[larsbrinkhoff]

A rough outline might be:

1. Build new essential programs for the target, with special attention to configurable parameters.
2. Make installation media: paper tapes, magnetic tapes.
3. Configure hardware/emulator.
4. Prepare an empty file system.
5. Install programs from step 1.
6. Install everything else.

@jwbrase would that be what you are looking for?

I think maybe "install new system from scratch" is a different document from "update existing system".

[larsbrinkhoff]

One parameter which has large implications is whether to make a Dynamic Modeling ITS or not. AI, ML, and MC were rather similar. DM had many unique features: demons, message slurper, E&S display, no Chaosnet.

[larsbrinkhoff]

@wyan, if you make a new ITS name please document any obstacles here.