/* CMDREF.TXT - KLH10 Command Reference documentation
*/
/* $Id: cmdref.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.
*/

KLH10 COMMAND SYNTAX:

	The KLH10 command parser is extremely simple-minded, since
normally very little user interaction is needed.  In particular, it is
not intended to be a general-purpose debugger, although it does have
various commands to help debug the "hardware".

	Each command is one complete line, and command verbs need only
a unique initial substring.  Case is not significant anywhere in KLH10
commands, except for filenames that must be given to the native OS.

	The various parts of a command must be separated by spaces or
tabs.  The backslash (\) character can be used to quote the next
character, but if you think you need this, you are probably trying
something funny that may not work.  Lines cannot be continued with
backslash; just keep typing.


KLH10 COMMAND REFERENCE: (in ASCII lexical order)

^\, CONTROL-\, ASCII "FS"
	This is not exactly a KLH10 command; it is the command escape
	character, which can be typed anytime the KN10 is running
	in order to return to the KLH10 command parser.

	If "fe_runenable" is off (default) then ^\ will halt the
	KN10 immediately with the message:

		[HALTED: FE interrupt]
		KLH10>		; command prompt when "halted"

	But if "fe_runenable" is on, then ^\ will NOT halt the
	KN10.  Instead, it will give you a slightly different prompt:

	       KLH10>>		; command prompt when "running"

	Typing ^\ while in the command parser should have no effect,
	although this depends on the native OS.


1-STEP [<n>]
	Single-steps the KN10 by executing <n> instructions.  For debugging.
	<n> defaults to 1 if not specified.
	Most useful with TRACE-TOGGLE.


BREAKPT <addr>
	Set PC breakpoint to <addr>.  For debugging.

	Only one PC breakpoint can be set.  It does not modify memory
	in any way.  Use an <addr> of 0 to turn it off.
	Execution is slower when the PC breakpoint is active, so don't
	leave it on if you don't need it.

	Currently, only the in-section part of the address is significant
	(low 18 bits).  The KN10 will be stopped whenever the low 18 bits
	of PC match the specified value, whether the CPU is in user or
	exec mode.


CONTINUE
	Continues the KN10 at the current PC.
	This works whether the KN10 is halted or running, and returns
	the CTY back to the KN10 (ie leaves the command parser).
	This is the normal method of continuing after interrupting the
	KN10 with ^\.


DEPOSIT <addr> <value>
	Deposits the word value at the given address.  For debugging.
	See the description of the LOAD command for the format of <addr>.

	The <value> should be one or two octal constants of the form <RH>
	or <LH>,,<RH>.  Instruction mnemonics are not recognized, sorry.


DEV <devid> <device-command-line>
	Execute a device-dependent command.
	<devid> must be already defined by the DEVDEFINE command.
	This is provided as a way for device drivers, especially dynamically
	loaded ones, to accept arbitrary commands if they wish to do so.
	No current driver uses this.


DEVDEBUG [<devid> [<debugval>]]
	Set or show device debug values.
	DEVDEBUG		- Shows values for all known devices.
	DEVDEBUG <devid>	- Shows value for that device.
	DEVDEBUG <devid> 0	- Turns off debug tracing for device.
	DEVDEBUG <devid> 1	- Turns on basic debug tracing for device.
	DEVDEBUG <devid> 3	- May turn on verbose tracing for device.

	<devid> must be already defined by the DEVDEFINE command.
	Each device may have a different interpretation of a non-zero
	debug value.  In general, when debug tracing is turned on, activity
	on that device will cause messages to be printed on the standard
	error stream, which is normally the KLH10 CTY.

	Note that devices may output error messages at any time whether or
	not debug tracing is in effect.


DEVDEFINE <new-devid> <dev#> <driver> <optional-parameters>
	Define, bind, and initialize a KN10 device or controller unit.
	See the file "install.txt" for more details.

    <devid> - A short (6-character) name of your choice to
	uniquely identify this device.  Examples might be
	dsk0, dsk1, mta0, etc.  These names are meaningful
	only to you; the KLH10 doesn't care, nor are they
	passed to the KN10 in any way.

	The <devid> is how you can refer to the device
	when using other KLH10 commands such as DEVMOUNT.

    <dev#> - The KN10 device number you are binding.
	For all machines but the KS10, this is normally
	an octal device number such as would be used in
	I/O instructions (DATAI/DATAO, etc).  For example,
	use 200 for DTE#0, 540 for RH20 #0, and so on.

	The <dev#> is how the KN10 can refer to the device.

    <drivername> - Specifies what the device actually is, by
	identifying the "emulator driver" you are binding
	this device to.  The driver is a software module that
	is invoked to support all references to the device,
	whether from you or from the KN10.

	Giving the "devshow" command will list all of the known
	drivers (currently DTE, RH20, RP, TM03, NI20).  External
	(dynamically linked) drivers are supported but untested;
	see the "devload" command.

    <optional-parameters> - Various parameters specific to the
	device driver type, usually optional.  Their syntax is
	normally of the form <keyword>=<value>, but sometimes
	just the <keyword> is sufficient.
	The ordering of these parameters does not matter; nor
	does the case of the keywords.

    NOTE!!!  There is currently no way to undefine a device.
	Once defined, a <devid> lasts until the user quits the KLH10.


DEVEVSHOW [<devid>]
	Show device event registration info.  Primarily for debugging.
	<devid> must be already defined by the DEVDEFINE command.

DEVLOAD <new-drivername> <path> <initsym> <comments>
	Load a DLL device driver.
	This command allows device emulator drivers to be loaded dynamically
	at runtime rather than being linked into the KLH10 binary at
	compile time.
	Warning: This almost certainly WILL NOT WORK yet for your platform.
	It is intended to provide a way for people to write their own
	device emulator drivers independently of those provided
	or built into the KN10.


DEVMOUNT <devid> <path> [<options>]
	Mount device media.
	<devid> must be already defined by the DEVDEFINE command.
	<options> are device dependent.

	Note that this command can only make a polite request to the device,
	which may respond with a failure message.  If the device is busy,
	the request may be ignored immediately with an error message; try again
	later.  Any currently mounted media will be automatically unmounted,
	but it's best to explicitly DEVUNMOUNT a device before trying
	to DEVMOUNT something on it.

	DEVMOUNT is used primarily for mounting virtual tapes on the
	TM02/TM03 driver, although it is intended to work for disks as well.

	The options for the TM02/TM03 depend on whether you are mounting
	a virtual tape or a physical tape drive.

	For a physical drive, you must specify:
	    HARD	   - <path> is a physical tape drive.  No other
				options will be recognized, not even RO.

	If HARD is not specified, a virtual tape is assumed.
	For virtual tapes, there are several options:

	    FMT=<format>   - Tape format (RAW, TPS, TPC, etc; see vtape.txt)
	    MODE=<mode>    - One of READ, CREATE, or UPDATE.
	    FSKIP=<#>	   - Skip <#> files/tapemarks when mounted.
	    UNZIP[=<bool>] - TRUE to allow uncompression if <path> suggests it.
	plus for convenience:
	    RO, READ       - same as MODE=READ (read-only)
	    RW, CREATE     - same as MODE=CREATE
	    UPDATE         - same as MODE=UPDATE
	and for debugging:
	    DEBUG[=<bool>] - TRUE for debug output from vmtape.
	    PATH=<path>    - Overrides command <path>
	    CPATH=<path>   - Overrides control path derivation
	    RPATH=<path>   - Overrides data (raw) path derivation

	The normal defaults are now FMT=TPS and MODE=READ.
	(Formerly they were RAW and RW)

    Example:
	@assign mta0:				; At T20 EXEC
	@i dev
	Devices assigned to/opened by this job: MTA0, TTY105
	@[HALTED: FE interrupt]			; ^\ typed here
	KLH10> devmo mta0 mybackup create	; Mount virtual R/W tape
	Mount requested: "mybackup"		; Request sent to device
	KLH10> [mta0: Tape online]		; Asynch response looks OK  
						; (Typed CR for fresh prompt)
	KLH10> c				; Continue KN10
	Continuing KN10 at loc 01117513...
	
	@dumper					; Back at T20 EXEC
	DUMPER>tape mta0:
	DUMPER>save ps:<KLH>*.*.* (AS) 
		[...etc...]

	Note in the above example that the <devid> "mta0" only happens to
	look like the TOPS-20 device designator "mta0:" because a KLH10
	DEVDEFINE command at startup defined it thusly for convenience.
	Don't confuse them.


DEVSHOW [<devid>]
	Show information about device definitions.
	<devid> must be already defined by the DEVDEFINE command.
	If no device is specified, all are shown; this can be useful.

	If a <devid> is specified, it is queried for whatever information
	it wants to show.  Currently none show anything, so this form isn't
	very interesting.


DEVUNMOUNT <devid>
	Unmount device media.
	<devid> must be already defined by the DEVDEFINE command.
	This is particularly useful for magtape devices, but is intended
	to also work for disks someday.

	IMPORTANT!  This command, like DEVMOUNT, can only make a polite
	request to the device.
	If the device is busy, the request is ignored immediately
	with an error message; try again later.

    Example:
	DUMPER>quit				; Leaving T20 DUMPER pgm
	@[HALTED: FE interrupt]			; ^\ typed at T20 EXEC
	KLH10> devunmount mta0			; KLH10 cmd given
	Unmount requested			; Request looks OK
	KLH10> c				; Continue KN10
	Continuing KN10 at loc 01117511...
	
	@					; Back at T20 EXEC


DEVWAIT [<devid>] [<secs>]
	Waits until device sub-process(es) are ready to accept new
	requests.

	If <devid> is specified, only that device is waited for.
	    Otherwise, all devices are waited for.

	If <secs> is specified, the command will only wait for that
	    many seconds.  Otherwise, it waits indefinitely.
	
	This is primarily intended for use in startup scripts, before
	(or after) a mount or unmount request is made to a disk or
	magtape device.  It ensures that further commands are not
	executed until the devices are ready for them.
	The likelihood that this will ever be needed is small, but
	the command exists anyway.


DUMP <file>
	Dump binary from KN10 memory into a native OS file.  This is the
	inverse of LOAD.
	Only the first 256K of memory is dumped; the data-format used is
	the same as the current LD_FMT setting, and the load-format is SAV.
	Zero words are not written out.


EXAMINE [<addr>]
	Show word at address.  For debugging.
	Sets the current location ("dot") to the specified address; if no
	address is given, the current location is used.
	The PDP-10 word value is printed out.  If it appears to be a
	valid PDP-10 instruction, it is shown in instruction format as well.

	The <addr> may be "local" or "global"; if in the form <LH>,,<RH>
	it is assumed to be global.  This can be specified explicitly by
	prefixing the address with either of the letters:
		L	- Address is "local" (relative to some section)
		G	- Address is "global"

	The <addr> can also be prefixed with one of the following letters
	to specify the memory mapping to use:
		C	- Current mode's memory map (the default)
		E	- Exec mode memory map
		U	- User mode memory map
		P	- Physical address
		A	- AC address, interpreted as <AC block #>,,<AC>

	Not all combinations are meaningful in all situations.
	EXAMINE is always safe; you cannot cause a page fault with
	an EXAMINE reference.  "??" will be printed if no mapping exists.


GO [<addr>]
	Start KN10 at address.
	Ignores the current PC and sets it to the address, if one is given.
	If no address is given, the start address from the most recent
	"load" command is used.

    Example:
	KLH10> go
	Starting KN10 at loc 040000...

	BOOT V11.0(315)

	BOOT>


HALT
	Halt KN10 immediately if running.


HELP [<cmd>]
	HELP			- Shows brief help for all commands.
	HELP <cmdprefix>	- Same for all matching commands.

	The HELP command is intended more for remembering commands than
	for documenting them, so don't expect much.  Keep this reference
	file handy.


LOAD <file>
	Load binary into KN10, sets start-addr if specified by file.
	This is how a PDP-10 bootstrap is initially loaded.  The KLH10
	uses the native OS filesystem as its "front-end" filesystem and
	can load any required bootstrap directly from ordinary files.

	The binary file must, of course, be formatted correctly with
	respect to both its data-format (how PDP-10 words are stored in
	8-bit bytes) and its load-format (typically EXE).

	The default data-format is core-dump, "c36" ("u36" for KSITS version).
	This can be changed with the command SET LD_FMT=<fmt> if necessary.

	Provided the selected data-format correctly matches that of the file,
	LOAD is able to determine the load-format automatically (SBLK, SAV,
	EXE) and determine the start address of the program.  However, if
	the data-format is wrong, LOAD will blindly load garbage; check
	to see if the start address it reports looks reasonable.

    Example:
	KLH10> load boot.sav
	Using word format "c36"...
	Loaded "boot.sav":
	Format: DEC-CSAV
	Data: 4632, Symwds: 0, Low: 040000, High: 054641, Startaddress: 040000
	Entvec: JRST (120 ST: 00, 124 RE: 00, 137 VR: 0,,0)
	KLH10>


NEXT-EXAMINE
	Show next word, for debugging.
	Increments the current location ("dot") by 1 and then does "examine".


PROCEED
	Similar to CONTINUE, but does not return the CTY to the KN10;
	the command parser remains active.


QUIT
	Quit emulator.  Asks for confirmation, since this kills the
	program entirely.  You should never kill or exit a KLH10
	process except with QUIT, or there will be a lot of leftover
	subprocesses and memory segments littering the native system.

	For an example, see the SHUTDOWN command.  You don't have to
	use SHUTDOWN prior to QUIT if you don't care about stopping your
	PDP-10 monitor gracefully.


RESET
	Reset KN10.  For debugging.


SET [<var>[=<val>]]
	Set/show KLH10 variables, primarily for debugging.

	SET		- Shows all known variables
	SET <var>	- Shows value of that variable
	SET <var>=<val> - Sets variable to specified value.  No spaces!

	Showing all known variables produces a long list; most of that
	information is of use only when debugging.  The variables
	that a user might plausibly want to set follow below.

SET FE_RUNENABLE=<boolean>	- Set desired handling of ^\
	Defaults to OFF, which means that ^\ halts the KN10 before
	returning to the command parser ("simple" input mode).
	If set to ON, ^\ will still return to the command parser but
	will keep the KN10 running ("concurrent" input mode).


SET SW=<word-value>	- Set KN10 data switches
	This is sometimes needed for diagnostics or bootstrap loaders,
	which read the data switches as a crude form of input.
	Example:
	    KLH10> set sw=20
	       sw: 0,,0  =>  0,,20
	    KLH10>

SET LD_FMT=<data-format> - Set data-format for LOAD/DUMP
	LD_FMT is a bit of a misnomer; it may be renamed.  It actually
	refers to the data format.
	The data format specifies how 36-bit words are read from or
	written into a sequence of 8-bit bytes.  When 9-track tape drives
	were introduced a variety of formats were created to address this
	issue, and these formats have all been provided as options
	for KLH10 I/O as well.
	    C36	- "Core-Dump"	 - Default.
	    H36 - "High-Density" - Most compact format, same as FTP Image.
	    A36 - "Ansi-Ascii"	 - Weird handling of low bit.
	    S36 - "SIXBIT"	 - used for 7-track tapes.
	    U36 - "Unixified"	 - Alan Bawden's archival format
	See "Tape Formats" in VTAPE.TXT for more details.

SET MEM_LOCK=<boolean>	- Set "ON" to lock emulator in memory
	If set TRUE, the emulator and all of its subprocesses call
	mlockall() to ensure that none of them are ever swapped out.
	You must be running the emulator as root for this to do anything.
	If used, this should be set prior to defining any devices.

	This results in locking down about 34M of RAM (6M for a KS10)
	so the overall system should have at least 64M and preferably more.

	!!! WARNING: there is a kernel bug in Digital Unix (up to at
	least version 4.0B) which can cause the entire system to eventually
	hang up when mlockall() is used in this way.  It's unclear whether this
	has been (or will be) fixed in 4.0D or later versions.
	Solaris does not suffer from this problem.
	FreeBSD does not implement mlockall().


SET PROC_PRI=<pri>	- Set to increase emulator process priority
	The PROC_PRI parameter gives its argument to the setpriority()
	call; the valid values range from -20 (highest priority) to 20 (lowest
	priority).  You may need to experiment with this setting to find the
	value that gives you the best combination of emulator and general Unix
	system response; I suggest starting with -10.
	You must be running the emulator as root for this to do anything.

	Note that the DPNI20 subprocess always runs at -20 to ensure
	fast network response; to avoid interfering with this, you should not
	set PROC_PRI to its "maximum" of -20.  -19 is quite enough to give the
	emulator so much priority that all other Unix system processes are
	noticeably slower.


SET CLK_ITHZFIX=<hz>	- Set to specify interval timer clock resolution
	The CLK_ITHZFIX parameter fixes the KN10 clock tick rate in
	Hz (ie ticks per second).  This originally defaulted to 30Hz as a
	compromise designed to allow the emulator to run on slower hardware
	platforms without spending all its time processing clock interrupts.
	However, faster platforms can now handle the full clock rate that
	TOPS-10 or TOPS-20 expects, so the default is now 60Hz.  You have the
	option of changing this parameter to either enforce a different rate,
	or (by setting it to 0) allowing the monitor to change the rate as it
	pleases.
	Recommendations:
	- If running on slow hardware you may need to set this back
		to 30 in order to get useful work done, regardless of
		the PDP-10 system being used.
	- For stand-alone processor diagnostics, set (or leave) this at 60.
		This is particularly true for the DFKFB timing test.
	- For ITS set (or leave) this at 60.  This is the normal clock rate.
	- For TOPS-20 try setting this to 0.  The monitor's desired
		rate is 1000 and system response on a fast machine may
		improve since the scheduler will be invoked much more often
		and its overall behavior will be closer to that of a real KL10.
		If things seem slower, use a smaller value like 100 or 60.
	- For TOPS-10 set (or leave) this at 60.  This is the monitor's
		normal clock rate, and it is NOT recommended to let it
		free-run with 0.
		The reason is that the TOPS-10 monitor twiddles the interval
		incessantly in a futile attempt to compensate for what it
		thinks are deviations when compared to the real-time base
		clock.  "Fixing" the rate at 60 keeps it stable.

SHUTDOWN
	Halt OS gracefully.
	This only works with a moderately healthy PDP-10 monitor.  It
	deposits -1 into location 30 and continues the KN10.  The monitor
	is supposed to notice this, carry out final shutdown operations, and
	then execute a HALT instruction, which returns control to the
	KLH10 command loop.

    Example:
	Shutdown complete			; Printed by PDP-10 OS
	[HALTED: FE interrupt]			; ^\ typed to get FE int
	KLH10> shutdown				; Now can give SHUTDOWN cmd
	Continuing KN10 at loc 01117511...
	**HALTED**
	[HALTED: Program Halt, PC = 1120252]
	KLH10> quit				; Now give QUIT to leave KLH10
	Are you sure you want to quit? [Confirm]
	Shutting down...Bye!
	%


TRACE-TOGGLE
	Toggle execution trace printout.  For debugging.


VIEW
	View KN10 status (PC, etc).  Primarily for debugging, but
	harmless for the curious.

    Example:
	KLH10> view
	KN10 status: EXEC
	  PC: 1117506  [JPC: 1117513  UJPC: 30144  EJPC: 6126407]
	  Flags: 704040
	Next: OCcID  1117506/ SKIPE 333013      333013/ 0
	KLH10>

	A little explanation: the JPC is the PC of the last jump instruction.
	UJPC and EJPC hold the JPC as of the last transition out of user
	or exec mode, respectively.  The flags are the left-half PC flags;
	the "Next:" line shows the next instruction that will be executed
	when the KN10 is continued.


ZERO
	Zero the first 256K of memory.  For debugging.


^-EXAMINE
	Show previous word, for debugging.
	Decrements the current location ("dot") by 1 and then does "examine".
