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