PDP-10.its/doc/_info_/decuuo.order

This file documents the DEC system emulator DECUUO.

DECUUO is a TOPS-10 emulator for the I.T.S. monitor.  It
is loaded in core along with a standard DEC program.  It will
trap on a DEC MUUO and do the necessary equivalent for I.T.S.
In general, DECUUO should be invisible to the emulated program.
DECUUO has the capacity to emulate DEC TOPS-10 version 6.02 and
the Stanford operating system.

1) HOW TO INVOKE THE DEC EMULATOR.

To emulate the program in a particular file, say

	:DEC <file>

To emulate a program which has been dumped out with a emulator
bootstrap, just load and start it.

Running any of the following programs: D, PC, WL, NODIPS, DPLT,
or PCPLT actually runs the emulator, which, on noticing that its
JNAME is one of the above, loads and emulates the appropriate
program from a file whose name is assembled into the emulator.
This is the old-fashioned way of doing what should now be done
with the bootstrap.

2) MODE SWITCHES

The emulator has several mode switches, that specify these two
types of option:

	(1)	What type of system or terminal to emulate, and
	(2)	Auxiliary services to the user.

The switches of the first sort are:

/DEC	emulate the DEC TOPS-10 system.  This is the default.
/SAIL	emulate the Stanford system.
/III	emulate a Stanford III terminal's display processing.
	 Makes sense only when /SAIL is specified.
/META	emulate Stanford's CONTROL and META bits on input.
	 On ITS terminals which have that feature, the extra
	 bits are passed right to the emulated program.  On
	 other ITS terminals, the characters ^B, ^C and ^F
	 are prefixes meaning CONTROL, META and CONTROL-META.
/FN2	emulate an altered DEC or Stanford system which
	 allows both filenames to have six characters, instead
	 of the three that the real DEC system allows.  There is
	 no such system in reality, but some programs have
	 been "converted" to ITS by making them read in full-word
	 filenames;  they are then emulated with this switch so
	 that the full-word filenames will be handed to ITS.
/SDIS	Is synonymous with /SAIL/III/META/MAP
/PRSV	Prevents EXIT 0, from killing the job.  This differs from
	 what happens when a program named LINK or LOADER is run
	 (EXIT 0, does not kill a job that has run a loader) in
	 that this switch is saved by the bootstrap while the
	 LINK/LOADER run condition is not.

The switches of the second type are:

/MAP	Map input characters according to the physical
	 correspondence between the Stanford keyboard and the
	 TV keyboard.  With this switch set, a TV key in a
	 particular place will have the same effect in the
	 emulator as the key in that same place on the Stanford
	 keyboard would have on the same program running at SAIL,
	 even if those two keys would have unrelated graphics
	 printed on them.  This feature is useful with programs
	 which try, at Stanford, to use physically adjacent keys
	 for related functions.
/DBUG	Stop in DDT after loading the program, before starting it.
	 The PC will be the emulated program's start address.
/SYMS	Pass the symbol table from the loaded file up to DDT.
	 This is the ITS-style symbol table of an ITS-format
	 binary file, not the DEC-style in-core symbol table
	 which need not be present.  See 5) for how to give an
	 in-core symbol table to DDT.

When the emulator is invoked by ":DEC", switches should be put
after the name of the file, preceded by slashes as shown above.
It doesn't work to put switches anywhere but at the end of the
command string.

When the emulator is loaded by a bootstrap, the switch settings
are set according to the bits in a word in the core image.
See 4).

When the emulator is invoked by running a specially-known program,
the emulator knows from a table what switches are appropriate.

3) FEATURE TEST SWITCHES

When a feature of the DEC system has no equivalent or is irrelevant
under ITS, it may not be clear whether an attempt to use it
should be ignored, reported to the user with an error message, or
reported to the program as a "This system call not implemented"
error.  Several parameters, often corresponding to DEC's "feature
test switches" which determine which features are implemented,
are used to control those choices.  Setting one of these parameters
to zero requests emulation of a system in which some feature is
not implemented;  the emulated program's attempts to use it are
reported to it as success or failure of the system call, but have
no other effect.  Setting the parameter nonzero requests emulation
of a system in which the feature is implemented;  attempts to use
the feature will either work properly or cause an error message.
For example, FTTMP controls the existence of the TMPCOR UUO.  If it
is 0, a system that does not have TMPCOR is emulated (which will
tell the program the file is not found on reading, and that zero
words are free on writing).  If it is -1, an attempt to use TMPCOR
will cause a "Simulator Deficiency Encountered" error message to be
printed.  Since most DEC programs that use TMPCOR win by writing a
temporary disk file if the TMPCOR fails, the normal setting for this
switch is 0.

To set these switches, it is necessary to have the emulator's symbols.
A full list of them is on page 7 of the source, MC:DECSYS;DECUUO >.

4) THE BOOTSTRAP

The emulator bootstrap is a program which lives in the job data
area whose purpose is to load in the emulator.  The emulator
inserts a bootstrap quite frequently into the emulated program;
in particular, after doing an F command there will be one.
A bootstrap can also be found in DECSYS;DECBOT BIN, so doing
$$1L DECSYS;DECBOT BIN will merge a bootstrap in with any program.
This will make the starting address point at the bootstrap, so the
REAL starting address should be placed in the RH of .JBSA first.
The F and D commands take care of that automatically.
The switch settings desired for the program should be expressed as
bits in the RH of the "switch word", location 56 (octal).
Each switch has a corresponding bit which causes it to be set;
their names are DECBT, IIIBT, METABT, etc.  Normally, there is no
need to worry about them, since the F and D commands set the bits
according to the switches that are in effect (with the exception of
/SYMS and /DBUG;  F and D leave the bits for those switches OFF
even if the switches were set.  That way, you can :DEC a file with
/DBUG /SYMS and other switches, then dump out after a D, all to
create a new file just like the old one but with the switch bits
set to whatever you specified).  The /PRSV switch is handled specially;
it will be set iff the program name (DEC-style) is LOADER or LINK,
or if the switch was explicitly turned on in the command string.
If PRSV was set by running the loader, that will not cause it to go
into the bootstrap - if it did, it would be hard to load any program
without having PRSV set.
For the sake of programs that must be run with specific feature-test
switch settings, the LH of the switch word, if nonzero, is taken to
point at a subroutine to initialize variables.  It will be called
(with a JSR) when DECUUO is bootstrapped.  That subroutine may
be patched in with DDT after loading DECUUO with symbols;  then
a D command may be done to replace the symbols with the program's
and prepare to dump.  F and D do not change the LH of the switch
word.
Note, however, that in the long run it is best for the emulator
to be made to work properly, so whenever something like this is
necessary always report precisely what and why with :BUG DECUUO.

5) SYSTEM COMMANDS

To issue a system command, do

	45$G

and then type the command character, which should be one of

S	Pass up to DDT the DEC-style in-core symbol table,
	 throwing away any symbols DDT has for this job.

F	Flush the emulator from core, leaving only the
	 emulated program.  Also, insert a bootstrap and set
	 the job's starting address to point to it.  The
	 current switch settings are remembered in the bootstrap
	 so that they will be copied into the emulator when it
	 is reloaded.

V	fill the Vestigial job data area with what it's supposed
	 to contain.  After doing this, 400000$,577777$0Y may be
	 done in HACTRN to dump a DEC-format SHR or HGH file.  Note
	 however that if there is any data in the low segment, there
	 has to be a DEC-style zero-compressed LOW or SAV file.
	 To make such a file, do 0$,377777$0Y <filename> XPN
	 which will make an "expanded file".  Then do :DEC SYS:FILEX
	 which runs the DEC FILEX (FILe EXpander) CUSP, and type
	 <filename>.SAV=<filename>.XPN to it, using appropriate
	 filenames and extensions.  Generally, the low segment to
	 a SHR or HGH file is called a LOW file, and a low segment
	 without a high segment is called a SAV file.

P	Purifies the high segment.  Useful if you really think more
	 than one person might ever use the program at once.
	 Does an automatic V (since afterward V is impossible).

D	prepare for Dumping.  Does S, V, P and F (omits the V, P
	 if there's no high segment).

R	Reenter the program - just like the DEC REENTER command.

N	No-op - simply finishes up a UUO if necessary.  Useful if
	 debugging and you ^Z'd the program while it was doing a
	 UUO.

H	Help.  Types out a help cruft.

?	Types out a list of commands.

If a system command is issued while the program is executing a
emulated UUO, the UUO must be either finished or backed out of.
DECUUO knows now how to back only out of TYI wait, so in all
other cases it will print "Finishing up a UUO first..." and
then complete the UUO before saying "Command: ".  DECUUO will
complain about any attempt to issue a system commands while
an ITS interrupt is being handled, but nothing will have been
clobbered.

6) THE DECSYS DIRECTORY

When emulated programs refer to the SYS device, they do not
access the ITS SYS device, since the ITS system programs are
probably not what they want.  Instead, they access the directory
DECSYS, which is intended to have on it all the files that
any DEC system "ought" to have on SYS, such as DDT.REL, JOBDAT.REL, ...
Also, bootstrapped ITS binaries of DEC system programs go there
so that RUN UUOs referring to SYS will find them, even though their
main use may be via ^K.

8) THE INTERFACE BETWEEN THE emulATED PROGRAM AND ITS.

 A) Up to 5 ^C's are removed from the end of any file read in
    ASCII or ASCII LINE mode.  Trailing nulls are changed to
    ^C's in the last word of any file written in one of those modes.

 B) Type-in Conventions:
    If /META is off, the conventions are that ^O and ^S both
    complement output-suppression, ^U clears the input buffer,
    rubout deletes one character, ^C causes a return to HACTRN
    if read by a TTCALL, but causes EOF on the TTY if the TTY
    is in use as a device.  ^Z (quoted by ^_) is read as ^Z
    by a TTCALL, but is EOF when the TTY is in use as a device.

    If /META is on, only rubout has its special meaning.  That
    is because at SAIL, on display terminals, the rest of those
    functions are generally placed on other characters, some of
    which could be handled by DECUUO if there is a demand.

    RESCAN attempts to read JCL, unless the program was run by
    :DEC ..., since in that case the JCL was intended for DECUUO
    and would only confuse the emulated program.  The JCL, if
    any, is put into the type-in buffer.

 C) Conventions dealing with DSK and other directory devices.

    A null FN2 is allowed on the DEC system.  DECUUO translates
    it into ">".

    In its normal mode, DECUUO allows one level of SFD to be
    specified in paths.  To find a file in an SFD, DECUUO looks
    in the ITS directory with the same name (on the specified
    device).  The PPN specified is totally ignored in that case.
    If there is no SFD spec'd, the PPN is used as the directory
    name.  In that case, the PPN must be the expression, as two
    right-justified octal halfwords, of the SIXBIT of the directory
    name (in other words, their standard representations in machine
    words must be equal).  Some newer DEC programs can handle "SIXBIT
    PPN's", in which case this crock is unnecessary.

    An ITS UFD may be read in with the file name -FILE- and any
    extension.  An MFD may be read with the file name M-F-D-.

 D) Job numbers and other jobs.

    If the emulated program tries to read its job number,
    its ITS job number is returned.
    If it tries to refer to a job by number, the job's own
    number is acceptable.  Any other argument which the DEC system
    would treat as the number of another job will either be held
    to provoke a deficiency or will return the information that
    the job does not exist, according to the setting of ZJOBS.

 E) Device names TTYnn will be translated into Tnn, thus allowing
    other terminals to be accessed using the same device names
    as are used on the DEC system.  Device MTA is translated into
    MT0.  No other device name (except SYS) is translated.
    ITS filename translations do work, of course;  if just a device
    name is translated then DECUUO will even manage to report to
    the emulated program that the translated device name is a
    logical name, and supply the physical one.

 F) RUN and GETSEG.

    The RUN and GETSEG UUOs work using the same algorithm as on the
    DEC system, looking for files named SHR, HGH, SAV or LOW,
    with the extension that BIN is also looked up for low segment
    files, and HBIN is looked at for high segment files.
    The file format is determined from the file name:
    SHR or HGH implies a DEC high segment file,
    SAV or LOW implies a DEC low segment file,
    anything else is assumed to be an ITS format binary file.
    It is possible for an ITS binary file loaded expecting it to
    contain a low segment only, to contain actually two segments;
    DECUUO will recognize this.  However, the file must be a PDUMPed
    file, so that it will leave a gap between the segments when loaded;
    otherwise, DECUUO will think it is one long low segment.
    Because of this, the only reason to have an HBIN file is so that
    a GETSEG (which tries only SHR, HGH and HBIN) can load it.
    An HBIN file must not load anything into the low segment part
    of the address space, or DECUUO will be very confused;  this is
    your responsibility.  An ITS binary file that loads into the
    AC's can also cause trouble.  No "real" DEC program loads or
    dumps ANYTHING below .JBPFI (location 114), and DECUUO assumes
    this rule will be followed.

    It is possible to have both a high segment file (SHR, HGH or HBIN),
    and a "low segment" ITS binary file that really contains both
    segments, without confusing DECUUO.  It will just cause the high
    segment to be loaded twice by a RUN UUO.  The utility of this is
    that a link TS MUMBLE can be made to the "low segment" file
    and then the program can be run successfully with either
    MUMBLE^K  or  :DEC MUMBLE  or a RUN UUO or a GETSEG.

8) DEFICIENCIES IN DECUUO.
("not supported" without qualification means that a "Simulator Deficiency"
error message results, at least with the F.T. switches in their normal
settings)

Update mode I/O is not supported.  It is very difficult to do in ITS.

Some data modes are not supported (for example, image mode on
terminals and paper tape).  IONEOU is equivalent to OUTCHR.

The Stanford features are far from being completely implemented.
Random UUO's and fixes will be implemented for the SAIL stuff as the
need arises.

High segments that do not start at 400000 (because the low segment
is longer than 400000) are not supported.  High segments longer than
64K are not supported, but with a little effort that figure could
be improved.  REMAP is not supported when the low segment is longer
than 128K.

DDTIN, TMPCOR, TRMOP., TAPOP., and FILOP. are not supported.  Since
currently emulated software uses TMPCOR and TRMOP., those two will
give the error return, unless an F.T. switch is set to act otherwise.
Eventually all of these will be implemented, with the possible
exception of DDTIN, since it is scheduled to be flushed from the DEC
system anyway.

All CALLIs connected with the MPX device, the software PI system,
the enqueuing facility, and the Interprocessor Communications facility
are not supported.  Since the enqueueing facility and IPCF involve
another job, they return "job non-existant".  No attempt is made to
handle privileged system calls; normally they return the appropriate
failure for being a non-privileged program, but an F.T. switch can
make them complain.

A few GETTABs are not supported, though many would be easy to handle
if there were a demand.  Normally, the unsupported ones complain,
but an F.T. switch can make them claim not to be implemented in this
"monitor".

SEEK, DISK., WAIT, UTPCLR, LOCATE, WHERE, WAKE, DAEMON, UNLOK., PAGE.,
NODE. are no-ops.  Either the UUO is meaningless under I.T.S., or its
failure is not noticeable by the emulated program.  A reasonable DEC
program will allow for failure of these UUO's.

Turning on UU.AIO, UU.DER, UU.DEL is not supported.  UU.AIO
complains;  the others are normally ignored.

60-cycle clock interrupts (AP.CLK) are not supported.

Setting a file's protection or its creation date is not supported,
but in the normal mode it will be ignored rather than barfed at.
The data mode returned by a LOOKUP or ENTER will be the one in
which the channel is initted;  there is no way in ITS to remember
that information, and unfortunately no way to tell whether the
program is being screwed by that lack.

ENTERing an SFD will fail with ERLVL% (the maximum SFD nesting level is
0).  Setting the additional library (LIB:) for LOOKUPs (with a PATH.)
is not supported.

Extended LOOKUPs, ENTERs and RENAMEs with arguments in the AC's
are not supported.

The "universal time/date standard" is not supported.  LOOKUPs return
zero (or may be set to complain).  The GETTABs that return a value
in the "universal time/date standard" either fail or cause a
"emulator Deficiency" error message, depending on an F.T. switch.

Many of the arguments to extended ENTERs and RENAMEs are ignored.

The access date is not returned (is always 0).

Renaming from one directory to another is not supported.  It can't
be done on I.T.S.


8) MISCELLANEOUS INFO

DECUUO exists in the same ITS job as the emulated program.
This makes for greater efficiency than TEN50 had, and also
makes it possible to debug the emulated program with ITS DDT
instead of DEC DDT.  The source for DECUUO is DECSYS;DECUUO > MC:
and DECSYS;DECBOT > MC: (the latter by itself assembles the
stand-alone bootstrap).

When a program is being emulated by means of :DEC <file>,
it is possible to reload DECUUO with $L, re-specify the JCL
and the $G again.  However, that should not be done if there
are any breakpoints set in the emulated program, since that
process involves reloading the program while DDT thinks
breakpoints are "in".  If the program has a bootstrap and
loads DECUUO, that case is no problem, but a similar problem
exists with breakpoints INSIDE of DECUUO.