github.com/PDP-10.klh10
1
0
Fork 0
mirror of https://github.com/PDP-10/klh10.git synced 2026-05-04 06:58:18 +00:00
Code Issues Releases Wiki Activity

Initial import of klh10-2.0a.tgz

Browse Source 
dated Nov 19  2001.
Source: http://klh10.trailing-edge.com/
This commit is contained in:
Olaf Seibert
2015-04-27 22:54:12 +02:00
commit 742b43d025
123 changed files with 80046 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
doc/Intro.txt Normal file
View File

@@ -0,0 +1,167 @@
/* INTRO.TXT - Introduction to the KLH10
*/
/* $Id: Intro.txt,v 2.4 2001/11/19 12:11:30 klh Exp $
*/
/* Copyright © 1997,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.
*/
CONTENTS
========
All KLH10 documentation is online in ASCII text files for
simplicity and portability. The contents, in suggested order of
perusal, are as follows:
Intro.txt - General intro
news.txt - Changes from previous versions
install.txt - Build, install, & configuration instructions
usage.txt - General usage instructions
klt20.txt - KL10 TOPS-20 installation and startup
klt10.txt - KL10 TOPS-10 installation and startup
kst20.txt - KS10 TOPS-20 installation and startup
kst10.txt - KS10 TOPS-10 installation and startup
ksits.txt - KS10 ITS installation and startup
backgrnd.txt - Background comments
coding.txt - Coding guidelines
cmdref.txt - Command reference
cmdsum.txt - Command summary cheat sheet
dfkfb.txt - KL10 timing diagnostic
dvhost.txt - Special host device
history.txt - Historical notes
kldiff.txt - Differences from real KL10
utils.txt - KLH10 Utilities
vtape.txt - Virtual tape details
GENERAL INFORMATION
===================
"KLH10" is an emulator for the PDP-10 series of machines from
Digital Equipment Corporation. The most important thing to know is
that this is a MACHINE emulator. It emulates a specific PDP-10 CPU
and all necessary I/O devices, running a site's existing operating
system (monitor) binary without change -- which then runs user-mode
application programs just as if they were on a real PDP-10. Even
floating-point results are bit-identical.
This means sites must continue to manage the virtual system in
the same way as a real one, without the old hardware. However, the
emulator doesn't monopolize the actual platform, and runs as a set of
simple user processes that co-exist with other software on the native
system. It is possible to configure it so that no actual CPU time is
used while the virtual system is idle.
The KLH10 emulator is extremely portable and flexible -- it is
written in ANSI C so that it can be ported to new platforms quickly,
and new "virtual hardware" can readily be added. The following
describes the currently supported versions:
Emulation Target: KL
CPU: KL10B with extended addressing
Memory: 4MW MF20 (22 bits - 8192 pages of 512 words)
Microcode: v.442 (supports final versions of TOPS-10 or TOPS-20)
Devices available:
DTE - one CTY
RH20 - up to 8 (7 if using a NI20)
Disk - 8 RP06 or RP07 drives per RH20
Tape - 8 TM02/3 formatters per RH20, with one TU45/TU77 each
Network - one NI20 (KLNI/NIA20) ethernet interface
Emulation Target: KS
CPU: KS10
Memory: 512KW (19 bits - 1024 pages of 512 words)
Microcode: ITS v.262 (supports final version of KS10 ITS)
DEC v.130 (supports final versions of KS TOPS-10/20)
Devices available:
FE - one CTY
RH11 - up to 2
Disk - 8 RP06 or RP07 drives per RH11
Tape - 8 TM02/3 formatters per RH11, with one TU45/TU77 each
Network - one "ACC LH-DH" IMP interface (ITS only)
Supported Host Platforms:
Compaq/DEC Alpha with Tru64 (formerly Digital Unix, formerly OSF/1)
SUN Sparc with Solaris
Any x86 with FreeBSD, NetBSD, or Linux
Plus: Any system providing equivalents to basic Unix system calls.
WNT/W2K ports are possible.
Requirements:
Memory: KL: 35MB (3MB program, 32MB emulated PDP-10 memory)
KS: 6MB (2MB program, 4MB emulated PDP-10 memory)
Disk: .2-.3 GB per RP06, .5-.9 GB per RP07, 50+GB per dynamic RPxx
Tape: optional, can use any variable-record-length drive
Network: optional, LAN interface advised (can share single interface
with native OS, but a second may be desirable)
Performance:
Varies with job mix and platform architecture, but general
observations suggest the following ratios relative to a
real PDP-10 (where 1.0 = KL10 speed):
SPARC: (MHz / 200)
Alpha: (MHz / 250)
x86: (MHz / 200)
Thus, a 450MHz x86 would provide slightly over 2x KL speed.
IMPLEMENTATION
==============
The KLH10 internals are organized in a fashion roughly similar
to that of actual hardware. There is a "KN10" process equivalent to a
KS10 or KL10 processor that carries out all CPU operations and is
continuously running, except when the KLH10 user-interface command
parser has control. Most importantly, each hardware device is
implemented as a separate subprocess, with optional direct access to
main PDP-10 memory for data transfers.
This architecture has several advantages:
- It can take advantage of multi-processor host platforms.
- The emulated CPU never needs to wait for I/O. This considerably speeds
up operation, compared to a non-threaded emulator which must
block on disk I/O.
- It can directly use very slow physical devices such as magtape drives
(half-inch, 8mm, 4mm, DLT, etc). Virtual tapes (i.e. tape images
on disk) are also supported.
- The sub-process implementation is more portable and robust than
a threaded implementation.
- Device failures need not be fatal. The NIA20 network device for example
can be reloaded and restarted without stopping the KN10 or the
TOPS monitor.
TERMINOLOGY
===========
There are two terms used in the documentation and source that
may cause confusion: KLH10 and KN10.
"KLH10" refers to the entire software product covered by the license.
This is theoretically a proper name ("KLH10 has") but is
often used as an object name ("the KLH10 has").
"KN10" refers to the virtual PDP-10 created at runtime by the
"kn10" executable image. It is specifically intended to
serve as an object name alongside the physical PDP-10s
KA10, KI10, KL10, and KS10.
Nearly all software products are referred to like people (ITS, Emacs,
Oracle, Solaris, etc) and the same can be done with "KLH10". However,
to emphasize that it emulates a hardware device, it is often still
referred to as an object -- "the KLH10". In fact this objectification
urge is so strong that it is actually difficult to avoid using the
articles "the" and "a". The term "KN10" was invented to help maintain
the distinction between the product and the virtual machine/object.
I will let others speculate on why English is this way.

402
doc/backgrnd.txt Normal file
View File

@@ -0,0 +1,402 @@
/* BACKGRND.TXT - KLH10 Background Commentary
*/
/* $Id: backgrnd.txt,v 2.3 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 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.
*/
FAIR WARNING:
You don't need to read this file. It has nothing of
interest to most users. Hackers, however, may like it.
It is mostly a rambling commentary on the KLH10 code that attempts
to explain why things are the way they are, and speculate on how
they might be.
And like the code itself, this is an incomplete work in progress.
As you read the source you will notice that some parts are
rather simplistic and specific, while others are too complex and
generalized. Many things are not fully implemented, and many others
are over-implemented. Sometimes there are good reasons for this and
other times that's just how it ended up when I ran out of time during
one development phase or another.
A little history may help set the context:
HISTORY
=======
From an outside viewpoint there have been essentially two
major KLH10 versions: the first being a "toy" KS10 emulator (V0.x),
and the second a commercial KL10B emulator (V1.x). Internally, of
course, many more versions have existed as part of a long incremental
development process.
[XXX: Flesh out later]
Roots - PDP-10 arithmetic package for KCC cross-compiling.
First version - KS10 running ITS, then TOPS-20.
Synchronous device model.
DEC intervention - KL10B version on Alpha, commercial use.
Extended addressing, KL devices.
Device subprocess model.
Merged version - KS and KL, shared devices. Intended for
Public ITS systems.
Source release - cleanups, multiple tape format support, etc.
PRIORITIES
==========
Once the decision was made to pursue a commercial KL10B
emulator, KLH10 design and implementation was driven by four main
priorities, in the following order of importance:
[1] Accuracy
[2] I/O Performance
[3] Stability & reliability
[4] Portability
[1] Accuracy
------------
The most important goal was implementing an accurate
emulation, with two facets. Not only did the emulator have to run
existing TOPS-10 and TOPS-20 monitor binaries as-is, it also had to
emulate a KL10B accurately enough for users to run their applications
and get exactly the same answers as before. Otherwise, it would be
worthless as a product.
This is a matter of judgement since perfect emulation is impossible,
but there is a huge difference between the initial "toy" KLH10 that
first ran ITS and the current one. By far the vast bulk of the work
went into the task of making the emulator behave correctly, certainly
much more than into making it "fast".
There were many problems. Some were difficult simply because of their
complexity, but the hardest were the ones where the documentation was
simply wrong or ambiguous in describing how a real KL10B behaved.
Even access to the microcode was not much of a help, since much of the
KL logic was actually implemented in hardware.
Some of the issues encountered:
- Extended addressing idiosyncracies, esp with PXCT
- EXTEND instructions - many ambiguities
- Floating point - hardware garbage
- RH20 and DC10 emulation (more "Adventures in RH20-Land")
- DTE 10-11 device emulation
- NI20 emulation
- Monitor race conditions
The DTE and NI20 are particularly complex since in reality those
devices were self-contained processors in their own right.
Of course, for practical reasons not everything could be emulated; see
the file "kldiff.txt" for details on the differences between the KN10
and a real KL10B.
[2] Stability & reliability
---------------------------
For this kind of product to be worth something, it has to work
and keep working. The more problems I ran into while developing it,
the more paranoid I became about making possibly destabilizing
changes. In particular, once it was deployed to clients I tried to
make only those changes that were absolutely necessary for one reason
or another.
I did build a large battery of tests to help verify whether or not the
internal KN10 processor was accurately emulating a real KL10B, as well
as a variety of device operations. These regression tests are still
very helpful, but they do not catch everything; they are good only up
to a point.
As a result, once code was proven to work, it tended to remain
relatively static from there on. Only with the KLH10 source release
and its availability to many more potential testers did I feel safe in
finally starting many long delayed cleanups.
What this means is that the V2.x sources you have are not the same as
the commercial V1.x versions. They are intended to be better, but
have not undergone anything close to the same amount of testing and
verification. At some point, of course, V2.x should be stable enough
that it can replace V1.x with minimal perturbations.
[3] I/O Performance
-------------------
The biggest problem with the initial toy KLH10 was its lack of
asynchronous I/O; this meant that any device I/O would always be
"instantaneous" in the sense that all CPU operations would block
completely until the I/O was finished. The CPU blockage is okay for a
single-user personal system, but unacceptable for a true time-sharing
system and completely prohibitive if trying to support real magnetic
tape drives.
The solution adopted was to implement devices as separate Unix child
processes (the DP filename prefix stands for "Device Process"), allowing
them all to run independently and asynchronously.
[XXX: flesh out a bit more]
[4] Portability
---------------
While always desirable on general principles, portability is a
somewhat idealistic goal -- there is no absolute requirement for it,
unlike the other issues. The main reason the emulator remains
portable is because I wanted it that way in preparation for the day
when it could be distributed.
There is nothing in the KLH10 code that requires an integer
type larger than 32 bits, nor does it require any features not found
in ANSI C. In fact, for a long time it did not even rely on ANSI
features either.
At the time it was first written, this was an inescapable requirement
because 64-bit types, not to mention ANSI compilers, were few and far
between; even GCC's "long long" had early bugs. With the Alpha
version 64-bit code became possible, but nothing has ever relied on
it.
This is why every reference to a PDP-10 word or value is done by means
of a macro. Even on platforms that support 64-bit types, the
architecture sometimes works better when restricted to 32 bits.
From the viewpoint of OS (rather than CPU) portability, the code again
tries to rely on ANSI C library functions rather than UNIX system
calls, but it is fair to say that most of the existing OS-dependent
support is Unix oriented, especially for the real-time asynchronous
version. Fortunately with the advent of true operating systems for
both MacOS (X) and Windows (NT, 2K, XP), this should less of a problem
in the future.
Non-issue: CPU speed
--------------------
It may seem odd to people who have not run a business or
service, but the speed of the emulated PDP-10 has never been a real
issue. In practice clients have just picked a hardware platform that
provides acceptable performance, and as soon as their systems are up
and working, they prefer to see as little change as possible. There
is little compulsion to upgrade with faster or more featureful versions
unless something is actually broken, which should only happen if the
platform OS is upgraded to yet another incompatible release.
MAJOR DESIGN ISSUES
===================
C vs Assembler
--------------
The notion of a PDP-10 emulator had been bouncing around for
some time before I decided to embark on the project, and performance
was always the number one issue; it was not clear whether it could be
made to execute PDP-10 code fast enough to be useful. A typical
workstation was a 33MHz SPARC-2, and the x86 PCs were still 386s.
Several people felt the best way to achieve this was to pick a host
architecture (SPARC or the forthcoming Alpha) and code in assembly
language.
As a long time PDP-10 assembler fan, this approach appealed to me as
well, but eventually I came to the conclusion that this would be best
attempted in C, for two major reasons:
- Portability. After having engineered a major porting effort
from TOPS-20 to Unix while at SRI, I never wanted to be locked
into a specific machine architecture again. Oracle's
extremely impressive porting system provided additional
conviction that this was the right approach.
- Implementation time. It was much faster to write in C than
assembler, especially for RISC-based machines.
There was also a third, subjective reason -- at the time, Stu Grossman
was writing a simple prototype in C called "KX10". While I was unable
to use anything from it, it did convince me that C was the right way
to go, and as far as I know Stu was the first to attempt it.
As it turned out, this decision also proved to be the right one in
terms of performance. I had anticipated that keeping the code
portable would eventually lead to "free" performance gains as hardware
improved over the years, and that was in fact the case. But one other
factor surprised me: C code was sometimes faster than assembly code!
It took a while to realize that for the new RISC-based machines with
pipelines and caches, new rules applied; often the C compiler provided
with a machine would know about tricks or scheduling rules that not
only were difficult for a human to code by hand, they also could
change from one machine to the next. While doing timing tests on
initial versions of the emulator, I found performance so sensitive to
tiny and logically unrelated changes that I finally gave up worrying
about it.
In retrospect all this may seem obvious, but it was not so at the
time.
Instruction Execution Loop
--------------------------
The decision to use C posed some problems with respect to
control flow. The microcode of real machines is like a huge plate of
extremely sticky spaghetti where every "instruction" has a jump
address that can go anywhere else, plus a bunch of chopsticks stirring
the mess up with external interrupts and asynchronous device
operations.
By contrast, C favors the use of separately defined functions with a
stack-based calling convention, and control flow strongly favors using
the normal call-return mechanism. It is possible to bypass the latter
with "longjmp" type invocations, but you can only jump to pre-existing
contexts and the mechanism can be very expensive. For someone used
to the freedom of assembly language, this is very frustrating.
Without going into all possible ways of implementing a PDP-10 emulator
in C, there appeared to be two main choices:
- Stuffing as much as possible inside a single huge function.
Normally this would involve using a large switch() statement
for instruction dispatch, plus assorted gotos to accomodate
weird control flow issues.
- Looping within a small function and dispatching to each
instruction as a function call.
(Note that the PDP-10 has one characteristic that makes things a
little easier -- every instruction must always calculate an effective
address regardless of whether it is used or not, so this naturally
leads to building an instruction execution loop with the EA
calculation as its central focus.)
The KN10 code uses the latter approach for a number of reasons, some
of which no longer apply. When it was first written, compilers still
existed that had problems with very large switch statements, and even
now it is still considered easier for them to optimize a function if
it does not contain "goto" statements. Keeping instructions in
separate routines also made it easier to invoke them explicitly as
needed (for XCT, PXCT, etc), examine their assembler output to see
what was being produced, and step through them with a debugger.
This is almost certainly not an optimal design for speed.
PDP-10 Word Representation
--------------------------
[XXX - some stuff about the tradeoffs, from word10.h]
FUTURE DIRECTIONS
=================
Since the odds of new commercial applications showing up are
essentially nil, whatever happens next will be entirely up to the
PDP-10 hacker community. It will either evolve with their help or
quietly go away without it.
Recently a number of other PDP-10 emulators have finally appeared,
most or all of which have the KS10 as a target. I have not yet looked
at them (partly to avoid contamination) and so have no basis for
comparison, but in general I think multiple KS implementations are a
good thing, and as software tools improve it should become easier.
The KS is a fairly clean yet respectable machine that would make an
excellent semester project, and was fun to do. The more people who
can get their hands dirty, the better.
The KL10 by contrast was much harder, and definitely not fun. I hope
that with the KLH10 release no one else will have to go through that
nightmare, or at least will be able to start from a far better place.
FUTURE KLH10 IMPROVEMENTS
=========================
The wish-list stack has always been a mile high. Here's a bunch of
stuff off the top of my head, in no particular order.
- Multi-processing extensions:
- Decouple FE from KN10.
- Allow other user processes to examine KN10 state and manipulate
devices (especially virtual magtapes) without requiring
console access.
- Re-investigate threading (very carefully; very unportable).
- The UI sucks:
- Improve present UI, add editing.
- Allow input scripts to feed OS console at startup.
- Add GUI interfaces:
- 340 display (Spacewar lives!)
- FE/Console (KA10 panel with blinkenlights!)
- Magtape UI
- CPU and device visualizations
- Accuracy improvements:
- Get rid of the last low-bit FDV divergence, even
though that may reduce mathematical accuracy.
- Implement address break (optional - very slow).
- Raw performance:
- Develop better performance metrics (TenStones? DECmarks?).
- Speed up floating point (DFDV is far and away the
slowest instruction).
- Alternative word representations.
- EA calculation and memory mapping (most of the CPU is burned
on this, I believe).
- Characterize workload to determine true bottlenecks.
- Alternative instruction loops:
- Hybrid switch & dispatch
- Hand-coded assembler (x86 primarily)
- Locality improvements; must match to host cache setup.
- Autoconf mechanism to run tests on host and automatically
select optimal build configuration.
- Network support:
- Add AN10 device, couple with IP tunnels like "tun".
- Determine OS mods to allow self-connection for systems that
currently can't do it (Linux, FreeBSD, Solaris).
Get mods incorporated in standard releases.
- Magtape support:
- Finalize tape naming conventions.
- Non-console access (cf UI above).
- Finish in-memory support.
- Add update capability.
- Emulator extensions:
- Finish KA10, KI10 versions. TENEX pager. WAITS?
- Emulate SC-40 and/or XKL (more "physical" memory).
- Additional devices (many!)
- DH11 (KS10), or extend DTE (KL10)
- AN10 (IMP interface)
- DX20, CI, ...
- Emulate NCP with IMP interface for older OSes.
- PDP-10 software:
- Public ITS support.
- Further KN10-conditionalized OS mods.
- Resurrect older KA/KI OSes.
- GCC on KL (Lars).
- Distribution:
- Add HTML versions of doc.
- Better build mechanism.
- Permission for Public ITS distribution (legal hoops).
- Packaged ITS filesystems.
- Packaged DEC OS filesystems.
- Packaged NIC/Stanford filesystem.

547
doc/cmdref.txt Normal file
View File

@@ -0,0 +1,547 @@
/* CMDREF.TXT - KLH10 Command Reference documentation
*/
/* $Id: cmdref.txt,v 2.3 2001/11/10 21:24:21 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.
It should halt the KN10 immediately with the message
[HALTED: FE interrupt]
Followed by the KLH10 command parser prompt:
KLH10>
Typing ^\ while in the command parser should have no effect,
although this depends on the native OS.
1-STEP
Single-steps the KN10 by executing one instruction. For debugging.
This is the same as "proceed 1".
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 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.
Currently this is a no-op because if you're in the KLH10 command
parser that means the KN10 is already halted!
When the KLH10 allows concurrent execution this will become a
meaningful command.
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 <#>
Single-steps the KN10 by the specified number of instructions.
Most useful with TRACE-TOGGLE.
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 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".

58
doc/cmdsum.txt Normal file
View File

@@ -0,0 +1,58 @@
/* CMDSUM.TXT - KLH10 Command Summary
*/
/* $Id: cmdsum.txt,v 2.3 2001/11/10 21:24:21 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 is a cheat-sheet summary of all KLH10 commands, grouped roughly
by functional category. See "cmdref.txt" for more details on each.
BASIC:
help [<cmd>] Shows help for all matching commands (defaults to all)
load <file> Load binary into KN10, sets start-addr
go [<addr>] Start KN10 at address (defaults to start-addr)
continue Continue KN10 (resume execution after ^\ or halt)
shutdown Halt OS gracefully (set loc 30 to -1, then continue)
quit Quit emulator
DEBUGGING:
set [<var>[=<val>]] Set/show KLH10 variables (if no args, show all)
view View KN10 status (PC, etc)
examine [<addr>] Show word at address
next-examine Show Next word
^-examine Show Previous word
deposit <addr> <val> Deposit value at address
breakpt <addr> Set PC breakpoint to <addr>
1-step Single-step KN10
proceed <#> Single-step # instrs
trace-toggle Toggle execution trace printout
continue Continue KN10
dump <file> Dump binary from KN10
halt Halt KN10 immediately
reset Reset KN10
zero Zero first 256K memory
DEVICE CONFIG/CONTROL:
devdefine <devid> <dev#> <driver> [<params>] Define/init device
devshow [<devid>] Show defined device info
devmount <devid> <path> [<options>] Mount device media
devunmount <devid> Unmount device media
DEVICE MISC:
devdebug <devid> [<debugval>] Set device debug value (0=off)
devevshow [<devid>] Show device event reg info
dev <devid> <device-command-line> Execute device-dep command
devload <driver> <path> <initsym> <comments> Load DLL dev driver

195
doc/coding.txt Normal file
View File

@@ -0,0 +1,195 @@
/* CODING.TXT - General coding rules for KLH10
*/
/* $Id: coding.txt,v 2.4 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 1992, 1993, 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 General coding rules
STYLE AND STANDARDS
===================
The style rule is simple: use the existing style. There is no
religious reason for this particular style, but it is always best for
edits and additions to remain consistent with what's already there.
All code should conform to the first ANSI C Standard (ANS X3.159-1989,
also called the 1990 Standard). Do not use or assume features from
later versions of the C Standard, or from any specific compiler,
unless conditionalized such that everything will still build without
those features. This specifically includes pragmas; none are
currently used. Similarly, the "long long" datatype cannot be assumed
to exist.
Do not use C++. Eventually this may become unavoidable for GUI
wrappers, but the existing core code must remain in C.
Simply using ANSI C is not enough to ensure code is portable. You
must also be careful about any assumptions regarding the host CPU:
little-endian vs big-endian, integer type sizes, printf arguments, and
so on. This is a long and complex topic that boils down to "don't do
stupid things".
PORTING AND OSD CODE
====================
OSD means "Operating System Dependent". To make it easier to
port the KLH10 to new platforms, all system calls or non-ANSI library
facilities should be encapsulated within one or more of the OSD*.C
modules, and accessed only by facilities with an "os" name prefix.
The bulk of this code is presently in OSDSUP.H and OSDSUP.C, which is
dedicated to the KN10 component and not used by any other programs.
The only exceptions are DPSUP.C and the separate DP* programs that use
it, but even those may be changed in the future to follow the same
conventions.
This should be done even for system calls that are considered
"standard" for all Unix systems, such as read(), because of the
existence of certain popular non-Unix platforms.
New platforms will almost certainly require new Makefiles. Try to
follow the scheme already in place.
WORD MANIPULATION
=================
NEVER, ever, operate on a PDP-10 word (w10_t) except with the
macros provided from k10ops.h and word10.h. The only things you can
do to words without macros are pointing to them (&) or copying (by
assignment or parameter passing).
The KLH10 is designed to be portable to environments where the longest
native integer type is 32 bits, so a w10_t may actually be a structure
or union rather than an integer.
An important ramification of this is that any arithmetic done on
values that might exceed 32 bits must always provide special handling;
you cannot merrily assume that a sufficiently large "long long" will
always be available. Even when it is, the "native" arithmetic may not
be as efficient as a 32-bit algorithm!
ARG/RET CHECKS
==============
An important rule for macros and functions:
Arguments are always *assumed* to be correctly formatted or masked.
Results are always *guaranteed* to be correctly formatted or masked.
This is important in order to maintain consistency and avoid redundant
operations. The rule permits incorrect values to be generated or
maintained, as long as they are corrected before being given to other
facilities.
There are only two known exceptions to this rule: mr_PC and E.
* mr_PC is not masked during the normal execution loop, to save time.
This may change for the KLX version.
* E is not masked when provided to instruction routines, also to
save time where the mask isn't needed.
FLOATING POINT
==============
Do not use it. No native implementation corresponds exactly
with that of the PDP-10, and floating point results are inherently
unportable, especially for extreme operands that may even trap.
In theory it may be possible to accelerate some PDP-10
floating point operations with carefully selected uses of native FP
operations or libraries, but this will take a VERY large amount of
work to verify that the results remain bit-identical with those of a
real PDP-10.
CODING INSTRUCTION ROUTINES
===========================
All instruction routines must be declared in this way:
insdef(i_xxx)
{ /* Function code */
}
The "insdef" macro declares the function with the following three args:
int op; /* 9-bit opcode of instruction */
int ac; /* 4-bit AC field of instruction */
vaddr_t e; /* Effective Address calculated from I(X)Y */
(WARNING! for KS10 may have junk in high bits!)
The op and ac values have already been masked.
Note that someday "op" may go away.
All memory references should be checked BEFORE anything is modified
either in memory or the ACs! Actually, it is good practice to verify
the memory reference before even starting the computation, especially
if there's a chance that PC flags such as TRAP1 might be set.
This ensures that abnormal termination (due to page failure or PI
interrupt) doesn't leave anything messed up.
Exceptions are BLT and IDBP/ILDB which know how to back out.
Normal memory operand reads and writes should be done with:
word = vm_read(e); - Read word, may page-fail!
vm_write(e, word); - Write word, may page-fail!
Halfword variants vm_{read,write}{lh,rh}() also exist, but note
that they operate on h10_t integer values, not w10_t words.
If the same memory location is to be read-modified (both read and
written) then these should be used:
vmptr_t p;
p = vm_modmap(e); - Get phys mem ptr (may page-fail!)
word = vm_pget(p); - Read word from phys mem (won't fail)
vm_pset(p, word); - Write word to phys mem (won't fail)
BLT, Stack, and Byte operations do special-case memory referencing to
allow for previous-context mappings by PXCT.
AC reads and writes are done with:
word = ac_get(ac); - Read AC
ac_set(ac, word); - Set AC
Halfword AC reads and writes have ac_{set,get}{lh,rh}()
but note that they operate on h10_t integer values, not w10_t words.
Multi-word operations (in particular the double-word instructions) must
reference each word individually, because AC+1 may wrap around (modulo 020)
and E+1 may likewise either wrap or cross a page boundary.
The return value is added to the PC, so normally this will be 1
except for jumps (0) and skips (2). The macro definitions PCINC_n
are used for this purpose; someday they may have different values.
Instructions which set any of the PC flags should do so with the macro
PCFSET(flags)
to ensure that various transition subtleties are handled properly.
PRINTF ARGS
===========
This is a generic portability tidbit. All printf-style
references to integer variables of unknown size (that is, defined by
typedefs) must promote the value to long and use %l in the format
string. In particular, h10_t and vaddr_t types require this.
MISCELLANY
==========
To keep some strict compiler modes happy, all functions with
external linkage must have a prototype declaration prior to their
definition. This is not needed for static functions, unless of course
they are referenced prior to their definition.

119
doc/dfkfb.txt Normal file
View File

@@ -0,0 +1,119 @@
/* DFKFB.TXT - README for DFKFB KL timing diagnostic
*/
/* $Id: dfkfb.txt,v 2.3 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 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.
*/
NOTE:
DFKDB is not KLH10 software; it is a KL10 instruction timing
diagnostic written by DEC and may only be used with a valid TOPS-10 or
TOPS-20 license. If present in the distribution, it is included
purely as a convenience for developers.
People with a weakness for instant gratification, which is most of us,
will like DFKFB. As soon as you have built a KN10-KL, you can
immediately run DFKFB without spending any time on installation or
configuration, and get an idea of how it compares with a real KL.
[1] Build a KN10-KL for your native platform.
$ cd <distrib>/bld/<platform>
$ make base-kl
[2] Go to the DFKFB directory, if present, and run it.
$ cd ../../run/dfkfb
$ ../../bld/<platform>/kn10-kl dfkfb.ini
[3] Compare output with other configurations, platforms, etc.
Strut or sulk as appropriate.
As with all benchmarks, the DFKFB output must be taken with large
grains of salt. Its results will be strongly influenced by the cache
behavior of your platform; with modern hardware it will usually run
entirely in the cache and thus will represent tne best speed you can
get. When running a PDP-10 OS with real applications, you will get
many more cache misses and the following factors become more
important:
- PDP-10 instruction mix. Floating point is slow.
- I/O response (fast physical disks make a difference).
- Non-KLH10 processes competing for the native platform's CPU.
Still, it's fun to see how many multiples of a real KL you can run at.
THE REAL THING
==============
Unfortunately, although I have output logs of DFKFB runs for a
variety of platforms, I do not have one for a real KL10 itself!
Hopefully someone will be able to contribute this from their archives.
The best information I can provide comes from a user-mode timing test
program I wrote called "ZOTZ"; the results I have are for a DEC-2065,
which is a KL10B with MCA25 cache. Even though this is a user-mode
program rather than exec-mode as for DFKFB, these numbers should be
within a few percent of the real thing. Copying this data into the
format of DFKFB gives the following simulated output, with "??"
inserted where nothing was available:
1 - BASIC CLOCK CYCLE IS ?? NSEC.
2 - INDEXING TAKES 36 NSEC.
3 - INDIRECT TAKES 269 NSEC.
4 - INDEXING AND INDIRECT TAKES 336 NSEC.
5 - MOVEI TAKES 269 NSEC.
6 - MOVE FROM AC TAKES 374 NSEC.
7 - MOVE FROM MEMORY TAKES 402 NSEC.
8 - HRR FROM MEMORY TAKES 443 NSEC.
9 - SETOM 0 TAKES 571 NSEC.
10 - JRST TAKES 303 NSEC.
11 - JSR TAKES 642 NSEC.
12 - PUSHJ TAKES 708 NSEC.
13 - ADD FROM MEMORY TAKES 438 NSEC.
14 - MUL (9 ADD/SUB - 18 SHIFTS) TAKES 2.42 USEC.
15 - DIV TAKES 4.70 USEC.
16 - FIX A FLOATING POINT ONE TAKES 874 NSEC.
17 - FLTR AN INTERGER ONE TAKES 881 NSEC.
18 - FAD (1 RIGHT SHIFT) TAKES 1.59 USEC.
19 - FAD (8 SHIFT RIGHT - 3 LEFT) TAKES 1.81 USEC.
20 - FMP (7 ADD/SUB - 14 SHIFTS) TAKES 2.56 USEC.
21 - FDV TAKES 4.82 USEC.
22 - DMOVE FROM MEMORY TAKES 608 NSEC.
23 - DFAD (1 RIGHT SHIFT) TAKES 2.06 USEC.
24 - DFAD (8 SHIFT RIGHT - 1 LEFT) TAKES 2.06 USEC.
25 - DFMP (7 ADD/SUB - 32 SHIFTS) TAKES 4.25 USEC.
26 - DFDV TAKES 8.71 USEC.
27 - CONO PI TAKES ?? NSEC.
28 - CONI PI TAKES ?? NSEC.
29 - DATAO APR TAKES ?? NSEC.
30 - DATAI APR TAKES ?? NSEC.
31 - MOVE TO MEMORY TAKES 573 NSEC.
32 - LOGICAL SHIFT (35 PLACES LEFT) TAKES 439 NSEC.
33 - LOGICAL SHIFT (35 PLACES RIGHT) TAKES 470 NSEC.
34 - LOGICAL SHIFT COMBINED (71 PLACES LEFT) TAKES 743 NSEC.
35 - LOGICAL SHIFT COMBINED (71 PLACES RIGHT) TAKES 745 NSEC.
36 - INCREMENT BYTE POINTER TAKES 924 NSEC.
37 - INCREMENT AND LOAD BYTE TAKES 1.21 USEC.
38 - INCREMENT AND DEPOSIT BYTE TAKES 1.60 USEC.
39 - JFCL TAKES 404 NSEC.
40 - CAI TAKES 272 NSEC.
41 - JUMP TAKES 342 NSEC.
42 - CAM TAKES 376 NSEC.
43 - EQV AC TO AC TAKES 402 NSEC.
44 - EQV MEMORY TO AC TAKES 742 NSEC.
45 - SETOB TAKES 571 NSEC.
46 - AOS TO MEMORY TAKES 539 NSEC.
47 - EXCHANGE AN AC WITH AN AC TAKES 545 NSEC.
48 - EXCHANGE AN AC WITH MEMORY TAKES 706 NSEC.
49 - EXECUTE TAKES 471 NSEC.
50 - BLT MEMORY TO MEMORY TAKES 1.58 USEC.
51 - BLT AC TO MEMORY TAKES 1.48 USEC.
52 - DATAI TAKES ?? NSEC.
53 - DATAO TAKES ?? NSEC.

118
doc/dvhost.txt Normal file
View File

@@ -0,0 +1,118 @@
/* DVHOST.TXT - The special HOST device
*/
/* $Id: dvhost.txt,v 2.3 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 1997-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.
*/
THE "HOST" DEVICE
This is not a real device, nor is it anything that ever
existed on a real PDP-10. Rather, it is a pseudo-device which serves
as a simple API to request services or information from the emulator.
It is called "HOST" to emphasize that its status or I/O represents
communication with the native host platform that the emulator is
running on.
"HOST" DEVICE CONFIGURATION
As for other devices, the DEVDEFINE command must be used
(typically as a line in "klh10.ini") to associate the HOST device with
either a unibus address (for the KS10) or a PDP-10 device number (for
all other models). This needs to be a device number or address that
is not otherwise used by something else, and any monitor modifications
that refer to this device must use the same number or address.
KL10 example:
devdefine idler 700 host ; PDP-10 device 700
where "host" specifies the HOST device; "idler" is a name
of your own choosing, and 700 is simply a device number that
does not conflict with any standard DEC devices.
KS10 example:
devdef idler ub3 host addr=777000
where "host" specifies the HOST device; "idler" is a name
of your own choosing, and "ub3" plus "addr=777000" specifies
a unibus address that should not conflict with any standard
DEC devices.
There are currently no configuration parameters associated with the HOST
device, and only one such device can be defined.
KL10 "HOST" DEVICE USAGE
Although any of the four basic PDP-10 I/O instructions (CONI,
CONO, DATAI, DATAO) can be used with this device, only one specific
instance is currently meaningful, and its use is very simple.
IDLE FUNCTION: CONO <hstdev>,1
The emulator process will enter an "idle" state with respect to the
host system, until a PI (priority interrupt) event occurs. During
this state no host CPU time is consumed emulating PDP-10 instructions,
although device subprocesses are still free to run. Instruction
execution will resume with a dispatch to the appropriate PI
interrupt handler, which should eventually return to the next
instruction following the CONO.
All other I/O instructions will behave as if the device was
non-existent. A CONO with an E != 1 will be a no-op, as will DATAO;
CONI and DATAI simply read a zero word. However, new functions can
obviously be readily added as the need arises.
KS10 "HOST" DEVICE USAGE
To invoke the "idle function" on the KS10, just write the
value "1" to the device's unibus address. The exact IO instruction
used to do this should not matter.
MONITOR PATCHES FOR THE "IDLE" FUNCTION:
In order to effectively use the HOST "idle" function, you must
determine the right place to patch your monitor to use it -- the point
in the scheduler where the system decides there isn't anything it can
do and begins to run the "null job".
For a TOPS-20 V7 monitor the most appropriate patch is to replace the
instruction at SCDNL1-1 in SCHED.MAC (a JRST SCDNL2) with the "IDLE"
function instruction. In context:
SCDNUL: SETOM NULJBF
SCDNL2: ...
<null job stuff>
JRST SCDNL1 ; Something to do.
JRST SCDNL2 ; Replace with CONO <hstdev>,1
; which will fall through when there's
; any PI activity.
SCDNL1: <start of sched cycle>
...
For a TOPS-10 monitor I would suggest replacing the instruction at
NULCOD+1 in CLOCK1.MAC (a SOJG 6,1) with the "IDLE" function
instruction. However, this has not been well tested and there may be
a more appropriate place.
You can verify whether this function is working by observing the
process CPU usage on the host system. As long as the KN10 is not
running the monitor's null job, the emulator will be using as much CPU
time as possible -- as much as 95% on an otherwise lightly loaded
single-CPU system. But when the monitor has nothing to run and the
KN10 is effectively idle, the emulator's CPU usage should drop to
perhaps 5%. It will never be completely zero because all monitors
always maintain a clock interrupt that drives periodic updates and
scheduler checks.

426
doc/history.txt Normal file
View File

@@ -0,0 +1,426 @@
/* HISTORY.TXT - KLH10 Historical notes
*/
/* $Id: history.txt,v 2.3 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 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.
*/
The following two messages were sent when the first version of the
emulator was announced. Although I always cringe a bit on reading
things from my younger self, I've included them as historical
documentation because of the glimpse they provide back into a more
innocent time when this was all just terrific fun. No kids, no gray,
no NDAs, no licenses, and no lawyers.
Date: Mon, 20 Jul 1992 23:51:04 BST
From: Ken Harrenstien <klh@us>
To: its-lovers@mc.lcs.mit.edu, tops-20@wsmr-simtel20.army.mil
Cc: klh
Subject: One small step, one giant leap
Message-Id: <CMM.0.88.711701464.klh@churchy.us.oracle.com>
On this anniversary of a truly historic moment, I would like to announce
a somewhat smaller event which may loom the larger for being closer to
our hearts.
stealth.us.oracle.com% telnet nx.us.oracle.com
Trying 139.185.5.134 ...
Connected to mit-nx.us.oracle.com.
Escape character is '^]'.
Unknown ITS PDP-10
NX ITS.1645. DDT.1545.
TTY 11
2. Lusers, Fair Share = 136%
klh$u
*peek^K!
NX ITS 1645 Peek 629 7/20/92 23:02:48 Up time = 2:15
Memory: Free=381 Runnable Total=83 Out=71 Users: High=6 Runnable=1
Index Uname Jname Sname Status TTY Core Out %Time Time PIs
0 SYS SYS SYS HANG ? 51 0 0% 4
1 CORE JOB CORE UUO ? 0 0 0%
2 KLH0 HACTRN SYS TTYI T0 30 9 1%
3 11TLNT TELSER 202405 SLEEP ? 1 0 0%
4 KLH HACTRN KLH HANG > 30 9 0%
5 KLH PEEK KLH +TTYBO T11 C 83 71 7%
Fair Share 135% Totals: 195 9% 7
Logout time = 2 Lost 0% Idle 98% Null time = 2:14
A
NX ITS 1645 Peek 629 7/20/92 23:02:50 Up time = 2:17
IMP is up. TCP/IP is available.
Ix Usr Uname Jname State RWnd Ibf SWnd ReTxQ Lclprt Fgnprt Fgnhst
34 3 11TLNT TELSER OPEN 5170 0 10000 0 0 27 10107 139.185.5.5
4 buffers (4 free)
STY Map
Idx STY owner Idx STY user Host
T11 3 11TLNT TELSER 5 KLH PEEK 139.185.5.5 (TCP)
Q
:KILL
*$$u
NX ITS 1645 Console 11 Free. 23:03:13
telnet> q
Connection closed.
stealth.us.oracle.com%
Yes, NX is a real, live, internet-host ITS assembled from the final
snapshot of AI. So here's the punch line...
***There is no KS-10.*** NX is running on a "KLH-10" -- a virtual PDP-10.
Over the past two months I was finally able to put everything together
to create a complete PDP-10 emulator, including all necessary devices
(RP06, TM03, console, IMP); to distinguish it from a real DEC machine
I'm calling it a KLH-10 per Alan Bawden's suggestion. The current
version is completely in C and should eventually be portable to most
platforms, but at the moment NX's host machine is a 33Mhz SUN Sparc-2
workstation sitting on my desk.
It's a long story with many more details and ramifications, all of which
I'll put off for later. Although I wrote it entirely on my own, it would
never have happened without many people who I'd like to thank here:
Stu Grossman, for convincing me with his KX-10 that a hardware
emulation in C was feasible.
Alan Bawden & Dave Moon, who (apart from their already legendary
roles in ITS) helped as much as they could without actually being there.
Jay Verkler (JLV), who with his group has re-created an AI lab
work environment within Oracle. It's called the Network Products Division
and made this hack possible.
Plus everyone else on these lists whose messages and actions
have helped keep the PDP-10 alive in spirit and reality a little
longer... may it now live as long as we wish!
--Ken
23-Jul-92 20:25:01-GMT,15781;000000000001
Received: by churchy.us.oracle.com (5.59.11/37.7)
id AA19272; Thu, 23 Jul 92 21:24:48 BST
Date: Thu, 23 Jul 1992 21:24:47 BST
From: Ken Harrenstien <klh@us>
To: its-lovers@mc.lcs.mit.edu, tops-20@wsmr-simtel20.army.mil
Cc: klh
Subject: KLH10 info
Message-Id: <CMM.0.88.711951887.klh@churchy.us.oracle.com>
OK, here are some more details about the KLH10. I've been a bit
overwhelmed by the many private responses and hope this answers most of
the questions.
First, the FAQs I've been getting:
* "When/How can I get a copy?"
Ouch, probably not until after Interop (Oct). It kills me to say
this, but my time *is* limited. (The usual bribes might help :-)
RMS has suggested distributing it via GNU/FSF, and I like that idea.
* "Will it run <my favorite PDP-10 OS>?"
Anything based on the KS10 should run with minor mods.
The 166, KA and KI will require moderate I/O instruction changes.
The KL10/20 (extended addressing, DTE20, etc) would require
major surgery -- without anesthetic.
* "How fast is it?"
That depends mostly on the host platform. Using a 33 MHz Sparc-2,
very roughly 0.2 MIPS, perhaps 50% of a KA.
More about this farther on.
* "Why can't I connect to NX?"
Oracle uses firewalls to prevent full Internet access to their
internal networks. We are trying to set up an ITS turist machine
but it needs to be done very carefully. Wait for an announcement.
* "Thanks!"
You're welcome!!
The rest of this message talks about various aspects at more length:
specifics of the target machine & devices, the emulator, and various
other thoughts. It is a bit long for one message, but I figure it's
better to get it all out of the way. My apologies to any uninterested
people.
Summary:
-------
Target machine: KS10 with MIT ITS microcode
Target config: 512K memory, RH11/RP06, RH11/TM03, FE console,
ACC LH/DH & IMP
Current speed: ~0.2 MIPS
Current host: 33 MHz Sparcstation-2 with internal disk, SunOS 4.1.1
Compiler: GCC 2.1
Misc: Sources .5MB, runtime memory 4.3MB, disk lotsaMB
About the Target Machine:
------------------------
The decisions I made while coding the emulator all boil down to
a simple desire to get something useful and interesting up as quickly
as possible. Among other things this meant using an ITS-microcode
KS10 as the target machine, because:
[1] I don't have official access to TOPS-20 binaries or sources,
and didn't want to worry about licensing hassles. Ditto TOPS-10.
I also am lacking the voluminous documentation about installation
and operating procedures.
[2] The most recent ITS binaries and sources are all archived
online (thanks to Alan), and all are for the KS10 version. All
documentation is likewise online, and in any case I have a
somewhat more intimate understanding of ITS.
[3] The KS10 has a simpler architecture than the KL10, which
allows an emulator to run much faster. If not for [2] I might
have started with the KA10 for this reason.
It is important to realize that the KLH10 is emulating the ITS
microcode, which is slightly different from that for TOPS-10 or
TOPS-20. The primary differences have to do with the pager and the
absence of the extended-instruction set (the noteworthy ITS features
such as one-proceed, JPC, and CIRC are of course supported).
In order to bring up TOPS-10 or TOPS-20, minor changes would be needed
to the pager code (somewhat more for TOPS-20, owing to its more complex
design). The extended string instructions are ugly but straightforward
for anybody with a strong stomach (and weak mind?).
Everything else is fully supported, including the double-precision
floating point instructions. I took pains to verify that all results
and PC flags are identical to the real hardware, even for wildly
unnormalized operands. This was *not* one of the fun parts.
With respect to a KA or KI version, the I/O instructions would also
need to be modified and a number of things changed in the APR and PI
system, but not a great deal. Bringing up TENEX should be relatively
easy given a complete description of the BBN pager. WAITS, however,
would be up to a true SAILor.
I know many people are going to wish for a KL10 they can run a
full-grown TOPS-20 on. Of course this is theoretically possible, but
it is not going to be easy to get something that runs at a useful speed
without a superfast host. Remember the KL10 is an oversexed mutant
with these strange bulging growths oozing out of random body parts, all
of which have to be duplicated no matter how bizarre. Just dealing
with extended addressing is going to slow down the basic instructions
as well as requiring much more pager overhead; this is one area where
the hardware parallelism is hard to beat. The additional device cruft
(DTE20s, meters, address breaks, etc) doesn't help. Personally I won't
try it without some concrete incentives.
P.S. Just for grins I included the KA10 and PDP-6 arithmetic ops,
although I don't have a reference machine for verification (ha). Who
knows, maybe a 340 will come along! Spacewar, yeah!
I/O Devices:
-----------
A great deal of the work consisted not of emulating the 10 but
rather emulating a basic set of peripherals. The KS10's use of Unibus
devices made it somewhat more painful than the old I/O device scheme,
because instead of a small matrix of devices and I/O instruction
opcodes, there's a long list of bus addresses to check, each of which
has completely arbitrary meanings. Not to mention the Unibus adapters
with their individual Unibus page maps, all of which are emulated as
well.
DSK: Currently one RH11/RP06 is supported as a virtual disk. The
actual implementation uses a standard Unix disk file (not a raw disk)
to hold the "RP06" contents; this is so all blocks that haven't been
written will simply not exist (also known as a holey file), thus taking
up much less space than a full raw disk would. Formatting the disk is
obviously unnecessary; sector headers are not written or read. Errors
are pretty much limited to those caused by garbage written into the
registers, so the interface is a bit simpler than the real thing. It's
possible that an OS which can't leave well enough alone will insist on
using some weird maintenance bits, in which case the device code will
need work. Mods for multiple drives or other RH-controlled drive types
are trivial.
MTA: Similar considerations apply to the RH11/TM03 magtape interface.
>From the "FE" (front-end controller interface) one can mount or unmount
"tapes" that consist of either binary tape images or virtual tapes
built on the fly from lists of unix files. Hooking up a real magtape
drive would probably have been easier, but loading virtual dump tapes
into the filesystem is very fast, actually -- much faster than the real
devices would be. In fact I found one race condition in the ITS
bootstrap loader that required slowing down disk I/O until I was able
to reassemble a fixed version.
NET: The network interface is an emulation of the ACC LH/DH that some
MIT machines used to have, as well as a virtual IMP. Putting this one
together was a major project in network hacking, not to mention deceit.
Using Sun's NIT (Network Interface Tap) and various trickery, I was
able to set up NX with its own IP address, independent of its
platform's address and thus permitting me to run ITS without
interfering with the other network stuff I'm doing on my workstation.
For efficiency, the virtual IMP is actually a "Simple IMP" that doesn't
bother sending RFNMs, and the virtual LH/DH does I/O in PDP-10 byte
order (not Unibus order) -- this all required changes to the ITS IMP
driver. For a while I considered munging the packets within the
virtual IMP to pretend that the local net was the ARPANET, but finally
decided it was better to fix ITS itself, and did so; ITS can now be
configured for non-ARPA subnets. Geez, I never thought after I did ITS
TCP/IP that I'd be hacking the code again ten years later!
TTY: The FE console TTY "interface" is emulated, tho the 8080 FE
commands aren't -- no need. There is also a dummy DZ11 driver that
merely reads and writes registers without doing anything. This (and an
equally empty Chaosnet driver) was needed because that's what the last
AI ITS binary image was configured for, and I had to get that up before
I could reassemble a new system (oh the joys of bootstrapping). The
DZ11 won't be hard to finish off, but I'm not sure it's worthwhile;
it's a horribly inefficient device and it's much faster to telnet in
over the network. If realio trulio serial-line I/O is needed, I'd
recommend going for a DH11 if the OS supports it. (It isn't as if
it still costs three times as much as a DZ :-)
About the emulator:
-----------------
The KLH10 is written in C for a vanilla Unix OS, largely so it
can be readily ported to other platforms; in particular, those of the
future as well as those of today. Although re-coding critical sections
in assembler would readily double or triple the basic instruction
speed, it is much easier to simply recompile it on a faster machine.
Although I use the GCC compiler for its efficiency, I don't use any
of its non-standard language constructs, again for portability.
The most fundamental design decision had to do with the method of
representing 36-bit words on a 32-bit architecture. I wound up coding
around a halfword-based scheme, with each 18-bit PDP-10 halfword
right-justified in a 32-bit host word; thus each PDP-10 word uses 8
octets. The same format is used for memory, ACs, and disk storage;
basically I traded off space for speed.
On a machine with a word size larger than 36, or a C compiler that
supported an equivalent integer type (such as double-word ints), many
things become easier, and I'd want to re-do a fair amount of the
arithmetic code. Not because the current version won't work -- it will
-- but because it won't be as efficient. I decided early on that the
differences between optimal code on a 32-bit and +36-bit machine were
just too great to easily combine with the primitive tools available in
C.
The arithmetic emulation relies only on well-defined native integer
operations; native floating point is never used, both because it is
non-portable (formats vary) and because it is very difficult to
precisely emulate the PDP-10's behavior without actually carrying out
the same internal operations "by hand". This is by far the slowest
part of the KLH10. I checked it out by compiling it on a real 20
(using KCC, of course!) and running it for hours under a test program
that generated various operand bit patterns and compared the results
with those for real instructions.
The current implementation is being used as a testbed for threads, and
includes code for both a non-threaded and threaded version. (I
figured, what better test of software parallelism than to emulate
hardware parallelism?) This means that running on a true
multi-processor platform could produce somewhat better performance,
although the main APR execution thread is still serial and will impose
an upper bound on the speedup. Let's not talk about pipelining just
now.
To clear up one thing that has caused confusion: the emulator is *not*
running standalone on my Sparc. Except for the net device it uses the
usual Unix system calls and burns 100% of the CPU, running flat out. I
don't really notice it since the amount of CPU I use most of the time
is typically a negligible fraction of the Sparc's capability; for
example, I'm writing this note in one window while ITS runs in the
other, and everything's cool.
The NEED for SPEED:
------------------
In the summary I mentioned a speed of 0.2 MIPS, or about 5 usec
per instruction. This is probably the number people are most avidly
interested in, but at the same time it's also one of the hardest to
measure. PDP-10 speeds have always been tricky, mainly because it all
depends on the precise mix of instructions and operands. Now it's even
fuzzier because so much of the KLH10 is variable.
Of course, the host platform speed is an overriding factor. But I've
seen that even minor changes in the main loop can produce noticeable
differences in response time, as can the exact nature of memory
references. For example, the SPARC is a register-window machine and
it's faster to pass arguments to functions than to set and read global
variables; it's also faster to use C structure members than globals!
Another machine could have precisely the opposite behavior. I should
add here that the compiler is also tremendously important; using
GCC results in code that is 40% faster than Sun's CC! Yow!
Anyway, I haven't really buckled down and tried to tune or measure its
performance, so take the 0.2 MIPS loosely. My back-of-the-envelope
calculations before I started suggested that an assembler-coded SPARC
implementation could achieve a KA performance level; the current C
version appears to get perhaps half that speed. Assembling the entire
ITS OS takes about 26 minutes of real time, but I don't know if anyone
remembers how long it took on a real KS10, much less a KA10.
The Sparc is already a slowpoke compared with some of the new
workstations and chipsets coming out, so it's just a matter of time
before someone cracks the KS10 speed limit on reasonably cheap
personal hardware. I can't help but wonder if might be worth paying
serious attention to a high-speed version, one that would represent a
cost-effective solution for those places still committed to PDP-10
software. Systems Concepts probably doesn't need to worry -- yet!
Future improvements:
-------------------
The obvious one is speed. Then more machine variants, more
devices. More instrumentation & profiling. A nicely packaged
distribution with your choice of OS and initial filesystem included.
The usual embellishments. Whatever people suggest.
There's also the possibility of evolving a new virtual machine, one
which realizes more closely whatever the ideal PDP-10 is conceived to
be. (That itself is an interesting question.) For example, the real
KS10 ITS microcode does not actually support JPC, which was a feature
of Holloway's MAC-10 pager; the KLH10 does it trivially and in that
sense is more than a simple KS10. Its pager could support 2048K as
easily as 512K. And so on, all of which implies reconfiguring a real OS
to run on an unreal machine. The first step down this road has already
been taken with NX ITS, assembled to use a non-existent net interface.
And I've always thought it would be lovely to have a window displaying
a KA-style console panel with a full bank of lights and clickable
switches. I know the KS10 never had one, but that doesn't mean it has
to stay that way, and besides, the KL10 cheated with a 11/40 panel, so
it's down to either the KA or KI. Of course it's just for fun, what
else is this all about?
Final thoughts:
--------------
I was going to close with the last paragraph, but realized
there's one more thing I want to say. It's just that, um, well,
this will sound silly, but it feels so... weird? ... eerie?
... just plain literally *mind-blowing* to watch this system boot up
and run happily, utterly unaware that it's not on a real machine, or
that anything odd happened since the last time it ran, or that its
earthly incarnation of a noisy roomful of huge cabinets and washing
machines is now entirely self-contained within a small innocuous pizza
box holding up my ITS manuals. Do systems have wathans? I've gotten a
bit more used to it, but every now and then I still sit back, realize
once again what the hell is going on, and hold on to something while
the chills pass. I didn't expect this at all. A side effect of being
imprinted at a tender young age, or something...
--Ken

1269
doc/install.txt Normal file
View File

File diff suppressed because it is too large Load Diff

191
doc/kldiff.txt Normal file
View File

@@ -0,0 +1,191 @@
/* KLDIFF.TXT - Differences between KLH10 and KL10
*/
/* $Id: kldiff.txt,v 2.3 2001/11/10 21:24:21 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 attempts to summarize the known visible differences between
the KLH10 emulator's "KN10" processor and an actual DEC KL10,
specifically a Model B CPU running version 442 of the microcode.
It is important to remember that it is very difficult to stumble
across these differences unless you are looking hard. As a practical
matter, for users there is far less of a difference between the KN10
and a KL10 than there were between different releases of the KL10
microcode.
As one illustration of this point, DEC diagnostics are mentioned in
several places, but their reports must be taken with large grains of
salt. Many stopped working for the latest KL10s, and some only worked
when loaded with older microcode; in order to run those, the KLH10 must
be built with a "hybrid" KN10.
USER MODE DIFFERENCES
=====================
[U1] No Public mode.
The KN10 does not implement public mode; it was considered to
have little real use (the KS10 does not implement it), and would make
execution slower. This is discussed in more detail in the exec mode
section.
[U2] Floating point results with normalized operands.
Some floating-point results may differ by a single low-order
bit, particularly FDV with negative operands.
This is noticed by the diagnostic DFKCA.
[U3] Floating point results with unnormalized operands.
There are certain cases where unnormalized operands may
produce different results in the low-order bits, apparently due to
sloppiness in the KL10 hardware.
DFDV is the most notable example; when given wildly
unnormalized operands, some low-order bits are cleared by the KN10 to
produce logically correct results, but these same bits are filled with
mysterious garbage on the KL10. Note that the same operands on a KS10
produce "clean" results that exactly match those of the KN10!
Diagnostics don't notice this as they never use unnormalized
operands.
[U4] Extended instruction set (string ops)
These instructions have so many undefined aspects, and their
microcode implementation changed so often, that it is difficult to say
much here beyond acknowledging that certain esoteric failure cases may
well produce different results. "Normal" cases should all be
identical.
The diagnostic DFKCC detects no differences except for the
intermediate AC values of an interrupted CVTBDx, where a KL10 saves a
fractional quantity and the KN10 saves an integral quantity; but
nothing should actually be examining this intermediate value.
[U5] Traps (1,2,3), PC, Page Fault.
Traps on the KN10 are handled in subtly different ways than
traps on a KL10. For the most part there is no observable difference,
but peculiar cases do exist.
In general, the PC seen by a trap instruction may be different
from that on a KL10 if the offending instruction (which set the trap
flags) was a jump or skip. However, either of these are problematical
for a KL10 trap handler as well.
On the KN10, an instruction that sets any trap flags will
trap as soon as the instruction is complete, with the PC pointing to
the next instruction (and backed up before executing the trap
instruction).
This differs from a KL10 where it is possible for the
next-instruction c(PC) fetch to cause a page fault before the trap is
handled. The diagnostic DFKEA notices this. N.B.: This is not the
same as a page fault during execution of either the offending
instruction or the trap instruction, both of which are correctly
handled.
EXEC MODE DIFFERENCES
=====================
Most of these are hidden from the user altogether.
[E1] No Public or Supervisor modes.
The KN10 does not implement public mode; it was considered to
have little real use, and would make execution slower. The KN10 does
keep the Public bit in page map entries, but never actually sets
Public when fetching instructions from a Public page, nor does it
verify whether an operation is permitted if in Public/Supervisor mode.
Note that the DEC KS10 does not implement this either, so the
functionality is presumably not terribly important.
However, this confuses and ultimately crashes the diagnostic
DFKEB which tests specifically for the operational differences between
user, public, kernel, and supervisor modes.
[E2] No Previous-Context-Public PC flag.
The KN10 always treats PC flag bit 0 as being "overflow",
which means that anything that stores the PC flags in exec mode will
get the state of the overflow flag, rather than the PCP flag as on a
real KL10.
This mildly irritates some diagnostics when run in exec mode,
specifically DFKCA, DFKCB, and DFKDA, which expect bit 0 to stay clear.
[E4] Page fail in interrupt instruction (IO Page Fail)
The KN10 implements the documented behavior for this, which
is to trigger an IO-Page-Fail interrupt rather than taking a page fail
trap. However, according to the diagnostic DFKEA, a real KL10 should
take the trap, contrary to the Processor Reference Manual (p.3-65).
It is unclear whether DFKEA's interpretation is correct or corresponds
to old versions of the KL10. In any case, a monitor should never let
this happen in the first place.
[E5] PXCT in non-zero section
The problem is that no one is sure any more exactly how PXCT
is *supposed* to work, or even how it *does* work on the KL10! The
original KN10 implementation conformed to the available
documentation, and passed the PXCT diagnostic DFKEC perfectly, but
caused page faults when used with real monitors and certain user
programs. The current modified implementation works for all TOPS-10
and TOPS-20 software tested to date, but now triggers two failure
cases in DFKEC.
CPU HARDWARE DIFFERENCES
========================
There are several things about the KL10 hardware that are not
implemented at all in the KN10, either because the features are
never used by a monitor or would be too impractical to implement.
Without going into unnecessary detail, here are the main items.
[C1] Interrupt Instructions - no BLKI, BLKO
Only JSR and XPCW are supported.
(plus AOSE, SKIPE, and JSP to keep diagnostics happy).
[C2] Interrupt Functions - only those needed are implemented.
[C3] CONI/CONO PI, - bits <18:20> not implemented.
The diagnostic DFKDA notices this.
[C4] No Cache
All of the "Sweep Cache" instructions are no-ops that merely
clear Sweep Busy and set Sweep Done. The cache strategy bits <18:19>
in a CONI/CONO PAG, are ignored.
[C5] No Address Break
DATAO APR, remembers the break information for a DATAI APR,
but the actual functionality is not implemented, and will probably
never be, for efficiency reasons.
The diagnostic DFKDA notices this.
[C6] Time Base doubleword - not updated except by RDTIME.
[C7] Interval Counter - not as precise.
[C8] No Execution Account counter
[C9] No Memory Account counter
[C10] No Performance Analysis counter
[C11] SBDIAG partially implemented
Only the SBDIAG functions necessary to keep the TOPS-10 and TOPS-20
monitors happy are implemented. The emulated machine pretends to
have a MF20 that responds to the entire range of 22-bit physical
memory (4096K).

93
doc/klt10.txt Normal file
View File

@@ -0,0 +1,93 @@
/* KLT10.TXT - KL TOPS-10 system startup on KLH10
*/
/* $Id: klt10.txt,v 2.3 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 1997, 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.
*/
[NOTE: Eventually this will describe how to install a TOPS-10 system
from an installation tape. For the time being it merely describes
startup using a ready-made filesystem that I may someday package
for distribution. Four monitors are included:
704NON.EXE - TOPS-10 V7.04 no network, won't try to load KLNI.
704DCN.EXE - TOPS-10 V7.04 with DECnet and LAT
704LAT.EXE - TOPS-10 V7.04 with just LAT (untested)
SYSTEM.EXE - TOPS-10 V7.04 for the KS.
You will need to specify an appropriate monitor from this list when
prompted by BOOT>.]
In the transcript that follows, all notes are prefaced by
triple semicolons (;;;), and user input is presented in lowercase
where possible -- note that the monitor sometimes echoes typein in
uppercase. Where there might be some confusion, a note such as "Type
CR" will identify what you need to type.
-----------------------------------------
;;; Here we go...
;;;
% ./kn10-kl klt10-img.ini ;;; Invoke KLH10
[usual output banners]
KLH10> ; KLH10 configuration for TOPS-10 test system
KLH10>
KLH10> ; DTE requires ackdly to avoid T10 race condition
KLH10> devdef dte0 200 dte master ackdly=5
KLH10> devdef rh0 540 rh20
KLH10> devdef rh1 544 rh20
KLH10> devdef dsk0 rh0.0 rp type=rp06 sn=4747 format=raw path=T10.RP06.0
KLH10> devdef dsk1 rh0.1 rp type=rp06 sn=1026 format=raw path=T10.RP06.1
KLH10> devdef mta0 rh1.0 tm02 type=TU77 fmtr=TM03
KLH10>
KLH10> ; NI: new param "c3dly" to see if it helps T10.
KLH10> ; NI: new param "rdtmo" to avoid system hangups with OSF/1 V3.0
KLH10> ;
KLH10> ; Decnet node TWONKY, 9.429
KLH10> devdef ni0 564 ni20 dedic=0 decnet=1 doarp=0 enaddr=aa:00:04:00:ad:25 dpdelay=12 c3dly=2 rdtmo=3
KLH10>
KLH10> load klboot.exe
Using word format "c36"...
Loaded "klboot.exe":
Format: DEC-PEXE
Data: 0, Symwds: 0, Low: 01000000, High: 00, Startaddress: 0703667 Entvec: 00 wds at 00
KLH10> [EOF on klt10-img.ini]
KLH10> go ;;; Type "go" to start KN10!
Starting KN10 at loc 0703667...
BOOT V4(100)
BOOT>704non ;;; Enter desired monitor, then CR
[Loading from DSKA:704NON.EXE[1,4]]
TOPS-10 704 No Network 11-Nov-93
Why reload: sa ;;; "sa" or whatever
Date: ;;; Just enter CR
Time: ;;; Just enter CR
Startup option: no ;;; Example; could say "go".
[Rebuilding the system search list from the HOM blocks]
[Rebuilding the active swapping list from the HOM blocks]
[Rebuilding the system dump list from the HOM blocks]
TOPS-10 704 No Network Thursday 24-Apr-97 3:00:25
.log 1,2/by ;;; Log in like this to bypass accting
Job 1 TOPS-10 704 No Network CTY
03:07 24-Apr-97 Thursday
. ;;; Ready to futz around...
;;; ... do whatever, then when OK to bring down:
.[HALTED: FE interrupt] ;;; Type ^\ (CTRL-\) to return to KLH10
KLH10> q ;;; OK to quit KLH10 now! TOPS-10 not fussy.
Are you sure you want to quit? [Confirm]
Shutting down...Bye!
% ;;; Back at unix shell prompt

628
doc/klt20.txt Normal file
View File

@@ -0,0 +1,628 @@
/* KLT20.TXT - KL TOPS-20 system installation on KLH10
*/
/* $Id: klt20.txt,v 2.5 2001/11/19 12:14:54 klh Exp $
*/
/* Copyright © 1997, 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.
*/
Once you have installed the KLH10 binaries, you will need to
install a PDP-10 operating system on the KN10's virtual disks. This
file documents the basic procedure for TOPS-20 on a KL10B.
The TOPS-20 installation procedures are described in a Digital
document titled "TOPS-20 KL Model B Installation Guide", available
online as a file called "install.mem" from some sites. Some of the
steps on a KN10 (aside from the obvious lack of hardware) may be
different, however.
You will need an "installation" tape or tape image to get started, and
almost certainly will want to install the accompanying sources and
tools. You should already have a valid TOPS-20 license (personal or
otherwise) in order to use them.
These are the tapes containing the last known DEC TOPS-20 distribution
for the KL10B (DEC-2065), which was TOPS-20 V7.0:
BB-H137F-BM TOPS-20 V7.0 INSTL 16MT9
BB-EV83B-BM TCP/IP-20 V4.0 DISTR 16MT9
BB-H138F-BM T20 V7.0 DIST 16MT9 TAPE 1OF2
BB-LW55A-BM T20 V7.0 DIST 16MT9 TAPE 2OF2
BB-M780D-SM TOPS-20 V7.0 MONITOR SRC 16MT
BB-GS97B-SM TOPS-20 EXEC SRC 16MT9
BB-M080Z-SM T20 V7.0 #04 MON SRC MOD 16MT
BB-M081Z-SM T20 V7.0 #04 EXEC SRC MOD 16M
BB-PENEA-BM TOPS-20 V7.0 TSU04 TP 1 OF 2
BB-KL11M-BM TOPS-20 V7.0 TSU04 TP 2 OF 2
BB-M836D-BM TOPS-20 V7.0 TOOLS 16MT9
It should be possible to obtain these from www.trailing-edge.com. In
particular, start with the first of these, which is the installation
tape:
ftp://ftp.trailing-edge.com/pub/pdp10/bb-h137f-bm.tap.gz
The script that follows assumes you have uncompressed this into
"bb-h137f-bm.tap" in your $KLH10_HOME.
NOTE: the installation tape does not contain a TCP/IP monitor
image. Before you can use the network, you will need to also restore
the files from the tape "BB-EV83B-BM TCP/IP-20 V4.0 DISTR 16MT9"
(there was more than one version; only the latest has monitor
images).
In the transcript that follows, all notes are prefaced by triple
semicolons (;;;), and user input is presented in lowercase where
possible -- note that the monitor sometimes echoes typein in
uppercase. Where there might be some confusion, a note such as "Type
CR" will identify what you need to type.
=====================================================
QUICK SUMMARY:
$ ./kn10-kl inst-klt20.ini ;;; Configure and load tape bootstrap
KLH10> go
MTBOOT>/l ;;; Load rest of monitor
MTBOOT>/g143 ;;; Start at FS-creation entry point
;;; After quiets down, ^C to get MEXEC, and carry on
;;; After installation finished:
$ ./kn10-kl klt20.ini ;;; Configure and load disk bootstrap
KLH10> go
BOOT> ;;; Type CR to load and start MONITR.EXE
=====================================================
FULL SCRIPT:
;;; Here we go...
;;;
$ ./kn10-kl inst-klt20.ini ;;; You type this
KLH10 V2.0 beta (MyKL) built Nov 10 2001 02:14:29
Copyright © 2001 Kenneth L. Harrenstien -- All Rights Reserved.
This program comes "AS IS" with ABSOLUTELY NO WARRANTY.
Compiled for LINUX on I386 with word model USEHWD
Emulated config:
CPU: KL10-extend SYS: T20 Pager: KL APRID: 1
Memory: 8192 pages of 512 words (SHARED)
Time interval: INTRP Base: OSGET
Interval default: 60Hz
Internal clock: OSINT
Other: MCA25 JPC DEBUG PCCACHE CTYINT EVHINT
Devices: DTE RH20 RPXX(DP) TM03(DP) NI20(DP)
[MEM: Allocating 8192 pages shared memory, clearing...done]
KLH10> ; Sample KLH10.INI for initial installation
KLH10>
KLH10> ; Define basic device config - one DTE, one disk, one tape.
KLH10> ; Use two RH20s because TOPS-10 doesn't like mixing disk and tape on
KLH10> ; the same controller (TOPS-20 is fine).
KLH10>
KLH10> devdef dte0 200 dte master
KLH10> devdef rh0 540 rh20
KLH10> devdef rh1 544 rh20
KLH10> devdef dsk0 rh0.0 rp type=rp06 format=dbd9
[Creating RP06 disk file "RH20.RP06.1"]
KLH10> devdef mta0 rh1.0 tm03 type=tu45
KLH10>
KLH10> ; Need KLNI to avoid LAPRBF BUGCHKs - use valid address if known
KLH10> ;
KLH10> devdef ni0 564 ni20 ipaddr=10.0.0.51
KLH10>
KLH10> ; Mount installation tape (no ucode or boot to skip)
KLH10> devmount mta0 bb-h137f-bm.tap
Mount requested: "bb-h137f-bm.tap"
KLH10>
KLH10> ; Load tape bootstrap directly
KLH10> load mtboot.sav
Using word format "c36"...
Loaded "mtboot.sav":
Format: DEC-CSAV
Data: 4067, Symwds: 0, Low: 040000, High: 054641, Startaddress: 040000
Entvec: JRST (120 ST: 0, 124 RE: 0, 137 VR: 0,,0)
KLH10>
KLH10> ; Now ready to GO
KLH10> [EOF on inst-klt20.ini]
KLH10>
[mta0: Tape online] ;;; Init file now done.
KLH10> go ;;; Boot is loaded, type "go" to start KN10!
Starting KN10 at loc 040000...
BOOT V11.0(315)
MTBOOT>/l ;;; Type "/l" to load monitor
[BOOT: Loading] [OK]
MTBOOT>/g143 ;;; Now type "/g143" to start monitor
;;; at the filesystem-create entry address.
;;; Answer the following questions as shown,
;;; unless you know what you're doing.
[FOR ADDITIONAL INFORMATION TYPE "?" TO ANY OF THE FOLLOWING QUESTIONS.]
DO YOU WANT TO REPLACE THE FILE SYSTEM ON THE SYSTEM STRUCTURE? Y ;;;
DO YOU WANT TO DEFINE THE SYSTEM STRUCTURE? Y ;;;
HOW MANY PACKS ARE IN THIS STRUCTURE: 1 ;;;
ON WHICH "CHANNEL,CONTROLLER,UNIT" IS LOGICAL PACK # 0 MOUNTED? 0,-1,0 ;;;
DO YOU WANT THE DEFAULT SWAPPING SPACE? Y ;;;
DO YOU WANT THE DEFAULT SIZE FRONT END FILE SYSTEM? Y ;;;
DO YOU WANT THE DEFAULT SIZE BOOTSTRAP AREA? Y ;;;
DO YOU WANT TO ENABLE PASSWORD ENCRYPTION FOR THE SYSTEM STRUCTURE? Y ;;;
WHAT IS THE NAME OF THIS STRUCTURE? PS ;;;
[STRUCTURE "PS" SUCCESSFULLY DEFINED]
[PS MOUNTED]
?PS UNIT 0 HAS NO BAT BLOCKS.
DO YOU WANT TO WRITE A SET OF PROTOTYPE BAT BLOCKS? Y
%%NO SETSPD.
System restarting, wait...
DATE AND TIME IS: SATURDAY, 29-SEPTEMBER-2001 10:40PM
WHY RELOAD? NEW ;;; Type "new" or whatever.
PROBLEM WITH <SYSTEM>ACCOUNTS-TABLE.BIN
CANNOT FIND ERROR MESSAGE FILE - ACCOUNT VALIDATION IS DISABLED
RUNNING DDMP
NO SYSJOB
;;; Unless you have fixed up the NI20 definition
;;; in the klh10.ini file, you will probably see
;;; a few KNI BUGCHKs which are harmless at this
;;; point, such as the following:
********************
*BUGCHK "KNICFF" AT 29-SEP-2001 22:40:28
*PHYKNI - CANNOT RELOAD THE KLNI
*JOB: 0, USER: OPERATOR
*ADDITIONAL DATA: 600104
********************
;;; After you get "NO SYSJOB" you can type either
;;; a CR or ^C to get to the MEXEC prompt ("MX>").
NO EXEC
MX>GET FILE MTA0: ;;; Type just "g" then "mta0:" and CR.
? ;;; Monitor will read an EOF and do nothing.
MX>GET FILE MTA0: ;;; Repeat, to read EXEC.EXE from tape.
MX>START ;;; Type just "s" then CR.
TOPS-20 Command processor 7(4143)
@TER NO RAI ;;; Success! Let's stop uppercasing our input,
@ena ;;; and must get enabled.
$run mta0: ;;; Now read and start DLUSER.EXE from tape.
DLUSER>load mta0: ;;; Now read DLUSER data to set up directories.
DONE.
DLUSER>exit ;;; Get out.
$run mta0: ;;; Now read and start DUMPER.EXE from tape.
DUMPER>tape mta0: ;;; Point to tape drive and start restoring files!
;;; Note in the next command it is important to
;;; explicitly specify "<system>", otherwise the
;;; files will be restored into "<NEW-SYSTEM>".
DUMPER>restore <*>*.*.* (TO) <system>*.*.*
Saveset "SYSTEM Files for TOPS-20 V7.0" 22-Jun-88 2035
Loading files into PS:<SYSTEM>
End of Saveset.
Total files restored: 26
Total pages restored: 1765
;;; Note in the next command it is important to
;;; explicitly specify "<subsys>", otherwise the
;;; files will be restored into "<NEW-SUBSYS>".
DUMPER>restore <*>*.*.* (TO) <subsys>*.*.*
Saveset "SUBSYS Files for TOPS-20 V7.0" 22-Jun-88 2037
Loading files into PS:<SUBSYS>
End of Saveset.
Total files restored: 176
Total pages restored: 4535
;;; Note in the next command it is important to
;;; explicitly specify "<subsys>", otherwise it
;;; will try and fail to restore the files into
;;; "<GALAXY-SUBSYS>".
DUMPER>restore <*>*.*.* (TO) <subsys>*.*.*
Saveset "GALAXY SUBSYS Files for TOPS-20 V7.0" 22-Jun-88 2043
Loading files into PS:<SUBSYS>
End of Saveset.
Total files restored: 25
Total pages restored: 586
;;; The last saveset is optional and can be skipped.
;;; If you want the UETP stuff, do:
DUMPER>
DUMPER>restore <*>*.*.* (TO) <*>*.*.*
Loading files into PS:<UETP.LIB>
End of Saveset.
Total files restored: 54
Total pages restored: 477
DUMPER>exit ;;; Done, with or without UETP.
$conn <system>
$vdir ;;; Check out what we have in <SYSTEM>
PS:<SYSTEM>
2060-MONBIG.EXE.1;P777752 597 305664(36) 26-May-88 17:05:33 BROOKS
2060-MONMAX.EXE.1;P777752 597 305664(36) 26-May-88 17:28:27 BROOKS
7-PTYCON.ATO.1;P777752 1 823(7) 2-Jun-88 22:29:16 BROOKS
7-SETSPD.EXE.1;P777752 14 7168(36) 28-May-88 02:21:05 BROOKS
7-SYSJOB.EXE.1;P777752 7 3584(36) 28-May-88 03:11:07 BROOKS
.RUN.1;P777752 1 158(7) 2-Jun-88 21:41:35 BROOKS
BOOT.EXB.1;P777752 12 11658(18) 27-May-88 21:36:22 BROOKS
BUGS.MAC.1;P777752 155 395399(7) 23-May-88 18:14:48 BROOKS
BUGSTRINGS.TXT.1;P777752 22 54680(7) 26-May-88 17:28:13 BROOKS
CHECKD.EXE.1;P777752 22 11264(36) 27-May-88 21:42:19 BROOKS
ERRMES.BIN.1;P777752 24 12013(36) 28-May-88 01:48:31 BROOKS
EXEC.EXE.1;P777752 125 64000(36) 27-May-88 11:40:08 BROOKS
FEDDT.EXE.1;P777752 9 4608(36) 14-Feb-79 20:37:17 BROOKS
IPALOD.EXE.1;P777752 28 14336(36) 28-May-88 00:53:56 BROOKS
KNILDR.EXE.1;P777752 26 13312(36) 28-May-88 00:58:59 BROOKS
MTBOOT.EXB.1;P777752 11 10247(18) 27-May-88 21:37:31 BROOKS
PROGRAM-NAME-CACHE.TXT.1;P777752 1 78(7) 9-Mar-81 15:24:00 BROOKS
RP2DBT.EXB.1;P777752 18 17687(18) 27-May-88 21:38:15 BROOKS
RP2MBT.EXB.1;P777752 16 16276(18) 27-May-88 21:39:26 BROOKS
RSX20F.MAP.1;P777752 29 74007(7) 22-Mar-88 14:17:44 BROOKS
SYSJOB.HLP.1;P777752 3 5679(7) 29-Mar-82 15:47:02 BROOKS
SYSTEM.CMD.1;P777752 1 598(7) 24-Feb-84 20:01:23 BROOKS
TGHA.EXE.1;P777752 29 14848(36) 28-May-88 03:20:32 BROOKS
.HLP.1;P777752 1 214(7) 11-Nov-86 20:49:44 BROOKS
TOPS20.BWR.1;P777752 3 1425(36) 1-Jun-88 18:17:20 BROOKS
.DOC.1;P777752 13 6432(36) 21-Jun-88 15:25:11 LOMARTIRE
Total of 1765 pages in 26 files
$
$ ;;; For convenience, now is a good time to
;;; make MONITR.EXE be your desired monitor!
$renAME (EXISTING FILE) 2060-monbig.EXE.* (TO BE) monitr.exe
2060-MONBIG.EXE.1 => MONITR.EXE.1 [OK]
$^Ecease now ;;; OK, now we can try a disk boot.
TOPS20 Will be shut down IMMEDIATELY
[Confirm]
$
[Timesharing is over]
OPERATOR - Wait for the message "Shutdown complete" before
entering commands to PARSER.
Shutdown complete ;;; When you see this, type ^\ (CTRL-\)
[HALTED: FE interrupt] ;;; to return to KLH10
KLH10> shutdown ;;; Then give "shutdown" command.
Continuing KN10 at loc 01047523...
**HALTED**
[HALTED: Program Halt, PC = 1050257]
KLH10> q ;;; OK to quit KLH10 now!
Are you sure you want to quit? [Confirm]
Shutting down...Bye!
$ ;;; Back at unix shell prompt
$
$ ./kn10-kl klt20.ini ;;; Fire it up again, with different ini file
KLH10 V2.0 beta (MyKL) built Nov 10 2001 02:14:29
Copyright © 2001 Kenneth L. Harrenstien -- All Rights Reserved.
This program comes "AS IS" with ABSOLUTELY NO WARRANTY.
Compiled for LINUX on I386 with word model USEHWD
Emulated config:
CPU: KL10-extend SYS: T20 Pager: KL APRID: 1
Memory: 8192 pages of 512 words (SHARED)
Time interval: INTRP Base: OSGET
Interval default: 60Hz
Internal clock: OSINT
Other: MCA25 JPC DEBUG PCCACHE CTYINT EVHINT
Devices: DTE RH20 RPXX(DP) TM03(DP) NI20(DP)
[MEM: Allocating 8192 pages shared memory, clearing...done]
KLH10> ; Sample KLH10.INI for initial installation
KLH10>
KLH10> ; Define basic device config - one DTE, one disk, one tape.
KLH10> ; Use two RH20s because TOPS-10 doesn't like mixing disk and tape on
KLH10> ; the same controller (TOPS-20 is fine).
KLH10>
KLH10> devdef dte0 200 dte master
KLH10> devdef rh0 540 rh20
KLH10> devdef rh1 544 rh20
KLH10> devdef dsk0 rh0.0 rp type=rp06 format=dbd9
KLH10> devdef mta0 rh1.0 tm03 type=tu45
KLH10>
KLH10> ; Need KLNI to avoid LAPRBF BUGCHKs - use valid address if known
KLH10> ;
KLH10> devdef ni0 564 ni20 ipaddr=10.0.0.51
KLH10>
KLH10> ; Load disk bootstrap directly
KLH10> load boot.sav
Using word format "c36"...
Loaded "boot.sav":
Format: DEC-CSAV
Data: 4630, Symwds: 0, Low: 040000, High: 054641, Startaddress: 040000
Entvec: JRST (120 ST: 0, 124 RE: 0, 137 VR: 0,,0)
KLH10>
KLH10> ; Now ready to GO
KLH10> [EOF on klt20.ini]
KLH10> go
Starting KN10 at loc 040000...
BOOT V11.0(315)
BOOT> ;;; Type just CR, will default to MONITR.EXE
[BOOT: Loading] [OK]
[PS MOUNTED]
System restarting, wait...
DATE AND TIME IS: SATURDAY, 29-SEPTEMBER-2001 10:46PM
WHY RELOAD? NEW ;;; Or whatever reason you want
PROBLEM WITH <SYSTEM>ACCOUNTS-TABLE.BIN
CANNOT GET A JFN FOR <SYSTEM>ACCOUNTS-TABLE.BIN - ACCOUNT VALIDATION IS
DISABLED
RUN CHECKD? N ;;; Type "n". Shouldn't be necessary yet.
RUNNING DDMP
SYSJOB 7(78) STARTED AT 29-SEP-2001 2246
RUN SYS:INFO
RUN SYS:MAPPER
JOB 0 /LOG OPERATOR XX OPERATOR
ENA
^ESET LOGIN PSEUDO
^ESET LOGIN CONSOLE
^ESET OPERATOR
PTYCON
GET SYSTEM:7-PTYCON.ATO
/
SJ 0: @LOG OPERATOR OPERATOR
SJ 0: JOB 1 ON TTY172 29-SEP-2001 22:46:51, LAST LOGIN NEVER
SJ 0:
[dpni20: Using default interface "eth0"]
[KNILDR: LOADING MICROCODE VERSION 1(172) INTO ETHERNET CHANNEL 0
]
@ENA
SJ 0: $^ESET LOGIN PSEUDO
SJ 0: $^ESET LOGIN CONSOLE
SJ 0: $^ESET OPERATOR
SJ 0: $PTYCON
SJ 0: PTYCON> GET SYSTEM:7-PTYCON.ATO
SJ 0: PTYCON> SILENCE
SJ 0: PTYCON> W ALL
SJ 0: GAL(0) 2 OPERATOR EXEC TI 0:0:0
SJ 0: BAT(1) 3 OPERATOR EXEC TI 0:0:0
SJ 0: NEB(2) 4 OPERATOR EXEC TI 0:0:0
SJ 0: OPR(3) 5 OPERATOR EXEC TI 0:0:0
SJ 0: MAILS(4) 6 OPERATOR MX RN 0:0:0
SJ 0: PTYCON> CONN OPR
SJ 0: [CONNECTED TO SUBJOB OPR(3)]
;;; When things seem quiet, type CR to get an EXEC.
TOPS-20 Big System, TOPS-20 Monitor 7(21017)
@TER NO RAI
@log operator ;;; Try logging in, pwd "DEC-20"
Job 7 on TTY145 29-Sep-2001 22:47:24, Last Login 29-Sep-2001 22:46:57
@ena
$ ;;; Now do whatever you wish...
=====================================================
Other things you probably want to do at some point:
$copy tty: monnam.txt ;;; Set the system name
MyKL TOPS-20 System
^Z
$copy tty: 4-1-config.cmd ;;; Set timezone here for now
timezone 8
^Z
$^Ecreate <operator> ;;; Change operator password
$$password tqbfjotld ;;; (use something better)
$$
$^Ecreate <me> ;;; Create your account
$$password nittfagmtc2taotp ;;; (or something better)
$$wheel
$$working 10000
$$permanent 10000
$$
$
There are large manuals devoted to TOPS-20 system maintenance, but
this is enough to make you dangerous.
TOPS-20 TCP/IP INSTALLATION
===========================
This aspect is probably the one that many KLH10 users will be
most interested in. Unfortunately I ran out of time to provide a full
script, but this should be enough to get you going:
(1) Install all of the V7 install tape (as above)
(2) Restore all files from the following tape:
BB-EV83B-BM TCP/IP-20 V4.0 DISTR 16MT9
This one is a pain, because the DLUSER.DAT on the install tape doesn't
set up the necessary directories beforehand, so you will have to create
them all by hand (make sure they are files-only!).
(3) Assign a valid IP address for your system, if you don't already have
one. This should be something consistent with your physical subnet.
(4) Create the file <SYSTEM>INTERNET.ADDRESS with either an editor or
a COPY from the TTY:, in the following format (replacing the
"192 168 0 201" with your desired IP address):
$vd internET.*.*
PS:<SYSTEM>
INTERNET.ADDRESS.1;P777752 1 57(7) 5-Oct-2001 22:06:55 OPERATOR
$ty internET.ADDRESS.1
IPNI#0,192 168 0 201,PACKET-SIZE:1500,DEFAULT,PREFERRED
$
Keep the packet size at 1500. I found it set to 1504 once and
that was breaking things.
(4) Now reboot, with this devdefine added to your KLH10 config file:
devdef ni0 564 ni20 ipaddr=192.168.0.201
(Again, use your correct IP address here)
(5) Manually specify this to the BOOT> prompt:
<NEW-SYSTEM>AN-MONMAX
Or you can just copy or rename that file to <SYSTEM>MONITR.EXE to
make it the default.
(6) After system comes up, telnet in from ANOTHER machine. Depending on
your platform it's unlikely you will be able to telnet in from the
same host that the emulator is running on, unless you are using
a separate dedicated interface.
If this succeeds, take a break and have a <favorite beverage here>.
(7) About now you will start to get really annoyed by periodic bleats that
look like this:
SJ 0: [SCHEDULER]: Waiting for UPS:
SJ 0: **** OPR(3) 22:18:48 ****
SJ 0: **** MAILS(4) 22:19:48 ****
This can be permanently turned off by removing its invocation from
the 7-PTYCON.ATO startup file, but a good temporary fix is simply
to kill the offending job.
Do a SYS to find the job called MX, then forcibly log it out:
$sys
Fri 5-Oct-2001 23:05:45 Up 0:53:26
0+8 Jobs Load av 0.03 0.03 0.03
Job Line Program User Origin
1 206 PTYCON OPERATOR
2 207 EXEC OPERATOR
3 210 EXEC OPERATOR
4 211 EXEC OPERATOR
5 212 EXEC OPERATOR
6 213 MX OPERATOR
7* 205 SYSTAT OPERATOR
8 270 EXEC OPERATOR 192.168.0.33(TCP)
$
$logo 6
User OPERATOR on TTY213, running MX
[Confirm]
$
TOPS-20 TCP/IP - OTHER NOTES
============================
These are miscellaneous notes from my files. I have not verified
whether they apply to the vanilla DEC TCP/IP system.
SYSTEM:KNILDR.EXE -- utility that can be used to restart the NI20.
The useful commands are "HALT 0" and "START 0" which will stop and
start the KLNI in case something went wrong during startup (timing
races) or the KLH10 DPNI20 subprocess needs to be replaced with a new
version without bringing the system down. Run this from the console,
or you'll saw off the branch you're sitting on.
---- SYSTEM:INTERNET.ADDRESS -----
---- Read on system startup; no provision I can see for re-reading any
other time.
;;;Internet addresses for system
IPNI#0, 16 151 16 13,DEFAULT,PREFERRED,PACKET-SIZE:1504
---- SYSTEM:INTERNET.GATEWAYS -----
---- Read on system startup, also with "^Einit gateways"
; IP addresses of local prime gateway; if only one, not clear if
; its args matter, but provide something plausible.
PRIME 192 33 33 3, 128 18 1 1
---- SYSTEM:HOSTS.TXT -----
---- Read on system startup, also with "^Einit hosts"
; Arbitrarily long, but basically defines local nets and hosts
; we need to know about in absence of DNS (CHIVES) info.
---- SYSTEM:HOSTNAME.TXT -----
---- Can't find anything in the monitor that reads this file, but this
---- should be similar to MONNAM.TXT except for containing the FULL domain
---- name of the system. E.g.:
BOOTSTRAP.SRI.COM
---- SYSTEM:MONNAM.TXT -----
---- Now *this* definitely is read on system startup.
BOOTSTRAP
---- SYSTEM:INTERNET-ETHERNET-MAPPINGS.BIN
---- Read on system startup; can also be reloaded by running IPHOST
with a command (ETHER INIT?)
This is apparently generated by the IPHOST program using the
command BUILD, which takes SYSTEM:INTERNET-ETHERNET-MAPPINGS.TXT
and translates it into .BIN.
TXT file format *appears* to be:
HOST xx-xx-xx-xx-xx-xx ddd.ddd.ddd.ddd [/ARP] [/NOARP]
BIN file format is documented in ANAUNV.MAC.
Current file is basically empty, contains one zero entry;
apparently this just makes everything use ARP.
---- SYSTEM:NETSRV.RUN -----
---- File of NETSRV commands, executed by NETSRV.EXE (started by SYSJOB)
This basically determines what TCP/IP servers will be started.
Note: NETSRV is not a DEC program; it is one of many non-DEC utilities
produced by the ARPANET user community, in this case Mark Crispin
and Kevin Paetzold.
---- SYS:FTSCTT.EXE -----
---- In a vanilla DEC setup this is the FTP server program. You can
put the line "RUN SYS:FTSCTT" in <SYSTEM>7-SYSJOB.RUN to start it
up automatically. You may also want to set the protection of
FTPSRT.EXE from 777700 to 777752 to allow general use.
---- System:INTERNET-LOGIN-MESSAGE.TXT -----
---- Contains initial login banner presented to users. May be a feature
of the SRI-NIC EXEC only.
General stuff, not network specific:
SYSTEM:7-CONFIG.CMD
File of commands for SYSTEM:SETSPD.EXE, which is executed by
monitor at startup (prior to running SYSJOB).
SYSTEM:SYSJOB.RUN
File of commands for SYSTEM:SYSJOB.EXE, which is also run by
monitor at startup.

81
doc/ksits.txt Normal file
View File

@@ -0,0 +1,81 @@
/* KSITS.TXT - KS ITS system installation on KLH10
*/
/* $Id: ksits.txt,v 2.4 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 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 is mainly a placeholder until distribution issues are resolved
for the starter ITS file system copy.
The run/ksits directory contains the boot files developed for the
Public ITS project, which had 3 systems called PI, DU, DX. These are
for PI:
klh10-pi.ini - KLH10 configuration for PI.
@.its-647pi-u - ITS. Normally you would just load this.
@.ddt-u - DDT stand-alone.
@.nsalv-260-u - SALV stand-alone. Start at 200000 !!
itsbin.647pi-u - ITS binary, without DDT or SALV.
Note: All binaries by default are in U36 format, as opposed
to the C36 format of all other KN10 configurations.
Eventually I hope to be able to distribute the actual filesystem image
as well, and then will include a large bunch of stuff containing
nearly everything I've discovered or written about ITS software
porting issues, machine names and addresses, dumps, utilities, bug
fixes, etc.
THE FIRST TIME
==============
Once you have installed the binaries per install.txt in a $KLH10_HOME
corresponding to an instance of run/ksits (don't forget to make
dpimp setuid root, or run as root) it should work to just do:
./kn10-ks klh10-kn.ini ;;; or whichever system you prefer)
[gubbish]
KLH10> go
After the dust settles, type ^Z.
The first time, ITS will complain that the time is not known.
Run PDSET.
To correctly set the date in the new millenium, you must use the
undocumented command "C", as in "20C".
-------------------------------------------------
pdset^K(Please Log In) ;;; or :pdset
!
___002 PDSET IOTLSR
PDSET.114
Please don't use this program unless you know how.
You are certain to break something if you happen to hit the wrong key.
Type Control-Z to exit, or ? for a reminder of the commands.
20C ;;; You type "20C"
011110D ;;; You type YYMMDD and D. YY=01 for 2001.
131012T ;;; Ditto for time, HHMMSS and T.
!. ;;; Finish with "!."
141425/ 765361,,514221 763707,,355545 ___002
IT IS NOW 1:10:12 PM EST, SATURDAY, NOV 10,2001
IT IS NOW 1:10:14 PM EST, SATURDAY, NOV 10,2001
Q ;;; Get out with "Q"
:KILL
*
-------------------------------------------------
From here on, ITS should always know the time. If it ever gets totally
out of whack, delete the file $KLH10_HOME/APR.TIMEBASE and reboot,
running PDSET again.

16
doc/kst10.txt Normal file
View File

@@ -0,0 +1,16 @@
/* KST10.TXT - KS TOPS-10 system startup on KLH10
*/
/* $Id: kst10.txt,v 2.3 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 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.
*/
[NOTE: Eventually this will describe how to install a KS TOPS-10 system
from an installation tape. For the time being, see
klt10.txt instead.]

587
doc/kst20.txt Normal file
View File

@@ -0,0 +1,587 @@
/* KST20.TXT - KS TOPS-20 system installation on KLH10
*/
/* $Id: kst20.txt,v 2.3 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 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 contains several sections:
KS TOPS-20 INSTALLATION (including tape and disk boot scripts)
KS T20 BOOT BUG NOTES
KS T20 MONITOR BUG
KS TOPS-20 INSTALLATION
=======================
Once you have installed the KLH10 binaries, you will need to
install a PDP-10 operating system on the KN10's virtual disks. This
file documents the basic procedure for TOPS-20 on a KS10 (2020).
Although the TOPS-20 installation procedures were certainly listed
somewhere in Digital's documentation, I'm not sure what references to
provide; they may be difficult or impossible to find. In any case,
some of the steps on a KN10 will be different.
(NB: the field service documentation files "red20.hlp" and "red20.mem"
helped me, but they were not intended for customers.)
You will need an "installation" tape or tape image to get started, and
almost certainly will want to install the accompanying sources and
tools. You should already have a valid TOPS-20 license (personal or
otherwise) in order to use them.
These are the tapes containing the last known DEC TOPS-20 distribution
for the KS10 (DEC-2020), which was TOPS-20 V4.1:
BB-D867E-BM TOPS-20 V4.1 2020 INSTL 16MT9 1983
BB-D868E-BM T-20 V4.1 2020 DIST 16MT9 1/2 1983
BB-V895A-BM T-20 V4.1 2020 DIST 16MT9 2/2 1983 ("1/9/85")
BB-J710B-BM TOPS-20 V4.1 TOOLS 16MT9 1983 ("3/27/85")
Tops-20 V4.1 TP#12 "Exec Src Mod" Gidney TU78 21-Nov-85
Tops-20 V4.1 TP#12 "Monitor Sources" Gidney TU78 21-Nov-85
It should be possible to obtain these from www.trailing-edge.com. In
particular, start with the first of these, which is the installation
tape:
ftp://ftp.trailing-edge.com/pub/pdp10/bb-d867e-bm_tops20_v41_2020_instl.tap.gz
The script that follows assumes you have uncompressed this into the
somewhat more manageable name of "bb-d867e-bm.tap" in your $KLH10_HOME.
In the transcript that follows, all notes are prefaced by triple
semicolons (;;;), and user input is presented in lowercase where
possible -- note that the monitor sometimes echoes typein in
uppercase. Where there might be some confusion, a note such as "Type
CR" will identify what you need to type.
=====================================================
QUICK SUMMARY:
$ ./kn10-ks inst-kst20.ini ;;; Configure and load tape bootstrap
;;; (normally smmtbt-k.sav, entry 40000)
KLH10> go
MTBOOT>/l ;;; Load rest of monitor
MTBOOT>/g143 ;;; Start at FS-creation entry point
;;; (/g147 if a filesystem already exists)
;;; After quiets down, ^C to get MEXEC, and carry on
;;; After installation finished:
$ ./kn10-ks klh10.ini ;;; Configure and load disk bootstrap
KLH10> go
BOOT> ;;; Type CR to load and start MONITR.EXE
=====================================================
FULL SCRIPT:
;;; Here we go...
;;;
$ ./kn10-ks inst-kst20.ini ;;; You type this
KLH10 V2.0 beta (MyKS) built Nov 10 2001 02:14:29
Copyright © 2001 Kenneth L. Harrenstien -- All Rights Reserved.
This program comes "AS IS" with ABSOLUTELY NO WARRANTY.
Compiled for LINUX on I386 with word model USEHWD
Emulated config:
CPU: KS10 SYS: T20 Pager: KL APRID: 759
Memory: 1024 pages of 512 words (SHARED)
Time interval: INTRP Base: OSGET
Interval default: 60Hz
Internal clock: OSINT
Other: JPC DEBUG PCCACHE CTYINT IMPINT EVHINT
Devices: RH11 RPXX(DP) TM03(DP)
[MEM: Allocating 1024 pages shared memory, clearing...done]
KLH10> ; This is a sample KLH10 config file for a KS10 running TOPS-20.
KLH10>
KLH10> ; Define basic KS10 device config - two RH11s each on its own Unibus
KLH10>
KLH10> devdef rh0 ub1 rh11 addr=776700 br=6 vec=254
KLH10> devdef rh1 ub3 rh11 addr=772440 br=6 vec=224
KLH10>
KLH10> ; Provide one disk, one tape in config T20 expects
KLH10>
KLH10> devdef dsk0 rh0.0 rp type=rp06 format=dbd9 path=T20-RP06.0-dbd9 iodly=0
KLH10> [dprpxx: WARNING! sigpend 37, 40, 43, 44, 45, 46, 47, 48, 49, 63]
[Creating RP06 disk file "T20-RP06.0-dbd9"]
devdef mta0 rh1.0 tm03 fmtr=tm03 type=tu45
KLH10>
KLH10> ; Mount installation tape, skipping past ucode and defective boot
KLH10> devmount mta0 bb-d867e-bm.tap fskip=2
Mount requested: "bb-d867e-bm.tap"
[dptm03: WARNING! sigpend 33, 35, 37, 39, 40, 42, 44, 46, 48, 50, 63]
KLH10>
[mta0: Tape online]
KLH10> ; Load fixed tape bootstrap directly
KLH10> load smmtbt-k.sav
Using word format "c36"...
Loaded "smmtbt-k.sav":
Format: DEC-CSAV
Data: 1017, Symwds: 0, Low: 040000, High: 044010, Startaddress: 040000
Entvec: JRST (120 ST: 0, 124 RE: 0, 137 VR: 0,,0)
KLH10>
KLH10> ; Now ready to GO
KLH10> [EOF on inst-kst20.ini] ;;; Init file now done.
KLH10> go ;;; Boot is loaded, type "go" to start KN10!
Starting KN10 at loc 040000...
MTBOOT>/l ;;; Type "/l" to load monitor
MTBOOT>/g143 ;;; Now type "/g143" to start monitor
uba_read: Bad unibus IO addr: 760540 ;;; KN10 reports probes of non-ex
uba_read: Bad unibus IO addr: 760010 ;;; devices; these are harmless.
[FOR ADDITIONAL INFORMATION TYPE "?" TO ANY OF THE FOLLOWING QUESTIONS.]
DO YOU WANT TO REPLACE THE FILE SYSTEM ON THE PUBLIC STRUCTURE? Y
DO YOU WANT TO DEFINE THE PUBLIC STRUCTURE? Y
HOW MANY PACKS ARE IN THIS STRUCTURE: 1
ON WHICH "CHANNEL,UNIT" IS LOGICAL PACK # 0 MOUNTED: 0,0
DO YOU WANT THE DEFAULT SWAPPING SPACE? Y
DO YOU WANT THE DEFAULT SIZE FRONT END FILE SYSTEM? Y ;;; Unnec but OK
DO YOU WANT THE DEFAULT SIZE BOOTSTRAP AREA? Y
[STRUCTURE "PS" SUCCESSFULLY DEFINED]
[PS MOUNTED]
?PS UNIT 0 HAS NO BAT BLOCKS.
DO YOU WANT TO WRITE A SET OF PROTOTYPE BAT BLOCKS? Y
uba_read: Bad unibus IO addr: 775400
uba_read: Bad unibus IO addr: 777160
%%NO SETSPD
System restarting, wait...
ENTER CURRENT DATE AND TIME: 30-SEP-2001 0605 ;;; Must enter time, sigh
YOU HAVE ENTERED SUNDAY, 30-SEPTEMBER-2001 6:05AM,
IS THIS CORRECT (Y,N) Y
WHY RELOAD? NEW ;;; Type "new" or whatever.
<SYSTEM>ACCOUNTS-TABLE.BIN NOT FOUND - ACCOUNT VALIDATION IS DISABLED
uba_read: Bad unibus IO addr: 760540
RUNNING DDMP
NO SYSJOB
;;; After you get "NO SYSJOB" you can type either
;;; a ^C to get to the MEXEC prompt ("MX>").
NO EXEC
MX>GET FILE MTA0: ;;; Type just "g" then "mta0:" and CR.
INTERRUPT AT 0 ;;; Monitor will read an EOF and do nothing.
MX>GET FILE MTA0: ;;; Repeat, to read EXEC.EXE from tape.
MX>START ;;; Type just "s" then CR.
TOPS-20 Command processor 5.1(1354)
@TER NO RAI ;;; Success! Let's stop uppercasing our input,
@ena ;;; and must get enabled.
$run mta0: ;;; Now read and start DLUSER.EXE from tape.
DLUSER>load mta0: ;;; Now read DLUSER data to set up directories.
DONE.
DLUSER>exit ;;; Get out.
$run mta0: ;;; Now read and start DUMPER.EXE from tape.
DUMPER>tape mta0: ;;; Point to tape drive and start restoring files!
;;; Note in the next command it is important to
;;; explicitly specify "<system>", otherwise the
;;; files will be restored into "<NEW-SYSTEM>".
DUMPER>restore <*>*.*.* (TO) <system>*.*.*
DUMPER tape # 1, "SYSTEM files for TOPS-20 V4.1", Thursday, 7-Apr-83 17
21
Loading file(s) into PS:<SYSTEM>
End of saveset
;;; Note in the next command it is important to
;;; explicitly specify "<system>", otherwise the
;;; files will be restored into "<NEW-SYSTEM>".
DUMPER>restore <*>*.*.* (TO) <subsys>*.*.*
DUMPER tape # 1, "SUBSYS files for TOPS-20 V4.1", Thursday, 7-Apr-83 17
23
Loading file(s) into PS:<SUBSYS>
End of saveset
;;; The last saveset is optional and can be skipped.
;;; If you want the UETP stuff, do:
DUMPER>restore <*>*.*.* (TO) <*>*.*.*
DUMPER tape # 1, "UETP files for TOPS-20 V4.1", Thursday, 7-Apr-83 1726
Loading file(s) into PS:<UETP.LIB>
End of saveset
DUMPER>exit ;;; Done, with or without UETP.
$conn <system>
$vdir ;;; Check out what we have in <SYSTEM>
PS:<SYSTEM>
2020-ARPA-MONMED.EXE.1;P777700 321 164352(36) 6-Apr-83 00:28:29 PURRET
TA
2020-ARPA-MONSML.EXE.1;P777700 321 164352(36) 6-Apr-83 00:24:37 PURRET
TA
2020-MONMED.EXE.1;P777700 326 166912(36) 5-Apr-83 23:37:27 PURRETTA
2020-MONSML.EXE.1;P777700 326 166912(36) 5-Apr-83 23:34:00 PURRETTA
4-1-SETSPD.EXE.1;P777700 10 5120(36) 7-Dec-82 16:19:35 PURRETTA
BUGS.MAC.1;P777700 50 127461(7) 10-Nov-82 23:09:16 PURRETTA
BUGSTRINGS.TXT.1;P777700 10 24240(7) 6-Apr-83 00:28:24 PURRETTA
CHECKD.EXE.1;P777700 17 8704(36) 7-Dec-82 16:53:16 PURRETTA
DUMP.EXE.1;P777700 1025 524800(36) 13-Feb-80 17:44:06 PURRETTA
ERRMES.BIN.1;P777752 16 7717(36) 20-Dec-82 16:18:48 PURRETTA
ERROR.SYS.1;P777752 1 23(36) 30-Sep-2001 06:05:03 OPERATOR
EXEC.EXE.1;P777752 102 52224(36) 1-Dec-82 02:17:14 PURRETTA
FTPSER.EXE.1;P777700 17 8704(36) 15-Apr-82 10:14:40 PURRETTA
GALAXY.BWR.1;P777700 2 818(36) 20-Dec-82 16:40:58 PURRETTA
.DOC.1;P777700 3 1402(36) 14-Jan-83 22:30:20 WING
HSTNAM.TXT.1;P777700 4 9974(7) 12-Aug-82 14:36:51 PURRETTA
KS10.RAM.1;P777700 12 6144(36) 20-May-82 10:46:56 PURRETTA
.ULD.1;P777700 42 21186(36) 1-Mar-82 16:27:00 PURRETTA
MTBOOT.RDI.1;P777700 6 3072(36) 20-May-82 10:47:30 PURRETTA
NETSRV.RUN.1;P777700 1 234(7) 3-Nov-81 16:32:05 PURRETTA
PROGRAM-NAME-CACHE.TXT.1;P777700 1 78(7) 9-Mar-81 15:24:00 PURRETTA
PTYCON.ATO.1;P777700 1 333(7) 29-Mar-82 15:46:43 PURRETTA
REAPER.CMD.1;P777700 1 537(7) 22-Aug-79 19:53:37 PURRETTA
SMBOOT.EXE.1;P777700 3 1175(36) 13-May-82 12:17:47 PURRETTA
SMFILE.EXE.1;P777700 42 21504(36) 19-Feb-79 15:58:00 PURRETTA
.HLP.1;P777700 1 163(36) 19-Feb-79 15:42:00 PURRETTA
SMMTBT.EXE.1;P777700 3 1030(36) 13-May-82 12:18:15 PURRETTA
SYSJOB.EXE.1;P777700 7 3584(36) 20-Dec-82 17:43:24 PURRETTA
.HLP.1;P777700 3 5679(7) 29-Mar-82 15:47:02 PURRETTA
.RUN.1;P777700 1 340(7) 29-Mar-82 15:46:54 PURRETTA
SYSTEM.CMD.1;P777700 1 725(7) 8-May-79 14:46:35 PURRETTA
TOPS20.BWR.1;P777700 6 2669(36) 6-Apr-83 16:12:07 PURRETTA
.DOC.1;P777700 3 1255(36) 6-Apr-83 16:04:44 PURRETTA
Total of 2685 pages in 33 files
$ ;;; For convenience, now is a good time to
;;; make MONITR.EXE be your desired monitor!
$ren 2020-monmed.EXE.* (TO BE) monitr.exe
2020-MONMED.EXE.1 => MONITR.EXE.1 [OK]
$^Ecease +1 ;;; OK, now we can try a disk boot.
[System going down in one minute!!]
$ ;;; It really does take a minute. Patience...
[System down]
Shutdown complete ;;; When you see this, type ^\ (CTRL-\)
[HALTED: FE interrupt] ;;; to return to KLH10
KLH10> shutdown ;;; Then give "shutdown" command.
Continuing KN10 at loc 03...
**HALTED**
[HALTED: Program Halt, PC = 10754]
KLH10> q ;;; OK to quit KLH10 now!
Are you sure you want to quit? [Confirm]
Shutting down...Bye!
$ ;;; Back at unix shell prompt
$ ./kn10-ks kst20.ini ;;; Fire it up again, with different ini file
KLH10 V2.0 alpha (MyKS) built Sep 30 2001 05:01:44
Copyright © 1992-2001 Kenneth L. Harrenstien -- All Rights Reserved.
Proprietary and Confidential; the copyright notice does not indicate
actual or intended publication.
This software is provided under a license agreement described by the
accompanying file "LICENSE". USE OF THIS SOFTWARE CONSTITUTES
ACCEPTANCE OF THE TERMS OF THE LICENSE AGREEMENT.
This program comes "AS IS" with ABSOLUTELY NO WARRANTY.
Compiled for LINUX on I386 with word model USEHWD
Emulated config:
CPU: KS10 SYS: T20 Pager: KL APRID: 759
Memory: 1024 pages of 512 words (SHARED)
Time interval: INTRP Base: OSGET
Interval default: 60Hz
Internal clock: OSINT
Other: JPC DEBUG PCCACHE CTYINT IMPINT EVHINT
Devices: RH11 RPXX(DP) TM03(DP)
[MEM: Allocating 1024 pages shared memory, clearing...done]
KLH10> ; This is a sample KLH10 config file for a KS10 running TOPS-20.
KLH10>
KLH10> ; Define basic KS10 device config - two RH11s each on its own Unibus
KLH10>
KLH10> devdef rh0 ub1 rh11 addr=776700 br=6 vec=254
KLH10> devdef rh1 ub3 rh11 addr=772440 br=6 vec=224
KLH10>
KLH10> ; Provide one disk, one tape in config T20 expects
KLH10>
KLH10> devdef dsk0 rh0.0 rp type=rp06 format=dbd9 path=T20-RP06.0-dbd9 iodly=0
KLH10> [dprpxx: WARNING! sigpend 37, 40, 43, 44, 45, 46, 47, 48, 49, 63]
devdef mta0 rh1.0 tm03 fmtr=tm03 type=tu45
KLH10>
KLH10> ; Define HOST device hackery if monitor supports it
KLH10> ;devdef idler 700 host
KLH10>
KLH10> ; For convenience, load up disk bootstrap
KLH10> load smboot-k.sav
Using word format "c36"...
Loaded "smboot-k.sav":
Format: DEC-CSAV
Data: 1162, Symwds: 0, Low: 040000, High: 044010, Startaddress: 040000
Entvec: JRST (120 ST: 0, 124 RE: 0, 137 VR: 0,,0)
KLH10> [EOF on kst20.ini] ;;; Init file now done.
KLH10> go ;;; Boot is loaded, type "go" to start KN10!
Starting KN10 at loc 040000...
BOOT> ;;; Type just CR, will default to MONITR.EXE
uba_read: Bad unibus IO addr: 760540
uba_read: Bad unibus IO addr: 760010
[PS MOUNTED]
uba_read: Bad unibus IO addr: 775400
uba_read: Bad unibus IO addr: 777160
System restarting, wait...
ENTER CURRENT DATE AND TIME: 30-SEP-2001 0611 ;;; Must enter time AGAIN!
YOU HAVE ENTERED SUNDAY, 30-SEPTEMBER-2001 6:11AM,
IS THIS CORRECT (Y,N) Y
WHY RELOAD? OTHER
<SYSTEM>ACCOUNTS-TABLE.BIN NOT FOUND - ACCOUNT VALIDATION IS DISABLED
RUN CHECKD? Y ;;; "Y" for first time is good idea
[CHECKING FILE CONSISTENCY]
[WORKING ON STRUCTURE - PS:]
LOCAL COUNT OF FILE PAGES: 8035
LOCAL COUNT OF OVERHEAD PAGES: 5402
LOCAL COUNT OF USED PAGES: 13437
SYSTEM COUNT BEFORE CHECKD: 13437
SYSTEM COUNT AFTER CHECKD: 13437
THERE ARE NO LOST PAGES.
********************
*BUGINF "UXXFIT" AT 30-SEP-2001 06:11:10
*CHECKPOINT FILE NOT IN CORRECT FORMAT FOR THIS SYSTEM, REBUILDING...
*JOB: 0, USER: OPERATOR
********************
uba_read: Bad unibus IO addr: 760540
RUNNING DDMP
SYSJOB 5(20) STARTED AT 30-SEP-2001 0611
RUN SYS:ORION
RUN SYS:QUASAR
RUN SYS:MOUNTR
RUN SYS:INFO
RUN SYS:MAILER
RUN SYS:MAPPER
RUN SYS:LPTSPL
RUN SYS:LPTSPL
RUN SYS:CDRIVE
RUN SYS:SPRINT
JOB 0 /LOG OPERATOR XX OPERATOR
ENA
^ESET LOGIN PSEUDO
^ESET LOGIN CONSOLE
^ESET OPERATOR
PTYCON
GET SYSTEM:PTYCON.ATO
/
JOB 1 /LOG OPERATOR XX OPERATOR
ENA
RUN SYS:BATCON
/
SJ 0: @LOG OPERATOR OPERATOR
SJ 1: @LOG OPERATOR OPERATOR
SJ 0: JOB 1 ON TTY43 30-SEP-2001 06:11:20
SJ 0: @ENA
SJ 0: $^ESET LOGIN PSEUDO
SJ 0: $^ESET LOGIN CONSOLE
SJ 0: $^ESET OPERATOR
SJ 0: $PTYCON
SJ 1: JOB 2 ON TTY44 30-SEP-2001 06:11:21
SJ 1: @ENA
SJ 1: $RUN SYS:BATCON
SJ 0: PTYCON> GET SYSTEM:PTYCON.ATO
SJ 0: PTYCON> SILENCE
[From OPERATOR on line 45 to all: SYSTEM IN OPERATION]
SJ 0: PTYCON.LOG.1
SJ 0: PTYCON> W ALL
SJ 0: OPR(0) 3 OPERATOR OPR TI 0:0:0
SJ 0: PTYCON> CONN OPR
SJ 0: [CONNECTED TO SUBJOB OPR(0)]
;;; When things seem quiet, type CR to get an EXEC.
TOPS-2020 MEDIUM SYSTEM, TOPS-20 Monitor 4.1(5471)
@TER NO RAI
@log operator ;;; Try logging in, pwd "DEC-20"
Job 4 on TTY42 30-Sep-2001 06:11:53
@ena
$ ;;; Now do whatever you wish...
=====================================================
Other things you probably want to do at some point:
$copy tty: monnam.txt ;;; Set the system name
MyKS TOPS-20 System
^Z
$copy tty: 4-1-config.cmd ;;; Set timezone here for now
timezone 8
^Z
$^Ecreate <operator> ;;; Change operator password
$$password tqbfjotld ;;; (use something better)
$$
$^Ecreate <me> ;;; Create your account
$$password nittfagmtc2taotp ;;; (or something better)
$$wheel
$$working 10000
$$permanent 10000
$$
$
There are large manuals devoted to TOPS-20 system maintenance, but
this is enough to make you dangerous.
KS T20 BOOT BUG NOTES
=====================
BOOT
----
The magtape bootstrap source is BOOT.MAC, which was still used
to build both KL and KS bootstraps as of V4.1 of TOPS-20 (but at some
point thereafter, and certainly as of V6.0, there were big changes --
the KS code no longer exists in the last TOPS-20 BOOT.MAC).
For the KS10, BOOT is assembled into either SMBOOT.EXE (for
booting from disk) or SMMTBT.EXE (for booting from tape), both in
CSAVE format. There is also SMBOOT.I?? which is SMBOOT.EXE converted
into FE-loadable format, which the KLH10 does not use.
Unfortunately the KS10 BOOT cannot be used as-is without either
patching it or playing tricks in the emulator. It has at least
three bugs:
[1] The most serious is the following:
40120/ J3+6/ WRCSTM [77B5]
should be: WRCSTM [77B5]-ENT(16)
(or better yet set up with a MOVSI 1,770000 ? WRCSTM 1)
This fails because at the time it is executed it has been
moved into high core and the literal is no longer at that
address! It ends up loading the CST mask with 0 which
causes an infinite page failure loop when the code turns
paging on for the first time.
It is not clear how a real KS10 managed to get past this bug.
For now, this has been patched:
40120/ 702540,,40127 => 702540,,774127
(Start address remains 40000.)
[2] In the code starting at FNDDEV there is the instruction
SETZM KLIOWD (zeros loc 35, KLINIK output word)
which causes a page trap because at this point page 0 is unmapped.
This instruction should either be done before turning paging on,
or after low pages have been mapped.
It was probably never noticed because the page fault handler
merely continues at .+1.
[3] The disk bootstrap (SMBOOT) also has a bug of its own:
CHKCHN: CAIG P,MAXCHN1 (CAIG 17,2)
should be: CAIG P1,MAXCHN-1 (CAIG 10,1)
Note there are two independent typo bugs in that one instruction!
Geez. First, the compare to P instead of P1 is clearly wrong.
Second, MAXCHN1 is undefined; the assembler does not distinguish
symbols beyond the first 6 characters so MAXCHN is silently being
used, with a value of 2. This causes the loop to check 3 channels
(0,1,2) but only 2 channels are provided for in the RH11CH table!
Trying to check the 3rd channel results in referencing the wrong
words of a valid channel, or worse.
This probably worked in real life because the first RH11
always existed and was always used for the boot.
For now, this has been patched:
SMMTBT: 41335/ 307740,,2 => 307400,,1
SMBOOT: 41441/ 307740,,2 => 307400,,1
FIXED VERSIONS
--------------
The patched versions of these binaries have been dumped out as:
SMBOOT: smboot-k.sav (c36 CSAVE format)
SMMTBT: smmtbt-k.sav (c36 CSAVE format)
MONITOR BOOT BUG
----------------
There is a T20 monitor bug with the G/143 boot code that
prevents simply loading monitr.exe directly into the KLH10 and
starting it.
When the monitor gets around to executing its first PXCT at
KISLOD+2 to set up the user ACs, it actually clobbers its own ACs.
The reason for this is that no WRUBR was ever done to set the
previous-context AC block; the emulator initializes both contexts to
AC block 0. Several WRUBRs have been executed prior to this, but none
of them ever set the AC block fields. One of them (at PGRON+3)
doesn't even set the base address either; they mostly seem to be used
as the CLHWPT macro to clear the cache and paging hardware, and refer
to an argument of KIPGW0 or KIPGWD which in the source (APRSRV.MAC)
don't have the set-ac-block flag set.
This appears to have worked in the past because BOOT, which
is expected to load monitr.exe, has already set the previous-context-AC
block to 6.
For now, this can be avoided by always using SMBOOT or SMMTBT.
One solution would be for the KLH10 FE to provide a "monitor load"
command that did this previous-context AC block setting (and any other
setup that might be found necessary) in addition to doing a normal
binary load.
KS T20 MONITOR BUG
------------------
There seems to be a timing race condition when outputting to
the CTY. Normally the KLH10 responds instantly to a KS->FE interrupt
request by gobbling a valid output char and sending a FE->KS interrupt.
This causes output to wedge after the first bufferful until another
FE->KS interrupt is given.
This happens because of the code in the tty driver that
tries to turn interrupts off and then on while initiating output of the
first char. It actually doesn't do any good and the entire buffer is
emptied at interrupt level before the first call returns!
KS T20 MONITOR SOURCE GLITCH
----------------------------
My copy of the "Monitor Sources" tape has a bad record data
header which resulted in problems with the "sources.cmd" file; it
either has its last page clobbered or has 444 zero words appended.
Shoppa's copy may not have this problem. Fortunately it isn't
an essential file.

39
doc/news.txt Normal file
View File

@@ -0,0 +1,39 @@
/* NEWS.TXT - KLH10 Change Summaries and other news
*/
/* $Id: news.txt,v 2.1 2001/11/19 12:13:12 klh Exp $
*/
/* Copyright © 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.
*/
KNOWN BUGS
==========
Still outstanding:
- KS TOPS-10 7.03 install from tape periodically hangs on MT.
- KS TOPS-10 7.03 disk boot produces:
KLH10 PANIC: rh11_iobeg: drv/ctrlr mismatch: 7/0
(Of course, this will never be a complete list!)
KLH10 CHANGES
=============
KLH10 2.0A: 19-Nov-2001
- Revised ARP code in dpimp.c to fix problems with Linux port;
ITS networking now supported on Linux!
- Cleaned up Solaris port. Two Makefiles now provided, one for
GCC and the other for SUN C. Compiles and runs, but actual network
operation not yet verified.
- Fixed bug with writing TPS format tape images (caught by John Wilson).
- Added "port-ks" target to Makefile to help porters.
KLH10 2.0: 10-Nov-2001
Initial Distribution release.

311
doc/usage.txt Normal file
View File

@@ -0,0 +1,311 @@
/* USAGE.TXT - KLH10 Usage Instructions
*/
/* $Id: usage.txt,v 2.3 2001/11/10 21:24:21 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 using the KLH10.
See "install.txt" for information on installing and configuring the KLH10.
KLH10 STARTUP:
You should not start the KLH10 unless you have installed it in
its "home directory" and are connected to that directory (see the file
"install.txt" if necessary). Then simply give the following shell
command:
% klh10
The KLH10 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:
% klh10 test.ini ; Use "test.ini" instead of "klh10.ini"
% klh10 /dev/null ; Use nothing
Or you can simply edit or delete "klh10.ini" itself.
KLH10 COMMAND PARSER:
After starting the KLH10 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 devices this way,
using the information in "install.txt".
KLH10 BOOTSTRAPPING:
The KLH10 is capable of loading PDP-10 binary files directly
into its KN10 memory with the "load" command. The KLH10 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 <SYSTEM>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:
It is very important to understand that the KLH10 is always
doing only one of two things. It is either reading and executing
commands typed to it, or it is running the KN10 which is executing
PDP-10 instructions. There is no way to enter KLH10 commands without
temporarily suspending KN10 execution.
While the KLH10 is reading commands, nothing else is
happening, and your typein is seen only by the KLH10 command parser.
The KN10 does not run until you give an explicit command to start or
resume execution.
While the KN10 is running, 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), which suspends KN10 execution. Control also returns
to the command parser if the KN10 halts for any reason.
Future versions of the KLH10 may allow concurrent execution so
that KLH10 commands can be given while the KN10 continues to run,
similar to the way a real KL system works with its front-end PDP-11
independent of the KL10 CPU. For now, simplicity is stability.
STOPPING THE KLH10:
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 <pid>" where <pid> 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 <pid>
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
will 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.

245
doc/utils.txt Normal file
View File

@@ -0,0 +1,245 @@
/* UTILS.TXT - KLH10 Utilities
*/
/* $Id: utils.txt,v 2.2 2001/11/10 21:24:21 klh Exp $
*/
/* Copyright © 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 attempts to provide a quick guide to the various utility
programs provided with this Distribution (or its Auxiliary
Distribution). There are no man pages nor GnuEmacs INFO files.
In rough order of utility:
wxtest - Test word10.h macros (used only to verify build configuration)
wfconv - 36-bit Word File conversion
tapedd - Tape copy & conversion (real or virtual)
vdkfmt - Virtual Disk initialization and conversion
enaddr - Ethernet interface configuration
read20 - (TOPS-20) Read & extract DUMPER format tapes & tape images
uexbconv - (TOPS-20) Convert .EXB files to .SAV format
udlconv - (ITS) Convert Alan's DIR.LIST into an ITSDUMP virtual tape
supdup - (ITS) SUPDUP client and server for Unix
More details, in alphabetical order:
ENADDR
------
Usage: enaddr [-v] [<ifc> [default | <ifaddr>] [+<addmcast>] [-<delmcast>]]
-v Outputs debug and config info for all interfaces
<ifc> Specific interface to read or modify
default Reset ether addr to HW default, if known
<ifaddr> Set ether addr to this (form x:x:x:x:x:x)
+<mcast> Add multicast addr (same form)
-<mcast> Delete multicast addr (same form)
This program exists primarily to help test and verify the
operation of some basic osdnet.c code while porting. In theory it is
not needed to run a correctly configured KN10 if the osdnet.c
implementation is correct, but is provided as a utility because its
manual functions have been useful in the past, especially when getting
non-IP protocols like DECNET to work.
This can be built individually with "make enaddr".
READ20
------
Usage: read20 [switches] [patterns]
Switches must be separated.
Patterns are simple substrings of the filenames to select.
-f <file> Specify tapefile. '-' uses stdin. Default is /dev/rmt8
-x Extract files
-t List contents (one of -t or -x must be given)
-tl Show tape locations in listing
-S <n> Only process saveset <n>
-e <regexp> Only process filenames matching <regexp> (one -e only)
-F <n> ... Only process files numbered <n> ...
-V Show FDB info for files extracted or listed
-s <loc> Start reading at this byte loc in tapefile (seeks)
-q Say using QIC (1/4") cartridge tape
-v Verbose feedback
-g Keep generation # in extracted filename
-n <n> Use numeric filenames for extracts, starting with <n>
-W Treat all files as 36-bit. Otherwise, 7-bit files
are treated as ascii, 8-bit as 8-bit binary, and
all others as 36-bit (direct copy of tape data).
-T Treat 0 or 36-bit files as 7-bit ascii
-B Treat 0 or 36-bit files as 8-bit binary
-c Keep CRs in CRLF pairs for ascii files
-d<n> Debug level (>0,>5,>10,>99) (default 0)
This program is part of the Auxiliary Distribution and the
source lives in the "contrib" directory. It appears to have
originated with Jim Guyton and was further modified by Jay Lepreau,
Charles Hedrick, Stu Grossman, and possibly others before undergoing a
substantial upgrade by Ken Harrenstien. Other versions may still
exist.
READ20 is used to list and extract files on Unix from a TOPS-20 DUMPER
tape image. This can be either a real tape, read directly as a
sequence of records, or a virtual tape image using the KLH10 RAW
format. It does NOT directly handle any other virtual tape formats,
but could do so indirectly by using the TAPEDD utility as an input
filter.
No Makefile is provided; just compile read20.c with your
favorite C invocation and install the binary. e.g.
cc -O -o read20 read20.c
SUPDUP
------
This is of interest mainly to ITS users. SUPDUP is a protocol
similar to TELNET which was primarily supported by ITS. However, at
least one Unix server was written.
This program is part of the Auxiliary Distribution and the
source lives in the "contrib" directory. It was originally written
by David Bridgham and modified by a few people since then.
I have only used the client program from this package, not the server.
You will have to hope that the Makefile included with it works for you,
or modify it to suit.
TAPEDD
------
Usage: tapedd <params>
itX=<path> (Required) Input Tape device, where 'X' is optional
drive spec: (defaults to 'h')
h - Half-inch magtape drive (default)
q - QIC (quarter-inch cartridge) drive
8 - 8mm drive
4 - 4mm DAT drive
vF - Virtual tape & drive, where 'F' is optional
format spec: (defaults based on file extension)
r - Raw format, paired with control file
s - TPS format
e - TPE format
c - TPC format
i - (read-only) ITS DUMP tapedir
otX=<path> (Required) Output Tape device, X as above
{i,o}c=<path> alternate tape Control file (old id=,od=)
{i,o}f=<path> alternate raw data file
{i,o,}bs=<n> Block size (record length)
log=<path> Log filespec (defaults to stderr)
rskip=<#> Skip # input records
fskip=<#> Skip # input files/tapemarks
rcnt=<#> Max # records to write
Fcnt=<#> Max # files/tapemarks to write
peot Use physical EOT, ignore logical EOT (double tapemark)
test Parse control file, output result to stdout
verbose Verbose
TAPEDD is a tape version of DD, used to copy magtapes.
Normally it will convert them from one format to another in the
process; for example, from a physical magtape to a virtual tape image,
in a variety of formats.
This can be built individually with "make tapedd".
UDLCONV
-------
Usage: ./udlconv [switches] < DIR.LIST > DIR.tpk
-p <prefixpath> - Prefix this path to all host filenames
This is of interest only to ITS users.
Standard input is assumed to be a DIR.LIST file from Alan Bawden's ITS
archives. The resulting standard output is a tape-control (.tpk) file
in ITSDUMP format, suitable for mounting as a virtual tape.
The reason this is far preferable to unpacking the files and FTPing them
into ITS is because this method preserves all of the available file
meta-information (symlinks, creation timestamps, authors, etc).
Note that the output can be fed into TAPEDD to generate a tape image
in some other format, if desired.
This can be built individually with "make udlconv".
UEXBCONV
--------
Usage: uexbconv [-v] < infile.exb > outfile.sav
(input file must be in core-dump (C36) format, as the
output file will be.)
The KL10 FE is a PDP-11 that stores its PDP-10 binaries,
particularly the bootstraps "boot.exe" and "mtboot.exe", in a format
called "RSX-BINARY". These files sometimes exist on the KL filesystem
with the extension .EXB.
The KL10 program RSXFMT.EXE converts from .SAV to .EXB but does not
furnish the opposite conversion; hence this utility, which was used to
obtain some of the KL10 bootstrap images.
This can be built individually with "make uexbconv".
VDKFMT
------
Usage: vdkfmt <params>
ip=<path> Input disk device/file:
op=<path> Output disk device
ifmt=<fmt> format of input pack data
ofmt=<fmt> format of output pack data
dt=<type> Type of drive (RP06, etc)
log=<path> Log filespec (optional, defaults to stderr)
verbose Verbose (optional)
This utility is similar to TAPEDD; it is used to copy virtual
disk images from one format to another. It is rarely needed, but a
lifesaver when it is.
This can be built individually with "make vdkfmt".
WFCONV
------
Usage: wfconv -io <infile >outfile
where 'i' and 'o' are chars specifying the input and output formats:
c - Core-dump (std tape format, 4 8-bit, 1 4-bit bytes = 36 bits)
h - High-density (FTP 36-bit image, 9 8-bit bytes = 72 bits)
a,7 - Ansi-Ascii (4 7-bit, 1 8-bit byte = 36 bits)
s,6 - Sixbit (6 6-bit bytes = 36 bits)
u - Unixified (Alan Bawden format, various = 36 bits)
t - Text-Newline (CRLF-NL conversion; 5 7-bit bytes = 35 bits ONLY)
d - Debug (output only - show word values)
D - Debug (like -d with offsets)
Note: EOF on input always zero-pads up to a PDP-10 word boundary.
This is one of the handiest utilities, used to convert PDP-10
word data from one representation to another. No filenames are given;
it always reads from standard input and writes to standard output.
The format names are similar to those for magtape formats.
This can be built individually with "make wfconv".
WXTEST
------
Usage: wxtest -[qvh]
-q Quiet
-v Verbose
-h Help (this stuff)
This "utility" is actually a diagnostic used to verify that a
particular port configuration is correctly defining the macros used to
manipulate PDP-10 words. While most people will never need to worry
about such things, this is an extremely useful regression test when
porting to a new machine architecture or trying out a new method of
representing a PDP-10 word.
This can be built individually with "make wxtest".

493
doc/vtape.txt Normal file
View File

@@ -0,0 +1,493 @@
/* VTAPE.TXT - KLH10 Virtual Tape Format
*/
/* $Id: vtape.txt,v 2.3 2001/11/10 21:24:21 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.
*/
One of the methods used by the KLH10 to emulate PDP-10
magnetic tape devices is to provide support for "virtual tapes".
These virtual tapes are in reality disk files on the native host
system which have a specific format. Because they are native disk
files, it is far easier and faster to manipulate these virtual tape
images (for reading, writing, copying, archival, and transport over
networks) than would be the case for real physical tapes.
The purpose of this description is to allow users to generate or
maintain virtual tapes using their own tools in addition to the ones
provided in the KLH10 distribution. In most cases these tools can be
nothing more than a text editor and a simple copy program such as Unix
"dd".
VIRTUAL TAPE FORMATS
====================
Several virtual tape formats exist, developed more or less
independently. The KLH10 software can handle most of them and others
could be added if necessary. These formats are:
"RAW" - original KLH10 format
"TPS" - Wilson & Supnik format
"TPC" - DECUS/Shoppa format
"ITSDUMP" - special KLH10 format for ITS
"RAW" VIRTUAL TAPE: Directory and Data files
==================
Each RAW-format virtual tape consists of two native files, one
for the actual tape data and the other to describe that data. For
example, a virtual tape with the name "kosh" would consist of these
two files:
Virtual tape "kosh":
kosh - Tape directory (text; defines structure of data)
kosh.tap - Tape data (binary; one byte per tape frame)
"RAW" DATA FILE FORMAT (.TAP)
The tape data file is simply a continuous sequence of 8-bit bytes
corresponding to the logical stream of 8-bit tape data frames. There is
nothing in this file except tape data; there are no record boundaries or
tapemarks. Because this is a binary data file, all operations on this
file must preserve the data exactly.
"RAW" DIRECTORY FILE FORMAT (.TDR)
The tape directory is a text file that describes the contents of
its associated tape data file; it defines how the tape is structured in
terms of record boundaries, tapemarks, length, and internal format. It
can be used to describe anything about the tape in an easily readable
and editable form.
The directory is formatted as a set of logical text lines. Each
line begins with a keyword, optionally followed by data. Comments are
introduced by a semi-colon character (';') and continue to the end of
that physical line. Blank lines are ignored. Whitespace is also
ignored except at the start of a line, where indentation may be used
only when continuing a logical <filedesc> line over several physical
lines.
Keywords:
TF-Format: <fmtword> [<filename>]
; Tape datafile format and optional filename
<#>: <filedesc> ; File/Record descriptors
<indentation> <filedesc> ; optional continuation of above
EOT: ; Physical End of Tape, remaining text ignored.
<fmtword> - REQUIRED. Describes how the tape file data is stored on
disk. Currently only one keyword is fully supported:
"raw" - 8-bit bytes, one per frame.
<filename> - DEPRECATED. Optional name of tape data file, a feature
no longer used (ie ignored on input, not generated on output).
The tape data filename is either specified at mount time or
dynamically generated using ".tap" as an extension to the name of
the tape directory file. This extension replaces ".tdr" if it
exists, otherwise ".tap" is simply appended.
<#> - location in data file of 1st record beginning next file. For "raw"
format this corresponds to the logical frame # on tape as well, but
for other formats this may serve a realignment purpose.
The string "BOT" is considered equivalent to "0".
<filedesc> - a list of <recdesc> record descriptors composing the file,
separated by whitespace. The list may be empty, as is normally
the case for two consecutive tapemarks that signal a logical EOT.
<recdesc> - A record descriptor, with the format
<len>[*<cnt>][E[<type>]]
where:
<len> - decimal record length, in frames (8-bit bytes)
<cnt> - # times this record length recurs.
E - indicates error when reading this record (or the last of a
series). <type> is an optional # and specifies additional
information, if any, as to nature of the error.
The string "EOF" is a special <recdesc> that signals a tape mark.
TAPE DIRECTORY EXAMPLE:
Here is an example of a tape directory file for a small dump:
; DUMPER saveset of PS:<SYSTEM> ; Human-readable comment
TF-Format: raw ; Required, and must be "raw"
0: 2590*8407 EOF ; First file
21774130: EOF ; Second file (empty == logical EOT)
EOT: ; Physical EOT
Note that comments can exist, that the data file format is RAW, and
that it starts at frame 0 with a 2590-byte record which is repeated
8407 times, followed by an EOF tapemark, then another EOF tapemark.
The emulator software generates the second EOF using a new line so
that the tape location (21774130) can serve as a validity cross-check;
this is a compromise between putting everything on a single line or
putting each record on its own line, either of which is equally valid.
"TPS" FILE FORMAT (.TAP, .TPS, .TPE)
====================================
This is the format used by Bob Supnik's SIMH emulators. It is
almost the same as John Wilson's E11 format, which it was intended to
resemble.
A TPS file is assumed to consist of 8-bit bytes.
Each record starts with a 4-byte header in little-endian order.
The high bit of this 32-bit header is set to indicate an error of
some kind (similar to the 'E' flag in a RAW-format control file) and
the remaining 31 bits contain the record length N.
This header is followed by N data bytes plus, if N is odd, a padding
byte (of undefined value) at the end. Following this is a copy of the
4-byte record header.
Tapemarks are represented by a single header with N=0.
The reason for having the record length both before and after the
record data is so tape motion in the reverse direction can be more
easily simulated.
The E11 (.TPE) format is identical except there are no padding bytes.
"TPC" FILE FORMAT (.TPC)
========================
This format is not as flexible as the others but was
apparently quite commonly used for DECUS tape images, and Tim Shoppa
has a "couple thousand" TPC images stashed away.
A TPC file is assumed to consist of 8-bit bytes.
Each record starts with a 2-byte header in little-endian order,
containing 16 bits of record length N.
This header is followed by N data bytes plus, if N is odd, a padding
byte (of undefined value) at the end. Unlike TPS format, there is no
trailing header.
Tapemarks are represented by a single header with N=0.
Obviously it is difficult to use this format directly when reverse
tape motion is desired; an internal representation must be built.
TAPE GENERATION
There are three principal ways to create virtual tapes:
(1) Using the emulator to write tapes.
(2) Copying from real PDP-10 tapes.
(3) Creating synthesized tapes "by hand".
TAPE GENERATION [1]: Using the emulator
=======================================
Method [1] is described in the documentation for the emulator
proper; see the section "Using Virtual Tapes" in USAGE.TXT.
TAPE GENERATION [2]: Copying a real tape
========================================
This is likely to be the most common use of virtual tapes for a
new installation. This is also the only way to move data in and out of
a virtual system if there is no network support.
The simplest method for copying a real tape is to use the TAPEDD utility
provided with the emulator, as follows:
<Mount the physical tape on a drive such as /dev/rmt0a>
% tapedd it=/dev/rmt0a otv=kosh
This will copy the tape into a virtual tape named "kosh" with whatever
extension is appropriate for the format. Note that the TAPEDD
arguments have a form similar to that of the standard Unix DD utility,
but are not the same. Invoking TAPEDD without arguments will cause it
to list the possible options, most of which are never needed.
If you want to copy a virtual tape back onto a physical tape, then
the counterpart to the above command would be:
% tapedd itv=kosh ot=/dev/rmt0a
If for some reason TAPEDD is not available or you want to build a virtual
tape that isn't a direct copy of an existing physical tape, you will need
to get your hands dirty with method [3].
TAPEDD allows specifying the virtual tape format with a letter following
the "v". For example:
% tapedd it=/dev/rmt0a otvs=kosh
will copy a tape into a TPS format file called "kosh.tps".
TAPE GENERATION [3]: Creating a synthesized tape
================================================
One of the primary reasons for implementing virtual tapes as a
RAW-format pair of files (data and directory) was to simplify the
process of creating and managing these tapes by hand in an extremely
portable way, without using any special software tools.
To generate the tape directory file, all you need is a text editor.
To generate the tape data file, normally it suffices to use the Unix
utility "dd" or equivalent device-to-device copying program. You simply
need to append every byte of tape data into a sequential binary file.
For example, the tape data file corresponding to the sample tape
directory above could have been read with a command like this:
% dd if=/dev/rmt0a of=kosh.tap bs=126b
0+8407 records in
0+8407 records out
Note that to use this technique properly you must have some prior
knowledge of the record sizes on the tape. For one thing, the blocksize
specified must be larger than the largest possible record size, to avoid
record truncation (hence the bs=126b); but more importantly, without
knowing the record size you don't know what to put in the tape directory
(TDR) file. In this case, we know that TOPS-20 DUMPER records are <518
words * 5 bytes/word> = 2590 bytes and so the appropriate <recdesc> is
2590*8407. But if the records were of different lengths then DD
provides no way for you to tell what these lengths were; this is one
reason TAPEDD is easier.
[Aside: TOPS-20 DUMPER could actually use a blocking factor of up to 15,
so that records could be 15*518*5 = 38850 bytes long, but for virtual
tapes the blocking is irrelevant and a factor of 1 always works for
DUMPER.]
To read multiple files from a tape using DD you must use a non-rewind
device specification, such as "/dev/nrmt0a", and invoke DD once for
each file. Remember to insert "EOF"s at appropriate places in the
descriptor file.
Although there is an UNIX utility called READ20 that can extract
native files from TOPS-20 DUMPER format tapes (real or virtual), there
is currently none for the inverse operation. In order to transport
native files into the virtual system without a network, pretty much
your only option is to synthesize a virtual tape where the contents
are simple data files.
WFCONV is a handy utility included with the emulator that will help
prepare such files. It acts as a conversion filter, copying the
standard input to the standard output and converting the data from one
PDP-10 tape format to another. In order to fully understand why this is
needed, you need to understand something about PDP-10 tape formats; for
now, just note the following examples, and see the appendix for details.
Example 1: transferring an ASCII text file:
# Make NL -> CRLF and convert into core-dump format
% wfconv -tc > temp.tap
# Find size of file
% ls -l temp.tap
-rw-rw-r-- 1 klh klh10 18641 Apr 1 1994 temp.tap
# Use size to compute number of 512-byte records
# 18641/512 = 36, plus leftover record of 209
% cat > temp
TF-Format: raw
0: 512*36 209 EOF EOF ; 36 records plus a short 37th
EOT:
^D
%
;; Then in TOPS-20 after mounting the tape "temp":
;; Note default format is CORE-DUMP, default reclen is 512.
@copY (FROM) mta0: (TO) temp.txt
MTA0: => TEMP.TXT.1 [OK]
@vd temp.txt
PS:<OPERATOR>
TEMP.TXT.1;P777700 8 3729(36) 20-Apr-97 01:00:59 OPERATOR
@
Example 2: transferring a binary file of 8-bit bytes (no conversion needed):
% cp temp.dat temp.tap
% ls -l temp.tap # Find size of file
-rw-rw-r-- 1 klh klh10 18641 Feb 13 1994 temp.tap
% cat > temp
TF-Format: raw
0: 2560*7 721 EOF EOF
EOT:
^D
%
;; Then in TOPS-20 after mounting the tape "temp":
@set taPE rECORD-LENGTH (TO) 2560
@set taPE fORMAT (TO) iNDUSTRY-COMPATIBLE
@copY (FROM) mta0: (TO) temp.dat,
@@byTE (SIZE) 8
@@
MTA0: => TEMP.DAT.1 [OK]
@vd temp.dat
PS:<OPERATOR>
TEMP.DAT.1;P777700 10 18641(8) 19-Apr-97 23:57:46 OPERATOR
@
Example 3: building a TOPS-20 installation tape
If you already have a TOPS-20 system, especially one with local
modifications (which pretty much includes everyone), you may wish to
build your own installation tape. The following illustrates what the
tape directory of the V7.0 TOPS-20 installation tape looks like. Note
it does not have an initial bootstrap on it since MTBOOT is assumed to
be already loaded in the PDP-10 memory.
; Tape directory for V7.0 TOPS-20 installation tape
; Bytes: 22519060, Records: 8704, Files(EOF marks): 7
TF-Format: raw
0: 2560*597 EOF ; MONITR.EXE
1528320: 2560*125 EOF ; EXEC.EXE
1848320: 2560*8 EOF ; DLUSER.EXE
1868800: 1270 EOF ; DLUSER data
1870070: 2560*36 EOF ; DUMPER.EXE
1962230: 2590*7937 EOF ; DUMPER savesets for <SYSTEM>, etc.
22519060: EOF
EOT:
All of these files must be in core-dump format. You can generate the
tape either by:
(1) creating it on a real TOPS system and then using it directly
or using TAPEDD to copy it into a virtual tape.
(2) copying the necessary files over, converting them into core-dump
format, and concatenating them to form a virtual tape.
See "klt20.txt" for more details on how such an installation tape is
actually used.
Quick lesson in tape formats:
A PDP-10 word is 36 bits. The 8-bit bytes ("frames" on 9-track
drives) that are now universal for tape don't fit exactly into 36 bits,
which opens a Pandora's Box of packing options. The basic formats
offered at one time or another on Digital systems are as follows:
WFCONV mode TOPS-20 name
----------- ------------------
a ANSI-ASCII
c CORE-DUMP
h HIGH-DENSITY
i INDUSTRY-COMPATIBLE
s SIXBIT
Only CORE-DUMP and INDUSTRY-COMPATIBLE are universally supported; the
others are features of older or newer formatters. In general, the TOPS-20
monitor expects CORE-DUMP format so that should be your normal choice.
Tape_Coredump (5 tape bytes per word)
B0 1 2 3 4 5 6 7
8 9 10 11 12 13 14 15
16 17 18 19 20 21 22 23
24 25 26 27 28 29 30 31
0 0 0 0 32 33 34 35
Tape_Indust (4 tape bytes per PARTIAL word)
B0 1 2 3 4 5 6 7
8 9 10 11 12 13 14 15
16 17 18 19 20 21 22 23
24 25 26 27 28 29 30 31 ; Bits 32-35 are unused!
Tape_Sixbit (6 tape bytes per word)
0 0 B0 1 2 3 4 5
0 0 6 7 8 9 10 11
0 0 12 13 14 15 16 17
0 0 18 19 20 21 22 23
0 0 24 25 26 27 28 29
0 0 30 31 32 33 34 35
Tape_Ascii (5 tape bytes per word)
0 B0 1 2 3 4 5 6
0 7 8 9 10 11 12 13
0 14 15 16 17 18 19 20
0 21 22 23 24 25 26 27
35 28 29 30 31 32 33 34
Tape_Hidens (9 tape bytes per 2 words)
B0 1 2 3 4 5 6 7
8 9 10 11 12 13 14 15
16 17 18 19 20 21 22 23
24 25 26 27 28 29 30 31
32 33 34 35 B0 1 2 3
4 5 6 7 8 9 10 11
12 13 14 15 16 17 18 19
20 21 22 23 24 25 26 27
28 29 30 31 32 33 34 35
WFCONV operation notes
======================
Invoking WFCONV without arguments will print out a summary similar to
the following:
Usage: wfconv -io <infile >outfile\n\
where 'i' and 'o' are chars specifying the input and output formats:
c - Core-dump (std tape format, 4 8-bit, 1 4-bit bytes = 36 bits)
h - High-density (FTP 36-bit image, 9 8-bit bytes = 72 bits)
a,7 - Ansi-Ascii (4 7-bit, 1 8-bit byte = 36 bits)
s,6 - Sixbit (6 6-bit bytes = 36 bits)
u - Unixified (Alan Bawden format, various = 36 bits)
t - Text-Newline (CRLF-NL conversion; 5 7-bit bytes = 35 bits ONLY)
d - Debug (for output only)
Note: EOF on input always causes zero-padding up to a PDP-10 word boundary.
Typical uses of WFCONV would be as follows:
1. Examining a PDP-10 text file copied from a tape:
# Convert from core-dump to ansi-ascii (preserve CRs)
$ wfconv -ca < file.tap > file.asc
or:
# Convert from core-dump to text-newline (convert CRLFs to NLs)
$ wfconv -ct < file.tap > file.txt
2. Preparing a text file for writing to tape:
# Convert from ansi-ascii to core-dump (preserve NLs)
$ wfconv -ac < file.asc > file.tap
or:
# Convert from text-newline to core-dump (convert NLs to CRLFs)
$ wfconv -tc < file.txt > file.tap
3. Preparing a file for tape after transferring it from a real PDP-10
using FTP 36-bit Image mode:
# Convert from high-density (FTP Image) to core-dump
$ wfconv -hc < file.ftp > file.tap
Note:
Due to the fact that PDP-10 words are used as the canonical input
conversion target (and output conversion source), input is always
effectively rounded up to a word boundary.
This can cause the addition of a few trailing zero bytes when converting
from Text-Newline or Ansi-ASCII format, so WFCONV is not a
general-purpose text-to-text conversion program. For that, one can use:
# To insert CR (must use ^V or equiv to quote the ^M)
$ sed 's/$/\^M/' temp.nls > temp.crlfs
# To delete CR (must use ^V or equiv to quote the ^M)
$ sed 's/\^M$//' temp.crlfs > temp.nls