From 48b8b4a019cc2b1311002c99dda71188cc6dec02 Mon Sep 17 00:00:00 2001 From: Eric Swenson Date: Mon, 12 Aug 2019 11:09:41 -0700 Subject: [PATCH] Resolves: #1468. Adds INFO topic Tips that includes various tips on using and administering ITS, including one on how to debug OJB devices. --- doc/info/{dir.230 => dir.231} | 1 + doc/info/tips.1 | 241 ++++++++++++++++++++++++++++++++++ 2 files changed, 242 insertions(+) rename doc/info/{dir.230 => dir.231} (99%) create mode 100644 doc/info/tips.1 diff --git a/doc/info/dir.230 b/doc/info/dir.231 similarity index 99% rename from doc/info/dir.230 rename to doc/info/dir.231 index 3a3b3096..22b15e1a 100755 --- a/doc/info/dir.230 +++ b/doc/info/dir.231 @@ -24,6 +24,7 @@ File: DIR Node: Top This is the top of the INFO tree * ITS: ITS * Simulators:: * Other:: +* Tips: (info;tips >)Top General information programs: diff --git a/doc/info/tips.1 b/doc/info/tips.1 new file mode 100644 index 00000000..37bad8af --- /dev/null +++ b/doc/info/tips.1 @@ -0,0 +1,241 @@ +-*-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 + + +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 + +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. +