A large commit.

[pdp8.git] / sw / kermit / k12 / k12ipl.doc

From: Charles Lasner <lasner@watsun.cc.columbia.edu>
Subject: Initial Program Load (.IPL) format description

    Some of the latest KERMIT-12 binary files are encoded in a
specialized format designed to allow direct memory loading without an
elaborate protocol such as KERMIT.  This document will describe the
internal encoding of this format known as IPL, and related subjects.

    The Initial Program Load (.IPL) format is designed expressly for
use with the IPL loading program.  An error-free connection to a
serving host is required as no checking or recovery is performed by
the program. (The program itself is meant to be keyed in on the
target PDP-8 where there is no other means of acquiring KERMIT-12.)
The format is also meant to be "printable" in the same sense as
ENCODE, .BOO, or uuencode files.  This makes the file format more
"friendly" to the host system, and allows simple editing of the file
to insert comments, etc.

    An .IPL file starts with at least one lower-case character (not
counting `) meaning any character in the range 141-177 octal.  Any number
of similar characters may follow immediately to create an arbitrary length
leader, but the lower-case requirement must be strictly enforced.  Once a
non-lower-case character is encountered, it is accepted as the first data
character.  Data characters continue throughout the rest of the file until
the next occurrence of a lower-case character which ends the loading.  Any
characters past this point are ignored and can be freely added as a
trailing comment.

    Throughout the entire .IPL file, control characters and <SPACE>
(000-040 octal) are ignored and may be used within the leader to make
the file comment(s) more readable.  In some loading situations, <NUL>
or <SPACE> characters may be pre-pended to the file to give the
operator sufficient time to run down the hall between machines in
different rooms to start the PDP-8 loading program after first
starting the server.  Data lines are broken every 64 characters with
<CR>/<LF> to make the file more "readable" to the host system.

    Each data character in the body of the file represents six bits of
PDP-8 data encoded in the form (value+041 octal).  This causes 00 octal to
be represented as ! through 77 octal to be represented as `.  Data
characters are taken in pairs where the first character is the upper six
bits and the second is the lower six bits of a twelve bit word.  Loading is
implied to start at 0000 of the loading field and continues through at most
7577.  The operating system generally prohibits loading into 7600-7777.
This is not a problem since KERMIT-12 conforms to these limitations as a
matter of design.  If the loading field is 3 or greater (or possibly 2 in
certain configurations) then the entire field can possibly be loaded.  This
is never recommended because such a file would violate loading restrictions
of certain configurations.  (The general rule is to never load into
x7600-x7777 for any field x in the range 0-7.)

    The loading field itself is not contained in the file data, so it is
the user's responsibility to setup the loading program parameters
accordingly.  File comments (in lower-case if in the leader) often contain
this information to aid the user.  After loading is complete, the loading
program exits to the operating system.  The user must save the recently
loaded data as an image (.SV) file by providing explicit arguments to a
SAVE command.  It is recommended that the appropriate command be contained
in the trailer of the .IPL file as a comment.  Placement at the end of the
file allows the commentary to be in upper-case, thus allowing it to be
given in the exact form required by OS/8.  Certain characters such as "."
are required in the complete documentation of these commands which are not
allowed in the leader area.  The leader can contain a comment referring the
user to the end of the file for the information itself.

[end of file]