Trailing-Edge
-
PDP-10 Archives
-
bb-d868b-bm_tops20_v3a_2020_dist
-
3a-documentation/macsym.doc
There are 26 other files named macsym.doc in the archive. Click here to see a list.
MACSYM.DOC
September 1978
COPYRIGHT (C) 1976,1977,1978 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.
MACSYM.DOC Page 2
MACSYM.DOC
September 1978
1.0 SUMMARY
MACSYM is a file containing macro definitions and object-time support
code which implement a number of useful machine-language coding
facilities used in the monitor and system program sources. These
facilities include variable naming and storage conventions and data
structure techniques similar in principle to capabilities found in
some implementation languages.
MACSYM is not an executable program. It may be assembled by and used
with MACRO version 52.
MACSYM requires MONSYM.UNV for assembly and use.
2.0 EXTERNAL CHANGES
There are no external changes in MACSYM for Release 3A.
3.0 KNOWN BUGS AND DEFICIENCES
There are no known bugs or deficiencies in MACSYM.
4.0 INSTALLATION INSTRUCTIONS
4.1 Files Needed for MACSYM Use
MACSYM.UNV - Universal file for MACRO assemblies
MACREL.REL - Object-time support routines.
MACSYM.DOC Page 3
4.2 Instructions for Loading and Installing MACSYM
Mount the tape labeled Installation Tape on MTA0: and type the
following commands:
R DUMPER
TAPE MTA0:
REWIND
DENSITY 1600-BPI
SKIP 2
RESTORE <*>MACSYM.* (TO) SYS:*.*.-1,<*>MACREL.* (TO)
<SUBSYS>*.*.-1
REWIND
4.3 Files Need to Build MACSYM
MACSYM.MAC
REL1.MAC
In addition, the following file must be on SYS:
MONSYM.UNV
4.4 Instructions for Building MACSYM
Mount the tape labeled Distribution Tape on MTA0: and type the
following commands:
R DUMPER
TAPE MTA0:
REWIND
DENSITY 1600-BPI
SKIP 3
RESTORE <*>*.*.* (TO) <self>*.*.*
REWIND
^C
SUBMIT MACSYM.CTL/TIME/UNIQ:0/REST
Once the batch job has successfully completed, the files MACSYM.UNV
and MACREL.REL should be copied into SYS:.
4.5 Special Considerations
MACSYM is not an executable program. Hence, there is no .EXE file of
it ever created.
MACSYM.DOC Page 4
5.0 INTERNAL CHANGES
There are no changes to MACSYM for Release 3A.
6.0 SUGGESTIONS
MACSYM.DOC Page 5
APPENDIX A
MACSYM is a file of standard macro and symbol definitions for
use with TOPS20 machine language programs. Use of these
definitions is recommended as a means of producing more
consistent and readable MACRO sources. Some of the definitions
were obtained from C.MAC; others will be added if they are
generally useful.
MACSYM is available on SYS: in two forms, MACSYM.UNV and
MACREL.REL. The first is the universal file of macro and
symbol definitions; the second is a file of small support
routines used by certain of the facilities (e.g., stack
variables). The universal file is normally obtained at
assembly time by the source statement
SEARCH MACSYM
The object file, if necessary, may be obtained by the source
statement
.REQUIRE SYS:MACREL
This instructs LINK to load the object file along with the main
program. The file is loaded only once even if the .REQUIRE
appears in several source modules, and no explicit LINK command
need be given.
Certain conventions are observed regarding the construction of
symbols as follows: ("x" represents any alphanumeric)
xxxxx. an opdef or macro defininition
.xxxxx a constant value
xx%xxx a mask, i.e., a bit or bits which specify a
field
Symbols containing multiple periods may be used
internally by some macros.
Symbols containing "$" are not used or defined by DEC
and are reserved for customer use.
The following definitions are available in MACSYM and are
arranged into groups as shown.
1. STANDARD PROGRAM VERSION
This macro assembles the standard contents of .JBVER.
PGVER. VERS,UPDAT,EDIT,CUST
MACSYM.DOC Page 6
where VERS is the major version number
UPDAT is the update or minor version number
(1=A, 2=B, ...)
EDIT is the edit number
CUST is the customer/SWS edit code (1=SWS,
2-7= customer)
A word constructed from these quantities is assembled into
absolute location .JBVER (137); the current assembly location
is restored.
2. MISCELLANEOUS CONSTANTS (SYMBOLS)
.INFIN = 377777,,777777 ;plus infinity
.MINFI = 400000,,0 ;minus infinity
.LHALF = 777777,,0 ;left half
.RHALF = 0,,777777 ;right half
.FWORD = 777777,,777777 ;full word
3. CONTROL CHARACTERS (SYMBOLS)
Symbols are defined for all control character codes 0 to 37 and
175-177. The following are the commonly used characters; see
source listing for others.
.CHBEL = 07 ;bell
.CHBSP = 10 ;backspace
.CHTAB = 11 ;tab
.CHLFD = 12 ;linefeed
.CHFFD = 14 ;formfeed
.CHCRT = 15 ;carriage return
.CHESC = 33 ;escape
.CHDEL = 177 ;delete (rubout)
4. PC FLAGS (MASK SMBOLS)
MACSYM.DOC Page 7
PC%OVF = 1B0 ;overflow
PC%CYO = 1B1 ;carry 0
PC%CY1 = 1B2 ;carry 1
PC%FOV = 1B3 ;floating overflow
PC%BIS = 1B4 ;first part done (byte increment
suppress)
PC%USR = 1B5 ;user mode
PC%UIO = 1B6 ;user IO mode
PC%LIP = 1B7 ;last instruction public
PC%AFI = 1B9 ;ADDRESS FAILURE INHIBIT
PC%ATN = 1B10 ;apr trap number
PC%FUF = 1B11 ;floating underflow
PC%NDV = 1B12 ;no divide
5. MACROS TO MANIPULATE FIELD MASKS
Many of the symbols in MACSYM and MONSYM define flag bits and
fields. A field mask is a full-word value with a single
contiguous group of 1's in the field. E.g., 000000,,777000
defines a field consisting of bits 18-26. The following macros
may be used in expressions to deal with these masks.
WID(MASK)
Width - computes the width of the field defined by the mask,
i.e., the number of contiguous 1-bits. Value is not defined if
mask contains non-contiguous 1-bits.
POS(MASK)
Position - computes the position of the field defined by the
mask. The position of a field is always represented by the bit
number of the rightmost bit of the field regardless of the
width of the field. This is sufficient to specify the entire
field in the case of flags (1-bit fields).
POINTR(LOC,MASK)
Byte pointer - constructs a byte pointer to location LOC which
references the byte defined by MASK. E.G.,
POINTR(100,77) = POINT 6,100,35 = 000600,,100
MACSYM.DOC Page 8
FLD(VAL,MASK)
Field value - Places the value VAL into the field defined by
MASK. E.g., FLD(3,700) = 0,,000300
.RTJST(VAL,MASK)
Right-justify - Shift VAL right such that the field defined by
MASK is moved to the low-order bits of the word. E.g.,
.RTJST(300,700) = 3
MASKB(LBIT,RBIT)
Mask - construct a mask word which defines a field from bit
LBIT to bit RBIT inclusive. E.g., MASKB(18,26) = 0,,777000.
6. INSTRUCTIONS USING FIELD MASKS (MACROS)
The following mnemonics are similar to certain machine
instructions used to move and test bits and fields. These
macros select the most efficient instruction for the mask being
used.
MOVX AC,MASK
Load AC with constant. MASK may be any constant; this
assembles one of the following instructions: MOVEI, MOVSI,
HRROI, HRLOI, or MOVE literal.
TXmn AC,MASK
where m is: N, Z, O, C
n is: E, N, A, null
There are 16 definitions of this form which include all of the
modification and testing combinations fo the test instructions,
i.e., TXNN, TXNE, TXO, TXON, etc. A TL, TR, or TD literal is
assembled as appropriate.
IORX AC,MASK
ANDX AC,MASK
XORX AC,MASK
These are equivalent to certain of the TX functions but are
provided for mnemonic value.
JXm AC,MASK,ADDRESS
This is a set of four definitions which jump to ADDRESS if the
field specified by MASK meets a certain condition. The
condition (m) may be:
MACSYM.DOC Page 9
E - jump if all masked bits are 0
N - jump if not all masked bits are 0
O - jump if all masked bits are 1
F - jump if not al masked bits are 1 (false)
These macros will assemble into one, two, or three instructions
as necessary to effect the specified result.
E.g., JXN T1,1B0,FOO = JUMPL T1,FOO
JXE T1,770,FOO = TRNN T1,770
JRST FOO
7. DATA STRUCTURE FACILITY (MACROS)
This set of macros provides a comprehensive facility for the
definition and use of data structures. It is an extension of
some of the techniques represented by the field mask facilities
above. Typically, a data structure definition will include
some information about the location of the data in memory as
well as its position within a word. These facilities are
intended to provide the following advantages:
1. Data items may be referenced more mnemonically, e.g.,
two data items in the same word would be given
different names rather than merely being known as the
left half or right half of the word.
2. Should the need arise, storage formats may be changed
without incurring the expense of a search of the code
to change each reference.
DEFSTR NAME,LOCATION,POSITION,SIZE
MSKSTR NAME,LOCATION,MASK
These macros both define a data structure called NAME.
LOCATION specifies the memory location of the desired word and
consists of address, index, and indirect fields in the usual
form, i.e., @address(index). Any of the fields may be omitted
if not needed, and the entire location argument may be null in
some circumstances. The remaining arguments define the desired
field. DEFSTR specifies the field in terms of its position
(right-most bit number) and size (number of bits), while MSKSTR
specifies the field by a full-word mask as described earlier.
Normally, the actual storage to be used is declared separately,
e.g., by a BLOCK statement.
As a simple example, consider an array of full-word data items.
MACSYM.DOC Page 10
We wish to use the name FOO for the data itself, so we declare
the actual storage by some other name, e.g.,
FOO1: BLOCK n
Then we declare the structure by
DEFSTR FOO,FOO1(FOOX),35,36
This says that we declare a data item called FOO, that the
items are addressed by FOO1(FOOX) (assuming that the index is
kept in register FOOX), that the items are 36-bit quantities
with the rightmost bit in bit 35 (i.e., full words). If
instead, we wish to declare that each word of FOO1 consists of
an item in the left half and two 9-bit items in the right half,
we could write:
DEFSTR FIRSTD,FOO1(FOOX),17,18 ;LH item
DEFSTR SECOND,FOO1(FOOX),26,9 ;one 9-bit item
DEFSTR THIRDD,FOO1(FOOX),35,9 ;another 9-bit
; item
Data items defined with DEFSTR or MSKSTR may be referenced in a
general way. At each instance, additional location information
may be given if necessary. A set of reference functions
(macros) is defined for most common operations, some affecting
AC and memory, others only memory. For example, the LOAD
function loads a data item into an AC and is written as
LOAD AC,NAME,LOCATION
where AC is the AC to be loaded
NAME is the structure name as defined with DEFSTR
LOC is location specification in addition to that
declared in the structure definition. This
field may be null in some cases.
Taking the example definitions above, we may write
LOAD T1,FOO
which would assemble into
MOVE T1,FOO1(FOOX)
or
LOAD T1,SECOND = LDB T1,[POINT 9,FOO1(FOOX),26]
LOAD T1,FIRSTD = HLRZ T1,FOO1(FOOX)
MACSYM.DOC Page 11
Note that the macro compiles the most efficient instruction
available to reference the specified field.
The optional third argument is provided to allow some of the
location information to be specified at each instance. For
example, if the definition is
DEFSTR FOO,FOO1,35,36
Then the index may be specified at each instance, e.g.,
LOAD T1,FOO,(XX)
LOAD T2,FOO,(T1)
The specification given in the definition is concatentated with
the specification given in the reference.
The following reference functions are presently defined:
LOAD AC,NAME,LOC load data item into AC
STOR AC,NAME,LOC store data item from AC into
memory
The data item is right justified in the AC.
SETZRO NAME,LOC set the data item to zero
SETONE NAME,LOC set the data item to all ones
SETCMP NAME,LOC complement the data item
INCR NAME,LOC increment the data item
DECR NAME,LOC decrement the data item
For functions not specifically provided, the following may be
used
OPSTR OP,NAME,LOC
OPSTRM OP,NAME,LOC
OP is any machine instruction written without an address field.
It will be assembled such as to reference the specified data
structure. OPSTR is used if memory is not modified, OPSTRM is
used if memory is modified. E.g.,
OPSTRM _<ADDM T1,>,FOO
to add the quantity in T1 to the data item FOO.
The following test and transfer functions are presently
defined:
MACSYM.DOC Page 12
JE NAME,LOC,ADDR jump to ADDR if data is 0
JN NAME,LOC,ADDR jump to ADDR if data is not 0
The following test and transfer functions take a list of
structure names (surrounded by angle-brackets) or a single
structure name. They compile code to test each data item in
the order given, and will stop as soon as the result of the
function is known (e.g., AND encounters a false term).
JOR NAMLST,LOC,ADDR jump to ADDR if any data item is true
(non-0)
JAND NAMLST,LOC,ADDR jump to ADDR if all data items true
(non-0)
JNOR NAMLST,LOC,ADDR jump to ADDR if all data items false
(0)
JNAND NAMLST,LOC,ADDR jump to ADDR if any data item is false
(0)
These functions optimize multiple fields in the same word if
they are adjacent in the structure list. If the final location
is an accumulator, further optimiZation is done.
As a final example of the data structure facility, consider the
typical case of data organized into unit blocks with pointers
to other blocks. Such a block may appear as
Flag 1 Flag 2 Code List pointer
! ! ! !
V V v V
+---+---+---------+---------+-------------------------+
! ! !/////////! ! !
+---+---+---------+---------+-------------------------+
! additional node data !
+-----------------------------------------------------+
! '''''''' !
We assume that n-word blocks will be allocated from a free pool
at execution time. The structure of the block is declared as
follows:
MSKSTR FLAG1,0,1B0
MSKSTR FLAG2,0,1B1
DEFSTR CODE,0,17,9
DEFSTR LINK,0,35,18
MACSYM.DOC Page 13
DEFSTR NODDAT,1,35,36
Note that the location field contains only the offset address
of the word within the block; the address of the block will be
specified in an index at each reference. References would
appear as follows:
LOAD T1,LINK,(T1) ;step to next node in list
STOR T2,CODE,(T1) ;set new block code
JE FLAG1,(T1),FLOFF ;jump if flag1 is off
JAND _<FLAG1,FLAG2>,(T1),FLGSON ;jump if flag1 and
; flag2 are both on
8. SUBROUTINE CONVENTIONS (MACROS/OPDEFs)
The following definitions are used to make subroutine mechanics
more mnemonic. Reference is made to these conventions
elsewhere in this document.
CALL address
Call subroutine at address; equivalent to PUSHJ P,address
RET
Return from subroutine; equivalent to POPJ P,
RETSKP
Return from subroutine and skip; equivalent to
JRST [AOS 0(P)
RET]
CALLRET address
Call the subroutine at address and return immediately
thereafter; equivalent to
CALL address
RET
RETSKP
CALLRET assembles as JRST but should be treated as if it
assembles into several instructions and cannot be skipped over.
AC Conventions
The facilities described here assume in some cases the
following AC conventions:
MACSYM.DOC Page 14
AC1-AC4 temporary, may be used to pass and
return values
AC0,AC5-AC15 preserved, i.e., saved and restored if
used by subroutine
AC16 temporary, used as scratch by some
MACSYM facilities
AC17 stack pointer
9. NAMED VARIABLE FACILITIES (macros and runtime code)
A traditional deficiency of machine language coding
environments is facilities for named transient storage
("automatic", etc.). Sometimes, permanent storage is assigned
(e.g., by BLOCK statements) when no recursion is expected.
More often, ACs are used for a small number of local variables.
In this case, the previous contents must usually be saved, and
a general mnemonic (e.g., T1, A, X) is usually used. In some
cases, data on the stack is referenced, e.g.,
MOVE T1,-2(P)
but this is completely non-mnemonic and likely to fail if
addition storage is added to or removed from the stack.
The facilities described here provide local named variable
storage. Two of these allocate the storage on the stack; the
third allocates it in the ACs.
STKVAR namelist
This statement allocates space on the stack and assigns local
names. The list consists of one or more symbols separated by
commas. Each symbol is assigned to one stack word. If more
than one word is needed for a particular variable, then a size
parameter may be given enclosed with the symbol in
angle-brackets. E.g.,
STKVAR _<AA,BB>
STKVAR _<AA,_<BB,3>>
Variables declared in this way may be referenced as ordinary
memory operands, e.g.,
MOVE T1,AA
DPB T1,[POINT 6,BB,5]
Each variable is assembled as a negative offset from the
current stack location, e.g.,
MACSYM.DOC Page 15
MOVE T1,AA = MOVE T1,-2(P)
Hence, no other index may be given in the address field.
Indirection may be used if desired.
There is no explicit limit to the scope of the variables
defined by STKVAR, but the following logical constraints must
be observed:
1. The stack pointer must not be changed within the
logical scope of the variables, e.g., by PUSH or PUSHJ
instructions. This also implies that the variables may
not be referenced within a local subroutine called from
the declaring routine.
2. The declaring routine must return with a RET or RETSKP.
This will cause the stack storage to be automatically
deallocated.
STKVAR assumes that the stack pointer is in P, and it uses .A16
(AC16) as a temporary.
TRVAR namelist
This statement allocates stack space and assigns local names.
It is equivalent to STKVAR except that it uses one additional
preserved AC and eliminates some of the scope restrictions of
STKVAR. In particular, it uses .FP (AC15) as a frame pointer.
.FP is setup (and the previous contents saved) at the same time
as the stack space is allocated, and references to the
variables use .FP as the index rather than P. This allows
additional storage to be allocated on the stack and allows the
variables to be referenced from local subroutines. Note that
all such subroutines (i.e., all variable references) must
appear after the declaration in the source. STKVAR may be used
within TRVAR, e.g., by a local subroutine.
STKVAR and TRVAR declarations are normally placed at the
beginning of a routine. They need not be the first statement.
If a routine has two or more entry points, a single declaration
may be placed in the common path, or several identical
declarations may be used in each of the separate paths. Care
must be taken that control passes through exactly one
declaration before any variables are referenced. E.g.,
;MAIN ROUTINE
ENT1: TXO F,FLAG ;entry 1, set flag
JRST ENT0 ;join common code
ENT2: TXZ F,FLAG ;entry 2, clear flag
ENT0: TRVAR _<AA,BB> ;common code, declare locals
..
MACSYM.DOC Page 16
CALL LSUBR ;call local subroutine
..
RET
;LOCAL SUBROUTINE
LSUBR: STKVAR _<CC> ;local subroutine, declare
; locals
MOVE T1,AA ;reference outer routine
; variable
MOVEM T1,CC ;reference local variable
..
RETSKP ;skip return
ASUBR namelist
This statement is used to declare formals for a subroutine.
The namelist consists of from one to four variable names. The
arguments are passed to the subroutine in ACs T1 to T4, and
values may be returned in these same ACs. ASUBR causes these
four ACs to be stored on the stack (regardless of how many
formals are declared), and defines the variable names as the
corresponding stack locations. The return does not restore
T1-T4. The same frame pointer AC is used by ASUBR and TRVAR,
hence these declarations may not be used within the same
routine. Scope rules are the same as for TRVAR.
ACVAR namelist
This statement declares local storage which is allocated from
the set of preserved ACs. An optional size parameter may be
given for each variable. The previous contents of the ACs are
saved on the stack and automatically restored on the next
return. Variables declared by ACVAR may be referenced as
ordinary AC operands.
10. MISCELLANEOUS
TMSG string
Type literal string; uses AC1, outputs to primary output.
E.g.,
TMSG _<TYPE THIS TEXT>
JSERR
Handle unexpected JSYS error; type "?JSYS ERROR: message".
This is a single instruction subroutine call which returns +1
always.
JSHLT
Handle unexpected fatal JSYS error; same as JSERR except does
MACSYM.DOC Page 17
HALTF instead of returning.
MOD.(DEND,DSOR)
Modulo - In assembly-time expression, gives remainder of DEND
divided by DSOR; e.g., MOD. 10,3 = 1.
[End of MACSYM.DOC]