-*-Text-*-  File: TIPS Node: TOP Up: (DIR) Next: DSKDMP This is a collection of tips, recipes, and hints, regarding the use of ITS. It is not intended to provide in-depth information about any specific subject and may, if details exist elsewhere, refer the reader to other documentation. * Menu: * DSKDMP:: Some useful hints about using DSKDMP * Debugging JOB Devices:: Instructions on how to debug JOB devices * Assembling a new ITS:: Instructions on assembling a new ITS * Adding an additional disk:: Instructions on adding an additional disk to ITS  File: TIPS, Node: DSKDMP, Previous: TOP, Up: TOP, Next: Debugging JOB Devices This topic describes some hints about how to use DSKDMP to manage the boot files, ITS, and other programs invoked on the operator console priot to starting ITS. * Menu: * Creating a Bootable ITS Image:: How to create a bootable ITS image  File: TIPS, Node: Debugging JOB Devices, Up: TOP, Next: Assembling a new ITS ITS supports custom device handlers by using the JOB: device. Links to "virtual" devices are create in the DEVICE directory, such as: DEVICE; JOBDEV DB => DEVICE; ATSIGN MLDEV The program DEVICE; ATSIGN MLDEV is called a BDH (BOJ Device Handler) and is invoked when attempting to perform i/o on a device whose name appears in the FN2 of a DEVICE; JOBDEV entry -- in this case, "DB:". The JOB and BOJ devices are described in SYSDOC; JOB > and all the information contained in that document is not duplicated here. Refer to that document for basic information, including high level instructions on how to debug BDHs. This INFO entry, gives an example of how to debug the MLDEV BDH. A similar method can be used to debug any BDH. The scenario is as follows: You discover that a job fails or an attempt to access a file using MLDEV gets an error. Say, for example, that you attempt the following command: :listf no:sys; where a link exists on your system from DEVICE; JOBDEV NO to DEVICE; ATSIGN MLDEV. And when you do this, you can an error or a hang in the job and you discover that there is a dead MLDEV job hanging around (perhaps it did a .VALUE). You in PEEK, these jobs appears to have a JNAME of JOB.NN. You want to debug why this is happening. You need two login sessions to debug this easily -- two HACTRNs. Assume in you logged into one as EJS. First, create a job: mldev$j Then, load in the MLDEV binary: $L device;atsign mldev Patch the value of .OPTION to enable the %opojb bit (2000): *.option/ 30000,,0 32000,,0 Set a breakpoint that will be hit when the BDH is invoked: go+4$b Start the BDH going: $0g $p In another HACTRN, say logged in as EJS0, set up a translation so that attempts to access the NO device will invoke the BDH under debug: $^t no:,ojb:ejs;ejs mldev Note: the two EJS instances above refer to the logged in HACTRN where MLDEV is being debugged. The MLDEV refers to the JNAME of the JOB being debugged. Now, in this HACTRN, access the NO device in whatever way you want. The easiest way is to simply reference the device in a LISTF command: :listf no:sys; This will appear to hang, but in the debugging HACTRN, your BDH job will have stopped at the breakpoint. $1B; GO+4>>.CALL 3316 (RFNAME) You are now free to debug the BDH to your heart's content.  File: TIPS, Node: Creating a Bootable ITS Image, Up: TOP A directly bootable ITS image resides in a file in the "." directory, with an FN1 of "@". For example, the file ".;@ ITS" might be a directly bootable ITS image. Such an image usually includes DDT, the Salvager, and ITS itself. In order to create such an image, you need to have image files for each of these components: - DDT (e.g. ".;DDT BIN") - Salvager (e.g ".;NSALV BIN") - ITS (e.g. ".;ITS BIN") Assuming each of the above files exists in the "." directory, in order to produce a directly bootable ITS image (".;@ ITS"), you invoke the following commands from DSKDMP: l$ddt bin t$its bin $U m$nsalv bin d$its The "l" command clears memory and loads in a copy of DDT. The "t" command loads in a copy of ITS, without clearing memory first and including the symbols for ITS. The resulting memory image includes both DDT and ITS. The "$U" command restarts DSKDMP so that you can issue the "m" command to merge in the salvager, NSALV. Finally the "d" command dumps out the memory image into a file in the "." directory, whose FN1 is "@" and whose FN2 is "its". At this point, you have a directly bootable ITS image. You can either type: G$ $g or its $g The first sequence sets the starting address and then executes the image from that starting address. The second sequence loads the image from the file system (".;@ ITS") and then starts it at the image's starting address.  File: TIPS, Node: Assembling a new ITS, Up: TOP, Next: Adding an additional disk Note: In the following description XX refers to the two-character ITS machine name you are building -- for example DB. 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. KA 10 options you may want to consider: - DC10P, RP10P: the kind of tape drives - TM10A or TM10B: the kind of tape drive. - NUNITS and NEWDTP: number and kind of DECtape drives - TEN11P to enable the Rubin 10-11 interface. Subordinate options are: - Knight TV, XGP, Chaos-11 - PDP6P to use an auxiliary PDP-6 - TK10P, DPKPP, MTYP: terminal ports - CH10P or T11CHP: the kind of Chaosnet interface KS10 options: - RM03P, RM80P, RP06P, RP07P: the kind of disk drive - DZ11P: terminal prots - CH11P: Chaosnet interface Common options: - NQS: the number of disk drives - IMPP: whether there is an IMP interface - NCPP, INETP, CHAOSP: network protocols To change properties for terminals, edit SYSTEM; TTYTYP >. Look for the section titled MCCONDX XX,{ 2. 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. It is merged with ITS when you build a new ITS image. NSALV is the corresponding program for the KS10. DSKDMP is used for booting the machine or reading a program from disk for standalone execution, and then starting it. Look for IFCE MCH,XX,[ in SALV or NSALV. Update parameters appropriately. For DSKDMP, use one of the default configurations, or use ASK so that you are prompted for parameters. - On a KA10, use the HRIFLG switch to make a new DSKDMP paper tape to boot from. - On a KS10, use the BOOOTSW switch to make a new DSKDMP boot block and save it as .; BT BIN. THen write it to the front end system: :KSFEDR !WRITE Are you sure you want to scribble in the FE filesystem? YES Which file? BT Input from (Default DSK: FOO; BT BIN): .;BT BIN !QUIT 3. Assemble ITS. It's prudent to store the binary file in the . directory with a new name. E.g. :MIDAS .:NITS BIN_SYSTEM; ITS Answer the question "MACHINE NAME =" with XX. 4. 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. a. Shut down ITS with LOCK. Reboot into DSKDMP. Use the new DSKDMP if you made one above. b. Load DDT: l$ddt c. Give ITS and its symbols to DDT: t$nits bin d. You're now in DDT. Exit back to DSKDMP: $u e. Merge in (N)SALV. For KA10: m$salv. For KS10: m$nsalv bin f. Write the result to disk: dSnits. It is prudent to make sure you write a new file name here. Use f$ for a file listing. - Timesharing DDT method a. Make a new job: its$j b. Load DDT without symbols: $1l .; @ DDT c. Merge in (N)SALV without symbols: For KA10: $$1l .; @ SALV. For KS10: $$1l .; NSALV BIN. d. Merge in ITS with symbols: $$l .; NITS BIN e. Write the result to disk: $y .; @ NITS 5. If you're in DSKDMP and want to run ITS right away after dumping, it, type G$. You're now in DDT and you can examine ITS, set breakpoints, etc. Type $g to start ITS. 6. When the new ITS has passed testing, rename the old .; @ ITS to .; @ OITS. Rename the new ITS to .; @ ITS.  File: TIPS, Node: Adding an additional disk, Next: Build new version of SALV or NSALV, Up: TOP * Menu: * Build new version of SALV or NSALV:: * Build new version of ITS:: * Build new version of DSKDMP (optional):: * Shut down ITS:: * Update emulator configuration for new disks:: * Boot SALV or NSALV:: * Format new disk pack:: * Copy user directories from first disk to new disk(s):: * Create new bootable ITS:: * Boot new ITS::  File: TIPS, Node: Build new version of SALV or NSALV, Up: Adding an additional disk, Next: Build new version of ITS 1. Edit the file KSHACK;NSALV > or SYSTEM;SALV >. The file contains definitions for the known ITS installations, so be sure to update the correct section of the file. For PiDP-10, we generally use the KA installation. 2. Update NDRIVE to specify the total number of drives desired. For RP06 and RP07 drives, the number of drives equals the number of packs. For a 1-pack system (default), NDRIVE==1. If you are adding a second drive, change this to NDRIVE==2. Note that some systems will not have this parameter specified, and will instead use a default of 8. This is harmless, but you can add an explicit setting if you prefer. 3. Update NUNITS to specify the total number of pasks desired. For RP06 and RP07 drives, the number of drives equals the number of packs. For a 1-pack system (default), NUNITS==1. If you are adding a second pack, change this to NUNITS==2. Note that like NDRIVE above, this parameter may be using a default setting and can be handled the same way. 4. Update LASTPK to specify the 0-based number of the last pack For a 1-pack system (default), LASTPK==0. If you are adding a second disk/pack, change this to LASTPK==1. 5. Back up active version of NSALV or SALV: a. For NSALV: :RENAME .;nsalv bin,nsalv obin b. For SALV: :RENAME .;salv bin,salv obin 6. Assemble a new NSALV or SALV: a. For NSALV: :MIDAS dsk0:.;_kshack;nsalv b. For SALV: :MIDAS dsk0:.;_system;salv You will be asked a few questions as the file is assembled. For "Run under time-sharing?" answer N followed by a carriage return, and for "Which machine?" answer with the appropriate installation name, such as KA for a PiDP-10 system. This name should be capitalized.  File: TIPS, Node: Build new version of ITS, Previous: Build new version of SALV or NSALV, Up: Adding an additional disk, Next: Build new version of DSKDMP (optional) 1. Edit the file SYSTEM; CONFIG >. 2. Update the value of NQS to reflect number of packs. For a 1-pack system (default), NQS==1. If you are adding a second pack, change this to NQS==2. 3. Back up active ITS binary: :RENAME .;its bin,oits bin 4. Assemble a new ITS: :MIDAS dsk0:.;_system;its You will be asked for the machine name, and for a PiDP-10 this would again be KA.  File: TIPS, Node: Build new version of DSKDMP (optional), Previous: Build new version of ITS, Up: Adding an additional disk, Next: Shut down ITS 1. Edit the file SYSTEM; DSKDMP >. 2. Make sure that the value of NDSK is equal or greater than the total number of disks you have defined in ITS. 3. Back up active DSKDMP binary: :RENAME .;dskdmp bin,dskdmp obin Note that this command may fail, because some systems don't have a dskdmp bin file. This error can be ignored as we will be building a new dskdmp bin file next. 4. Reassemble DSKDMP: :MIDAS DSK0:.;_SYSTEM;DSKDMP Note that we will be presented with a request for "Configuration...". If your machine is using a standard configuration, you can choose it here. But for PiDP-10, choose ASK, which will ask a bunch of follow-up questions. The correct answers for the PiDP-10 are N for everything except the "Number of dirs?" question, which should be 500 plus a period (.). It is vital that we put a period immediately after the 500 because that makes it a base-10 number rather than a base-8 number.  File: TIPS, Node: Shut down ITS, Previous: Build new version of DSKDMP (optional), Up: Adding an additional disk, Next: Update emulator configuration for new disks 1. Logout all users except on system console. 2. On system console, invoke LOCK to shut the system down LOCK^K 5DOWN y ^C 3. Wait until ITS has shut down.  File: TIPS, Node: Update emulator configuration for new disks, Previous: Shut down ITS, Up: Adding an additional disk, Next: Boot SALV or NSALV This procedure is different for the various emulators used to boot ITS. For KLH10, update the dskdmp.ini file to add a new line similar to this one: devdef dskN rh0.N rp type=rp06 format=dbd9 path=rpN.dsk iodly=0 where the value N is replaced with the the disk number. For example, the default system contains a single line like this: devdef dsk0 rh0.0 rp type=rp06 format=dbd9 path=rp0.dsk iodly=0 If you are adding a single new disk, the resulting lines should look like this: devdef dsk0 rh0.0 rp type=rp06 format=dbd9 path=rp0.dsk iodly=0 devdef dsk1 rh0.1 rp type=rp06 format=dbd9 path=rp1.dsk iodly=0 Note that the PiDP-10 uses SIMH instead of KLH10. The rest of this section describes how to add the drives on PiDP-10. First, edit two files: /opt/pidp10/systems/its/boot.pi /opt/pidp10/systems/its/boot.pidp Search for a line containing dpa3 in those files, and add lines for however many additional disks you want below it. Assuming you want the maximum of 8 disks, you would add the following four lines: at dpa4 ./rp03.4 at dpa5 ./rp03.5 at dpa6 ./rp03.6 at dpa7 ./rp03.7 Next, stop and start SIMH so it sees those new definitions. Do this via: pdpcontrol stop pdpcontrol start There is one complication for PiDP-10. We need the disk headers to be writable in order to format the new disks, but ITS requires that the disk headers are write-protected when it is in normal operation. The way to deal with that is to interrupt SIMH and change the write-protect setting when needed. For now, we enable writing the headers as follows. Open the SIMH console by double-clicking the SIMH icon on the desktop. Type the following to make the headers writable: ^E set dpa headers continue where the first line is "control-E" (this interrupts SIMH).  File: TIPS, Node: Boot SALV or NSALV, Previous: Update emulator configuration for new disks, Up: Adding an additional disk, Next: Format new disk pack 1. Boot the old (or new) version of DSKDMP. On PiDP-10, this is done by pressing the STOP key followed by the READ IN key. 2. Invoke NSALV or SALV. a. For NSALV: l$ddt t$nsalv bin b. For SALV: l$ddt t$salv bin  File: TIPS, Node: Format new disk pack, Previous: Boot SALV or NSALV, Up: Adding an additional disk, Next: Copy user directories from first disk to new disk(s) 1. Make sure you are in DDT with NSALV or SALV loaded. 2. Format the new pack(s). DO NOT FORMAT THE OLD PACKS BECAUSE THAT WOULD DESTROY YOUR SYSTEM! If you are adding more than one new pack you will repeat the command below for each one. On PiDP-10, there are 4 old packs numbered 0 through 3, so the new pack(s) begin at #4. MARK$G You will be asked for the unit number. Answer with the new drive number. Again be careful not to format an existing pack. You will be asked if you are sure. Answer Y for yes, or N for no. You will be asked for the pack number. This can be the same as the drive number. On some systems you may be asked to verify the new pack. You can answer N. You will be asked for the swapping allocation. The typical answer is 3000 (without a decimal point). Finally, you will be asked for the pack ID. You could type a short name here, but for simplicity you can just use the drive number again. 3. After you have formatted all the new drives, check the format of all drives - you only need to do this once regardless of how many drives you are adding: CHKR$G You will be asked for the active unit numbers. For example, if you have units 0 through 5 you would enter 012345. Or, for all eight drives, you would enter 01234567. You will be asked for the unit that will provide the MFD. Answer 0. You will be asked if you want to read all the blocks from all files. This is fairly quick in most cases, so it is recommended that you answer Y. You will be asked which unit to get the user directories from. Answer 0. Finally, you will be asked if the changes should be written out. Answer Y.  File: TIPS, Node: Copy user directories from first disk to new disk(s), Previous: Format new disk pack, Up: Adding an additional disk, Next: Create new bootable ITS Make sure are in DDT with NSALV or SALV loaded in memory. Copy user directories from unit 0 to each of the new units, one at a time. For the PiDP-10, if you are adding four new drives, you will run this command four times. UCOP$G You will be asked for the "From Unit". Answer 0. You will be asked for the "Destination Unit". Answer with the number of the new drive. You will be asked to confirm. Answer Y. Note that in some cases no DDT prompt is provided at the end of UCOP. Just wait about 10 seconds. You can tell if you are back to DDT by typing a DDT command. For example: 0/ That should display the contents of location 0.  File: TIPS, Node: Create new bootable ITS, Previous: Copy user directories from first disk to new disk(s), Up: Adding an additional disk, Next: Boot new ITS 1. Make sure you are in DSKDMP. If you are at DDT, type: $U 2. Load DDT and ITS into memory: l$ddt t$its bin 3. Reenter DSKDMP. $U 4. Merge in NSALV or SALV a. For NSALV: m$nsalv bin b. For SALV: m$salv bin 5. Dump out its d$nits 6. If you are using a PiDP-10, you must write-protect the disk headers. To do that, open the SIMH console as described above. Type the following commands: ^E set dpa noheaders continue 7. Start ITS g$ 8. If ITS doesn't start, reenter DSKDMP: $U 9. And load and start the new ITS: nits $g 10. On some systems, the nits file will not be on the correct disk pack. DSKDMP by default only mounts drive 0, so the file may initially not be available. The file can be moved to the right pack from ITS. Login to ITS, and type the following: :cwd . ^F Find the entry for the file named @ its; this is the old copy of the system kernel. Note the first number on that line; this is the pack number. For PiDP-10, this will be a 2. Now find the line for the file named @ nits. If it is on the same pack as the @ its file, then you can skip the next step. If it is on a different pack then we must move it, using the following command: :move @ nits, dsk0: Again use ^F and verify that the pack number is now correct.  File: TIPS, Node: Boot new ITS, Previous: Create new bootable ITS, Up: Adding an additional disk 1. Make sure you are in DSKDMP. If you are at DDT, type: $U 2. Load and run ITS. nits $g 3. Note that the previous copy of ITS will no longer run. If you try, you will find that old ITS will examine the disk packs, find that they don't match what it expects, and will abort. Therefore, we might as well delete the old copy, and rename the one we just built: :cwd . :delete @ its :rename @ nits, @ its Make one final check that the file is still on the correct pack - it should be, but it is good to verify this. ^F