-@c Copyright 2009
-@c Free Software Foundation, Inc.
+@c Copyright (C) 2009-2020 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
@ifset GENERIC
@cindex s390 support
The s390 version of @code{@value{AS}} supports two architectures modes
-and seven chip levels. The architecture modes are the Enterprise System
+and eleven chip levels. The architecture modes are the Enterprise System
Architecture (ESA) and the newer z/Architecture mode. The chip levels
-are g5, g6, z900, z990, z9-109, z9-ec and z10.
+are g5 (or arch3), g6, z900 (or arch5), z990 (or arch6), z9-109, z9-ec
+(or arch7), z10 (or arch8), z196 (or arch9), zEC12 (or arch10), z13
+(or arch11), z14 (or arch12), and z15 (or arch13).
@menu
* s390 Options:: Command-line Options.
@cindex s390 options
The following table lists all available s390 specific options:
-
+
@table @code
@cindex @samp{-m31} option, s390
@cindex @samp{-m64} option, s390
@cindex @samp{-march=} option, s390
@item -march=@var{CPU}
This option specifies the target processor. The following processor names
-are recognized:
-@code{g5},
+are recognized:
+@code{g5} (or @code{arch3}),
@code{g6},
-@code{z900},
-@code{z990},
+@code{z900} (or @code{arch5}),
+@code{z990} (or @code{arch6}),
@code{z9-109},
-@code{z9-ec} and
-@code{z10}.
-Assembling an instruction that is not supported on the target processor
-results in an error message. Do not specify @code{g5} or @code{g6}
-with @samp{-mzarch}.
+@code{z9-ec} (or @code{arch7}),
+@code{z10} (or @code{arch8}),
+@code{z196} (or @code{arch9}),
+@code{zEC12} (or @code{arch10}),
+@code{z13} (or @code{arch11}),
+@code{z14} (or @code{arch12}), and
+@code{z15} (or @code{arch13}).
+
+Assembling an instruction that is not supported on the target
+processor results in an error message.
+
+The processor names starting with @code{arch} refer to the edition
+number in the Principle of Operations manual. They can be used as
+alternate processor names and have been added for compatibility with
+the IBM XL compiler.
+
+@code{arch3}, @code{g5} and @code{g6} cannot be used with the
+@samp{-mzarch} option since the z/Architecture mode is not supported
+on these processor levels.
+
+There is no @code{arch4} option supported. @code{arch4} matches
+@code{-march=arch5 -mesa}.
@cindex @samp{-mregnames} option, s390
@item -mregnames
@samp{#} is the line comment character.
+If a @samp{#} appears as the first character of a line then the whole
+line is treated as a comment, but in this case the line could also be
+a logical line number directive (@pxref{Comments}) or a preprocessor
+control command (@pxref{Preprocessing}).
+
+@cindex line separator, s390
+@cindex statement separator, s390
+@cindex s390 line separator
+The @samp{;} character can be used instead of a newline to separate
+statements.
+
@node s390 Syntax
@section Instruction syntax
@cindex instruction syntax, s390
@cindex s390 instruction syntax
-The assembler syntax closely follows the syntax outlined in
-Enterprise Systems Architecture/390 Principles of Operation (SA22-7201)
-and the z/Architecture Principles of Operation (SA22-7832).
+The assembler syntax closely follows the syntax outlined in
+Enterprise Systems Architecture/390 Principles of Operation (SA22-7201)
+and the z/Architecture Principles of Operation (SA22-7832).
Each instruction has two major parts, the instruction mnemonic
and the instruction operands. The instruction format varies.
@end display
There are many exceptions to the scheme outlined in the above lists, in
-particular for the priviledged instructions. For non-priviledged
+particular for the privileged instructions. For non-privileged
instruction it works quite well, for example the instruction @samp{clgfr}
c: compare instruction, l: unsigned operands, g: 64-bit operands,
f: 32- to 64-bit extension, r: register operands. The instruction compares
base register and the displacement field Dn.
@item Dn(Ln,Bn)
the address for operand number n is formed from the content of general
-regiser Bn called the base register and the displacement field Dn.
+register Bn called the base register and the displacement field Dn.
The length of the operand n is specified by the field Ln.
@end table
The Principles of Operation manuals lists 26 instruction formats where
some of the formats have multiple variants. For the @samp{.insn}
-pseudo directive the assembler recognizes some of the formats.
+pseudo directive the assembler recognizes some of the formats.
Typically, the most general variant of the instruction format is used
by the @samp{.insn} directive.
+--------+----+----+
| OpCode | R1 | R2 |
+--------+----+----+
-0 8 12 15
+0 8 12 15
@end verbatim
@item RRE format: <insn> R1,R2
symbol.
@item @@gotoff
The @@gotoff modifier can be used for 16-bit immediate fields. The symbol
-term is replaced with the offset from the start of the GOT to the
+term is replaced with the offset from the start of the GOT to the
address of the symbol.
@item @@gotplt
The @@gotplt modifier can be used for displacement fields, 16-bit immediate
The @@gotntpoff modifier can be used for displacement fields. The symbol
is added to the static TLS block and the negated offset to the symbol
in the static TLS block is added to the GOT. The symbol term is replaced
-with the offset to the GOT slot from the start of the GOT.
+with the offset to the GOT slot from the start of the GOT.
@item @@indntpoff
The @@indntpoff modifier can be used for 32-bit pc-relative immediate
fields. The symbol is added to the static TLS block and the negated offset
@item :tls_load
The :tls_load marker is used to flag the load instruction in the initial
exec TLS model that retrieves the offset from the thread pointer to a
-thread local storage variable from the GOT.
+thread local storage variable from the GOT.
@item :tls_gdcall
The :tls_gdcall marker is used to flag the branch-and-save instruction to
the __tls_get_offset function in the global dynamic TLS model.
@node s390 Directives
@section Assembler Directives
-@code{@value{AS}} for s390 supports all of the standard ELF
+@code{@value{AS}} for s390 supports all of the standard ELF
assembler directives as outlined in the main part of this document.
Some directives have been extended and there are some additional
directives, which are only available for the s390 @code{@value{AS}}.
@itemx .quad
This directive places one or more 16-bit (.short), 32-bit (.long), or
64-bit (.quad) values into the current section. If an ELF or TLS modifier
-is used only the following expressions are allowed:
+is used only the following expressions are allowed:
@samp{symbol@@modifier + constant},
@samp{symbol@@modifier + label + constant}, and
@samp{symbol@@modifier - label + constant}.
@item .ltorg
This directive causes the current contents of the literal pool to be
dumped to the current location (@ref{s390 Literal Pool Entries}).
+
+@cindex @code{.machine} directive, s390
+@item .machine @var{STRING}[+@var{EXTENSION}]@dots{}
+
+This directive allows changing the machine for which code is
+generated. @code{string} may be any of the @code{-march=}
+selection options, or @code{push}, or @code{pop}. @code{.machine
+push} saves the currently selected cpu, which may be restored with
+@code{.machine pop}. Be aware that the cpu string has to be put
+into double quotes in case it contains characters not appropriate
+for identifiers. So you have to write @code{"z9-109"} instead of
+just @code{z9-109}. Extensions can be specified after the cpu
+name, separated by plus characters. Valid extensions are:
+@code{htm},
+@code{nohtm},
+@code{vx},
+@code{novx}.
+They extend the basic instruction set with features from a higher
+cpu level, or remove support for a feature from the given cpu
+level.
+
+Example: @code{z13+nohtm} allows all instructions of the z13 cpu
+except instructions from the HTM facility.
+
+@cindex @code{.machinemode} directive, s390
+@item .machinemode string
+This directive allows to change the architecture mode for which code
+is being generated. @code{string} may be @code{esa}, @code{zarch},
+@code{zarch_nohighgprs}, @code{push}, or @code{pop}.
+@code{.machinemode zarch_nohighgprs} can be used to prevent the
+@code{highgprs} flag from being set in the ELF header of the output
+file. This is useful in situations where the code is gated with a
+runtime check which makes sure that the code is only executed on
+kernels providing the @code{highgprs} feature.
+@code{.machinemode push} saves the currently selected mode, which may
+be restored with @code{.machinemode pop}.
@end table
@node s390 Floating Point