1 03/03/89  alm
  2 
  3 Syntax as a command:  alm path {-control_args}
  4 
  5 
  6 Function: translates program containing text of an assembly language
  7 program into a Multics standard object segment.
  8 
  9 
 10 Arguments:
 11 path
 12    is pathname of ALM source program; alm suffix need not be given.
 13    The archive component pathname convention is allowed.
 14 
 15 
 16 Control arguments:
 17 -list, -ls
 18    produces an assembly listing segment. (Default is no listing)
 19 -no_symbols, -nsb
 20    suppresses listing of cross-reference table produced by default with
 21    -list control argument.
 22 -brief, -bf
 23    does not print errors on terminal.
 24 -arguments, -ag
 25    Arguments following -arguments are accessible to macros as "&An",
 26    and may be tested for with the "ifarg" and "inarg" pseudo-ops.
 27 
 28 
 29 Treatment of errors--
 30 These flags appear in the ALM listing, and on the terminal. Some may be
 31 accompanied by an explanatory message from ALM, describing the problem
 32 in more detail. Fatal and nonfatal errors differ only in their
 33 generation of the "Translation failed" message; an object segment is
 34 always generated, though if fatal errors have occurred, it is probably
 35 useless.
 36 
 37 
 38 List of error flags:
 39 B  mnemonic used belongs to obsolete (Honeywell Model 645) processor
 40    instruction set.
 41 D  error in macro definition or macro expansion- more detailed
 42    diagnostic for specific error given in listing. (Fatal)
 43 E  malformed expression in arithmetic field. (Fatal)
 44 F  error in formation of pseudo-operation operand field. (Nonfatal)
 45 M  reference to a multiply defined symbol. (Fatal)
 46 
 47 
 48 N  unimplemented or obsolete pseudo-operation. (Nonfatal)
 49 O  unrecognized opcode. (Nonfatal)
 50 P  phase error; location counter at this statement has changed
 51    between passes. (Fatal)
 52 R  expression has invalid relocatability. (Nonfatal)
 53 S  error in the definition of a symbol. (Nonfatal)
 54 T  undefined modifier in tag field. (Nonfatal)
 55 U  reference to an undefined symbol. (Fatal)
 56 7  digit 8 or 9 appears in an octal field. (Nonfatal)
 57 
 58 
 59 List of alm pseudo-ops:
 60 acc       /string/,expression -- 9 bit length, 9 bit string
 61 aci       /string/,expression -- 9 bit string
 62 ac4       /string/,expression -- 4 bit string
 63 arg       operand -- operand in upper halfword
 64 bci       /string/,expression -- 6 bit string
 65 bfs       name,expression -- reserve a block of words -- name is the
 66           first word after the reserved block
 67 
 68 
 69 block     {name} -- start of symbol table definitions for runtime
 70           block.
 71 bool      name,expression (octal) -- define a symbol
 72 bss       {name},expression -- reserve a named block of words
 73 call      routine(arglist) -- generate ALM full call, calling routine
 74           with specified arglist.
 75 dec       number1{,number2,...numberN} -- define N decimal numbers
 76 dec_unal  number1{,number2,...numberN} -- define N unaligned decimal
 77           numbers.
 78 desc4a    address{(offset)},length -- EIS alpha descriptor
 79 desc6a    address{(offset)},length -- EIS alpha descriptor
 80 desc9a    address{(offset)},length -- EIS alpha descriptor
 81 
 82 
 83 desc4fl   address{(offset)},length{,scale} -- EIS numeric descriptor
 84 desc4ns   address{(offset)},length{,scale} -- EIS numeric descriptor
 85 desc4ns   address{(offset)},length{,scale} -- EIS numeric descriptor
 86 desc4ts   address{(offset)},length{,scale} -- EIS numeric descriptor
 87 descb     address{(offset)},length -- EIS bit descriptor
 88 dup       expression -- duplicate code until dupend, as many times as
 89           specified by expression.
 90 dupend    -- terminate a "dup" block
 91 
 92 
 93 end_block -- end of symbol table definitions for runtime block.
 94 end_enum  -- end of symbol table definition of enumeration set.
 95 end_source  -- end of symbol table definitions from source program.
 96 end_structure  -- end of symbol table definition of structure.
 97 end_union  -- end of symbol table definition of union.
 98 enum      name -- start of symbol table definition of enumeration set.
 99 
100 
101 eight     -- align on eight word boundary, pad with NOP
102 entry     name1{,name2,...,nameN} -- Make entry sequences for names
103 equ       name,expression -- define a symbol
104 error     -- cause fatal error and print "Translation failed." message.
105 even      -- align on doubleword boundary, pad with NOP
106 ext_entry elabel{,{stacksize}{,{clabel}{,{dlabel}{,function}}}}
107           -- make a probe-able entry sequence for 'elabel' with
108           stackframe size of 'stacksize' and with descriptors at
109           'dlabel'. 'clabel' will be assigned the address of the code
110           sequence associated with the entrypoint. 'function' indicates
111           that the entrypoint is a function.
112 firstref  extexpression1(extexpression2) -- call extexpression1 with
113           arg pointer extexpression2 each time this object segment is
114           made known.
115 
116 
117 getlp     -- set PR4 and PR5 (with segdef, simulates effect of entry).
118           PR6 & PR7 must be set properly. PR2, X0, and X7 are changed.
119 include   segmentname -- include segmentname.incl.alm
120 inhibit   on|off -- start/stop generating instructions with the inhibit
121           bits set.
122 init_link name, extexpression -- associates name as the location of the
123           initialization data for the link mentioned in extexpression.
124 itp       prno,offset{,tag} -- generate an ITP doubleword.
125 its       segno,offset{,tag} -- generate an ITS doubleword. Should
126           already be doubleword aligned, or labels will be incorrect.
127 
128 
129 join      /text/name1{,...}/link/name2{,...}/static/name3{,...}
130           /definition/name1{,...} -- appends location counters (names)
131           to the specified (text/link/static/definition) sections;
132           names must have been defined with a "use" statement.
133 link      name,extexpression -- define a link, ref'd with pr4|name,*
134 maclist   off|on|object|restore{,save} -- set the state of listing in a
135           macro, optionally saving it for restoration via "restore"
136 macro     name -- begin a macro -- terminate with &end
137 mod       expression -- align to <expression> boundary, pad with NOP
138 
139 
140 name      objectname -- define the name of the object segment
141 null      -- ignored.
142 oct       number1{,number2,...numberN} -- define N octal constants
143 oct_unal  number1{,number2,...numberN} -- define N unaligned octal
144           constants.
145 org       expression -- set the location counter to expression
146 perprocess_static  -- set the perprocess_static switch
147 push      {expression} -- generate code to push a stack frame of
148           expression words; if omitted, enough words for all temp
149           pseudo-ops are allocated.
150 rem       -- ignored.
151 
152 
153 return    -- generate full ALM return
154 segdef    name1{,name2,...,nameN} -- define external symbols
155 segref    segname,name1{,...,nameN} -- define external references in
156           segname, with implicit pr4 reference.
157 set       name,expression -- define a redefinable symbol
158 shortcall  routine -- generate ALM short call
159 shortreturn  -- generate ALM short call
160 sixtyfour  -- align on 64 word boundary, pad with NOP
161 
162 
163 source    path -- start of symbol definitions for source program.
164 statement num1,num2,num3{,num4} -- define symbol table entry for source
165           statement that starts at character offset num1, has length num2,
166           is source line number num3 and is statement num4 on the line.
167 structure name -- start of symbol table definitions of structure name.
168 symbol    name,type_desc{,expression} -- define symbol name, of type
169           described by type_desc, at location expression.
170 union     name -- start of symbol table definitions of union name.
171 
172 
173 temp      name1{(n1)}{,name2{(n2)}....} -- define named single word
174           stack temporaries. N1, etc. allocate multiple words per name.
175 tempd     name1{(n1)}{,name2{(n2)}....} -- doubleword stack temporaries
176 temp8     name1{(n1)}{,name2{(n2)}....} -- eight word stack temporaries
177 use       name -- start using name as a location counter (see join)
178 vfd       T1L1/expr1{,T2L2/expr2...} -- generate data. Ln are bit
179           lengths, Tn is "" (decimal), "o" (octal), "a" (ascii).
180 zero      {expr1}{,expr2} -- generate expr1 in DU, expr2 in DL, or zero
181 
182 
183 Expressions--
184 Most pseudo-ops require a decimal dexpression, involving decimal
185 numbers, symbols and the arithmetic operators "+", "-", "*", and "/".
186 Parentheses may also be used. An asterisk in an expression, when not
187 used as an operator, has the value of the current location counter.
188 All symbols in an expression must be absolute, or refer to the same
189 location counter. Relocatable expressions may not be multiplied or
190 divided.
191 
192 
193 Logical expressions are made of octal numbers, symbols, and logical
194 operators: "+" (OR), "-" (XOR), "*" (AND), "^" (NOT). Parentheses may
195 also be used. Logical expressions are used by the bool and vfd
196 pseudo-ops.
197 
198 
199 List of macro constructs:
200 &&        expands to "&"
201 &#        arguments to macro -- # is number
202 &end      terminate a macro
203 &A#       arguments to alm -ag -- # is number
204 &Fn       macro arguments n through last
205 &FQn      macro arguments n through last, quoted in parens, for use as
206           arguments to other macros.
207 
208 
209 &u        generates a label which is unique within this assembly, of
210           the form .._00000.
211 &p        previous &u expansion
212 &n        next &u expression
213 &U        unique within macro expansion
214 &Rm,n     iterate over macro args m through n
215 
216 
217 &(n       begin iteration, for "n" times, repeatedly expanding the
218           construct until the &).
219 &)        end iteration
220 &i        current element of iteration set
221 &x        relative position in iteration set
222 &k        number of elements in iteration set
223 &K        number of arguments to macro
224 &fn       iteration set elements n through last
225 &fqn      iteration set elements n through last, quoted in parens
226 
227 
228 &[        begin a selection group, at most one component of which
229           will be expanded.
230 &]        end a selection group
231 &;        separate elements of a selection group
232 &sn       select element n of following selection group
233 
234 
235 &=c1,c2   if c1 = c2, expand next selection group. The comparison is
236           a standard ASCII string compare.
237 &^=c1,c2  if c1 ^= c2, expand next selection group
238 &>c1,c2   if c1 > c2 (numeric), expand next selection group
239 &<c1,c2   if c1 < c2 (numeric), expand next selection group
240 &>=c1,c2  if c1 >= c2 (numeric), expand next selection group
241 &<=c1,c2  if c1 <= c2 (numeric), expand next selection group
242 
243 
244 List of macro pseudo-ops:
245 warn      (message) -- print message on terminal
246 ife       arg1,arg2 -- assemble until ifend if arg1 = arg2. No if/ifend
247           pseudo-ops may be nested.
248 ine       arg1,arg2 -- assemble until ifend if arg1 ^= arg2
249 ifarg     arg -- assemble until ifend if arg specified after alm -ag
250 inarg     arg -- assemble until ifend if arg specified not after
251             alm -ag
252 
253 
254 ifint     arg -- assemble until ifend if arg is an integer
255 inint     arg -- assemble until ifend if arg is not an integer
256 ifend     -- end a conditional assembly block
257 ifend_exit  -- end conditional assembly, stop macro expansion. May only
258           be used within a macro.
259 
260 
261 Repeat instruction coding format--
262 The RPT, RPL, and RPD instructions are coded as follows:
263    rpt    tally,delta,term1{,term2 ...}
264    rpl    tally,delta,term1{,term2 ...}
265    rpd    tally,delta,term1{,term2 ...}
266 These alternate forms are used to indicate that the termination
267 conditions and tally are in X0:
268    rptx   ,delta
269    rpdx   ,delta
270 
271 
272 The tally and delta must be absolute arithmetic expressions. The rpda,
273 rpdax, rpdb, rpdbx, rpdab, and rpdabx opcodes are used to generate RPD
274 instructions with the A and B bits set. The A bit causes the index
275 register referenced by the even instruction modifier to be incremented
276 in each repeat, and the B bit causes this to be done for the odd
277 instruction. There is no way to set the "ignore overflow" bit.
278 
279 
280 List of repeat termination conditions--
281 trc
282    terminate on carry
283 tnc
284    terminate on no carry
285 tmi
286    terminate on negative
287 tpl
288    terminate on not negative
289 tze
290    terminate on zero
291 tnz
292    terminate on non-zero