gas/doc/c-s390.texi

   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
  17 The s390 version of @code{@value{AS}} supports two architectures modes
  18 and seven chip levels. The architecture modes are the Enterprise System
  19 Architecture (ESA) and the newer z/Architecture mode. The chip levels
  20 are 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
  35 The 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
  41 Select 31- or 64-bit ABI implying a word size of 32- or 64-bit.
  42
  43 These options are only available with the ELF object file format, and
  44 require that the necessary BFD support has been included (on a 31-bit
  45 platform you must add --enable-64-bit-bfd on the call to the configure
  46 script 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
  51 Select the architecture mode, either the Enterprise System Architecture
  52 (esa) mode or the z/Architecture mode (zarch).
  53
  54 The 64-bit instructions are only available with the z/Architecture mode.
  55 The combination of @samp{-m64} and @samp{-mesa} results in a warning
  56 message.
  57
  58 @cindex @samp{-march=} option, s390
  59 @item -march=@var{CPU}
  60 This option specifies the target processor. The following processor names
  61 are 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}.
  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}
  71 with @samp{-mzarch}.
  72
  73 @cindex @samp{-mregnames} option, s390
  74 @item -mregnames
  75 Allow symbolic names for registers.
  76
  77 @cindex @samp{-mno-regnames} option, s390
  78 @item -mno-regnames
  79 Do not allow symbolic names for registers.
  80
  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.
  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
 101 The assembler syntax closely follows the syntax outlined in
 102 Enterprise Systems Architecture/390 Principles of Operation (SA22-7201)
 103 and the z/Architecture Principles of Operation (SA22-7832).
 104
 105 Each instruction has two major parts, the instruction mnemonic
 106 and 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
 124 The @code{@value{AS}} recognizes a number of predefined symbols for the
 125 various processor registers. A register specification in one of the
 126 instruction formats is an unsigned integer between 0 and 15. The specific
 127 instruction and the position of the register in the instruction format
 128 denotes 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
 147 All instructions documented in the Principles of Operation are supported
 148 with the mnemonic and order of operands as described.
 149 The instruction mnemonic identifies the instruction format
 150 (@ref{s390 Formats}) and the specific operation code for the instruction.
 151 For example, the @samp{lr} mnemonic denotes the instruction format @samp{RR}
 152 with the operation code @samp{0x18}.
 153
 154 The definition of the various mnemonics follows a scheme, where the first
 155 character 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
 162 register 32-bit
 163 @item d @tab divide instruction, for example @samp{dlr} devide logical register
 164 64-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
 175 logical 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
 178 character
 179 @end multitable
 180 @end display
 181
 182 Certain characters at the end of the mnemonic may describe a property
 183 of 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
 199 There are many exceptions to the scheme outlined in the above lists, in
 200 particular for the priviledged instructions. For non-priviledged
 201 instruction it works quite well, for example the instruction @samp{clgfr}
 202 c: compare instruction, l: unsigned operands, g: 64-bit operands,
 203 f: 32- to 64-bit extension, r: register operands. The instruction compares
 204 an 64-bit value in a register with the zero extended 32-bit value from
 205 a second register.
 206 For a complete list of all mnemonics see appendix B in the Principles
 207 of Operation.
 208
 209 @node s390 Operands
 210 @subsection Instruction Operands
 211 @cindex instruction operands, s390
 212 @cindex s390 instruction operands
 213
 214 Instruction operands can be grouped into three classes, operands located
 215 in registers, immediate operands, and operands in storage.
 216
 217 A register operand can be located in general, floating-point, access,
 218 or control register. The register is identified by a four-bit field.
 219 The field containing the register operand is called the R field.
 220
 221 Immediate operands are contained within the instruction and can have
 222 8, 16 or 32 bits. The field containing the immediate operand is called
 223 the I field. Dependent on the instruction the I field is either signed
 224 or unsigned.
 225
 226 A storage operand consists of an address and a length. The address of a
 227 storage 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
 232 register B plus the content of a displacement field D
 233 @item The sum of the contents of two general registers called the
 234 index register X and the base register B plus the content of a
 235 displacement field
 236 @item The sum of the current instruction address and a 32-bit signed
 237 immediate field multiplied by two.
 238 @end itemize
 239
 240 The 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
 249 The notation for storage operand addresses formed from multiple fields is
 250 as follows:
 251
 252 @table @code
 253 @item Dn(Bn)
 254 the address for operand number n is formed from the content of general
 255 register Bn called the base register and the displacement field Dn.
 256 @item Dn(Xn,Bn)
 257 the address for operand number n is formed from the content of general
 258 register Xn called the index register, general register Bn called the
 259 base register and the displacement field Dn.
 260 @item Dn(Ln,Bn)
 261 the address for operand number n is formed from the content of general
 262 regiser Bn called the base register and the displacement field Dn.
 263 The length of the operand n is specified by the field Ln.
 264 @end table
 265
 266 The base registers Bn and the index registers Xn of a storage operand can
 267 be skipped. If Bn and Xn are skipped, a zero will be stored to the operand
 268 field. 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
 286 The Principles of Operation manuals lists 26 instruction formats where
 287 some of the formats have multiple variants. For the @samp{.insn}
 288 pseudo directive the assembler recognizes some of the formats.
 289 Typically, the most general variant of the instruction format is used
 290 by the @samp{.insn} directive.
 291
 292 The following table lists the abbreviations used in the table of
 293 instruction 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
 309 An instruction is two, four, or six bytes in length and must be aligned
 310 on a 2 byte boundary. The first two bits of the instruction specify the
 311 length of the instruction, 00 indicates a two byte instruction, 01 and 10
 312 indicates a four byte instruction, and 11 indicates a six byte instruction.
 313
 314 The following table lists the s390 instruction formats that are available
 315 with the @samp{.insn} pseudo directive:
 316
 317 @table @code
 318 @item E format
 319 @verbatim
 320 +-------------+
 321 |    OpCode   |
 322 +-------------+
 323 0            15
 324 @end verbatim
 325
 326 @item RI format: <insn> R1,I2
 327 @verbatim
 328 +--------+----+----+------------------+
 329 | OpCode | R1 |OpCd|        I2        |
 330 +--------+----+----+------------------+
 331 0        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 +--------+----+----+------------------+--------+--------+
 339 0        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 +--------+----+----+------------------------------------+
 347 0        8    12   16                                  47
 348 @end verbatim
 349
 350 @item RILU format: <insn> R1,U2
 351 @verbatim
 352 +--------+----+----+------------------------------------+
 353 | OpCode | R1 |OpCd|                  U2                |
 354 +--------+----+----+------------------------------------+
 355 0        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 +--------+----+----+----+-------------+--------+--------+
 363 0        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 +--------+----+----+
 371 0        8    12  15
 372 @end verbatim
 373
 374 @item RRE format: <insn> R1,R2
 375 @verbatim
 376 +------------------+--------+----+----+
 377 |      OpCode      |////////| R1 | R2 |
 378 +------------------+--------+----+----+
 379 0                  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 +------------------+----+----+----+----+
 387 0                  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 +--------+----+----+----+-------------+----+----+--------+
 395 0        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 +--------+----+----+----+-------------+
 403 0        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 +--------+----+----+----+-------------+--------+--------+
 411 0        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 +--------+----+----+------------------------------------+
 419 0        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 +--------+----+----+----+-------------+--------+--------+
 427 0        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 +--------+----+----+----+-------------+
 435 0        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 +--------+----+----+----+-------------+--------+--------+
 443 0        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 +--------+----+----+----+-------------+----+---+--------+
 451 0        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 +--------+----+----+----+-------------+--------+--------+
 459 0        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 +------------------+----+-------------+
 467 0                  16   20           31
 468 @end verbatim
 469
 470 @item SI format: <insn> D1(B1),I2
 471 @verbatim
 472 +--------+---------+----+-------------+
 473 | OpCode |   I2    | B1 |     D1      |
 474 +--------+---------+----+-------------+
 475 0        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 +--------+---------+----+-------------+--------+--------+
 483 0        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 +------------------+----+-------------+-----------------+
 491 0                  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 +--------+----+----+----+-------------+----+------------+
 499 0        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 +------------------+----+-------------+----+------------+
 507 0        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 +--------+----+----+----+-------------+----+------------+
 515 0        8    12   16   20            32   36           47
 516 @end verbatim
 517
 518 @end table
 519
 520 For the complete list of all instruction format variants see the
 521 Principles of Operation manuals.
 522
 523 @node s390 Aliases
 524 @subsection Instruction Aliases
 525 @cindex instruction aliases, s390
 526 @cindex s390 instruction aliases
 527
 528 A specific bit pattern can have multiple mnemonics, for example
 529 the 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.
 532 These are the short forms of the branch instructions, where the condition
 533 code mask operand is encoded in the mnemonic. This is relevant for the
 534 branch instructions, the compare and branch instructions, and the
 535 compare and trap instructions.
 536
 537 For the branch instructions there are 20 condition code strings that can
 538 be used as part of the mnemonic in place of a mask operand in the instruction
 539 format:
 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
 551 In the mnemonic for a branch instruction the condition code string <m>
 552 can 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
 579 For the compare and branch, and compare and trap instructions there
 580 are 12 condition code strings that can be used as part of the mnemonic in
 581 place 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
 613 In the mnemonic for a compare and branch and compare and trap instruction
 614 the 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
 638 If a symbol modifier is attached to a symbol in an expression for an
 639 instruction operand field, the symbol term is replaced with a reference
 640 to an object in the global offset table (GOT) or the procedure linkage
 641 table (PLT). The following expressions are allowed:
 642 @samp{symbol@@modifier + constant},
 643 @samp{symbol@@modifier + label + constant}, and
 644 @samp{symbol@@modifier - label + constant}.
 645 The term @samp{symbol} is the symbol that will be entered into the GOT or
 646 PLT, @samp{label} is a local label, and @samp{constant} is an arbitrary
 647 expression that the assembler can evaluate to a constant value.
 648
 649 The term @samp{(symbol + constant1)@@modifier +/- label + constant2}
 650 is also accepted but a warning message is printed and the term is
 651 converted to @samp{symbol@@modifier +/- label + constant1 + constant2}.
 652
 653 @table @code
 654 @item @@got
 655 @itemx @@got12
 656 The @@got modifier can be used for displacement fields, 16-bit immediate
 657 fields and 32-bit pc-relative immediate fields. The @@got12 modifier is
 658 synonym to @@got. The symbol is added to the GOT. For displacement
 659 fields and 16-bit immediate fields the symbol term is replaced with
 660 the offset from the start of the GOT to the GOT slot for the symbol.
 661 For a 32-bit pc-relative field the pc-relative offset to the GOT
 662 slot from the current instruction address is used.
 663 @item @@gotent
 664 The @@gotent modifier can be used for 32-bit pc-relative immediate fields.
 665 The symbol is added to the GOT and the symbol term is replaced with
 666 the pc-relative offset from the current instruction to the GOT slot for the
 667 symbol.
 668 @item @@gotoff
 669 The @@gotoff modifier can be used for 16-bit immediate fields. The symbol
 670 term is replaced with the offset from the start of the GOT to the
 671 address of the symbol.
 672 @item @@gotplt
 673 The @@gotplt modifier can be used for displacement fields, 16-bit immediate
 674 fields, and 32-bit pc-relative immediate fields. A procedure linkage
 675 table entry is generated for the symbol and a jump slot for the symbol
 676 is added to the GOT. For displacement fields and 16-bit immediate
 677 fields the symbol term is replaced with the offset from the start of the
 678 GOT to the jump slot for the symbol. For a 32-bit pc-relative field
 679 the pc-relative offset to the jump slot from the current instruction
 680 address is used.
 681 @item @@plt
 682 The @@plt modifier can be used for 16-bit and 32-bit pc-relative immediate
 683 fields. A procedure linkage table entry is generated for the symbol.
 684 The symbol term is replaced with the relative offset from the current
 685 instruction to the PLT entry for the symbol.
 686 @item @@pltoff
 687 The @@pltoff modifier can be used for 16-bit immediate fields. The symbol
 688 term is replaced with the offset from the start of the PLT to the address
 689 of the symbol.
 690 @item @@gotntpoff
 691 The @@gotntpoff modifier can be used for displacement fields. The symbol
 692 is added to the static TLS block and the negated offset to the symbol
 693 in the static TLS block is added to the GOT. The symbol term is replaced
 694 with the offset to the GOT slot from the start of the GOT.
 695 @item @@indntpoff
 696 The @@indntpoff modifier can be used for 32-bit pc-relative immediate
 697 fields. The symbol is added to the static TLS block and the negated offset
 698 to the symbol in the static TLS block is added to the GOT. The symbol term
 699 is replaced with the pc-relative offset to the GOT slot from the current
 700 instruction address.
 701 @end table
 702
 703 For 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
 712 The thread local storage instruction markers are used by the linker to
 713 perform code optimization.
 714
 715 @table @code
 716 @item :tls_load
 717 The :tls_load marker is used to flag the load instruction in the initial
 718 exec TLS model that retrieves the offset from the thread pointer to a
 719 thread local storage variable from the GOT.
 720 @item :tls_gdcall
 721 The :tls_gdcall marker is used to flag the branch-and-save instruction to
 722 the __tls_get_offset function in the global dynamic TLS model.
 723 @item :tls_ldcall
 724 The :tls_ldcall marker is used to flag the branch-and-save instruction to
 725 the __tls_get_offset function in the local dynamic TLS model.
 726 @end table
 727
 728 For more information about the thread local storage instruction marker
 729 and 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
 737 A literal pool is a collection of values. To access the values a pointer
 738 to the literal pool is loaded to a register, the literal pool register.
 739 Usually, register %r13 is used as the literal pool register
 740 (@ref{s390 Register}). Literal pool entries are created by adding the
 741 suffix :lit1, :lit2, :lit4, or :lit8 to the end of an expression for an
 742 instruction operand. The expression is added to the literal pool and the
 743 operand is replaced with the offset to the literal in the literal pool.
 744
 745 @table @code
 746 @item :lit1
 747 The literal pool entry is created as an 8-bit value. An operand modifier
 748 must not be used for the original expression.
 749 @item :lit2
 750 The 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}
 752 will put the got offset for the global symbol x to the literal pool as
 753 16 bit value.
 754 @item :lit4
 755 The 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
 758 literal pool as a 32-bit value. The term @samp{x@@plt:lit4} will put the
 759 plt offset for the global symbol x to the literal pool as a 32-bit value.
 760 @item :lit8
 761 The 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
 764 literal pool as a 64-bit value. The term @samp{x@@plt:lit8} will put the
 765 plt offset for the global symbol x to the literal pool as a 64-bit value.
 766 @end table
 767
 768 The assembler directive @samp{.ltorg} is used to emit all literal pool
 769 entries 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
 775 assembler directives as outlined in the main part of this document.
 776 Some directives have been extended and there are some additional
 777 directives, which are only available for the s390 @code{@value{AS}}.
 778
 779 @table @code
 780 @cindex @code{.insn} directive, s390
 781 @item .insn
 782 This directive permits the numeric representation of an instructions
 783 and makes the assembler insert the operands according to one of the
 784 instructions formats for @samp{.insn} (@ref{s390 Formats}).
 785 For 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
 793 This directive places one or more 16-bit (.short), 32-bit (.long), or
 794 64-bit (.quad) values into the current section. If an ELF or TLS modifier
 795 is 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}.
 799 The following modifiers are available:
 800 @table @code
 801 @item @@got
 802 @itemx @@got12
 803 The @@got modifier can be used for .short, .long and .quad. The @@got12
 804 modifier is synonym to @@got. The symbol is added to the GOT. The symbol
 805 term is replaced with offset from the start of the GOT to the GOT slot for
 806 the symbol.
 807 @item @@gotoff
 808 The @@gotoff modifier can be used for .short, .long and .quad. The symbol
 809 term is replaced with the offset from the start of the GOT to the address
 810 of the symbol.
 811 @item @@gotplt
 812 The @@gotplt modifier can be used for .long and .quad. A procedure linkage
 813 table entry is generated for the symbol and a jump slot for the symbol
 814 is added to the GOT. The symbol term is replaced with the offset from the
 815 start of the GOT to the jump slot for the symbol.
 816 @item @@plt
 817 The @@plt modifier can be used for .long and .quad. A procedure linkage
 818 table entry us generated for the symbol. The symbol term is replaced with
 819 the address of the PLT entry for the symbol.
 820 @item @@pltoff
 821 The @@pltoff modifier can be used for .short, .long and .quad. The symbol
 822 term is replaced with the offset from the start of the PLT to the address
 823 of the symbol.
 824 @item @@tlsgd
 825 @itemx @@tlsldm
 826 The @@tlsgd and @@tlsldm modifier can be used for .long and .quad. A
 827 tls_index structure for the symbol is added to the GOT. The symbol term is
 828 replaced with the offset from the start of the GOT to the tls_index structure.
 829 @item @@gotntpoff
 830 @itemx @@indntpoff
 831 The @@gotntpoff and @@indntpoff modifier can be used for .long and .quad.
 832 The symbol is added to the static TLS block and the negated offset to the
 833 symbol in the static TLS block is added to the GOT. For @@gotntpoff the
 834 symbol term is replaced with the offset from the start of the GOT to the
 835 GOT slot, for @@indntpoff the symbol term is replaced with the address
 836 of the GOT slot.
 837 @item @@dtpoff
 838 The @@dtpoff modifier can be used for .long and .quad. The symbol term
 839 is replaced with the offset of the symbol relative to the start of the
 840 TLS block it is contained in.
 841 @item @@ntpoff
 842 The @@ntpoff modifier can be used for .long and .quad. The symbol term
 843 is replaced with the offset of the symbol relative to the TCB pointer.
 844 @end table
 845
 846 For more information about the thread local storage modifiers see the
 847 ELF extension documentation @samp{ELF Handling For Thread-Local Storage}.
 848
 849 @cindex @code{.ltorg} directive, s390
 850 @item .ltorg
 851 This directive causes the current contents of the literal pool to be
 852 dumped 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
 860 The assembler recognizes both the @sc{ieee} floating-point instruction and
 861 the 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.