1@c Copyright (C) 2009-2016 Free Software Foundation, Inc.
2@c This is part of the GAS manual.
3@c For copying conditions, see the file as.texinfo.
4@ifset GENERIC
5@page
6@node S/390-Dependent
7@chapter IBM S/390 Dependent Features
8@end ifset
9@ifclear GENERIC
10@node Machine Dependencies
11@chapter IBM S/390 Dependent Features
12@end ifclear
13
14@cindex s390 support
15
16The s390 version of @code{@value{AS}} supports two architectures modes
17and seven chip levels. The architecture modes are the Enterprise System
18Architecture (ESA) and the newer z/Architecture mode. The chip levels
19are g5, g6, z900, z990, z9-109, z9-ec, z10, z196, zEC12, and z13.
20
21@menu
22* s390 Options::                Command-line Options.
23* s390 Characters::		Special Characters.
24* s390 Syntax::                 Assembler Instruction syntax.
25* s390 Directives::             Assembler Directives.
26* s390 Floating Point::         Floating Point.
27@end menu
28
29@node s390 Options
30@section Options
31@cindex options for s390
32@cindex s390 options
33
34The following table lists all available s390 specific options:
35
36@table @code
37@cindex @samp{-m31} option, s390
38@cindex @samp{-m64} option, s390
39@item -m31 | -m64
40Select 31- or 64-bit ABI implying a word size of 32- or 64-bit.
41
42These options are only available with the ELF object file format, and
43require that the necessary BFD support has been included (on a 31-bit
44platform you must add --enable-64-bit-bfd on the call to the configure
45script to enable 64-bit usage and use s390x as target platform).
46
47@cindex @samp{-mesa} option, s390
48@cindex @samp{-mzarch} option, s390
49@item -mesa | -mzarch
50Select the architecture mode, either the Enterprise System Architecture
51(esa) mode or the z/Architecture mode (zarch).
52
53The 64-bit instructions are only available with the z/Architecture mode.
54The combination of @samp{-m64} and @samp{-mesa} results in a warning
55message.
56
57@cindex @samp{-march=} option, s390
58@item -march=@var{CPU}
59This option specifies the target processor. The following processor names
60are recognized:
61@code{g5},
62@code{g6},
63@code{z900},
64@code{z990},
65@code{z9-109},
66@code{z9-ec},
67@code{z10},
68@code{z196},
69@code{zEC12}, and
70@code{z13}.
71Assembling an instruction that is not supported on the target processor
72results in an error message. Do not specify @code{g5} or @code{g6}
73with @samp{-mzarch}.
74
75@cindex @samp{-mregnames} option, s390
76@item -mregnames
77Allow symbolic names for registers.
78
79@cindex @samp{-mno-regnames} option, s390
80@item -mno-regnames
81Do not allow symbolic names for registers.
82
83@cindex @samp{-mwarn-areg-zero} option, s390
84@item -mwarn-areg-zero
85Warn whenever the operand for a base or index register has been specified
86but evaluates to zero. This can indicate the misuse of general purpose
87register 0 as an address register.
88
89@end table
90
91@node s390 Characters
92@section Special Characters
93@cindex line comment character, s390
94@cindex s390 line comment character
95
96@samp{#} is the line comment character.
97
98If a @samp{#} appears as the first character of a line then the whole
99line is treated as a comment, but in this case the line could also be
100a logical line number directive (@pxref{Comments}) or a preprocessor
101control command (@pxref{Preprocessing}).
102
103@cindex line separator, s390
104@cindex statement separator, s390
105@cindex s390 line separator
106The @samp{;} character can be used instead of a newline to separate
107statements.
108
109@node s390 Syntax
110@section Instruction syntax
111@cindex instruction syntax, s390
112@cindex s390 instruction syntax
113
114The assembler syntax closely follows the syntax outlined in
115Enterprise Systems Architecture/390 Principles of Operation (SA22-7201)
116and the z/Architecture Principles of Operation (SA22-7832).
117
118Each instruction has two major parts, the instruction mnemonic
119and the instruction operands. The instruction format varies.
120
121@menu
122* s390 Register::               Register Naming
123* s390 Mnemonics::              Instruction Mnemonics
124* s390 Operands::               Instruction Operands
125* s390 Formats::                Instruction Formats
126* s390 Aliases::		Instruction Aliases
127* s390 Operand Modifier::       Instruction Operand Modifier
128* s390 Instruction Marker::     Instruction Marker
129* s390 Literal Pool Entries::   Literal Pool Entries
130@end menu
131
132@node s390 Register
133@subsection Register naming
134@cindex register naming, s390
135@cindex s390 register naming
136
137The @code{@value{AS}} recognizes a number of predefined symbols for the
138various processor registers. A register specification in one of the
139instruction formats is an unsigned integer between 0 and 15. The specific
140instruction and the position of the register in the instruction format
141denotes the type of the register. The register symbols are prefixed with
142@samp{%}:
143
144@display
145@multitable {%rN} {the 16 general purpose registers, 0 <= N <= 15}
146@item %rN @tab the 16 general purpose registers, 0 <= N <= 15
147@item %fN @tab the 16 floating point registers, 0 <= N <= 15
148@item %aN @tab the 16 access registers, 0 <= N <= 15
149@item %cN @tab the 16 control registers, 0 <= N <= 15
150@item %lit @tab an alias for the general purpose register %r13
151@item %sp @tab an alias for the general purpose register %r15
152@end multitable
153@end display
154
155@node s390 Mnemonics
156@subsection Instruction Mnemonics
157@cindex instruction mnemonics, s390
158@cindex s390 instruction mnemonics
159
160All instructions documented in the Principles of Operation are supported
161with the mnemonic and order of operands as described.
162The instruction mnemonic identifies the instruction format
163(@ref{s390 Formats}) and the specific operation code for the instruction.
164For example, the @samp{lr} mnemonic denotes the instruction format @samp{RR}
165with the operation code @samp{0x18}.
166
167The definition of the various mnemonics follows a scheme, where the first
168character usually hint at the type of the instruction:
169
170@display
171@multitable {sla, sll} {if r is the last character the instruction operates on registers}
172@item a @tab add instruction, for example @samp{al} for add logical 32-bit
173@item b @tab branch instruction, for example @samp{bc} for branch on condition
174@item c @tab compare or convert instruction, for example @samp{cr} for compare
175register 32-bit
176@item d @tab divide instruction, for example @samp{dlr} devide logical register
17764-bit to 32-bit
178@item i @tab insert instruction, for example @samp{ic} insert character
179@item l @tab load instruction, for example @samp{ltr} load and test register
180@item mv @tab move instruction, for example @samp{mvc} move character
181@item m @tab multiply instruction, for example @samp{mh} multiply halfword
182@item n @tab and instruction, for example @samp{ni} and immediate
183@item o @tab or instruction, for example @samp{oc} or character
184@item sla, sll @tab shift left single instruction
185@item sra, srl @tab shift right single instruction
186@item st @tab store instruction, for example @samp{stm} store multiple
187@item s @tab subtract instruction, for example @samp{slr} subtract
188logical 32-bit
189@item t @tab test or translate instruction, of example @samp{tm} test under mask
190@item x @tab exclusive or instruction, for example @samp{xc} exclusive or
191character
192@end multitable
193@end display
194
195Certain characters at the end of the mnemonic may describe a property
196of the instruction:
197
198@display
199@multitable {c} {if r is the last character the instruction operates on registers}
200@item c @tab the instruction uses a 8-bit character operand
201@item f @tab the instruction extends a 32-bit operand to 64 bit
202@item g @tab the operands are treated as 64-bit values
203@item h @tab the operand uses a 16-bit halfword operand
204@item i @tab the instruction uses an immediate operand
205@item l @tab the instruction uses unsigned, logical operands
206@item m @tab the instruction uses a mask or operates on multiple values
207@item r @tab if r is the last character, the instruction operates on registers
208@item y @tab the instruction uses 20-bit displacements
209@end multitable
210@end display
211
212There are many exceptions to the scheme outlined in the above lists, in
213particular for the priviledged instructions. For non-priviledged
214instruction it works quite well, for example the instruction @samp{clgfr}
215c: compare instruction, l: unsigned operands, g: 64-bit operands,
216f: 32- to 64-bit extension, r: register operands. The instruction compares
217an 64-bit value in a register with the zero extended 32-bit value from
218a second register.
219For a complete list of all mnemonics see appendix B in the Principles
220of Operation.
221
222@node s390 Operands
223@subsection Instruction Operands
224@cindex instruction operands, s390
225@cindex s390 instruction operands
226
227Instruction operands can be grouped into three classes, operands located
228in registers, immediate operands, and operands in storage.
229
230A register operand can be located in general, floating-point, access,
231or control register. The register is identified by a four-bit field.
232The field containing the register operand is called the R field.
233
234Immediate operands are contained within the instruction and can have
2358, 16 or 32 bits. The field containing the immediate operand is called
236the I field. Dependent on the instruction the I field is either signed
237or unsigned.
238
239A storage operand consists of an address and a length. The address of a
240storage operands can be specified in any of these ways:
241
242@itemize
243@item The content of a single general R
244@item The sum of the content of a general register called the base
245register B plus the content of a displacement field D
246@item The sum of the contents of two general registers called the
247index register X and the base register B plus the content of a
248displacement field
249@item The sum of the current instruction address and a 32-bit signed
250immediate field multiplied by two.
251@end itemize
252
253The length of a storage operand can be:
254
255@itemize
256@item Implied by the instruction
257@item Specified by a bitmask
258@item Specified by a four-bit or eight-bit length field L
259@item Specified by the content of a general register
260@end itemize
261
262The notation for storage operand addresses formed from multiple fields is
263as follows:
264
265@table @code
266@item Dn(Bn)
267the address for operand number n is formed from the content of general
268register Bn called the base register and the displacement field Dn.
269@item Dn(Xn,Bn)
270the address for operand number n is formed from the content of general
271register Xn called the index register, general register Bn called the
272base register and the displacement field Dn.
273@item Dn(Ln,Bn)
274the address for operand number n is formed from the content of general
275regiser Bn called the base register and the displacement field Dn.
276The length of the operand n is specified by the field Ln.
277@end table
278
279The base registers Bn and the index registers Xn of a storage operand can
280be skipped. If Bn and Xn are skipped, a zero will be stored to the operand
281field. The notation changes as follows:
282
283@display
284@multitable @columnfractions 0.30 0.30
285@headitem full notation @tab short notation
286@item Dn(0,Bn) @tab Dn(Bn)
287@item Dn(0,0) @tab Dn
288@item Dn(0) @tab Dn
289@item Dn(Ln,0) @tab Dn(Ln)
290@end multitable
291@end display
292
293
294@node s390 Formats
295@subsection Instruction Formats
296@cindex instruction formats, s390
297@cindex s390 instruction formats
298
299The Principles of Operation manuals lists 26 instruction formats where
300some of the formats have multiple variants. For the @samp{.insn}
301pseudo directive the assembler recognizes some of the formats.
302Typically, the most general variant of the instruction format is used
303by the @samp{.insn} directive.
304
305The following table lists the abbreviations used in the table of
306instruction formats:
307
308@display
309@multitable {OpCode / OpCd} {Displacement lower 12 bits for operand x.}
310@item OpCode / OpCd @tab Part of the op code.
311@item Bx @tab Base register number for operand x.
312@item Dx @tab Displacement for operand x.
313@item DLx @tab Displacement lower 12 bits for operand x.
314@item DHx @tab Displacement higher 8-bits for operand x.
315@item Rx @tab Register number for operand x.
316@item Xx @tab Index register number for operand x.
317@item Ix @tab Signed immediate for operand x.
318@item Ux @tab Unsigned immediate for operand x.
319@end multitable
320@end display
321
322An instruction is two, four, or six bytes in length and must be aligned
323on a 2 byte boundary. The first two bits of the instruction specify the
324length of the instruction, 00 indicates a two byte instruction, 01 and 10
325indicates a four byte instruction, and 11 indicates a six byte instruction.
326
327The following table lists the s390 instruction formats that are available
328with the @samp{.insn} pseudo directive:
329
330@table @code
331@item E format
332@verbatim
333+-------------+
334|    OpCode   |
335+-------------+
3360            15
337@end verbatim
338
339@item RI format: <insn> R1,I2
340@verbatim
341+--------+----+----+------------------+
342| OpCode | R1 |OpCd|        I2        |
343+--------+----+----+------------------+
3440        8    12   16                31
345@end verbatim
346
347@item RIE format: <insn> R1,R3,I2
348@verbatim
349+--------+----+----+------------------+--------+--------+
350| OpCode | R1 | R3 |        I2        |////////| OpCode |
351+--------+----+----+------------------+--------+--------+
3520        8    12   16                 32       40      47
353@end verbatim
354
355@item RIL format: <insn> R1,I2
356@verbatim
357+--------+----+----+------------------------------------+
358| OpCode | R1 |OpCd|                  I2                |
359+--------+----+----+------------------------------------+
3600        8    12   16                                  47
361@end verbatim
362
363@item RILU format: <insn> R1,U2
364@verbatim
365+--------+----+----+------------------------------------+
366| OpCode | R1 |OpCd|                  U2                |
367+--------+----+----+------------------------------------+
3680        8    12   16                                  47
369@end verbatim
370
371@item RIS format: <insn> R1,I2,M3,D4(B4)
372@verbatim
373+--------+----+----+----+-------------+--------+--------+
374| OpCode | R1 | M3 | B4 |     D4      |   I2   | Opcode |
375+--------+----+----+----+-------------+--------+--------+
3760        8    12   16   20            32       36      47
377@end verbatim
378
379@item RR format: <insn> R1,R2
380@verbatim
381+--------+----+----+
382| OpCode | R1 | R2 |
383+--------+----+----+
3840        8    12  15
385@end verbatim
386
387@item RRE format: <insn> R1,R2
388@verbatim
389+------------------+--------+----+----+
390|      OpCode      |////////| R1 | R2 |
391+------------------+--------+----+----+
3920                  16       24   28  31
393@end verbatim
394
395@item RRF format: <insn> R1,R2,R3,M4
396@verbatim
397+------------------+----+----+----+----+
398|      OpCode      | R3 | M4 | R1 | R2 |
399+------------------+----+----+----+----+
4000                  16   20   24   28  31
401@end verbatim
402
403@item RRS format: <insn> R1,R2,M3,D4(B4)
404@verbatim
405+--------+----+----+----+-------------+----+----+--------+
406| OpCode | R1 | R3 | B4 |     D4      | M3 |////| OpCode |
407+--------+----+----+----+-------------+----+----+--------+
4080        8    12   16   20            32   36   40      47
409@end verbatim
410
411@item RS format: <insn> R1,R3,D2(B2)
412@verbatim
413+--------+----+----+----+-------------+
414| OpCode | R1 | R3 | B2 |     D2      |
415+--------+----+----+----+-------------+
4160        8    12   16   20           31
417@end verbatim
418
419@item RSE format: <insn> R1,R3,D2(B2)
420@verbatim
421+--------+----+----+----+-------------+--------+--------+
422| OpCode | R1 | R3 | B2 |     D2      |////////| OpCode |
423+--------+----+----+----+-------------+--------+--------+
4240        8    12   16   20            32       40      47
425@end verbatim
426
427@item RSI format: <insn> R1,R3,I2
428@verbatim
429+--------+----+----+------------------------------------+
430| OpCode | R1 | R3 |                  I2                |
431+--------+----+----+------------------------------------+
4320        8    12   16                                  47
433@end verbatim
434
435@item RSY format: <insn> R1,R3,D2(B2)
436@verbatim
437+--------+----+----+----+-------------+--------+--------+
438| OpCode | R1 | R3 | B2 |    DL2      |  DH2   | OpCode |
439+--------+----+----+----+-------------+--------+--------+
4400        8    12   16   20            32       40      47
441@end verbatim
442
443@item RX format: <insn> R1,D2(X2,B2)
444@verbatim
445+--------+----+----+----+-------------+
446| OpCode | R1 | X2 | B2 |     D2      |
447+--------+----+----+----+-------------+
4480        8    12   16   20           31
449@end verbatim
450
451@item RXE format: <insn> R1,D2(X2,B2)
452@verbatim
453+--------+----+----+----+-------------+--------+--------+
454| OpCode | R1 | X2 | B2 |     D2      |////////| OpCode |
455+--------+----+----+----+-------------+--------+--------+
4560        8    12   16   20            32       40      47
457@end verbatim
458
459@item RXF format: <insn> R1,R3,D2(X2,B2)
460@verbatim
461+--------+----+----+----+-------------+----+---+--------+
462| OpCode | R3 | X2 | B2 |     D2      | R1 |///| OpCode |
463+--------+----+----+----+-------------+----+---+--------+
4640        8    12   16   20            32   36  40      47
465@end verbatim
466
467@item RXY format: <insn> R1,D2(X2,B2)
468@verbatim
469+--------+----+----+----+-------------+--------+--------+
470| OpCode | R1 | X2 | B2 |     DL2     |   DH2  | OpCode |
471+--------+----+----+----+-------------+--------+--------+
4720        8    12   16   20            32   36   40      47
473@end verbatim
474
475@item S format: <insn> D2(B2)
476@verbatim
477+------------------+----+-------------+
478|      OpCode      | B2 |     D2      |
479+------------------+----+-------------+
4800                  16   20           31
481@end verbatim
482
483@item SI format: <insn> D1(B1),I2
484@verbatim
485+--------+---------+----+-------------+
486| OpCode |   I2    | B1 |     D1      |
487+--------+---------+----+-------------+
4880        8         16   20           31
489@end verbatim
490
491@item SIY format: <insn> D1(B1),U2
492@verbatim
493+--------+---------+----+-------------+--------+--------+
494| OpCode |   I2    | B1 |     DL1     |  DH1   | OpCode |
495+--------+---------+----+-------------+--------+--------+
4960        8         16   20            32   36   40      47
497@end verbatim
498
499@item SIL format: <insn> D1(B1),I2
500@verbatim
501+------------------+----+-------------+-----------------+
502|      OpCode      | B1 |      D1     |       I2        |
503+------------------+----+-------------+-----------------+
5040                  16   20            32               47
505@end verbatim
506
507@item SS format: <insn> D1(R1,B1),D2(B3),R3
508@verbatim
509+--------+----+----+----+-------------+----+------------+
510| OpCode | R1 | R3 | B1 |     D1      | B2 |     D2     |
511+--------+----+----+----+-------------+----+------------+
5120        8    12   16   20            32   36          47
513@end verbatim
514
515@item SSE format: <insn> D1(B1),D2(B2)
516@verbatim
517+------------------+----+-------------+----+------------+
518|      OpCode      | B1 |     D1      | B2 |     D2     |
519+------------------+----+-------------+----+------------+
5200        8    12   16   20            32   36           47
521@end verbatim
522
523@item SSF format: <insn> D1(B1),D2(B2),R3
524@verbatim
525+--------+----+----+----+-------------+----+------------+
526| OpCode | R3 |OpCd| B1 |     D1      | B2 |     D2     |
527+--------+----+----+----+-------------+----+------------+
5280        8    12   16   20            32   36           47
529@end verbatim
530
531@end table
532
533For the complete list of all instruction format variants see the
534Principles of Operation manuals.
535
536@node s390 Aliases
537@subsection Instruction Aliases
538@cindex instruction aliases, s390
539@cindex s390 instruction aliases
540
541A specific bit pattern can have multiple mnemonics, for example
542the bit pattern @samp{0xa7000000} has the mnemonics @samp{tmh} and
543@samp{tmlh}. In addition, there are a number of mnemonics recognized by
544@code{@value{AS}} that are not present in the Principles of Operation.
545These are the short forms of the branch instructions, where the condition
546code mask operand is encoded in the mnemonic. This is relevant for the
547branch instructions, the compare and branch instructions, and the
548compare and trap instructions.
549
550For the branch instructions there are 20 condition code strings that can
551be used as part of the mnemonic in place of a mask operand in the instruction
552format:
553
554@display
555@multitable @columnfractions .30 .30
556@headitem instruction @tab short form
557@item bcr   M1,R2  @tab  b<m>r  R2
558@item bc    M1,D2(X2,B2) @tab  b<m>   D2(X2,B2)
559@item brc   M1,I2 @tab j<m>   I2
560@item brcl  M1,I2 @tab jg<m>  I2
561@end multitable
562@end display
563
564In the mnemonic for a branch instruction the condition code string <m>
565can be any of the following:
566
567@display
568@multitable {nle} {jump on not zero / if not zeros}
569@item o @tab jump on overflow / if ones
570@item h @tab jump on A high
571@item p @tab jump on plus
572@item nle @tab jump on not low or equal
573@item l @tab jump on A low
574@item m @tab jump on minus
575@item nhe @tab jump on not high or equal
576@item lh @tab jump on low or high
577@item ne @tab jump on A not equal B
578@item nz @tab jump on not zero / if not zeros
579@item e @tab jump on A equal B
580@item z @tab jump on zero / if zeroes
581@item nlh @tab jump on not low or high
582@item he @tab jump on high or equal
583@item nl @tab jump on A not low
584@item nm @tab jump on not minus / if not mixed
585@item le @tab jump on low or equal
586@item nh @tab jump on A not high
587@item np @tab jump on not plus
588@item no @tab jump on not overflow / if not ones
589@end multitable
590@end display
591
592For the compare and branch, and compare and trap instructions there
593are 12 condition code strings that can be used as part of the mnemonic in
594place of a mask operand in the instruction format:
595
596@display
597@multitable @columnfractions .40 .40
598@headitem instruction @tab short form
599@item crb    R1,R2,M3,D4(B4)  @tab  crb<m>    R1,R2,D4(B4)
600@item cgrb   R1,R2,M3,D4(B4)  @tab  cgrb<m>   R1,R2,D4(B4)
601@item crj    R1,R2,M3,I4  @tab  crj<m>    R1,R2,I4
602@item cgrj   R1,R2,M3,I4  @tab  cgrj<m>   R1,R2,I4
603@item cib    R1,I2,M3,D4(B4)  @tab  cib<m>    R1,I2,D4(B4)
604@item cgib   R1,I2,M3,D4(B4)  @tab  cgib<m>   R1,I2,D4(B4)
605@item cij    R1,I2,M3,I4  @tab  cij<m>    R1,I2,I4
606@item cgij   R1,I2,M3,I4  @tab  cgij<m>   R1,I2,I4
607@item crt    R1,R2,M3  @tab  crt<m>    R1,R2
608@item cgrt   R1,R2,M3  @tab  cgrt<m>   R1,R2
609@item cit    R1,I2,M3  @tab  cit<m>    R1,I2
610@item cgit   R1,I2,M3  @tab  cgit<m>   R1,I2
611@item clrb   R1,R2,M3,D4(B4)  @tab  clrb<m>   R1,R2,D4(B4)
612@item clgrb  R1,R2,M3,D4(B4)  @tab  clgrb<m>  R1,R2,D4(B4)
613@item clrj   R1,R2,M3,I4  @tab  clrj<m>   R1,R2,I4
614@item clgrj  R1,R2,M3,I4  @tab  clgrj<m>  R1,R2,I4
615@item clib   R1,I2,M3,D4(B4)  @tab  clib<m>   R1,I2,D4(B4)
616@item clgib  R1,I2,M3,D4(B4)  @tab  clgib<m>  R1,I2,D4(B4)
617@item clij   R1,I2,M3,I4  @tab  clij<m>   R1,I2,I4
618@item clgij  R1,I2,M3,I4  @tab  clgij<m>  R1,I2,I4
619@item clrt   R1,R2,M3  @tab  clrt<m>   R1,R2
620@item clgrt  R1,R2,M3  @tab  clgrt<m>  R1,R2
621@item clfit  R1,I2,M3  @tab  clfit<m>  R1,I2
622@item clgit  R1,I2,M3  @tab  clgit<m>  R1,I2
623@end multitable
624@end display
625
626In the mnemonic for a compare and branch and compare and trap instruction
627the condition code string <m> can be any of the following:
628
629@display
630@multitable {nle} {jump on not zero / if not zeros}
631@item h @tab jump on A high
632@item nle @tab jump on not low or equal
633@item l @tab jump on A low
634@item nhe @tab jump on not high or equal
635@item ne @tab jump on A not equal B
636@item lh @tab jump on low or high
637@item e @tab jump on A equal B
638@item nlh @tab jump on not low or high
639@item nl @tab jump on A not low
640@item he @tab jump on high or equal
641@item nh @tab jump on A not high
642@item le @tab jump on low or equal
643@end multitable
644@end display
645
646@node s390 Operand Modifier
647@subsection Instruction Operand Modifier
648@cindex instruction operand modifier, s390
649@cindex s390 instruction operand modifier
650
651If a symbol modifier is attached to a symbol in an expression for an
652instruction operand field, the symbol term is replaced with a reference
653to an object in the global offset table (GOT) or the procedure linkage
654table (PLT). The following expressions are allowed:
655@samp{symbol@@modifier + constant},
656@samp{symbol@@modifier + label + constant}, and
657@samp{symbol@@modifier - label + constant}.
658The term @samp{symbol} is the symbol that will be entered into the GOT or
659PLT, @samp{label} is a local label, and @samp{constant} is an arbitrary
660expression that the assembler can evaluate to a constant value.
661
662The term @samp{(symbol + constant1)@@modifier +/- label + constant2}
663is also accepted but a warning message is printed and the term is
664converted to @samp{symbol@@modifier +/- label + constant1 + constant2}.
665
666@table @code
667@item @@got
668@itemx @@got12
669The @@got modifier can be used for displacement fields, 16-bit immediate
670fields and 32-bit pc-relative immediate fields. The @@got12 modifier is
671synonym to @@got. The symbol is added to the GOT. For displacement
672fields and 16-bit immediate fields the symbol term is replaced with
673the offset from the start of the GOT to the GOT slot for the symbol.
674For a 32-bit pc-relative field the pc-relative offset to the GOT
675slot from the current instruction address is used.
676@item @@gotent
677The @@gotent modifier can be used for 32-bit pc-relative immediate fields.
678The symbol is added to the GOT and the symbol term is replaced with
679the pc-relative offset from the current instruction to the GOT slot for the
680symbol.
681@item @@gotoff
682The @@gotoff modifier can be used for 16-bit immediate fields. The symbol
683term is replaced with the offset from the start of the GOT to the
684address of the symbol.
685@item @@gotplt
686The @@gotplt modifier can be used for displacement fields, 16-bit immediate
687fields, and 32-bit pc-relative immediate fields. A procedure linkage
688table entry is generated for the symbol and a jump slot for the symbol
689is added to the GOT. For displacement fields and 16-bit immediate
690fields the symbol term is replaced with the offset from the start of the
691GOT to the jump slot for the symbol. For a 32-bit pc-relative field
692the pc-relative offset to the jump slot from the current instruction
693address is used.
694@item @@plt
695The @@plt modifier can be used for 16-bit and 32-bit pc-relative immediate
696fields. A procedure linkage table entry is generated for the symbol.
697The symbol term is replaced with the relative offset from the current
698instruction to the PLT entry for the symbol.
699@item @@pltoff
700The @@pltoff modifier can be used for 16-bit immediate fields. The symbol
701term is replaced with the offset from the start of the PLT to the address
702of the symbol.
703@item @@gotntpoff
704The @@gotntpoff modifier can be used for displacement fields. The symbol
705is added to the static TLS block and the negated offset to the symbol
706in the static TLS block is added to the GOT. The symbol term is replaced
707with the offset to the GOT slot from the start of the GOT.
708@item @@indntpoff
709The @@indntpoff modifier can be used for 32-bit pc-relative immediate
710fields. The symbol is added to the static TLS block and the negated offset
711to the symbol in the static TLS block is added to the GOT. The symbol term
712is replaced with the pc-relative offset to the GOT slot from the current
713instruction address.
714@end table
715
716For more information about the thread local storage modifiers
717@samp{gotntpoff} and @samp{indntpoff} see the ELF extension documentation
718@samp{ELF Handling For Thread-Local Storage}.
719
720@node s390 Instruction Marker
721@subsection Instruction Marker
722@cindex instruction marker, s390
723@cindex s390 instruction marker
724
725The thread local storage instruction markers are used by the linker to
726perform code optimization.
727
728@table @code
729@item :tls_load
730The :tls_load marker is used to flag the load instruction in the initial
731exec TLS model that retrieves the offset from the thread pointer to a
732thread local storage variable from the GOT.
733@item :tls_gdcall
734The :tls_gdcall marker is used to flag the branch-and-save instruction to
735the __tls_get_offset function in the global dynamic TLS model.
736@item :tls_ldcall
737The :tls_ldcall marker is used to flag the branch-and-save instruction to
738the __tls_get_offset function in the local dynamic TLS model.
739@end table
740
741For more information about the thread local storage instruction marker
742and the linker optimizations see the ELF extension documentation
743@samp{ELF Handling For Thread-Local Storage}.
744
745@node s390 Literal Pool Entries
746@subsection Literal Pool Entries
747@cindex literal pool entries, s390
748@cindex s390 literal pool entries
749
750A literal pool is a collection of values. To access the values a pointer
751to the literal pool is loaded to a register, the literal pool register.
752Usually, register %r13 is used as the literal pool register
753(@ref{s390 Register}). Literal pool entries are created by adding the
754suffix :lit1, :lit2, :lit4, or :lit8 to the end of an expression for an
755instruction operand. The expression is added to the literal pool and the
756operand is replaced with the offset to the literal in the literal pool.
757
758@table @code
759@item :lit1
760The literal pool entry is created as an 8-bit value. An operand modifier
761must not be used for the original expression.
762@item :lit2
763The literal pool entry is created as a 16 bit value. The operand modifier
764@@got may be used in the original expression. The term @samp{x@@got:lit2}
765will put the got offset for the global symbol x to the literal pool as
76616 bit value.
767@item :lit4
768The literal pool entry is created as a 32-bit value. The operand modifier
769@@got and @@plt may be used in the original expression. The term
770@samp{x@@got:lit4} will put the got offset for the global symbol x to the
771literal pool as a 32-bit value. The term @samp{x@@plt:lit4} will put the
772plt offset for the global symbol x to the literal pool as a 32-bit value.
773@item :lit8
774The literal pool entry is created as a 64-bit value. The operand modifier
775@@got and @@plt may be used in the original expression. The term
776@samp{x@@got:lit8} will put the got offset for the global symbol x to the
777literal pool as a 64-bit value. The term @samp{x@@plt:lit8} will put the
778plt offset for the global symbol x to the literal pool as a 64-bit value.
779@end table
780
781The assembler directive @samp{.ltorg} is used to emit all literal pool
782entries to the current position.
783
784@node s390 Directives
785@section Assembler Directives
786
787@code{@value{AS}} for s390 supports all of the standard ELF
788assembler directives as outlined in the main part of this document.
789Some directives have been extended and there are some additional
790directives, which are only available for the s390 @code{@value{AS}}.
791
792@table @code
793@cindex @code{.insn} directive, s390
794@item .insn
795This directive permits the numeric representation of an instructions
796and makes the assembler insert the operands according to one of the
797instructions formats for @samp{.insn} (@ref{s390 Formats}).
798For example, the instruction @samp{l %r1,24(%r15)} could be written as
799@samp{.insn rx,0x58000000,%r1,24(%r15)}.
800@cindex @code{.short} directive, s390
801@cindex @code{.long} directive, s390
802@cindex @code{.quad} directive, s390
803@item .short
804@itemx .long
805@itemx .quad
806This directive places one or more 16-bit (.short), 32-bit (.long), or
80764-bit (.quad) values into the current section. If an ELF or TLS modifier
808is used only the following expressions are allowed:
809@samp{symbol@@modifier + constant},
810@samp{symbol@@modifier + label + constant}, and
811@samp{symbol@@modifier - label + constant}.
812The following modifiers are available:
813@table @code
814@item @@got
815@itemx @@got12
816The @@got modifier can be used for .short, .long and .quad. The @@got12
817modifier is synonym to @@got. The symbol is added to the GOT. The symbol
818term is replaced with offset from the start of the GOT to the GOT slot for
819the symbol.
820@item @@gotoff
821The @@gotoff modifier can be used for .short, .long and .quad. The symbol
822term is replaced with the offset from the start of the GOT to the address
823of the symbol.
824@item @@gotplt
825The @@gotplt modifier can be used for .long and .quad. A procedure linkage
826table entry is generated for the symbol and a jump slot for the symbol
827is added to the GOT. The symbol term is replaced with the offset from the
828start of the GOT to the jump slot for the symbol.
829@item @@plt
830The @@plt modifier can be used for .long and .quad. A procedure linkage
831table entry us generated for the symbol. The symbol term is replaced with
832the address of the PLT entry for the symbol.
833@item @@pltoff
834The @@pltoff modifier can be used for .short, .long and .quad. The symbol
835term is replaced with the offset from the start of the PLT to the address
836of the symbol.
837@item @@tlsgd
838@itemx @@tlsldm
839The @@tlsgd and @@tlsldm modifier can be used for .long and .quad. A
840tls_index structure for the symbol is added to the GOT. The symbol term is
841replaced with the offset from the start of the GOT to the tls_index structure.
842@item @@gotntpoff
843@itemx @@indntpoff
844The @@gotntpoff and @@indntpoff modifier can be used for .long and .quad.
845The symbol is added to the static TLS block and the negated offset to the
846symbol in the static TLS block is added to the GOT. For @@gotntpoff the
847symbol term is replaced with the offset from the start of the GOT to the
848GOT slot, for @@indntpoff the symbol term is replaced with the address
849of the GOT slot.
850@item @@dtpoff
851The @@dtpoff modifier can be used for .long and .quad. The symbol term
852is replaced with the offset of the symbol relative to the start of the
853TLS block it is contained in.
854@item @@ntpoff
855The @@ntpoff modifier can be used for .long and .quad. The symbol term
856is replaced with the offset of the symbol relative to the TCB pointer.
857@end table
858
859For more information about the thread local storage modifiers see the
860ELF extension documentation @samp{ELF Handling For Thread-Local Storage}.
861
862@cindex @code{.ltorg} directive, s390
863@item .ltorg
864This directive causes the current contents of the literal pool to be
865dumped to the current location (@ref{s390 Literal Pool Entries}).
866
867@cindex @code{.machine} directive, s390
868@item .machine @var{STRING}[+@var{EXTENSION}]@dots{}
869
870This directive allows changing the machine for which code is
871generated.  @code{string} may be any of the @code{-march=}
872selection options, or @code{push}, or @code{pop}.  @code{.machine
873push} saves the currently selected cpu, which may be restored with
874@code{.machine pop}.  Be aware that the cpu string has to be put
875into double quotes in case it contains characters not appropriate
876for identifiers.  So you have to write @code{"z9-109"} instead of
877just @code{z9-109}.  Extensions can be specified after the cpu
878name, separated by plus charaters.  Valid extensions are:
879@code{htm},
880@code{nohtm},
881@code{vx},
882@code{novx}.
883They extend the basic instruction set with features from a higher
884cpu level, or remove support for a feature from the given cpu
885level.
886
887Example: @code{z13+nohtm} allows all instructions of the z13 cpu
888except instructions from the HTM facility.
889
890@cindex @code{.machinemode} directive, s390
891@item .machinemode string
892This directive allows to change the architecture mode for which code
893is being generated.  @code{string} may be @code{esa}, @code{zarch},
894@code{zarch_nohighgprs}, @code{push}, or @code{pop}.
895@code{.machinemode zarch_nohighgprs} can be used to prevent the
896@code{highgprs} flag from being set in the ELF header of the output
897file.  This is useful in situations where the code is gated with a
898runtime check which makes sure that the code is only executed on
899kernels providing the @code{highgprs} feature.
900@code{.machinemode push} saves the currently selected mode, which may
901be restored with @code{.machinemode pop}.
902@end table
903
904@node s390 Floating Point
905@section Floating Point
906@cindex floating point, s390
907@cindex s390 floating point
908
909The assembler recognizes both the @sc{ieee} floating-point instruction and
910the hexadecimal floating-point instructions. The floating-point constructors
911@samp{.float}, @samp{.single}, and @samp{.double} always emit the
912@sc{ieee} format. To assemble hexadecimal floating-point constants the
913@samp{.long} and @samp{.quad} directives must be used.
914