-@c Copyright 2001 Free Software Foundation, Inc.
+@c Copyright (C) 2001-2020 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
@c MMIX description by Hans-Peter Nilsson, hp@bitrange.com
@cindex MMIX options
The MMIX version of @code{@value{AS}} has some machine-dependent options.
-@cindex @samp{--fixed-special-register-names} command line option, MMIX
+@cindex @samp{--fixed-special-register-names} command-line option, MMIX
When @samp{--fixed-special-register-names} is specified, only the register
names specified in @ref{MMIX-Regs} are recognized in the instructions
@code{PUT} and @code{GET}.
-@cindex @samp{--globalize-symbols} command line option, MMIX
+@cindex @samp{--globalize-symbols} command-line option, MMIX
You can use the @samp{--globalize-symbols} to make all symbols global.
This option is useful when splitting up a @code{mmixal} program into
several files.
-@cindex @samp{--gnu-syntax} command line option, MMIX
+@cindex @samp{--gnu-syntax} command-line option, MMIX
The @samp{--gnu-syntax} turns off most syntax compatibility with
@code{mmixal}. Its usability is currently doubtful.
-@cindex @samp{--relax} command line option, MMIX
+@cindex @samp{--relax} command-line option, MMIX
The @samp{--relax} option is not fully supported, but will eventually make
the object file prepared for linker relaxation.
-@cindex @samp{--no-predefined-syms} command line option, MMIX
+@cindex @samp{--no-predefined-syms} command-line option, MMIX
If you want to avoid inadvertently calling a predefined symbol and would
rather get an error, for example when using @code{@value{AS}} with a
compiler or other machine-generated code, specify
``system calls''. It also turns off predefined special-register names,
except when used in @code{PUT} and @code{GET} instructions.
-@cindex @samp{--no-expand} command line option, MMIX
+@cindex @samp{--no-expand} command-line option, MMIX
By default, some instructions are expanded to fit the size of the operand
or an external symbol (@pxref{MMIX-Expand}). By passing
@samp{--no-expand}, no such expansion will be done, instead causing errors
at link time if the operand does not fit.
-@cindex @samp{--no-merge-gregs} command line option, MMIX
+@cindex @samp{--no-merge-gregs} command-line option, MMIX
The @code{mmixal} documentation (@pxref{mmixsite}) specifies that global
registers allocated with the @samp{GREG} directive (@pxref{MMIX-greg}) and
initialized to the same non-zero value, will refer to the same global
-register. This isn't strictly enforcable in @code{@value{AS}} since the
+register. This isn't strictly enforceable in @code{@value{AS}} since the
final addresses aren't known until link-time, but it will do an effort
unless the @samp{--no-merge-gregs} option is specified. (Register merging
isn't yet implemented in @code{@value{LD}}.)
-@cindex @samp{-x} command line option, MMIX
+@cindex @samp{-x} command-line option, MMIX
@code{@value{AS}} will warn every time it expands an instruction to fit an
operand unless the option @samp{-x} is specified. It is believed that
this behaviour is more useful than just mimicking @code{mmixal}'s
be expanded. It needs to be kept in mind that @code{mmixal} is both an
assembler and linker, while @code{@value{AS}} will expand instructions
that at link stage can be contracted. (Though linker relaxation isn't yet
-implemented in @code{@value{LD}}.)
+implemented in @code{@value{LD}}.) The option @samp{-x} also implies
+@samp{--linker-allocated-gregs}.
+
+@cindex @samp{--no-pushj-stubs} command-line option, MMIX
+@cindex @samp{--no-stubs} command-line option, MMIX
+If instruction expansion is enabled, @code{@value{AS}} can expand a
+@samp{PUSHJ} instruction into a series of instructions. The shortest
+expansion is to not expand it, but just mark the call as redirectable to a
+stub, which @code{@value{LD}} creates at link-time, but only if the
+original @samp{PUSHJ} instruction is found not to reach the target. The
+stub consists of the necessary instructions to form a jump to the target.
+This happens if @code{@value{AS}} can assert that the @samp{PUSHJ}
+instruction can reach such a stub. The option @samp{--no-pushj-stubs}
+disables this shorter expansion, and the longer series of instructions is
+then created at assembly-time. The option @samp{--no-stubs} is a synonym,
+intended for compatibility with future releases, where generation of stubs
+for other instructions may be implemented.
+
+@cindex @samp{--linker-allocated-gregs} command-line option, MMIX
+Usually a two-operand-expression (@pxref{GREG-base}) without a matching
+@samp{GREG} directive is treated as an error by @code{@value{AS}}. When
+the option @samp{--linker-allocated-gregs} is in effect, they are instead
+passed through to the linker, which will allocate as many global registers
+as is needed.
@node MMIX-Expand
@section Instruction expansion
The characters @samp{*} and @samp{#} are line comment characters; each
start a comment at the beginning of a line, but only at the beginning of a
line. A @samp{#} prefixes a hexadecimal number if found elsewhere on a
-line.
+line. If a @samp{#} appears at the start of a line the whole line is
+treated as a comment, but the line can also act as a logical line
+number directive (@pxref{Comments}) or a preprocessor control command
+(@pxref{Preprocessing}).
Two other characters, @samp{%} and @samp{!}, each start a comment anywhere
on the line. Thus you can't use the @samp{modulus} and @samp{not}
higher-to-lower within a file. Other than that, the exact order of
register allocation and elimination is undefined. For example, the order
is undefined when more than one file with such directives are linked
-together.
+together. With the options @samp{-x} and @samp{--linker-allocated-gregs},
+@samp{GREG} directives for two-operand cases like the one mentioned above
+can be omitted. Sufficient global registers will then be allocated by the
+linker.
@item BYTE
@cindex assembler directive BYTE, MMIX
The directives @samp{WYDE}, @samp{TETRA} and @samp{OCTA} emit constants of
two, four and eight bytes size respectively. Before anything else happens
for the directive, the current location is aligned to the respective
-constant-size bondary. If a label is defined at the beginning of the
+constant-size boundary. If a label is defined at the beginning of the
line, its value will be that after the alignment. A single operand can be
omitted, defaulting to a zero value emitted for the directive. Operands
can be expressed as strings (@pxref{Strings}), in which case each
must write @code{addu $1,$2,3}.
You can't LOC to a lower address than those already visited
-(i.e. ``backwards'').
+(i.e., ``backwards'').
A LOC directive must come before any emitted code.
There's no unicode support.
-The following is a list of programs in
-@url{http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html} dated
-2001-08-25 (md5sum c393470cfc86fac040487d22d2bf0172) that assemble with
-@code{mmixal} but do not assemble with @code{@value{AS}}:
+The following is a list of programs in @samp{mmix.tar.gz}, available at
+@url{http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html}, last
+checked with the version dated 2001-08-25 (md5sum
+c393470cfc86fac040487d22d2bf0172) that assemble with @code{mmixal} but do
+not assemble with @code{@value{AS}}:
@table @code
@item silly.mms