PDP-8 MainDEC Diagnostic Area

Welcome to the mainDEC area.  This is where official DEC PDP-8 family
paper-tape diagnostics and related material are kept.  The usual material
here is a collection of diagnostic programs originally distributed as
binary paper tapes.  Originally associated with each tape was a (generally
badly-xeroxed) paper listing of an associated write-up file documenting
the program, which usually concluded with a highly reduced (and often only
barely readable) copy of an assembly listing of the program itself. 
Often, the user was referred to the listing itself to deal with specific
hardware-induced and detected problems, etc. 

Available Files. 

1)  Binary Files.

In some cases, the only article available will be the binary program
itself.  In which case, only those already familiar with the program can
use it, or else you have to disassemble it yourself and figure out how to! 

2)  User-provided Help Files.

Hopefully, knowledgeable users can fill us in on how to use the program,
at least the fundamentals of how to make it run to a successful
no-errors-found completion, etc.  Many diagnostics halt for all sorts of
reasons.  Some may be innocuous but require some action to correct.  Even
the successful exit of the program might be a halt!  Without that basic
information, the binary files are useless, so a short help file can make
the program viable, etc. 

3)  Machine-readable write-ups.

If available, it is hoped that someone will at least submit the front of
the write-up, which was usually a plain text file using a paragraph
numbering scheme common in DEC documentation.  This is usually an adequate
form of documentation, except where it refers to specifics within the
program listing, etc.  The best thing would be to provide the equivalent
of the write-up front and also the PAL source program file.  With both of
these available we can create an equivalent of the absolute original
write-up, minus the degradation caused by the poor copying technique DEC
often used! 

4)  Additional Warning Files and Notes.

Additionally, associated .BWR files might be present to indicate warnings
to would-be users about non-obvious quirks of the program. 

For example, some diagnostics are actually incompatible with the various
operating systems (P?S/8, OS/8, etc.) that would be expected to run them! 
One would expect the contrary, but some of the programs can merely be
stored on these systems, not loaded from them!  (And even worse, there may
be limitations on the storage method, i.e., attempts to use the system
loading utility could create a corrupted copy of the program!  For
example, the PDP-8/e Random ISZ test assumes that 07600-07777 is the
exclusive province of the RIM loader, the BIN loader, and itself!  Not
only does it access locations in this page (which would destroy OS/8 or
P?S/8), but it actually loads code there!  Thus, it is acceptable to
create a binary file called RANISZ.BN and store that on OS/8, but it is
not acceptable to create a file named RANISZ.SV, since OS/8 ABSLDR will
"protect" OS/8 and inhibit the loading into 07600-07777.  The resultant
RANISZ.SV is corrupted and non-functional.)

It is conceivable that a patch may be available to allow some form of
restrictive loading of a program on an operating system, or some quirk of
a system can be exploited to overcome a straight-forward restriction. 

For example, the problematic RANISZ program could be loaded into field 3
on a 16K or more machine. (Field 2 can be used on some systems!) An
additional small program could then move all of field 3 to all of field 0
and start the original program up as intended.  As a result of this, OS/8
is wiped out in memory and will need manual re-boot later, but the program
can run as intended. 

Alternately, there is a P?S/8 method that may allow problematic programs
to run in a similar manner without requiring extended memory at all. 
P?S/8 inhibits loading into 07600-07777 in a manner similar to OS/8, and
this is done to provide the same kind of protection against system
corruption.  This is accomplished using the BIN program's /V switch (which
is default on certain system configurations). 

However, the inhibited loading is not totally lost under P?S/8 BIN,
because, unlike OS/8 ABSLDR, BIN stores an image of the attempt to load
into 07600-07777 in a known save area on the system device.  It is
possible to write a P?S/8-specific patch to a program requiring only a
small patch loading area, and a one-page buffer to temporarily move the
07600-07777 loading into.  The patch is started first, and it reads the
image of the inhibited loading into the provided page buffer, then moves
the data from the buffer to 07600-07777.  P?S/8 is destroyed in memory,
and will require a re-boot later, but the program is now loaded as
intended and can be started up by the patch, etc. 

Additional changes beyond the diagnostic can be provided.  For example, by
making a two-word patch to the PDP-8/e extended memory checkerboard, and
then providing a very short program to start before starting the main
program up, it is possible to have the memory diagnostic performed while a
VT8E is running in worst-case DMA graphics mode.  (Note:  the VT8E can
request many back-to-back DMA cycles that can exercise a memory faster
than the diagnostic!) During such a test, MM8E 4K and 8K memory modules
have been found to fail unless the strobe adjustment is fine-tuned more
carefully that would otherwise pass the unpatched test.  This enhances
reliability, and is always recommended where applicable, etc.  This small
patch program will be provided in the associated EXMCHK.BWR file for the
diagnostic which is itself available as EXMCHK.BN. 

Thus, it is possible for any specific diagnostic program to have a small
collection of hints and kinks associated with it.  Some of the methods
described are somewhat generic for a class of troublesome diagnostics, so
it is likely that the program-specific note file will refer to another
file on how to implement the relevant technique, etc. 

File Formats.

Other than the actual programs, all files in this section are ASCII text
files.  The binary programs will be stored in a variety of ways to allow a
variety of purposes. 

1) BIN Format.  In this format, the original paper-tape is stored frame by
frame into 8-bit bytes.  The system that stores this archive file must be
capable of maintaining the 8-bit characters exactly as provided.  This
format is the one most likely to be used by a PDP-8 emulator running on
another machine where the underlying file structure can maintain the 8-bit
frames of the original paper-tape correctly.  These files consist of a
leader, the binary program in RIM or BIN format, and a trailer.  Some
files will essentially be composites of this format.  For example, FOCAL,
1969 is generally read in as two independent binary tapes spliced
together, with leader/trailer between the sections.  Whether a file is RIM
or BIN should be clear from the file name; most are BIN format.  (Some
files are actually compatible with both the RIM and BIN loaders.  In some
special cases, the file may be in some alternate format such as the "help"
or "slim" loader format.  Utilities such as these were developed to make
it easier to load tapes from scratch than even the RIM loader.  Generally,
the only files in their format are the help-out files that cause RIM
and/or BIN to be present as a consequence, etc.)

Note:  some files may appear to have quite short leader/trailer, and a
single ^Z character within the trailer.  These files have been processed
by OS/8, and are either the output of an assembler, or were converted via
OS/8 PIP using the /B option.  There is no operational difference between
these files and the original paper-tapes, but the precise format of the
non-data leader and trailer is admittedly different.  (Some paper-tapes
included checksum information provided by a program known as "master tape
duplicator" which is stripped by this process.  The lost information is
not related to the binary program's contents, but rather is only
meaningful to the tape duplication program, etc.)

2) .BOO format.  This is a printably encoded format that is popular on
MS-DOS and other systems to transfer 8-bit-oriented files through
"hostile" environments such as e-mail.  It uses a restricted character set
that will pass through many systems, and a limited form of compression. 
(Note:  since the compression is 8-bit oriented, and only compresses
zeroes, little PDP-8 binary file compression will tend to occur.)
Utilities exist for all popular systems, including OS/8, to encode/decode
files into .BOO format for transport between systems.  When a .BOO format
version of a binary file is decoded on a target system, the resultant file
should be identical to the BIN format file described above.  The OS/8
version of the utilities ensure that this is true by following the
standard OS/8 pack/unpack scheme of the so-called "3 for 2" technique. 
Thus, all binary and text files will convert correctly through .BOO
transfers, etc. 

3) ENCODE format.  This is a printably encoded format that is currently
unique to OS/8.  It uses a more restrictive character set than .BOO
encoding, to achieve a more robust format that can be transmitted through
even more "hostile" environments than .BOO is capable of.  (For example,
ENCODE format files can survive being transferred as a WPS document.  This
facility may be unique to ENCODE format.  It has already been determined
that .BOO and uuencode format cannot pass as a WPS document!)
Additionally, ENCODE format can "survive" having the case of all of the
letters changed.  Any OS/8 file can be transferred through the
ENCODE/DECODE utilities, as the method is intrinsically image oriented, so
there is no problem encoding .SV or other files, etc. 

The ENCODE file format is 12-bit oriented, and includes a form of
compression that allows any 12-bit data value to be repeat compressed (as
opposed to .BOO's 8-bit-zeroes-only compression) if possible.  The file
includes imbedded commands, file checksums, and encourages internal
documentation regarding what the file is about, etc. The OS/8 version
include automatically generated comments about the file's creation date,
ENCODE file's creation date, etc. 

An ENCODE file may contain either a single file or multiple files.
(Currently, the OS/8 utilities only support a single file.) Each file in
turn represents either a single OS/8 file, or an image of an entire OS/8
device, or an approximate "half" of an OS/8 device.  (The reason for
representing "half" of a device is that on a meager configuration, it may
not be possible to convert an entire device image.  For example, an OS/8
system device could consist of merely a dual-drive RX01, and no other
devices are available.  Since an ENCODE image of an entire RX01 is usually
larger than a single RX01's capacity to hold that encoded file, it's
usually not possible to provide the image file as input to the DECODE
utility! (In cases of extraordinary compression, this wouldn't be a
problem.  For example, a sparsely used RX01 would have a lot of unused
space hopefully containing blocks totally consisting of a repeated
formatting pattern.  In that case, the resultant ENCODE file would be
quite small!) By splitting the image into a "first half" and a "second
half" it is then possible to store a bootable OS/8 system, the DECODE
utility, and a copy of the ENCODE input file on one drive, and write the
half-image to the other drive.  Repeating the process with the other
"half's" file finishes the transfer, etc.  The "half" files are an
approximate description, because the ENCODE files cover half of the
device, but each is subject individually and independantly to the
possibility of compression to a somewhat smaller size that will likely
vary, etc.)

4) IPL format.  This is a format vaguely similar to BIN format, except
that it's stripped down like RIM format in terms of loading controls, etc. 
However, the data is encoded into printable characters instead of
paper-tape frames.  Thus, the loader has to strip off a "bias" value from
the data.  As a result, all "white space" and other control characters
such as CR, LF, FF, HT, etc. are ignored during the loading.  This allows
the file to exist as an easily maintained printably encoded text file in
any system. 

The IPL format file is restricted to an implied initial loading address of
0000 and all loading is strictly sequential.  The file and loader must
agree on the length of the load implicitly, although the usual practice is
to load all of 0000 through 7577 to conform with the usual OS/8 and P?S/8
restrictions, etc.  (An IPL loader could be written to load 0000-7777 of
an available field, such as 3.  But 07600-07777 is never available in OS/8
or P?S/8.  In OS/8 17600-17777 is never available, and 27600-27777 is
often not available.  In certain P?S/8 configurations 6000-7777 or perhaps
0000-7777 of the highest implemented field (through 7) may be unavailable,
while a lesser field greater than 0 might be available for loading from
0000-7777.) The loading program controls what memory field the program is
loaded into, although comments in the IPL file might indicate the intended
field, etc. An OS/8 SAVE command is generally given after the loader exits
to the keyboard monitor to finish the loading.  P?S/8 versions of an IPL
loader can exit to the keyboard monitor after having 0000-7777 preserved
in the % and $ files with all other memory intact.  This accomplishes the
equivalent of the OS/8 SAVE command for most files, etc. 

An advantage of the IPL format is that it allows elaborate leader/trailer
comments.  The only restriction placed on the leader is that the
characters in the leader must be lower-case and devoid of characters from
octal 041 (!) through 140 (`).  Since space characters (octal 040) are
freely allowed anywhere in the file, as well as CR (octal 15) and LF
(octal 12), a rather elaborate leader can be constructed.  The trailer
consists of at least one lower-case character followed by literally
anything.  Thus, IPL files may have a lower-case comment referring the
reader to a mixed-case comment at the other end. Since the only purpose of
an IPL file is to load a mutually agreed upon single PDP-8 field, the file
cannot be longer than 8K characters, not including formatting overhead and
comments, etc. 

The IPL format was developed to allow a direct transfer between a PDP-8 or
DECmate and a "nearby" other system that can transfer the IPL file over a
serial line.  The IPL loading program is very tiny, although somewhat
larger than the RIM loader.  The serving system can treat the IPL file as
a normal text file; cosmetic alterations such as FF, CR/LF breaks, etc.
are allowed to make the file more "palatable" to the serving system as
necessary without corrupting the data.  The only requirement is that the
connection between systems be error-free.  (The IPL format is used to
distribute Kermit-12 to systems lacking any other form of communication
program.  Since all of the data is stored in memory, no particular
protocol is required; the serving system can send the file as fast as
possible once the loading program is started on the PDP-8 end, etc.)

5) Other formats.  If there is sufficient interest, uuencode format can be
provided, but there is no current PDP-8 uuencode program. Most other
systems that have uuencode can also run the .BOO utilities however.  The
.BOO utilities maintained by Columbia University for MS-Kermit
distribution are generally adaptable to most other systems that may
require any additional formats, etc. Note: only the latest version of the
Columbia .BOO utilities should be used due to longstanding bugs now
corrected.  The PDP-8 .BOO utilities have never had these problems, etc. 

[End of file; last edit 19-Dec-1993 cjl]