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