IMP11 User's Guide
Contents
1. Introduction
2. IMP11 (Source code: Pass 1, Pass 2, Pass 3)
3. LINK11 (Source code)
4. CODE11 (Source code)
5. DUMP11 (Source code)
6. CON11 (Source code)
7. Code conventions
8. Standard procedures
9. Language features
10. Relocatable object file format
1. Introduction
This document describes the IMP77 compiler and utilities which are
currently available on EMAS 2970. The compiler is aimed at producing
optimised code on PDP11 systems (assuming the EIS option is present);
there are currently no run-time checks compiled into the code and no
run-time diagnostics are produced. If the EIS option is not present on
the host PDP11 the compiler may be instructed to use subroutines for the
missing instructions (see under IMP11).
In all the commands described below the separator '/' may be replaced by
',' for compatibility with EMAS command format.
2. IMP11
This command invokes the IMP11 compiler to compile a source program
and produce a relocatable object file and a program listing file.
The form of the command is: IMP11 SOURCE/OBJECT,LISTING
If OBJECT is omitted the file source#REL is assumed, and if LISTING is
omitted the file source#LIS is assumed.
If SOURCE does not exist SOURCE#IMP is tried.
e.g. the command: IMP11 TEST
would produce an object file TEST#REL and a listing file TEST#LIS.
Compiler error reports are sent to both the listing file and the report
stream.
Control bit significance
The statement "CONTROL N" may be used to set various compile-time
options. Currently the significant bit values are:
1 Inhibit the check for matching recordformats in record
operations.
2 Permit RETURN from a function or map.
256 Use subroutines for MUL, DIV, and XOR.
3. LINK11
This command is used to link together all the component parts of a
complete program and produce an executable program file.
The form of the command is LINK11 {FLIST}, {MAP}
FLIST contains the list of files to be linked together (terminated by
.END) followed by the name of the file into which the linked program is
to be placed.
If FLIST is omitted the same information is requested from the command
input stream with the prompts File: for the files to be linked and
Object: for the final object file name.
MAP (which defaults to the null file) will receive a listing of the
entry points used in the object file together with their absolute
addresses.
e.g. Command: LINK11
File: main
File: subrt1
File: mylib
File: .end
Object: mainobj
LINK11 automatically defines several external values:
$TOP the address of the first instruction of the
program.
$SP the initial address for the stack pointer (R6).
$DS the initial address for the data stack pointer
(R5).
In reply to the File: prompt several keywords may be specified to alter
linking parameters:
.STACK nnn sets the stack size to nnn (octal) bytes. Default: 8K
bytes.
.NAME cccc sets the program name to the four characters cccc.
Default: the first 4 characters of the object file
name.
.STREAMS n defines the number of active I/O streams the program
will use. Default: 2
.FIXUP file specifies a file containing a list of entry names
together with the absolute addresses to which they are
to be bound. Each address may be preceeded by the
symbol '@' to indicate that the reference is indirect.
The list is terminated by .END.
e.g. TEST1 = 1760
TEST2 = 1762
ESCAPE=@1764
.END
.NOLIB inhibits the search of the standard library LIB11#REL
.NOPERM inhibits the inclusion of the standard library of
permanent procedures (assumed by the compiler)
PERM11#REL.
.ALONE s f specifies, in octal, the start address (s) and finish
address (f) of the area in which the object program is
to be executed in a stand-alone environment.
.ENTRY e s f
specifies that the program will be entered (at address
'e') with all registers set appropriately and so
inhibits the inclusion of the startup procedure. 's'
and 'f' are as for .ALONE.
4. CODE11
This command is used to combine a source program with a decoded
version of the relocatable object program in order to be able to examine
the machine-code produced by the compiler.
The form of the command is: CODE11 SOURCE,OBJECT,OFFSET/LISTING
If OBJECT is omitted it defaults to source#REL, and LISTING defaults to
the report stream.
e.g. Command: CODE11 TEST,TEST#REL
If offset is omitted the code is assumed to start at address zero.
Offset is interpreted as octal.
A variant of CODE11 ia ALIST11. This produces only a program map.
5. DUMP11
This command produces an octal dump of an executable object file.
The form of the command is: DUMP11 OBJECT/LISTING
LISTING defaults to the report stream.
6. CON11
This program takes as input an absolute loader format program (as may
be produced by a PDP11 assembler) and converts it into a relocatable
library file which may be input to the linker, LINK11, or the library
generator, LIB11.
The absolute object program must conform to the following standards.
1. The code must be position independent.
2. Each procedure must be of the form:
.WORD END-. ;size in bytes
.BYTE 4 ;length of entry name(4 in this case)
.ASCII /NAME/ ;entry name
.EVEN
EP: ....... ;entry point
.......
END: ;end of procedure
3. References to objects defined outwith the current
procedure must be made through GLOBL statements at the
start of the file. Each identifier specified in a
GLOBL will be replaced by the address of the
corresponding object. Note that as CON11 produces a
library file only those procedures which are used will
be loaded.
4. The file must be terminated with a null procedure,
i.e. .WORD 0
Note that at present the type of the object file
produced by the 2900 PDP11 assembler is incompatible
with this routine. The type may be changed by a call
on the routine NEWTYPE.
e.g. NEWTYPE ASS#REL
7. Code Conventions
This section describes the conventions used by the IMP11 compiler.
Register Usage
R0 work register (free for use)
second parameter
R1 work register (free for use)
first parameter
final string value parameter address
Function result (value)
Map result (address)
R2 work register (free for use)
R3 work register (free for use)
R4 local name base, LNB (locked)
R5 data stack pointer, DS (locked)
R6 stack pointer, SP (locked)
R7 program counter, PC (locked)
During the execution of a program the storage looks like:
small addresses +--------+
|........|
|........|
|--------|
|........| <--- LNB (local variables)
|........|
\........\
+--------+
| | <--- DS (first free location)
| |
\ \
| |
+--------+
|........| <--- SP (last used location)
|........|
large addresses +--------+
Procedure entry and exit
In general procedures are entered by pushing their parameters onto
the stack (DS) in the order given and jumping to the procedure using
JSR PC,....
e.g. FRED(1,2,3)
MOV #1,(DS)+
MOV #2,(DS)+
MOV #3,(DS)+
JSR PC,FRED
If the procedure has exactly one or two parameters and both of them
may be held in registers (e.g. INTEGER, ...NAME, ..ARRAYNAME) the
parameters will be placed in registers R1 and R2 before the call.
e.g. BERT(0, 7)
CLR R1
MOV #7,R0
JSR PC,BERT
If the final parameter of the procedure is a string value the address of
the actual parameter will be loaded into R1 before the call.
e.g. JIM(0, "Testing")
CLR (DS)+
MOV #text,R1
JSR PC,JIM
The called procedure is responsible for restoring LNB, DS, and SP to the
values they contained before the call. In particular the data stack,
DS, must be moved back over any stacked parameters.
Data Formats
integer 2 bytes word aligned
byteinteger 1 byte (unsigned) no alignment
string max+1 bytes, no alignment
real 4 bytes word aligned
record word aligned
...name 2 bytes word aligned {addr(n)}
..arrayname 2 bytes word aligned {addr(A(0,0,..))}
procedure (parameter) 2 bytes word aligned
containing the address of a two-word
descriptor
<<address of entry point>>
<<LNB at time of passing>>
8. Standard Procedures
The following external procedures are standard but their use depends
on the program executing under the control of a suitable
system-dependent control package.
integerfnspec ADDR(name N)
returns the absolute address of the object N.
integermapspec INTEGER(integer AD)
returns a reference to the integer at absolute address
AD.
byteintegermapspec BYTEINTEGER(integer AD)
returns a reference to the byteinteger at absolute
address AD.
realmapspec REAL(integer AD)
returns a reference to the real at absolute address AD.
string(*)mapspec STRING(integer AD)
returns a reference to the string at absolute address
AD.
record(*)mapspec RECORD(integer AD)
returns a reference to the record at absolute address
AD.
routinespec READSYMBOL(name SYM)
Inputs one unsigned 8-bit quantity from the currently
selected input stream and advances to the following
item. Depending on the control package attempting to
read beyond the end of file will either cause event 9
to be signalled, or will return the value x'8004'
{which is negative}.
integerfnspec NEXTSYMBOL
Inputs one unsigned 8-bit quantity from the currently
selected input stream without advancing to the
following item. On reaching end of file the function
will either cause event 9 to be signalled or will
return the value x'8004'.
routinespec SKIPSYMBOL
Discards the next 8-bit item from the currently
selected input stream and advances to the following
item. On end of file event 9 will be signalled.
routinespec PRINTSYMBOL(integer SYM)
Outputs one 8-bit item to the currently selected output
stream.
routinespec PRINTSTRING(string(255) TEXT)
Outputs the characters of the string TEXT to the
currently select output stream (using PRINTSYMBOL).
This routine has no effect if TEXT is the null string.
routinespec NEWLINE
Outputs one newline character to the currently selected
output stream {by calling PRINTSYMBOL(NL)}.
routinespec NEWLINES(integer N)
Outputs N newlines to the currently selected output
stream if N is greater than zero, otherwise no effect.
routinespec SPACE
Outputs one space character to the currently selected
output stream {by calling PRINTSYMBOL(' ')}.
routinespec SPACES(integer N)
Outputs N space characters to the currently selected
output stream if N is greater than zero, otherwise no
effect.
routinespec NEWPAGE
Outputs one form-feed character to the currently
selected output stream {by calling PRINTSYMBOL(12)}.
routinespec WRITE(integer N, PLACES)
outputs the decimal value of N to the currently
selected output stream (using PRINTSYMBOL). If PLACES
is greater than zero the number will be output
right-justified in a field of PLACES+1 character
positions, otherwise it will be output right-justified
in a field of -PLACES character positions. In either
case the size of the field will be expanded if the
requested size is too small to hold the number. The
maximum field size is 63 characters.
string(63)fn ITOS(integer N, PLACES)
has a similar effect to WRITE(N, PLACES) but returns
the number as a string rather than printing it.
WRITE(N, PLACES) has exactly the same effect as
PRINTSTRING(ITOS(N, PLACES)).
routinespec READ(name N)
first skips spaces and newlines from the currently
selected input stream. If N is an integer this routine
will input an integer value from the currently selected
input stream. The number may be represented in any
base by using the 'basedigits' form accepted by the
compiler. If N is a string this routine will input
characters until a space or a newline is the next
symbol, and return the characters read in the string.
routinespec SELECT INPUT(integer STREAM)
Makes STREAM the currently selected input stream.
Undefined input streams are considered to be attached
to the null file.
routinespec SELECT OUTPUT(integer STREAM)
Makes STREAM the currently selected output stream.
Undefined output streams are considered to be attached
to the null file.
routinespec OPEN INPUT(integer STREAM, string(31) FILE)
closes stream STREAM and re-opens it attached to the
object FILE (which must exist). This routine has no
effect on the currently selected input stream unless it
is STREAM, in which case the new definition will be
used in subsequent input requests.
routinespec OPEN OUTPUT(integer STREAM, string(31) FILE)
closes stream STREAM and re-opens it attached to the
object FILE (which need not exist). This routine has
no effect on the currently selected output stream
unless it is STREAM, in which case the new definition
will be used in subsequent output requests.
routinespec CLOSE INPUT
Closes the currently selected input stream and leaves
that stream selected, but attached to the null file.
Any subsequent input requests from that stream will
cause the appropriate end of file actions to be taken.
routinespec CLOSE OUTPUT
closes the currently selected output stream and leaves
that stream selected but attached to the null file.
Any subsequent output requests to that stream will
cause the output to be discarded.
routinespec RESET INPUT
causes subsequent read requests from the currently
selected input stream to take the items from the start
of the input source. The effects of this command when
the currently selected input stream is attached to a
device (terminal etc.) are system dependent.
routinespec RESET OUTPUT
causes all output sent to the currently selected output
stream to be discarded and for subsequent output
requests to start from the beginning of the stream.
The effects of the routine when the currently selected
output stream is attached to a device (terminal etc.)
are system dependent.
routinespec ABANDON INPUT
has the same effect as CLOSE INPUT; it is only provided
for symmetry.
routinespec ABANDON OUTPUT
is similar to CLOSE OUTPUT except that the output file
is not closed properly - it is destroyed without
affecting any previous version.
integerfnspec IN STREAM
returns the number of the currently selected input
stream.
integerfnspec OUT STREAM
returns the number of the currently selected output
stream.
string(31)fnspec IN FILE NAME
returns the string given to OPEN INPUT when the
currently selected input stream was opened.
string(31)fnspec OUT FILE NAME
returns the string given to OPEN OUTPUT when the
currently selected output stream was opened.
integerfnspec IN TYPE
returns a code for the type of the currently selected
input stream:
<0 null file
=0 interactive terminal
>0 file
the exact interpretation of the non-zero values is
system dependent.
integerfnspec OUT TYPE
returns the type of the currently selected output
stream. The type codes are described under IN TYPE.
routinespec PROMPT(string(15) TEXT)
Defines TEXT to be the message output to an interactive
terminal as a prompt when input is next requested. The
exact interpretation of this routine is system
dependent.
integerfnspec FREE STORE
returns the number of bytes available for program use.
integerfnspec REM(integer A, B)
returns the remainder when A is divided by B,
i.e. A-A//B*B
byteintegermapspec LENGTH(string(*)name S)
returns a reference to the byte containing the current
length of the string S.
byteintegermapspec CHARNO(string(*)name S, integer N)
returns a reference to the N'th character of the string
S.
string(1)fnspec TOSTRING(integer N)
returns a single character string, S, such that
CHARNO(S,1)=N&255
string(255)fnspec SUBSTRING(string(255) S, integer A, B)
returns the fragment of the string S from character
positions A to B inclusive. The length of the fragment
will be B-A+1 characters. The parameters A and B must
satisfy the relations:
0 < A <= LENGTH(S) and A-1 <= B <= LENGTH(S)
9. Language features
. Record format variants are now specified using the syntax:
"recordformat" <name> "(" <declist> ("or" <declist>)* ")"
<declist> :== <declarations>,
"(" <declist> ("or" <declist>)* ")"
e.g. recordformat PF(integer DE, SR,
(integer P1, P2, P3 or
string(3) PS), integer EN)
Each variant will start at the same relative address and all
will be padded out to the size of the largest.
For example, a record of the format PF declared above would
be laid out:
+----+----+----+----+----+----+
| | | P1 | P2 | P3 | |
| DE | SR |--------------| EN |
| | | PS |****| |
+----+----+---------+----+----+
0 2 4 6 10 12
. Constants may be specified either in the form:
<base>_<digits>
or using X', B', K', or O' (a convenience form of K').
. The form of multi-character constants 'CCC' is no longer
accepted as it lead to obscure errors following typing
errors. The form M'CCC' is accepted instead.
. CONST......NAME has been revived. The form is:
"const" <declarator> "name" <id> "==" <integer expression>
e.g. constinteger BASE = 8177700
costintegername VECTOR == BASE+4
10. Relocatable object file format
|==============================|
| Number of external entries |
|------------------------------+
| |
| external entries | integer ADDR, byte TYPE
| | string TEXT
+------------------------------+
| Number of references |
+------------------------------+
1: | |
2: | References | byte TYPE, string TEXT
.. | |
+==============================+
| Code size (bytes) |
+------------------------------+
| Glap size (bytes) |
+------------------------------+
| |
| Object records |
| |
|------------------------------+
| X'E0E0E0' |
+==============================+
Object record format
In the following list of items <<N>> stands for the 2 byte quantity
N, and <M> stands for the 1 byte quantity M. CA stands for the current
code address into which the next code item will be placed.
CB is the start of the code area (Code Base).
GB is the start of the gla area (Gla Base).
<1> <<N>> Add the word N to the current code area.
<2> <<N>> Add the word N to the gla.
<4> <<N>> <<D>> Add the word N+CB to the gla at location
D+GB.
<5> <<N>> Set the current code address to N+CB.
<6> <<L>> Set the current line number to L.
<7> <<X>> Add the address of the X'th external
reference to the next word added to the
code or gla.
<8> <<E>> End of object records. E+CB is the address
of the end of the event chain for this
module.
<9> Add CB to the next word to be planted.
<10> Add GB to the next word to be planted.
<11> Subtract (CA+2) from the next word to be
planted.