-@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
-The @code{mmixal} documentation (@pxref{MMIX-Syntax}) specifies that global
-registers allocated with the @samp{GREG} directive (@pxref{MMIX-Pseudos}) and
+@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
described in Sections 1.3 and 1.4 of @samp{The Art of Computer
Programming, Volume 1}. Draft versions of those chapters as well as other
MMIX information is located at
-@emph{mmixsite} @emph{http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html}.
+@anchor{mmixsite}@url{http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html}.
Most code examples from the mmixal package located there should work
unmodified when assembled and linked as single files, with a few
noteworthy exceptions (@pxref{MMIX-mmixal}).
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}
exceptions to it being treated as any other symbol character: if a symbol
begins with @samp{:}, it means that the symbol is in the global namespace
and that the current prefix should not be prepended to that symbol
-(@pxref{MMIX-Pseudos}). The @samp{:} is then not considered part of the
+(@pxref{MMIX-prefix}). The @samp{:} is then not considered part of the
symbol. For a symbol in the label position (first on a line), a @samp{:}
at the end of a symbol is silently stripped off. A label is permitted,
but not required, to be followed by a @samp{:}, as with many other
and @samp{.data} segments of the final program can be defined, though when
linking more than one object file, the code or data in the object file
containing the symbol is not guaranteed to be start at that position; just
-the final executable. @xref{MMIX-Pseudos}.
+the final executable. @xref{MMIX-loc}.
@node MMIX-Regs
@subsection Register names
@cindex MMIX assembler directive LOC
@cindex MMIX pseudo-op LOC
-@emph{MMIX-loc}
+@anchor{MMIX-loc}
The @code{LOC} directive sets the current location to the value of the
operand field, which may include changing sections. If the operand is a
constant, the section is set to either @code{.data} if the value is
@cindex MMIX assembler directive LOCAL
@cindex MMIX pseudo-op LOCAL
-@emph{MMIX-local}
+@anchor{MMIX-local}
Example:
@smallexample
LOCAL external_symbol
@cindex MMIX assembler directive IS
@cindex MMIX pseudo-op IS
-@emph{MMIX-is}
+@anchor{MMIX-is}
The @code{IS} directive:
@smallexample
asymbol IS an_expression
@cindex MMIX assembler directive GREG
@cindex MMIX pseudo-op GREG
-@emph{MMIX-greg}
+@anchor{MMIX-greg}
This directive reserves a global register, gives it an initial value and
optionally gives it a symbolic name. Some examples:
@samp{STUNC},
@samp{SYNCD},
@samp{SYNCID},
-can have a value nearby @emph{GREG-base}an initial value in place of its
+can have a value nearby @anchor{GREG-base}an initial value in place of its
second and third operands. Here, ``nearby'' is defined as within the
range 0@dots{}255 from the initial value of such an allocated register.
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
@cindex MMIX assembler directive BYTE
@cindex MMIX pseudo-op BYTE
-@emph{MMIX-byte}
+@anchor{MMIX-byte}
The @samp{BYTE} directive takes a series of operands separated by a comma.
If an operand is a string (@pxref{Strings}), each character of that string
is emitted as a byte. Other operands must be constant expressions without
@cindex MMIX assembler directive OCTA
@cindex MMIX pseudo-op OCTA
-@emph{MMIX-constants}
+@anchor{MMIX-constants}
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
@cindex MMIX assembler directive PREFIX
@cindex MMIX pseudo-op PREFIX
-@emph{MMIX-prefix}
+@anchor{MMIX-prefix}
The @samp{PREFIX} directive sets a symbol name prefix to be prepended to
all symbols (except local symbols, @pxref{MMIX-Symbols}), that are not
prefixed with @samp{:}, until the next @samp{PREFIX} directive. Such
@cindex MMIX assembler directive ESPEC
@cindex MMIX pseudo-op ESPEC
-@emph{MMIX-spec}
+@anchor{MMIX-spec}
A pair of @samp{BSPEC} and @samp{ESPEC} directives delimit a section of
special contents (without specified semantics). Example:
@smallexample
@cindex differences, mmixal
The binutils @code{@value{AS}} and @code{@value{LD}} combination has a few
-differences in function compared to @code{mmixal} (@pxref{MMIX-Syntax}).
+differences in function compared to @code{mmixal} (@pxref{mmixsite}).
The replacement of a symbol with a GREG-allocated register
-(@xref{MMIX-Pseudos}) is not handled the exactly same way in
+(@pxref{GREG-base}) is not handled the exactly same way in
@code{@value{AS}} as in @code{mmixal}. This is apparent in the
@code{mmixal} example file @code{inout.mms}, where different registers
with different offsets, eventually yielding the same address, are used in
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.
attempted, but that functionality is easily confused and should be avoided
unless compatibility with @code{mmixal} is required. A LOC expression to
@samp{0x2000000000000000} or higher, maps to the @samp{.data} section and
-lower addresses map to the @samp{.text} section (@pxref{MMIX-Pseudos}).
+lower addresses map to the @samp{.text} section (@pxref{MMIX-loc}).
The code and data areas are each contiguous. Sparse programs with
far-away LOC directives will take up the same amount of space as a
There's no unicode support.
-The following is a list of programs in
-@emph{http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html} dated
-2001-08-25 (md5sum c393470cfc86fac040487d22d2bf0172) that assembles with
-@code{mmixal} but don't 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