IMP11 User's Guide __________________ Contents ________ 1. Introduction 2. IMP11 3. LINK11 4. CODE11 5. DUMP11 6. CON11 7. Code conventions 8. Standard procedures 9. Language features 10. Relocatable object file format 1 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 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 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). 4 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. 5 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 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 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 +--------+ 8 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 <
> <> 9 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 name _____________ ADDR(____ N) returns the absolute address of the object N. integermapspec integer ______________ INTEGER(_______ AD) returns a reference to the integer at absolute address AD. byteintegermapspec integer __________________ BYTEINTEGER(_______ AD) returns a reference to the byteinteger at absolute address AD. realmapspec integer ___________ REAL(_______ AD) returns a reference to the real at absolute address AD. string mapspec integer ______(*)_______ STRING(_______ AD) returns a reference to the string at absolute address AD. record mapspec integer ______(*)_______ RECORD(_______ AD) returns a reference to the record at absolute address AD. routinespec name ___________ READSYMBOL(____ 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 integer ___________ PRINTSYMBOL(_______ SYM) Outputs one 8-bit item to the currently selected output stream. routinespec string ___________ PRINTSTRING(______(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. 10 routinespec ___________ NEWLINE Outputs one newline character to the currently selected output stream {by calling PRINTSYMBOL(NL)}. routinespec integer ___________ NEWLINES(_______ 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 integer ___________ SPACES(_______ 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 integer ___________ WRITE(_______ 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 fn integer ______(63)__ ITOS(_______ 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 name ___________ READ(____ 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 'based _igits' 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. 11 routinespec integer ___________ SELECT INPUT(_______ STREAM) Makes STREAM the currently selected input stream. Undefined input streams are considered to be attached to the null file. routinespec integer ___________ SELECT OUTPUT(_______ STREAM) Makes STREAM the currently selected output stream. Undefined output streams are considered to be attached to the null file. routinespec integer string ___________ OPEN INPUT(_______ STREAM, ______(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 integer string ___________ OPEN OUTPUT(_______ STREAM, ______(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. 12 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 string ___________ PROMPT(______(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 integer _____________ REM(_______ A, B) returns the remainder when A is divided by B, i.e. A-A//B*B 13 byteintegermapspec string name __________________ LENGTH(______(*)____ S) returns a reference to the byte containing the current length of the string S. byteintegermapspec string name integer __________________ CHARNO(______(*)____ S, _______ N) returns a reference to the N'th character of the string S. string fnspec integer ______(1)______ TOSTRING(_______ N) returns a single character string, S, such that CHARNO(S,1)=N&255 string fnspec string integer ______(255)______ SUBSTRING(______(255) S, _______ 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) 14 9. Language features ____________________ . Record format variants are now specified using the syntax: "recordformat or ____________" "(" ("__" )* ")" :== , "(" ("or __" )* ")" e.g. recordformat integer ____________ PF(_______ DE, SR, (integer or _______ P1, P2, P3 __ string integer ______(3) PS), _______ 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: _ 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 name _____" "____" "==" e.g. constinteger ____________ BASE = 8_177700 costintegername _______________ VECTOR == BASE+4 15 10. Relocatable object file format __________________________________ |==============================| | Number of external entries | |------------------------------+ | | | external entries | integer byte _______ ADDR, ____ TYPE | | string ______ TEXT +------------------------------+ | Number of references | +------------------------------+ 1: | | 2: | References | byte string ____ TYPE, ______ TEXT .. | | +==============================+ | Code size (bytes) | +------------------------------+ | Glap size (bytes) | +------------------------------+ | | | Object records | | | |------------------------------+ | X'E0E0E0' | +==============================+ 16 Object record format ____________________ In the following list of items <> stands for the 2 byte quantity N, and 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> <> Add the word N to the current code area. <2> <> Add the word N to the gla. <4> <> <> Add the word N+CB to the gla at location D+GB. <5> <> Set the current code address to N+CB. <6> <> Set the current line number to L. <7> <> Add the address of the X'th external reference to the next word added to the code or gla. <8> <> 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. 17