/* USAGE.TXT - KLH10 Usage Instructions */ /* $Id: usage.txt,v 2.4 2002/03/21 09:43:01 klh Exp $ */ /* Copyright © 1994-1999, 2001 Kenneth L. Harrenstien ** All Rights Reserved ** ** This file is part of the KLH10 Distribution. Use, modification, and ** re-distribution is permitted subject to the terms in the file ** named "LICENSE", which contains the full text of the legal notices ** and should always accompany this Distribution. */ This file provides basic pointers for KLH10 operation. See "install.txt" for information on KLH10 installation and configuration. KLH10 STARTUP: A KLH10 installation has several binaries; the one you want to start is normally called either "kn10-ks", "kn10-ks-its" or "kn10-kl" depending on the version you have built. These should all be installed in a KLH10 "home directory" and you should be connected to that directory (see the file "install.txt" if necessary). Then simply give the following shell command: % ./kn10-kl ; or ./kn10-ks or ./kn10-ks-its The KN10 process will start up, allocate and clear KN10 memory, and begin reading commands from the default file "klh10.ini". If you wish to use a different init file, you can specify it on the command line, for example: % ./kn10-kl test.ini ; Use "test.ini" instead of "klh10.ini" % ./kn10-kl /dev/null ; Use nothing Or you can simply edit or delete "klh10.ini" itself. KLH10 COMMAND PARSER: After starting the KN10 you will be talking to the command parser. This serves a function very similar to that of the RSX20F PARSER front-end program for a real KL10. However, the KLH10 commands are nothing like PARSER commands. For a list of the commands, see the files "cmdsum.txt" and "cmdref.txt". Normally the only reason you will be talking to the command parser is to get the KN10 configured, load a bootstrap program, and start it; from there on you interact only with the KN10. This can all be done automatically by commands in the "klh10.ini" file, and it is highly advisable to at least configure the KN10's devices this way, using the information in "install.txt". KLH10 BOOTSTRAPPING: KLH10 is capable of loading PDP-10 binary files directly into its KN10 memory with the "load" command; it uses the native OS filesystem as its "front-end filesystem", and does not require a special area on a virtual disk. Ordinarily you will use this capability to load a PDP-10 bootstrap program, which when started will then load either the TOPS-10 or TOPS-20 monitor. For example: KLH10> load boot.exe will load "boot.exe" from the native filesystem, producing this output: Using word format "c36"... Loaded "boot.exe": Format: DEC-CSAV Data: 4630, Symwds: 0, Low: 040000, High: 054641, Startaddress: 040000 Entvec: JRST (120 ST: 00, 124 RE: 00, 137 VR: 0,,0) KLH10> Once the bootstrap is loaded, you can start it by giving the "go" command: KLH10> go Starting KN10 at loc 040000... BOOT V11.0(315) BOOT> And from this point on, you are talking to the PDP-10 software, and the remaining procedures for bringing up the monitor should be the same as for a real system. In particular, typing CR should spur the bootstrap into loading and starting the default of MONITR.EXE. Note that there are two TOPS-20 boot programs included with the KLH10 distribution: "boot.exe" which boots from disk, and "mtboot.exe" which boots from tape. There is also a TOPS-10 boot program, "klboot.exe". These are exact copies of the Digital bootstraps by those names, provided only as a convenience to users who already have a TOPS-10 or TOPS-20 license. The details of a complete boot and filesystem rebuild from tape, using "mtboot.exe", are too intricate for a few paragraphs. Suffice to say here that once you get to the BOOT> prompt of MTBOOT, you can proceed just as for a real KL10, with the exception that building a "front-end filesystem" area is not necessary. See the file "klt20.txt" for an example of a TOPS-20 system installation. KLH10 COMMANDS vs KN10 EXECUTION: Previous KLH10 versions had no way to enter KLH10 commands without suspending KN10 execution. This is no longer the case, and there are now 3 principal modes of console input: [1] Simple command mode, prompt "KLH10>" (or "KLH10#" during init). The KN10 is halted. CTY input goes to the KLH10 command parser. CTY output is halted as the KN10 is halted. [2] Concurrent command mode, prompt "KLH10>>". The KN10 is running. CTY input goes to the KLH10 command parser. CTY output is accepted from the KN10. [3] CTY I/O mode, no prompt. The KN10 is running. CTY input/output goes to/from the KN10. The latter two modes are similar to the way a real KL system works, with its front-end PDP-11 independent of the KL10 CPU. In "simple" mode, the KLH10 is always doing only one of two things. It is either reading and executing KLH10 commands typed to it, or it is running the KN10 which is executing PDP-10 instructions. While the KLH10 parser is reading commands, nothing else is happening, and your typein is seen only by the parser. The KN10 does not run until you give an explicit command to start or resume execution. In "CTY" mode, the KN10 is running and your typein is seen only by the PDP-10, as CTY input. You can return to the KLH10 command parser at any time by typing the command escape character (^\, CONTROL-\, ASCII "FS", octal 034). This normally suspends KN10 execution and enters "simple" mode, but if the fe_runenable variable is "on" then it will enter "concurrent" mode. Control also returns to the command parser if the KN10 halts for any reason. STOPPING THE KN10: Normally, you will be running a PDP-10 monitor. Bring it down as you would for a real KL10, except that at the point where you type ^\ to return to the RSX20F PARSER, instead you are returned to the KLH10 command parser and the KN10 is stopped. You can give the "shutdown" command, which deposits -1 in location 30 and continues the KN10; this should cause the monitor to execute a HALT instruction, which returns control back to the KLH10 command parser. You can then give the "quit" command (which asks for confirmation) to leave the KLH10 program completely. This command performs essential cleanups of the various device processes and shared memory areas, and should always be done. Alternatively, if the monitor is wedged or you don't care about the PDP-10 filesystem consistency, you can blow everything away immediately by returning to the command parser with ^\ and using "quit" right away. A word about restarting. Although it may work to use "reset" and then load the PDP-10 bootstrap in order to restart a monitor without actually quitting the KLH10 program, this is not recommended; it is much safer to quit entirely and invoke the KLH10 again from scratch. IF THE KLH10 CRASHES: If the KLH10 process dies accidentally or is killed in any way other than via the "quit" command, then you will probably find some leftover device processes (DPs) littering your host system. If this happens, you can clean up as follows: Use the shell command "ps ax" (on Solaris, "ps -eaf") to find the processes. They will be called "dprpxx", "dptm03", or "dpni20". You will notice a -DPM:<#> argument to the DP; this identifies the shared memory segment ID it's using. Kill each DP with "kill " where is the process ID. Find the active shared memory segments with "ipcs". Those with segment IDs belonging to the killed processes (the numbers in the -DPM: args) must be flushed; use "ipcrm -m <#>" for each one. Yes, this is tedious, isn't it? Blame AT&T SYSV's moronic IPC facilities. And next time, use "quit" if you can... RUNNING THE KLH10 IN BACKGROUND MODE: As of V1.1 the emulator can now be run as a background process, which for example makes it possible to start it up automatically, without manual intervention, whenever the hardware system is rebooted. This feature is very simple but has the disadvantage that once the background process has started, you cannot talk to the emulator's CTY. The procedure is as follows: (1) Create a klh10.ini file for monitor auto-start, perhaps distinguishing it with a different filename such as klh10.ini-q. The exact details will vary depending on the monitor; for TOPS-20 an auto-start can be done as follows: KLH10>load boot.exe KLH10>dep 0 400000,,0 KLH10>go 40001 (2) Invoke the KLH10 using the "-background" switch and auto-start initialization file, with output redirected to a log file, and running in the background. Examples: Bourne Shell (/bin/sh): $ ./klh10 -background klh10.ini-q > logfile 2>&1 & C Shell (/bin/csh, /bin/tcsh, etc): % ./klh10 -background klh10.ini-q >& logfile & Note and remember the process ID that the shell prints out, for use when bringing the system/emulator down. In order to bring down the system and emulator when running in the background: (1) Bring down the monitor in the usual way (e.g. on TOPS-20 you would use the ^ECEASE command). (2) Find the process ID of the emulator if you didn't already note it, by using "ps". (3) Terminate the emulator by sending a SIGTERM signal, e.g. % kill This will attempt to perform a graceful shutdown of the OS by internally executing the SHUTDOWN command. Check the log file to make sure that everything went OK. This file simply records all output to the emulated CTY. If you wish to observe it while the emulator is running, do "tail -f logfile". Again, UNIX unfortunately provides no mechanism for re-attaching a terminal to a background process, so there is currently no way to provide input to the emulated CTY in this situation. Eventually this feature may be provided by a front-end daemon that can be connected to at will. USING VIRTUAL TAPES: A useful feature of the KLH10 is its "virtual tape" mechanism, which allows PDP-10 programs to believe they are reading and writing magtapes when in fact they are merely doing I/O to a disk file in the native filesystem. This is very fast and convenient. Unfortunately, the process of "mounting" and "unmounting" virtual tapes is not as convenient as it should be, and is the major interface quirk that remains to be fixed. What follows documents the current procedure, warts and all. This should be read in conjunction with the descriptions of DEVMOUNT and DEVUNMOUNT in the "cmdref.txt" file, as well as "vtape.txt" for further details. To CREATE a virtual tape, use the DEVMOUNT command with the name of a non-existent file and the parameter MODE=CREATE (or just "RW"; for the full list of parameters see cmdref.txt). When done writing and reading the tape, use DEVUNMOUNT to "unmount" it from the virtual drive and finalize the tape file(s). To READ an existing virtual tape, use DEVMOUNT with the filename of the existing tape file; it will default to MODE=READ which will make the drive appear to be write-locked. For safety, the tape code will not allow you to mount an existing virtual tape for writing (a mode known as "update"). If you try to do this, you will see something like the following: @[HALTED: FE interrupt] ; ^\ typed at T20 EXEC KLH10> devmount mta0 klhbackup rw ; Try to mount existing tape DPTM03: vmt_xmount: Tape file "klhbackup" already exists [dptm03: Couldn't mount read/write virtual tape: klhbackup] Mount requested: "klhbackup" KLH10> Note that the command parser doesn't have a clean way to know if the mount request succeeded or failed; it can only say that a request was made. Any failure or success reports come directly from the tape device. USING HARDWARE TAPES: The KLH10 has the capability of using physical ("hard") tape drives to read and write actual, not virtual, tapes. Normally a hard mount will be made at the time the tape device is first defined with DEVDEFINE, but it is also possible to use DEVMOUNT to change this later. Usage is the same as for virtual tapes, except that in the DEVMOUNT command, the option "hard" must be specified: @[HALTED: FE interrupt] KLH10> devmo mta0 /dev/rmt0a hard Mount requested: "/dev/rmt0a" KLH10> Do NOT use either the block (/dev/mt0a) or non-rewind (/dev/nrmt0a) forms of the physical device pathnames. No other options are recognized when "hard" is set; they will be ignored. In particular, "ro" has no effect, because the binding established by a hard mount is between the KN10 device and an external device, not between the KN10 and a particular tape. In order to write-lock physical types, you must use their physical write-lock mechanism. In general physical tapes can be loaded and unloaded from the drive manually and all should operate as if the drive was a real TU45, TU77, or whatever. My favorite example of this is the "UNLOAD" command in the TOPS-20 EXEC, which will eject the physical tape if the host system supports that capability. An error message will be printed if any problem is detected; for example, the following can happen if the drive is powered off: @[HALTED: FE interrupt] KLH10> devmo mta0 /dev/rmt0a hard Mount requested: "/dev/rmt0a" KLH10> [dptm03: Cannot mount device "/dev/rmt0a": I/O error] KLH10> When using hardware drives, there may be some lag between the time of physical events (like going offline or online) and the time the KN10 finds out about the new status. This is primarily due to the overly thick insulation that the native OS interposes between the KN10 and the actual hardware.