1 @c Copyright (C) 2009-2014 Free Software Foundation, Inc.
2 @c This is part of the GAS manual.
3 @c For copying conditions, see the file as.texinfo.
7 @chapter IBM S/390 Dependent Features
10 @node Machine Dependencies
11 @chapter IBM S/390 Dependent Features
16 The s390 version of @code{@value{AS}} supports two architectures modes
17 and seven chip levels. The architecture modes are the Enterprise System
18 Architecture (ESA) and the newer z/Architecture mode. The chip levels
19 are g5, g6, z900, z990, z9-109, z9-ec, z10, z196, and zEC12.
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.
31 @cindex options for s390
34 The following table lists all available s390 specific options:
37 @cindex @samp{-m31} option, s390
38 @cindex @samp{-m64} option, s390
40 Select 31- or 64-bit ABI implying a word size of 32- or 64-bit.
42 These options are only available with the ELF object file format, and
43 require that the necessary BFD support has been included (on a 31-bit
44 platform you must add --enable-64-bit-bfd on the call to the configure
45 script to enable 64-bit usage and use s390x as target platform).
47 @cindex @samp{-mesa} option, s390
48 @cindex @samp{-mzarch} option, s390
50 Select the architecture mode, either the Enterprise System Architecture
51 (esa) mode or the z/Architecture mode (zarch).
53 The 64-bit instructions are only available with the z/Architecture mode.
54 The combination of @samp{-m64} and @samp{-mesa} results in a warning
57 @cindex @samp{-march=} option, s390
58 @item -march=@var{CPU}
59 This option specifies the target processor. The following processor names
69 Assembling an instruction that is not supported on the target processor
70 results in an error message. Do not specify @code{g5} or @code{g6}
73 @cindex @samp{-mregnames} option, s390
75 Allow symbolic names for registers.
77 @cindex @samp{-mno-regnames} option, s390
79 Do not allow symbolic names for registers.
81 @cindex @samp{-mwarn-areg-zero} option, s390
82 @item -mwarn-areg-zero
83 Warn whenever the operand for a base or index register has been specified
84 but evaluates to zero. This can indicate the misuse of general purpose
85 register 0 as an address register.
90 @section Special Characters
91 @cindex line comment character, s390
92 @cindex s390 line comment character
94 @samp{#} is the line comment character.
96 If a @samp{#} appears as the first character of a line then the whole
97 line is treated as a comment, but in this case the line could also be
98 a logical line number directive (@pxref{Comments}) or a preprocessor
99 control command (@pxref{Preprocessing}).
101 @cindex line separator, s390
102 @cindex statement separator, s390
103 @cindex s390 line separator
104 The @samp{;} character can be used instead of a newline to separate
108 @section Instruction syntax
109 @cindex instruction syntax, s390
110 @cindex s390 instruction syntax
112 The assembler syntax closely follows the syntax outlined in
113 Enterprise Systems Architecture/390 Principles of Operation (SA22-7201)
114 and the z/Architecture Principles of Operation (SA22-7832).
116 Each instruction has two major parts, the instruction mnemonic
117 and the instruction operands. The instruction format varies.
120 * s390 Register:: Register Naming
121 * s390 Mnemonics:: Instruction Mnemonics
122 * s390 Operands:: Instruction Operands
123 * s390 Formats:: Instruction Formats
124 * s390 Aliases:: Instruction Aliases
125 * s390 Operand Modifier:: Instruction Operand Modifier
126 * s390 Instruction Marker:: Instruction Marker
127 * s390 Literal Pool Entries:: Literal Pool Entries
131 @subsection Register naming
132 @cindex register naming, s390
133 @cindex s390 register naming
135 The @code{@value{AS}} recognizes a number of predefined symbols for the
136 various processor registers. A register specification in one of the
137 instruction formats is an unsigned integer between 0 and 15. The specific
138 instruction and the position of the register in the instruction format
139 denotes the type of the register. The register symbols are prefixed with
143 @multitable {%rN} {the 16 general purpose registers, 0 <= N <= 15}
144 @item %rN @tab the 16 general purpose registers, 0 <= N <= 15
145 @item %fN @tab the 16 floating point registers, 0 <= N <= 15
146 @item %aN @tab the 16 access registers, 0 <= N <= 15
147 @item %cN @tab the 16 control registers, 0 <= N <= 15
148 @item %lit @tab an alias for the general purpose register %r13
149 @item %sp @tab an alias for the general purpose register %r15
154 @subsection Instruction Mnemonics
155 @cindex instruction mnemonics, s390
156 @cindex s390 instruction mnemonics
158 All instructions documented in the Principles of Operation are supported
159 with the mnemonic and order of operands as described.
160 The instruction mnemonic identifies the instruction format
161 (@ref{s390 Formats}) and the specific operation code for the instruction.
162 For example, the @samp{lr} mnemonic denotes the instruction format @samp{RR}
163 with the operation code @samp{0x18}.
165 The definition of the various mnemonics follows a scheme, where the first
166 character usually hint at the type of the instruction:
169 @multitable {sla, sll} {if r is the last character the instruction operates on registers}
170 @item a @tab add instruction, for example @samp{al} for add logical 32-bit
171 @item b @tab branch instruction, for example @samp{bc} for branch on condition
172 @item c @tab compare or convert instruction, for example @samp{cr} for compare
174 @item d @tab divide instruction, for example @samp{dlr} devide logical register
176 @item i @tab insert instruction, for example @samp{ic} insert character
177 @item l @tab load instruction, for example @samp{ltr} load and test register
178 @item mv @tab move instruction, for example @samp{mvc} move character
179 @item m @tab multiply instruction, for example @samp{mh} multiply halfword
180 @item n @tab and instruction, for example @samp{ni} and immediate
181 @item o @tab or instruction, for example @samp{oc} or character
182 @item sla, sll @tab shift left single instruction
183 @item sra, srl @tab shift right single instruction
184 @item st @tab store instruction, for example @samp{stm} store multiple
185 @item s @tab subtract instruction, for example @samp{slr} subtract
187 @item t @tab test or translate instruction, of example @samp{tm} test under mask
188 @item x @tab exclusive or instruction, for example @samp{xc} exclusive or
193 Certain characters at the end of the mnemonic may describe a property
197 @multitable {c} {if r is the last character the instruction operates on registers}
198 @item c @tab the instruction uses a 8-bit character operand
199 @item f @tab the instruction extends a 32-bit operand to 64 bit
200 @item g @tab the operands are treated as 64-bit values
201 @item h @tab the operand uses a 16-bit halfword operand
202 @item i @tab the instruction uses an immediate operand
203 @item l @tab the instruction uses unsigned, logical operands
204 @item m @tab the instruction uses a mask or operates on multiple values
205 @item r @tab if r is the last character, the instruction operates on registers
206 @item y @tab the instruction uses 20-bit displacements
210 There are many exceptions to the scheme outlined in the above lists, in
211 particular for the priviledged instructions. For non-priviledged
212 instruction it works quite well, for example the instruction @samp{clgfr}
213 c: compare instruction, l: unsigned operands, g: 64-bit operands,
214 f: 32- to 64-bit extension, r: register operands. The instruction compares
215 an 64-bit value in a register with the zero extended 32-bit value from
217 For a complete list of all mnemonics see appendix B in the Principles
221 @subsection Instruction Operands
222 @cindex instruction operands, s390
223 @cindex s390 instruction operands
225 Instruction operands can be grouped into three classes, operands located
226 in registers, immediate operands, and operands in storage.
228 A register operand can be located in general, floating-point, access,
229 or control register. The register is identified by a four-bit field.
230 The field containing the register operand is called the R field.
232 Immediate operands are contained within the instruction and can have
233 8, 16 or 32 bits. The field containing the immediate operand is called
234 the I field. Dependent on the instruction the I field is either signed
237 A storage operand consists of an address and a length. The address of a
238 storage operands can be specified in any of these ways:
241 @item The content of a single general R
242 @item The sum of the content of a general register called the base
243 register B plus the content of a displacement field D
244 @item The sum of the contents of two general registers called the
245 index register X and the base register B plus the content of a
247 @item The sum of the current instruction address and a 32-bit signed
248 immediate field multiplied by two.
251 The length of a storage operand can be:
254 @item Implied by the instruction
255 @item Specified by a bitmask
256 @item Specified by a four-bit or eight-bit length field L
257 @item Specified by the content of a general register
260 The notation for storage operand addresses formed from multiple fields is
265 the address for operand number n is formed from the content of general
266 register Bn called the base register and the displacement field Dn.
268 the address for operand number n is formed from the content of general
269 register Xn called the index register, general register Bn called the
270 base register and the displacement field Dn.
272 the address for operand number n is formed from the content of general
273 regiser Bn called the base register and the displacement field Dn.
274 The length of the operand n is specified by the field Ln.
277 The base registers Bn and the index registers Xn of a storage operand can
278 be skipped. If Bn and Xn are skipped, a zero will be stored to the operand
279 field. The notation changes as follows:
282 @multitable @columnfractions 0.30 0.30
283 @headitem full notation @tab short notation
284 @item Dn(0,Bn) @tab Dn(Bn)
285 @item Dn(0,0) @tab Dn
287 @item Dn(Ln,0) @tab Dn(Ln)
293 @subsection Instruction Formats
294 @cindex instruction formats, s390
295 @cindex s390 instruction formats
297 The Principles of Operation manuals lists 26 instruction formats where
298 some of the formats have multiple variants. For the @samp{.insn}
299 pseudo directive the assembler recognizes some of the formats.
300 Typically, the most general variant of the instruction format is used
301 by the @samp{.insn} directive.
303 The following table lists the abbreviations used in the table of
307 @multitable {OpCode / OpCd} {Displacement lower 12 bits for operand x.}
308 @item OpCode / OpCd @tab Part of the op code.
309 @item Bx @tab Base register number for operand x.
310 @item Dx @tab Displacement for operand x.
311 @item DLx @tab Displacement lower 12 bits for operand x.
312 @item DHx @tab Displacement higher 8-bits for operand x.
313 @item Rx @tab Register number for operand x.
314 @item Xx @tab Index register number for operand x.
315 @item Ix @tab Signed immediate for operand x.
316 @item Ux @tab Unsigned immediate for operand x.
320 An instruction is two, four, or six bytes in length and must be aligned
321 on a 2 byte boundary. The first two bits of the instruction specify the
322 length of the instruction, 00 indicates a two byte instruction, 01 and 10
323 indicates a four byte instruction, and 11 indicates a six byte instruction.
325 The following table lists the s390 instruction formats that are available
326 with the @samp{.insn} pseudo directive:
337 @item RI format: <insn> R1,I2
339 +--------+----+----+------------------+
340 | OpCode | R1 |OpCd| I2 |
341 +--------+----+----+------------------+
345 @item RIE format: <insn> R1,R3,I2
347 +--------+----+----+------------------+--------+--------+
348 | OpCode | R1 | R3 | I2 |////////| OpCode |
349 +--------+----+----+------------------+--------+--------+
353 @item RIL format: <insn> R1,I2
355 +--------+----+----+------------------------------------+
356 | OpCode | R1 |OpCd| I2 |
357 +--------+----+----+------------------------------------+
361 @item RILU format: <insn> R1,U2
363 +--------+----+----+------------------------------------+
364 | OpCode | R1 |OpCd| U2 |
365 +--------+----+----+------------------------------------+
369 @item RIS format: <insn> R1,I2,M3,D4(B4)
371 +--------+----+----+----+-------------+--------+--------+
372 | OpCode | R1 | M3 | B4 | D4 | I2 | Opcode |
373 +--------+----+----+----+-------------+--------+--------+
374 0 8 12 16 20 32 36 47
377 @item RR format: <insn> R1,R2
385 @item RRE format: <insn> R1,R2
387 +------------------+--------+----+----+
388 | OpCode |////////| R1 | R2 |
389 +------------------+--------+----+----+
393 @item RRF format: <insn> R1,R2,R3,M4
395 +------------------+----+----+----+----+
396 | OpCode | R3 | M4 | R1 | R2 |
397 +------------------+----+----+----+----+
401 @item RRS format: <insn> R1,R2,M3,D4(B4)
403 +--------+----+----+----+-------------+----+----+--------+
404 | OpCode | R1 | R3 | B4 | D4 | M3 |////| OpCode |
405 +--------+----+----+----+-------------+----+----+--------+
406 0 8 12 16 20 32 36 40 47
409 @item RS format: <insn> R1,R3,D2(B2)
411 +--------+----+----+----+-------------+
412 | OpCode | R1 | R3 | B2 | D2 |
413 +--------+----+----+----+-------------+
417 @item RSE format: <insn> R1,R3,D2(B2)
419 +--------+----+----+----+-------------+--------+--------+
420 | OpCode | R1 | R3 | B2 | D2 |////////| OpCode |
421 +--------+----+----+----+-------------+--------+--------+
422 0 8 12 16 20 32 40 47
425 @item RSI format: <insn> R1,R3,I2
427 +--------+----+----+------------------------------------+
428 | OpCode | R1 | R3 | I2 |
429 +--------+----+----+------------------------------------+
433 @item RSY format: <insn> R1,R3,D2(B2)
435 +--------+----+----+----+-------------+--------+--------+
436 | OpCode | R1 | R3 | B2 | DL2 | DH2 | OpCode |
437 +--------+----+----+----+-------------+--------+--------+
438 0 8 12 16 20 32 40 47
441 @item RX format: <insn> R1,D2(X2,B2)
443 +--------+----+----+----+-------------+
444 | OpCode | R1 | X2 | B2 | D2 |
445 +--------+----+----+----+-------------+
449 @item RXE format: <insn> R1,D2(X2,B2)
451 +--------+----+----+----+-------------+--------+--------+
452 | OpCode | R1 | X2 | B2 | D2 |////////| OpCode |
453 +--------+----+----+----+-------------+--------+--------+
454 0 8 12 16 20 32 40 47
457 @item RXF format: <insn> R1,R3,D2(X2,B2)
459 +--------+----+----+----+-------------+----+---+--------+
460 | OpCode | R3 | X2 | B2 | D2 | R1 |///| OpCode |
461 +--------+----+----+----+-------------+----+---+--------+
462 0 8 12 16 20 32 36 40 47
465 @item RXY format: <insn> R1,D2(X2,B2)
467 +--------+----+----+----+-------------+--------+--------+
468 | OpCode | R1 | X2 | B2 | DL2 | DH2 | OpCode |
469 +--------+----+----+----+-------------+--------+--------+
470 0 8 12 16 20 32 36 40 47
473 @item S format: <insn> D2(B2)
475 +------------------+----+-------------+
477 +------------------+----+-------------+
481 @item SI format: <insn> D1(B1),I2
483 +--------+---------+----+-------------+
484 | OpCode | I2 | B1 | D1 |
485 +--------+---------+----+-------------+
489 @item SIY format: <insn> D1(B1),U2
491 +--------+---------+----+-------------+--------+--------+
492 | OpCode | I2 | B1 | DL1 | DH1 | OpCode |
493 +--------+---------+----+-------------+--------+--------+
494 0 8 16 20 32 36 40 47
497 @item SIL format: <insn> D1(B1),I2
499 +------------------+----+-------------+-----------------+
500 | OpCode | B1 | D1 | I2 |
501 +------------------+----+-------------+-----------------+
505 @item SS format: <insn> D1(R1,B1),D2(B3),R3
507 +--------+----+----+----+-------------+----+------------+
508 | OpCode | R1 | R3 | B1 | D1 | B2 | D2 |
509 +--------+----+----+----+-------------+----+------------+
510 0 8 12 16 20 32 36 47
513 @item SSE format: <insn> D1(B1),D2(B2)
515 +------------------+----+-------------+----+------------+
516 | OpCode | B1 | D1 | B2 | D2 |
517 +------------------+----+-------------+----+------------+
518 0 8 12 16 20 32 36 47
521 @item SSF format: <insn> D1(B1),D2(B2),R3
523 +--------+----+----+----+-------------+----+------------+
524 | OpCode | R3 |OpCd| B1 | D1 | B2 | D2 |
525 +--------+----+----+----+-------------+----+------------+
526 0 8 12 16 20 32 36 47
531 For the complete list of all instruction format variants see the
532 Principles of Operation manuals.
535 @subsection Instruction Aliases
536 @cindex instruction aliases, s390
537 @cindex s390 instruction aliases
539 A specific bit pattern can have multiple mnemonics, for example
540 the bit pattern @samp{0xa7000000} has the mnemonics @samp{tmh} and
541 @samp{tmlh}. In addition, there are a number of mnemonics recognized by
542 @code{@value{AS}} that are not present in the Principles of Operation.
543 These are the short forms of the branch instructions, where the condition
544 code mask operand is encoded in the mnemonic. This is relevant for the
545 branch instructions, the compare and branch instructions, and the
546 compare and trap instructions.
548 For the branch instructions there are 20 condition code strings that can
549 be used as part of the mnemonic in place of a mask operand in the instruction
553 @multitable @columnfractions .30 .30
554 @headitem instruction @tab short form
555 @item bcr M1,R2 @tab b<m>r R2
556 @item bc M1,D2(X2,B2) @tab b<m> D2(X2,B2)
557 @item brc M1,I2 @tab j<m> I2
558 @item brcl M1,I2 @tab jg<m> I2
562 In the mnemonic for a branch instruction the condition code string <m>
563 can be any of the following:
566 @multitable {nle} {jump on not zero / if not zeros}
567 @item o @tab jump on overflow / if ones
568 @item h @tab jump on A high
569 @item p @tab jump on plus
570 @item nle @tab jump on not low or equal
571 @item l @tab jump on A low
572 @item m @tab jump on minus
573 @item nhe @tab jump on not high or equal
574 @item lh @tab jump on low or high
575 @item ne @tab jump on A not equal B
576 @item nz @tab jump on not zero / if not zeros
577 @item e @tab jump on A equal B
578 @item z @tab jump on zero / if zeroes
579 @item nlh @tab jump on not low or high
580 @item he @tab jump on high or equal
581 @item nl @tab jump on A not low
582 @item nm @tab jump on not minus / if not mixed
583 @item le @tab jump on low or equal
584 @item nh @tab jump on A not high
585 @item np @tab jump on not plus
586 @item no @tab jump on not overflow / if not ones
590 For the compare and branch, and compare and trap instructions there
591 are 12 condition code strings that can be used as part of the mnemonic in
592 place of a mask operand in the instruction format:
595 @multitable @columnfractions .40 .40
596 @headitem instruction @tab short form
597 @item crb R1,R2,M3,D4(B4) @tab crb<m> R1,R2,D4(B4)
598 @item cgrb R1,R2,M3,D4(B4) @tab cgrb<m> R1,R2,D4(B4)
599 @item crj R1,R2,M3,I4 @tab crj<m> R1,R2,I4
600 @item cgrj R1,R2,M3,I4 @tab cgrj<m> R1,R2,I4
601 @item cib R1,I2,M3,D4(B4) @tab cib<m> R1,I2,D4(B4)
602 @item cgib R1,I2,M3,D4(B4) @tab cgib<m> R1,I2,D4(B4)
603 @item cij R1,I2,M3,I4 @tab cij<m> R1,I2,I4
604 @item cgij R1,I2,M3,I4 @tab cgij<m> R1,I2,I4
605 @item crt R1,R2,M3 @tab crt<m> R1,R2
606 @item cgrt R1,R2,M3 @tab cgrt<m> R1,R2
607 @item cit R1,I2,M3 @tab cit<m> R1,I2
608 @item cgit R1,I2,M3 @tab cgit<m> R1,I2
609 @item clrb R1,R2,M3,D4(B4) @tab clrb<m> R1,R2,D4(B4)
610 @item clgrb R1,R2,M3,D4(B4) @tab clgrb<m> R1,R2,D4(B4)
611 @item clrj R1,R2,M3,I4 @tab clrj<m> R1,R2,I4
612 @item clgrj R1,R2,M3,I4 @tab clgrj<m> R1,R2,I4
613 @item clib R1,I2,M3,D4(B4) @tab clib<m> R1,I2,D4(B4)
614 @item clgib R1,I2,M3,D4(B4) @tab clgib<m> R1,I2,D4(B4)
615 @item clij R1,I2,M3,I4 @tab clij<m> R1,I2,I4
616 @item clgij R1,I2,M3,I4 @tab clgij<m> R1,I2,I4
617 @item clrt R1,R2,M3 @tab clrt<m> R1,R2
618 @item clgrt R1,R2,M3 @tab clgrt<m> R1,R2
619 @item clfit R1,I2,M3 @tab clfit<m> R1,I2
620 @item clgit R1,I2,M3 @tab clgit<m> R1,I2
624 In the mnemonic for a compare and branch and compare and trap instruction
625 the condition code string <m> can be any of the following:
628 @multitable {nle} {jump on not zero / if not zeros}
629 @item h @tab jump on A high
630 @item nle @tab jump on not low or equal
631 @item l @tab jump on A low
632 @item nhe @tab jump on not high or equal
633 @item ne @tab jump on A not equal B
634 @item lh @tab jump on low or high
635 @item e @tab jump on A equal B
636 @item nlh @tab jump on not low or high
637 @item nl @tab jump on A not low
638 @item he @tab jump on high or equal
639 @item nh @tab jump on A not high
640 @item le @tab jump on low or equal
644 @node s390 Operand Modifier
645 @subsection Instruction Operand Modifier
646 @cindex instruction operand modifier, s390
647 @cindex s390 instruction operand modifier
649 If a symbol modifier is attached to a symbol in an expression for an
650 instruction operand field, the symbol term is replaced with a reference
651 to an object in the global offset table (GOT) or the procedure linkage
652 table (PLT). The following expressions are allowed:
653 @samp{symbol@@modifier + constant},
654 @samp{symbol@@modifier + label + constant}, and
655 @samp{symbol@@modifier - label + constant}.
656 The term @samp{symbol} is the symbol that will be entered into the GOT or
657 PLT, @samp{label} is a local label, and @samp{constant} is an arbitrary
658 expression that the assembler can evaluate to a constant value.
660 The term @samp{(symbol + constant1)@@modifier +/- label + constant2}
661 is also accepted but a warning message is printed and the term is
662 converted to @samp{symbol@@modifier +/- label + constant1 + constant2}.
667 The @@got modifier can be used for displacement fields, 16-bit immediate
668 fields and 32-bit pc-relative immediate fields. The @@got12 modifier is
669 synonym to @@got. The symbol is added to the GOT. For displacement
670 fields and 16-bit immediate fields the symbol term is replaced with
671 the offset from the start of the GOT to the GOT slot for the symbol.
672 For a 32-bit pc-relative field the pc-relative offset to the GOT
673 slot from the current instruction address is used.
675 The @@gotent modifier can be used for 32-bit pc-relative immediate fields.
676 The symbol is added to the GOT and the symbol term is replaced with
677 the pc-relative offset from the current instruction to the GOT slot for the
680 The @@gotoff modifier can be used for 16-bit immediate fields. The symbol
681 term is replaced with the offset from the start of the GOT to the
682 address of the symbol.
684 The @@gotplt modifier can be used for displacement fields, 16-bit immediate
685 fields, and 32-bit pc-relative immediate fields. A procedure linkage
686 table entry is generated for the symbol and a jump slot for the symbol
687 is added to the GOT. For displacement fields and 16-bit immediate
688 fields the symbol term is replaced with the offset from the start of the
689 GOT to the jump slot for the symbol. For a 32-bit pc-relative field
690 the pc-relative offset to the jump slot from the current instruction
693 The @@plt modifier can be used for 16-bit and 32-bit pc-relative immediate
694 fields. A procedure linkage table entry is generated for the symbol.
695 The symbol term is replaced with the relative offset from the current
696 instruction to the PLT entry for the symbol.
698 The @@pltoff modifier can be used for 16-bit immediate fields. The symbol
699 term is replaced with the offset from the start of the PLT to the address
702 The @@gotntpoff modifier can be used for displacement fields. The symbol
703 is added to the static TLS block and the negated offset to the symbol
704 in the static TLS block is added to the GOT. The symbol term is replaced
705 with the offset to the GOT slot from the start of the GOT.
707 The @@indntpoff modifier can be used for 32-bit pc-relative immediate
708 fields. The symbol is added to the static TLS block and the negated offset
709 to the symbol in the static TLS block is added to the GOT. The symbol term
710 is replaced with the pc-relative offset to the GOT slot from the current
714 For more information about the thread local storage modifiers
715 @samp{gotntpoff} and @samp{indntpoff} see the ELF extension documentation
716 @samp{ELF Handling For Thread-Local Storage}.
718 @node s390 Instruction Marker
719 @subsection Instruction Marker
720 @cindex instruction marker, s390
721 @cindex s390 instruction marker
723 The thread local storage instruction markers are used by the linker to
724 perform code optimization.
728 The :tls_load marker is used to flag the load instruction in the initial
729 exec TLS model that retrieves the offset from the thread pointer to a
730 thread local storage variable from the GOT.
732 The :tls_gdcall marker is used to flag the branch-and-save instruction to
733 the __tls_get_offset function in the global dynamic TLS model.
735 The :tls_ldcall marker is used to flag the branch-and-save instruction to
736 the __tls_get_offset function in the local dynamic TLS model.
739 For more information about the thread local storage instruction marker
740 and the linker optimizations see the ELF extension documentation
741 @samp{ELF Handling For Thread-Local Storage}.
743 @node s390 Literal Pool Entries
744 @subsection Literal Pool Entries
745 @cindex literal pool entries, s390
746 @cindex s390 literal pool entries
748 A literal pool is a collection of values. To access the values a pointer
749 to the literal pool is loaded to a register, the literal pool register.
750 Usually, register %r13 is used as the literal pool register
751 (@ref{s390 Register}). Literal pool entries are created by adding the
752 suffix :lit1, :lit2, :lit4, or :lit8 to the end of an expression for an
753 instruction operand. The expression is added to the literal pool and the
754 operand is replaced with the offset to the literal in the literal pool.
758 The literal pool entry is created as an 8-bit value. An operand modifier
759 must not be used for the original expression.
761 The literal pool entry is created as a 16 bit value. The operand modifier
762 @@got may be used in the original expression. The term @samp{x@@got:lit2}
763 will put the got offset for the global symbol x to the literal pool as
766 The literal pool entry is created as a 32-bit value. The operand modifier
767 @@got and @@plt may be used in the original expression. The term
768 @samp{x@@got:lit4} will put the got offset for the global symbol x to the
769 literal pool as a 32-bit value. The term @samp{x@@plt:lit4} will put the
770 plt offset for the global symbol x to the literal pool as a 32-bit value.
772 The literal pool entry is created as a 64-bit value. The operand modifier
773 @@got and @@plt may be used in the original expression. The term
774 @samp{x@@got:lit8} will put the got offset for the global symbol x to the
775 literal pool as a 64-bit value. The term @samp{x@@plt:lit8} will put the
776 plt offset for the global symbol x to the literal pool as a 64-bit value.
779 The assembler directive @samp{.ltorg} is used to emit all literal pool
780 entries to the current position.
782 @node s390 Directives
783 @section Assembler Directives
785 @code{@value{AS}} for s390 supports all of the standard ELF
786 assembler directives as outlined in the main part of this document.
787 Some directives have been extended and there are some additional
788 directives, which are only available for the s390 @code{@value{AS}}.
791 @cindex @code{.insn} directive, s390
793 This directive permits the numeric representation of an instructions
794 and makes the assembler insert the operands according to one of the
795 instructions formats for @samp{.insn} (@ref{s390 Formats}).
796 For example, the instruction @samp{l %r1,24(%r15)} could be written as
797 @samp{.insn rx,0x58000000,%r1,24(%r15)}.
798 @cindex @code{.short} directive, s390
799 @cindex @code{.long} directive, s390
800 @cindex @code{.quad} directive, s390
804 This directive places one or more 16-bit (.short), 32-bit (.long), or
805 64-bit (.quad) values into the current section. If an ELF or TLS modifier
806 is used only the following expressions are allowed:
807 @samp{symbol@@modifier + constant},
808 @samp{symbol@@modifier + label + constant}, and
809 @samp{symbol@@modifier - label + constant}.
810 The following modifiers are available:
814 The @@got modifier can be used for .short, .long and .quad. The @@got12
815 modifier is synonym to @@got. The symbol is added to the GOT. The symbol
816 term is replaced with offset from the start of the GOT to the GOT slot for
819 The @@gotoff modifier can be used for .short, .long and .quad. The symbol
820 term is replaced with the offset from the start of the GOT to the address
823 The @@gotplt modifier can be used for .long and .quad. A procedure linkage
824 table entry is generated for the symbol and a jump slot for the symbol
825 is added to the GOT. The symbol term is replaced with the offset from the
826 start of the GOT to the jump slot for the symbol.
828 The @@plt modifier can be used for .long and .quad. A procedure linkage
829 table entry us generated for the symbol. The symbol term is replaced with
830 the address of the PLT entry for the symbol.
832 The @@pltoff modifier can be used for .short, .long and .quad. The symbol
833 term is replaced with the offset from the start of the PLT to the address
837 The @@tlsgd and @@tlsldm modifier can be used for .long and .quad. A
838 tls_index structure for the symbol is added to the GOT. The symbol term is
839 replaced with the offset from the start of the GOT to the tls_index structure.
842 The @@gotntpoff and @@indntpoff modifier can be used for .long and .quad.
843 The symbol is added to the static TLS block and the negated offset to the
844 symbol in the static TLS block is added to the GOT. For @@gotntpoff the
845 symbol term is replaced with the offset from the start of the GOT to the
846 GOT slot, for @@indntpoff the symbol term is replaced with the address
849 The @@dtpoff modifier can be used for .long and .quad. The symbol term
850 is replaced with the offset of the symbol relative to the start of the
851 TLS block it is contained in.
853 The @@ntpoff modifier can be used for .long and .quad. The symbol term
854 is replaced with the offset of the symbol relative to the TCB pointer.
857 For more information about the thread local storage modifiers see the
858 ELF extension documentation @samp{ELF Handling For Thread-Local Storage}.
860 @cindex @code{.ltorg} directive, s390
862 This directive causes the current contents of the literal pool to be
863 dumped to the current location (@ref{s390 Literal Pool Entries}).
865 @cindex @code{.machine} directive, s390
866 @item .machine string
867 This directive allows you to change the machine for which code is
868 generated. @code{string} may be any of the @code{-march=} selection
869 options (without the -march=), @code{push}, or @code{pop}.
870 @code{.machine push} saves the currently selected cpu, which may be
871 restored with @code{.machine pop}. Be aware that the cpu string has
872 to be put into double quotes in case it contains characters not
873 appropriate for identifiers. So you have to write @code{"z9-109"}
874 instead of just @code{z9-109}.
876 @cindex @code{.machinemode} directive, s390
877 @item .machinemode string
878 This directive allows to change the architecture mode for which code
879 is being generated. @code{string} may be @code{esa}, @code{zarch},
880 @code{zarch_nohighgprs}, @code{push}, or @code{pop}.
881 @code{.machinemode zarch_nohighgprs} can be used to prevent the
882 @code{highgprs} flag from being set in the ELF header of the output
883 file. This is useful in situations where the code is gated with a
884 runtime check which makes sure that the code is only executed on
885 kernels providing the @code{highgprs} feature.
886 @code{.machinemode push} saves the currently selected mode, which may
887 be restored with @code{.machinemode pop}.
890 @node s390 Floating Point
891 @section Floating Point
892 @cindex floating point, s390
893 @cindex s390 floating point
895 The assembler recognizes both the @sc{ieee} floating-point instruction and
896 the hexadecimal floating-point instructions. The floating-point constructors
897 @samp{.float}, @samp{.single}, and @samp{.double} always emit the
898 @sc{ieee} format. To assemble hexadecimal floating-point constants the
899 @samp{.long} and @samp{.quad} directives must be used.