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