* doc/c-mmix.texi: Use texinfo 4 features.
[platform/upstream/binutils.git] / gas / doc / c-mmix.texi
1 @c Copyright 2001 Free Software Foundation, Inc.
2 @c This is part of the GAS manual.
3 @c For copying conditions, see the file as.texinfo.
4 @c MMIX description by Hans-Peter Nilsson, hp@bitrange.com
5 @ifset GENERIC
6 @page
7 @node MMIX-Dependent
8 @chapter MMIX Dependent Features
9 @end ifset
10 @ifclear GENERIC
11 @node Machine Dependencies
12 @chapter MMIX Dependent Features
13 @end ifclear
14
15 @cindex MMIX support
16 @menu
17 * MMIX-Opts::              Command-line Options
18 * MMIX-Expand::            Instruction expansion
19 * MMIX-Syntax::            Syntax
20 * MMIX-mmixal::            Differences to @code{mmixal} syntax and semantics
21 @end menu
22
23 @node MMIX-Opts
24 @section Command-line Options
25
26 @cindex options, MMIX
27 @cindex MMIX options
28 The MMIX version of @code{@value{AS}} has some machine-dependent options.
29
30 @cindex @samp{--fixed-special-register-names} command line option, MMIX
31 When @samp{--fixed-special-register-names} is specified, only the register
32 names specified in @ref{MMIX-Regs} are recognized in the instructions
33 @code{PUT} and @code{GET}.
34
35 @cindex @samp{--globalize-symbols} command line option, MMIX
36 You can use the @samp{--globalize-symbols} to make all symbols global.
37 This option is useful when splitting up a @code{mmixal} program into
38 several files.
39
40 @cindex @samp{--gnu-syntax} command line option, MMIX
41 The @samp{--gnu-syntax} turns off most syntax compatibility with
42 @code{mmixal}.  Its usability is currently doubtful.
43
44 @cindex @samp{--relax} command line option, MMIX
45 The @samp{--relax} option is not fully supported, but will eventually make
46 the object file prepared for linker relaxation.
47
48 @cindex @samp{--no-predefined-syms} command line option, MMIX
49 If you want to avoid inadvertently calling a predefined symbol and would
50 rather get an error, for example when using @code{@value{AS}} with a
51 compiler or other machine-generated code, specify
52 @samp{--no-predefined-syms}.  This turns off built-in predefined
53 definitions of all such symbols, including rounding-mode symbols, segment
54 symbols, @samp{BIT} symbols, and @code{TRAP} symbols used in @code{mmix}
55 ``system calls''.  It also turns off predefined special-register names,
56 except when used in @code{PUT} and @code{GET} instructions.
57
58 @cindex @samp{--no-expand} command line option, MMIX
59 By default, some instructions are expanded to fit the size of the operand
60 or an external symbol (@pxref{MMIX-Expand}).  By passing
61 @samp{--no-expand}, no such expansion will be done, instead causing errors
62 at link time if the operand does not fit.
63
64 @cindex @samp{--no-merge-gregs} command line option, MMIX
65 The @code{mmixal} documentation (@pxref{mmixsite}) specifies that global
66 registers allocated with the @samp{GREG} directive (@pxref{MMIX-greg}) and
67 initialized to the same non-zero value, will refer to the same global
68 register.  This isn't strictly enforcable in @code{@value{AS}} since the
69 final addresses aren't known until link-time, but it will do an effort
70 unless the @samp{--no-merge-gregs} option is specified.  (Register merging
71 isn't yet implemented in @code{@value{LD}}.)
72
73 @cindex @samp{-x} command line option, MMIX
74 @code{@value{AS}} will warn every time it expands an instruction to fit an
75 operand unless the option @samp{-x} is specified.  It is believed that
76 this behaviour is more useful than just mimicking @code{mmixal}'s
77 behaviour, in which instructions are only expanded if the @samp{-x} option
78 is specified, and assembly fails otherwise, when an instruction needs to
79 be expanded.  It needs to be kept in mind that @code{mmixal} is both an
80 assembler and linker, while @code{@value{AS}} will expand instructions
81 that at link stage can be contracted.  (Though linker relaxation isn't yet
82 implemented in @code{@value{LD}}.)
83
84 @node MMIX-Expand
85 @section Instruction expansion
86
87 @cindex instruction expansion, MMIX
88 When @code{@value{AS}} encounters an instruction with an operand that is
89 either not known or does not fit the operand size of the instruction,
90 @code{@value{AS}} (and @code{@value{LD}}) will expand the instruction into
91 a sequence of instructions semantically equivalent to the operand fitting
92 the instruction.  Expansion will take place for the following
93 instructions:
94
95 @table @asis
96 @item @samp{GETA}
97 Expands to a sequence of four instructions: @code{SETL}, @code{INCML},
98 @code{INCMH} and @code{INCH}.  The operand must be a multiple of four.
99 @item Conditional branches
100 A branch instruction is turned into a branch with the complemented
101 condition and prediction bit over five instructions; four instructions
102 setting @code{$255} to the operand value, which like with @code{GETA} must
103 be a multiple of four, and a final @code{GO $255,$255,0}.
104 @item @samp{PUSHJ}
105 Similar to expansion for conditional branches; four instructions set
106 @code{$255} to the operand value, followed by a @code{PUSHGO $255,$255,0}.
107 @item @samp{JMP}
108 Similar to conditional branches and @code{PUSHJ}.  The final instruction
109 is @code{GO $255,$255,0}.
110 @end table
111
112 The linker @code{@value{LD}} is expected to shrink these expansions for
113 code assembled with @samp{--relax} (though not currently implemented).
114
115 @node MMIX-Syntax
116 @section Syntax
117
118 The assembly syntax is supposed to be upward compatible with that
119 described in Sections 1.3 and 1.4 of @samp{The Art of Computer
120 Programming, Volume 1}.  Draft versions of those chapters as well as other
121 MMIX information is located at
122 @anchor{mmixsite}@url{http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html}.
123 Most code examples from the mmixal package located there should work
124 unmodified when assembled and linked as single files, with a few
125 noteworthy exceptions (@pxref{MMIX-mmixal}).
126
127 Before an instruction is emitted, the current location is aligned to the
128 next four-byte boundary.  If a label is defined at the beginning of the
129 line, its value will be the aligned value.
130
131 In addition to the traditional hex-prefix @samp{0x}, a hexadecimal number
132 can also be specified by the prefix character @samp{#}.
133
134 After all operands to an MMIX instruction or directive have been
135 specified, the rest of the line is ignored, treated as a comment.
136
137 @menu
138 * MMIX-Chars::                  Special Characters
139 * MMIX-Symbols::                Symbols
140 * MMIX-Regs::                   Register Names
141 * MMIX-Pseudos::                Assembler Directives
142 @end menu
143
144 @node MMIX-Chars
145 @subsection Special Characters
146 @cindex line comment characters, MMIX
147 @cindex MMIX line comment characters
148
149 The characters @samp{*} and @samp{#} are line comment characters; each
150 start a comment at the beginning of a line, but only at the beginning of a
151 line.  A @samp{#} prefixes a hexadecimal number if found elsewhere on a
152 line.
153
154 Two other characters, @samp{%} and @samp{!}, each start a comment anywhere
155 on the line.  Thus you can't use the @samp{modulus} and @samp{not}
156 operators in expressions normally associated with these two characters.
157
158 A @samp{;} is a line separator, treated as a new-line, so separate
159 instructions can be specified on a single line.
160
161 @node MMIX-Symbols
162 @subsection Symbols
163 The character @samp{:} is permitted in identifiers.  There are two
164 exceptions to it being treated as any other symbol character: if a symbol
165 begins with @samp{:}, it means that the symbol is in the global namespace
166 and that the current prefix should not be prepended to that symbol
167 (@pxref{MMIX-prefix}).  The @samp{:} is then not considered part of the
168 symbol.  For a symbol in the label position (first on a line), a @samp{:}
169 at the end of a symbol is silently stripped off.  A label is permitted,
170 but not required, to be followed by a @samp{:}, as with many other
171 assembly formats.
172
173 The character @samp{@@} in an expression, is a synonym for @samp{.}, the
174 current location.
175
176 In addition to the common forward and backward local symbol formats
177 (@pxref{Symbol Names}), they can be specified with upper-case @samp{B} and
178 @samp{F}, as in @samp{8B} and @samp{9F}.  A local label defined for the
179 current position is written with a @samp{H} appended to the number:
180 @smallexample
181 3H LDB $0,$1,2
182 @end smallexample
183 This and traditional local-label formats cannot be mixed: a label must be
184 defined and referred to using the same format.
185
186 There's a minor caveat: just as for the ordinary local symbols, the local
187 symbols are translated into ordinary symbols using control characters are
188 to hide the ordinal number of the symbol.  Unfortunately, these symbols
189 are not translated back in error messages.  Thus you may see confusing
190 error messages when local symbols are used.  Control characters
191 @samp{\003} (control-C) and @samp{\004} (control-D) are used for the
192 MMIX-specific local-symbol syntax.
193
194 The symbol @samp{Main} is handled specially; it is always global.
195
196 By defining the symbols @samp{__.MMIX.start..text} and
197 @samp{__.MMIX.start..data}, the address of respectively the @samp{.text}
198 and @samp{.data} segments of the final program can be defined, though when
199 linking more than one object file, the code or data in the object file
200 containing the symbol is not guaranteed to be start at that position; just
201 the final executable.  @xref{MMIX-loc}.
202
203 @node MMIX-Regs
204 @subsection Register names
205 @cindex register names, MMIX
206 @cindex MMIX register names
207
208 Local and global registers are specified as @samp{$0} to @samp{$255}.
209 The recognized special register names are @samp{rJ}, @samp{rA}, @samp{rB},
210 @samp{rC}, @samp{rD}, @samp{rE}, @samp{rF}, @samp{rG}, @samp{rH},
211 @samp{rI}, @samp{rK}, @samp{rL}, @samp{rM}, @samp{rN}, @samp{rO},
212 @samp{rP}, @samp{rQ}, @samp{rR}, @samp{rS}, @samp{rT}, @samp{rU},
213 @samp{rV}, @samp{rW}, @samp{rX}, @samp{rY}, @samp{rZ}, @samp{rBB},
214 @samp{rTT}, @samp{rWW}, @samp{rXX}, @samp{rYY} and @samp{rZZ}.  A leading
215 @samp{:} is optional for special register names.
216
217 Local and global symbols can be equated to register names and used in
218 place of ordinary registers.
219
220 Similarly for special registers, local and global symbols can be used.
221 Also, symbols equated from numbers and constant expressions are allowed in
222 place of a special register, except when either of the options
223 @code{--no-predefined-syms} and @code{--fixed-special-register-names} are
224 specified.  Then only the special register names above are allowed for the
225 instructions having a special register operand; @code{GET} and @code{PUT}.
226
227 @node MMIX-Pseudos
228 @subsection Assembler Directives
229 @cindex assembler directives, MMIX
230 @cindex pseudo-ops, MMIX
231 @cindex MMIX assembler directives
232 @cindex MMIX pseudo-ops
233
234 @table @code
235 @item LOC
236 @cindex assembler directive LOC, MMIX
237 @cindex pseudo-op LOC, MMIX
238 @cindex MMIX assembler directive LOC
239 @cindex MMIX pseudo-op LOC
240
241 @anchor{MMIX-loc}
242 The @code{LOC} directive sets the current location to the value of the
243 operand field, which may include changing sections.  If the operand is a
244 constant, the section is set to either @code{.data} if the value is
245 @code{0x2000000000000000} or larger, else it is set to @code{.text}.
246 Within a section, the current location may only be changed to
247 monotonically higher addresses.  A LOC expression must be a previously
248 defined symbol or a ``pure'' constant.
249
250 An example, which sets the label @var{prev} to the current location, and
251 updates the current location to eight bytes forward:
252 @smallexample
253 prev LOC @@+8
254 @end smallexample
255
256 When a LOC has a constant as its operand, a symbol
257 @code{__.MMIX.start..text} or @code{__.MMIX.start..data} is defined
258 depending on the address as mentioned above.  Each such symbol is
259 interpreted as special by the linker, locating the section at that
260 address.  Note that if multiple files are linked, the first object file
261 with that section will be mapped to that address (not necessarily the file
262 with the LOC definition).
263
264 @item LOCAL
265 @cindex assembler directive LOCAL, MMIX
266 @cindex pseudo-op LOCAL, MMIX
267 @cindex MMIX assembler directive LOCAL
268 @cindex MMIX pseudo-op LOCAL
269
270 @anchor{MMIX-local}
271 Example:
272 @smallexample
273  LOCAL external_symbol
274  LOCAL 42
275  .local asymbol
276 @end smallexample
277
278 This directive-operation generates a link-time assertion that the operand
279 does not correspond to a global register.  The operand is an expression
280 that at link-time resolves to a register symbol or a number.  A number is
281 treated as the register having that number.  There is one restriction on
282 the use of this directive: the pseudo-directive must be placed in a
283 section with contents, code or data.
284
285 @item IS
286 @cindex assembler directive IS, MMIX
287 @cindex pseudo-op IS, MMIX
288 @cindex MMIX assembler directive IS
289 @cindex MMIX pseudo-op IS
290
291 @anchor{MMIX-is}
292 The @code{IS} directive:
293 @smallexample
294 asymbol IS an_expression
295 @end smallexample
296 sets the symbol @samp{asymbol} to @samp{an_expression}.  A symbol may not
297 be set more than once using this directive.  Local labels may be set using
298 this directive, for example:
299 @smallexample
300 5H IS @@+4
301 @end smallexample
302
303 @item GREG
304 @cindex assembler directive GREG, MMIX
305 @cindex pseudo-op GREG, MMIX
306 @cindex MMIX assembler directive GREG
307 @cindex MMIX pseudo-op GREG
308
309 @anchor{MMIX-greg}
310 This directive reserves a global register, gives it an initial value and
311 optionally gives it a symbolic name.  Some examples:
312
313 @smallexample
314 areg GREG
315 breg GREG data_value
316      GREG data_buffer
317      .greg creg, another_data_value
318 @end smallexample
319
320 The symbolic register name can be used in place of a (non-special)
321 register.  If a value isn't provided, it defaults to zero.  Unless the
322 option @samp{--no-merge-gregs} is specified, non-zero registers allocated
323 with this directive may be eliminated by @code{@value{AS}}; another
324 register with the same value used in its place.
325 Any of the instructions
326 @samp{CSWAP},
327 @samp{GO},
328 @samp{LDA},
329 @samp{LDBU},
330 @samp{LDB},
331 @samp{LDHT},
332 @samp{LDOU},
333 @samp{LDO},
334 @samp{LDSF},
335 @samp{LDTU},
336 @samp{LDT},
337 @samp{LDUNC},
338 @samp{LDVTS},
339 @samp{LDWU},
340 @samp{LDW},
341 @samp{PREGO},
342 @samp{PRELD},
343 @samp{PREST},
344 @samp{PUSHGO},
345 @samp{STBU},
346 @samp{STB},
347 @samp{STCO},
348 @samp{STHT},
349 @samp{STOU},
350 @samp{STSF},
351 @samp{STTU},
352 @samp{STT},
353 @samp{STUNC},
354 @samp{SYNCD},
355 @samp{SYNCID},
356 can have a value nearby @anchor{GREG-base}an initial value in place of its
357 second and third operands.  Here, ``nearby'' is defined as within the
358 range 0@dots{}255 from the initial value of such an allocated register.
359
360 @smallexample
361 buffer1 BYTE 0,0,0,0,0
362 buffer2 BYTE 0,0,0,0,0
363  @dots{}
364  GREG buffer1
365  LDOU $42,buffer2
366 @end smallexample
367 In the example above, the @samp{Y} field of the @code{LDOUI} instruction
368 (LDOU with a constant Z) will be replaced with the global register
369 allocated for @samp{buffer1}, and the @samp{Z} field will have the value
370 5, the offset from @samp{buffer1} to @samp{buffer2}.  The result is
371 equivalent to this code:
372 @smallexample
373 buffer1 BYTE 0,0,0,0,0
374 buffer2 BYTE 0,0,0,0,0
375  @dots{}
376 tmpreg GREG buffer1
377  LDOU $42,tmpreg,(buffer2-buffer1)
378 @end smallexample
379
380 Global registers allocated with this directive are allocated in order
381 higher-to-lower within a file.  Other than that, the exact order of
382 register allocation and elimination is undefined.  For example, the order
383 is undefined when more than one file with such directives are linked
384 together.
385
386 @item BYTE
387 @cindex assembler directive BYTE, MMIX
388 @cindex pseudo-op BYTE, MMIX
389 @cindex MMIX assembler directive BYTE
390 @cindex MMIX pseudo-op BYTE
391
392 @anchor{MMIX-byte}
393 The @samp{BYTE} directive takes a series of operands separated by a comma.
394 If an operand is a string (@pxref{Strings}), each character of that string
395 is emitted as a byte.  Other operands must be constant expressions without
396 forward references, in the range 0@dots{}255.  If you need operands having
397 expressions with forward references, use @samp{.byte} (@pxref{Byte}).  An
398 operand can be omitted, defaulting to a zero value.
399
400 @item WYDE
401 @itemx TETRA
402 @itemx OCTA
403 @cindex assembler directive WYDE, MMIX
404 @cindex pseudo-op WYDE, MMIX
405 @cindex MMIX assembler directive WYDE
406 @cindex MMIX pseudo-op WYDE
407 @cindex assembler directive TETRA, MMIX
408 @cindex pseudo-op TETRA, MMIX
409 @cindex MMIX assembler directive TETRA
410 @cindex MMIX pseudo-op TETRA
411 @cindex assembler directive OCTA, MMIX
412 @cindex pseudo-op OCTA, MMIX
413 @cindex MMIX assembler directive OCTA
414 @cindex MMIX pseudo-op OCTA
415
416 @anchor{MMIX-constants}
417 The directives @samp{WYDE}, @samp{TETRA} and @samp{OCTA} emit constants of
418 two, four and eight bytes size respectively.  Before anything else happens
419 for the directive, the current location is aligned to the respective
420 constant-size bondary.  If a label is defined at the beginning of the
421 line, its value will be that after the alignment.  A single operand can be
422 omitted, defaulting to a zero value emitted for the directive.  Operands
423 can be expressed as strings (@pxref{Strings}), in which case each
424 character in the string is emitted as a separate constant of the size
425 indicated by the directive.
426
427 @item PREFIX
428 @cindex assembler directive PREFIX, MMIX
429 @cindex pseudo-op PREFIX, MMIX
430 @cindex MMIX assembler directive PREFIX
431 @cindex MMIX pseudo-op PREFIX
432
433 @anchor{MMIX-prefix}
434 The @samp{PREFIX} directive sets a symbol name prefix to be prepended to
435 all symbols (except local symbols, @pxref{MMIX-Symbols}), that are not
436 prefixed with @samp{:}, until the next @samp{PREFIX} directive.  Such
437 prefixes accumulate.  For example,
438 @smallexample
439  PREFIX a
440  PREFIX b
441 c IS 0
442 @end smallexample
443 defines a symbol @samp{abc} with the value 0.
444
445 @item BSPEC
446 @itemx ESPEC
447 @cindex assembler directive BSPEC, MMIX
448 @cindex pseudo-op BSPEC, MMIX
449 @cindex MMIX assembler directive BSPEC
450 @cindex MMIX pseudo-op BSPEC
451 @cindex assembler directive ESPEC, MMIX
452 @cindex pseudo-op ESPEC, MMIX
453 @cindex MMIX assembler directive ESPEC
454 @cindex MMIX pseudo-op ESPEC
455
456 @anchor{MMIX-spec}
457 A pair of @samp{BSPEC} and @samp{ESPEC} directives delimit a section of
458 special contents (without specified semantics).  Example:
459 @smallexample
460  BSPEC 42
461  TETRA 1,2,3
462  ESPEC
463 @end smallexample
464 The single operand to @samp{BSPEC} must be number in the range
465 0@dots{}255.  The @samp{BSPEC} number 80 is used by the GNU binutils
466 implementation.
467 @end table
468
469 @node MMIX-mmixal
470 @section Differences to @code{mmixal}
471 @cindex mmixal differences
472 @cindex differences, mmixal
473
474 The binutils @code{@value{AS}} and @code{@value{LD}} combination has a few
475 differences in function compared to @code{mmixal} (@pxref{mmixsite}).
476
477 The replacement of a symbol with a GREG-allocated register
478 (@pxref{GREG-base}) is not handled the exactly same way in
479 @code{@value{AS}} as in @code{mmixal}.  This is apparent in the
480 @code{mmixal} example file @code{inout.mms}, where different registers
481 with different offsets, eventually yielding the same address, are used in
482 the first instruction.  This type of difference should however not affect
483 the function of any program unless it has specific assumptions about the
484 allocated register number.
485
486 Line numbers (in the @samp{mmo} object format) are currently not
487 supported.
488
489 Expression operator precedence is not that of mmixal: operator precedence
490 is that of the C programming language.  It's recommended to use
491 parentheses to explicitly specify wanted operator precedence whenever more
492 than one type of operators are used.
493
494 The serialize unary operator @code{&}, the fractional division operator
495 @samp{//}, the logical not operator @code{!} and the modulus operator
496 @samp{%} are not available.
497
498 Symbols are not global by default, unless the option
499 @samp{--globalize-symbols} is passed.  Use the @samp{.global} directive to
500 globalize symbols (@pxref{Global}).
501
502 Operand syntax is a bit stricter with @code{@value{AS}} than
503 @code{mmixal}.  For example, you can't say @code{addu 1,2,3}, instead you
504 must write @code{addu $1,$2,3}.
505
506 You can't LOC to a lower address than those already visited
507 (i.e. ``backwards'').
508
509 A LOC directive must come before any emitted code.
510
511 Predefined symbols are visible as file-local symbols after use.  (In the
512 ELF file, that is---the linked mmo file has no notion of a file-local
513 symbol.)
514
515 Some mapping of constant expressions to sections in LOC expressions is
516 attempted, but that functionality is easily confused and should be avoided
517 unless compatibility with @code{mmixal} is required.  A LOC expression to
518 @samp{0x2000000000000000} or higher, maps to the @samp{.data} section and
519 lower addresses map to the @samp{.text} section (@pxref{MMIX-loc}).
520
521 The code and data areas are each contiguous.  Sparse programs with
522 far-away LOC directives will take up the same amount of space as a
523 contiguous program with zeros filled in the gaps between the LOC
524 directives.  If you need sparse programs, you might try and get the wanted
525 effect with a linker script and splitting up the code parts into sections
526 (@pxref{Section}).  Assembly code for this, to be compatible with
527 @code{mmixal}, would look something like:
528 @smallexample
529  .if 0
530  LOC away_expression
531  .else
532  .section away,"ax"
533  .fi
534 @end smallexample
535 @code{@value{AS}} will not execute the LOC directive and @code{mmixal}
536 ignores the lines with @code{.}.  This construct can be used generally to
537 help compatibility.
538
539 Symbols can't be defined twice--not even to the same value.
540
541 Instruction mnemonics are recognized case-insensitive, though the
542 @samp{IS} and @samp{GREG} pseudo-operations must be specified in
543 upper-case characters.
544
545 There's no unicode support.
546
547 The following is a list of programs in
548 @url{http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html} dated
549 2001-08-25 (md5sum c393470cfc86fac040487d22d2bf0172) that assemble with
550 @code{mmixal} but do not assemble with @code{@value{AS}}:
551
552 @table @code
553 @item silly.mms
554 LOC to a previous address.
555 @item sim.mms
556 Redefines symbol @samp{Done}.
557 @item test.mms
558 Uses the serial operator @samp{&}.
559 @end table