1@c Copyright (C) 2009-2016 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 16The s390 version of @code{@value{AS}} supports two architectures modes 17and seven chip levels. The architecture modes are the Enterprise System 18Architecture (ESA) and the newer z/Architecture mode. The chip levels 19are 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 34The 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 40Select 31- or 64-bit ABI implying a word size of 32- or 64-bit. 41 42These options are only available with the ELF object file format, and 43require that the necessary BFD support has been included (on a 31-bit 44platform you must add --enable-64-bit-bfd on the call to the configure 45script 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 50Select the architecture mode, either the Enterprise System Architecture 51(esa) mode or the z/Architecture mode (zarch). 52 53The 64-bit instructions are only available with the z/Architecture mode. 54The combination of @samp{-m64} and @samp{-mesa} results in a warning 55message. 56 57@cindex @samp{-march=} option, s390 58@item -march=@var{CPU} 59This option specifies the target processor. The following processor names 60are 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}. 71Assembling an instruction that is not supported on the target processor 72results in an error message. Do not specify @code{g5} or @code{g6} 73with @samp{-mzarch}. 74 75@cindex @samp{-mregnames} option, s390 76@item -mregnames 77Allow symbolic names for registers. 78 79@cindex @samp{-mno-regnames} option, s390 80@item -mno-regnames 81Do not allow symbolic names for registers. 82 83@cindex @samp{-mwarn-areg-zero} option, s390 84@item -mwarn-areg-zero 85Warn whenever the operand for a base or index register has been specified 86but evaluates to zero. This can indicate the misuse of general purpose 87register 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 98If a @samp{#} appears as the first character of a line then the whole 99line is treated as a comment, but in this case the line could also be 100a logical line number directive (@pxref{Comments}) or a preprocessor 101control command (@pxref{Preprocessing}). 102 103@cindex line separator, s390 104@cindex statement separator, s390 105@cindex s390 line separator 106The @samp{;} character can be used instead of a newline to separate 107statements. 108 109@node s390 Syntax 110@section Instruction syntax 111@cindex instruction syntax, s390 112@cindex s390 instruction syntax 113 114The assembler syntax closely follows the syntax outlined in 115Enterprise Systems Architecture/390 Principles of Operation (SA22-7201) 116and the z/Architecture Principles of Operation (SA22-7832). 117 118Each instruction has two major parts, the instruction mnemonic 119and 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 137The @code{@value{AS}} recognizes a number of predefined symbols for the 138various processor registers. A register specification in one of the 139instruction formats is an unsigned integer between 0 and 15. The specific 140instruction and the position of the register in the instruction format 141denotes 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 160All instructions documented in the Principles of Operation are supported 161with the mnemonic and order of operands as described. 162The instruction mnemonic identifies the instruction format 163(@ref{s390 Formats}) and the specific operation code for the instruction. 164For example, the @samp{lr} mnemonic denotes the instruction format @samp{RR} 165with the operation code @samp{0x18}. 166 167The definition of the various mnemonics follows a scheme, where the first 168character 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 175register 32-bit 176@item d @tab divide instruction, for example @samp{dlr} devide logical register 17764-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 188logical 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 191character 192@end multitable 193@end display 194 195Certain characters at the end of the mnemonic may describe a property 196of 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 212There are many exceptions to the scheme outlined in the above lists, in 213particular for the priviledged instructions. For non-priviledged 214instruction it works quite well, for example the instruction @samp{clgfr} 215c: compare instruction, l: unsigned operands, g: 64-bit operands, 216f: 32- to 64-bit extension, r: register operands. The instruction compares 217an 64-bit value in a register with the zero extended 32-bit value from 218a second register. 219For a complete list of all mnemonics see appendix B in the Principles 220of Operation. 221 222@node s390 Operands 223@subsection Instruction Operands 224@cindex instruction operands, s390 225@cindex s390 instruction operands 226 227Instruction operands can be grouped into three classes, operands located 228in registers, immediate operands, and operands in storage. 229 230A register operand can be located in general, floating-point, access, 231or control register. The register is identified by a four-bit field. 232The field containing the register operand is called the R field. 233 234Immediate operands are contained within the instruction and can have 2358, 16 or 32 bits. The field containing the immediate operand is called 236the I field. Dependent on the instruction the I field is either signed 237or unsigned. 238 239A storage operand consists of an address and a length. The address of a 240storage 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 245register B plus the content of a displacement field D 246@item The sum of the contents of two general registers called the 247index register X and the base register B plus the content of a 248displacement field 249@item The sum of the current instruction address and a 32-bit signed 250immediate field multiplied by two. 251@end itemize 252 253The 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 262The notation for storage operand addresses formed from multiple fields is 263as follows: 264 265@table @code 266@item Dn(Bn) 267the address for operand number n is formed from the content of general 268register Bn called the base register and the displacement field Dn. 269@item Dn(Xn,Bn) 270the address for operand number n is formed from the content of general 271register Xn called the index register, general register Bn called the 272base register and the displacement field Dn. 273@item Dn(Ln,Bn) 274the address for operand number n is formed from the content of general 275regiser Bn called the base register and the displacement field Dn. 276The length of the operand n is specified by the field Ln. 277@end table 278 279The base registers Bn and the index registers Xn of a storage operand can 280be skipped. If Bn and Xn are skipped, a zero will be stored to the operand 281field. 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 299The Principles of Operation manuals lists 26 instruction formats where 300some of the formats have multiple variants. For the @samp{.insn} 301pseudo directive the assembler recognizes some of the formats. 302Typically, the most general variant of the instruction format is used 303by the @samp{.insn} directive. 304 305The following table lists the abbreviations used in the table of 306instruction 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 322An instruction is two, four, or six bytes in length and must be aligned 323on a 2 byte boundary. The first two bits of the instruction specify the 324length of the instruction, 00 indicates a two byte instruction, 01 and 10 325indicates a four byte instruction, and 11 indicates a six byte instruction. 326 327The following table lists the s390 instruction formats that are available 328with the @samp{.insn} pseudo directive: 329 330@table @code 331@item E format 332@verbatim 333+-------------+ 334| OpCode | 335+-------------+ 3360 15 337@end verbatim 338 339@item RI format: <insn> R1,I2 340@verbatim 341+--------+----+----+------------------+ 342| OpCode | R1 |OpCd| I2 | 343+--------+----+----+------------------+ 3440 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+--------+----+----+------------------+--------+--------+ 3520 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+--------+----+----+------------------------------------+ 3600 8 12 16 47 361@end verbatim 362 363@item RILU format: <insn> R1,U2 364@verbatim 365+--------+----+----+------------------------------------+ 366| OpCode | R1 |OpCd| U2 | 367+--------+----+----+------------------------------------+ 3680 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+--------+----+----+----+-------------+--------+--------+ 3760 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+--------+----+----+ 3840 8 12 15 385@end verbatim 386 387@item RRE format: <insn> R1,R2 388@verbatim 389+------------------+--------+----+----+ 390| OpCode |////////| R1 | R2 | 391+------------------+--------+----+----+ 3920 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+------------------+----+----+----+----+ 4000 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+--------+----+----+----+-------------+----+----+--------+ 4080 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+--------+----+----+----+-------------+ 4160 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+--------+----+----+----+-------------+--------+--------+ 4240 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+--------+----+----+------------------------------------+ 4320 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+--------+----+----+----+-------------+--------+--------+ 4400 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+--------+----+----+----+-------------+ 4480 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+--------+----+----+----+-------------+--------+--------+ 4560 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+--------+----+----+----+-------------+----+---+--------+ 4640 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+--------+----+----+----+-------------+--------+--------+ 4720 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+------------------+----+-------------+ 4800 16 20 31 481@end verbatim 482 483@item SI format: <insn> D1(B1),I2 484@verbatim 485+--------+---------+----+-------------+ 486| OpCode | I2 | B1 | D1 | 487+--------+---------+----+-------------+ 4880 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+--------+---------+----+-------------+--------+--------+ 4960 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+------------------+----+-------------+-----------------+ 5040 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+--------+----+----+----+-------------+----+------------+ 5120 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+------------------+----+-------------+----+------------+ 5200 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+--------+----+----+----+-------------+----+------------+ 5280 8 12 16 20 32 36 47 529@end verbatim 530 531@end table 532 533For the complete list of all instruction format variants see the 534Principles of Operation manuals. 535 536@node s390 Aliases 537@subsection Instruction Aliases 538@cindex instruction aliases, s390 539@cindex s390 instruction aliases 540 541A specific bit pattern can have multiple mnemonics, for example 542the 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. 545These are the short forms of the branch instructions, where the condition 546code mask operand is encoded in the mnemonic. This is relevant for the 547branch instructions, the compare and branch instructions, and the 548compare and trap instructions. 549 550For the branch instructions there are 20 condition code strings that can 551be used as part of the mnemonic in place of a mask operand in the instruction 552format: 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 564In the mnemonic for a branch instruction the condition code string <m> 565can 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 592For the compare and branch, and compare and trap instructions there 593are 12 condition code strings that can be used as part of the mnemonic in 594place 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 626In the mnemonic for a compare and branch and compare and trap instruction 627the 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 651If a symbol modifier is attached to a symbol in an expression for an 652instruction operand field, the symbol term is replaced with a reference 653to an object in the global offset table (GOT) or the procedure linkage 654table (PLT). The following expressions are allowed: 655@samp{symbol@@modifier + constant}, 656@samp{symbol@@modifier + label + constant}, and 657@samp{symbol@@modifier - label + constant}. 658The term @samp{symbol} is the symbol that will be entered into the GOT or 659PLT, @samp{label} is a local label, and @samp{constant} is an arbitrary 660expression that the assembler can evaluate to a constant value. 661 662The term @samp{(symbol + constant1)@@modifier +/- label + constant2} 663is also accepted but a warning message is printed and the term is 664converted to @samp{symbol@@modifier +/- label + constant1 + constant2}. 665 666@table @code 667@item @@got 668@itemx @@got12 669The @@got modifier can be used for displacement fields, 16-bit immediate 670fields and 32-bit pc-relative immediate fields. The @@got12 modifier is 671synonym to @@got. The symbol is added to the GOT. For displacement 672fields and 16-bit immediate fields the symbol term is replaced with 673the offset from the start of the GOT to the GOT slot for the symbol. 674For a 32-bit pc-relative field the pc-relative offset to the GOT 675slot from the current instruction address is used. 676@item @@gotent 677The @@gotent modifier can be used for 32-bit pc-relative immediate fields. 678The symbol is added to the GOT and the symbol term is replaced with 679the pc-relative offset from the current instruction to the GOT slot for the 680symbol. 681@item @@gotoff 682The @@gotoff modifier can be used for 16-bit immediate fields. The symbol 683term is replaced with the offset from the start of the GOT to the 684address of the symbol. 685@item @@gotplt 686The @@gotplt modifier can be used for displacement fields, 16-bit immediate 687fields, and 32-bit pc-relative immediate fields. A procedure linkage 688table entry is generated for the symbol and a jump slot for the symbol 689is added to the GOT. For displacement fields and 16-bit immediate 690fields the symbol term is replaced with the offset from the start of the 691GOT to the jump slot for the symbol. For a 32-bit pc-relative field 692the pc-relative offset to the jump slot from the current instruction 693address is used. 694@item @@plt 695The @@plt modifier can be used for 16-bit and 32-bit pc-relative immediate 696fields. A procedure linkage table entry is generated for the symbol. 697The symbol term is replaced with the relative offset from the current 698instruction to the PLT entry for the symbol. 699@item @@pltoff 700The @@pltoff modifier can be used for 16-bit immediate fields. The symbol 701term is replaced with the offset from the start of the PLT to the address 702of the symbol. 703@item @@gotntpoff 704The @@gotntpoff modifier can be used for displacement fields. The symbol 705is added to the static TLS block and the negated offset to the symbol 706in the static TLS block is added to the GOT. The symbol term is replaced 707with the offset to the GOT slot from the start of the GOT. 708@item @@indntpoff 709The @@indntpoff modifier can be used for 32-bit pc-relative immediate 710fields. The symbol is added to the static TLS block and the negated offset 711to the symbol in the static TLS block is added to the GOT. The symbol term 712is replaced with the pc-relative offset to the GOT slot from the current 713instruction address. 714@end table 715 716For 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 725The thread local storage instruction markers are used by the linker to 726perform code optimization. 727 728@table @code 729@item :tls_load 730The :tls_load marker is used to flag the load instruction in the initial 731exec TLS model that retrieves the offset from the thread pointer to a 732thread local storage variable from the GOT. 733@item :tls_gdcall 734The :tls_gdcall marker is used to flag the branch-and-save instruction to 735the __tls_get_offset function in the global dynamic TLS model. 736@item :tls_ldcall 737The :tls_ldcall marker is used to flag the branch-and-save instruction to 738the __tls_get_offset function in the local dynamic TLS model. 739@end table 740 741For more information about the thread local storage instruction marker 742and 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 750A literal pool is a collection of values. To access the values a pointer 751to the literal pool is loaded to a register, the literal pool register. 752Usually, register %r13 is used as the literal pool register 753(@ref{s390 Register}). Literal pool entries are created by adding the 754suffix :lit1, :lit2, :lit4, or :lit8 to the end of an expression for an 755instruction operand. The expression is added to the literal pool and the 756operand is replaced with the offset to the literal in the literal pool. 757 758@table @code 759@item :lit1 760The literal pool entry is created as an 8-bit value. An operand modifier 761must not be used for the original expression. 762@item :lit2 763The 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} 765will put the got offset for the global symbol x to the literal pool as 76616 bit value. 767@item :lit4 768The 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 771literal pool as a 32-bit value. The term @samp{x@@plt:lit4} will put the 772plt offset for the global symbol x to the literal pool as a 32-bit value. 773@item :lit8 774The 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 777literal pool as a 64-bit value. The term @samp{x@@plt:lit8} will put the 778plt offset for the global symbol x to the literal pool as a 64-bit value. 779@end table 780 781The assembler directive @samp{.ltorg} is used to emit all literal pool 782entries 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 788assembler directives as outlined in the main part of this document. 789Some directives have been extended and there are some additional 790directives, which are only available for the s390 @code{@value{AS}}. 791 792@table @code 793@cindex @code{.insn} directive, s390 794@item .insn 795This directive permits the numeric representation of an instructions 796and makes the assembler insert the operands according to one of the 797instructions formats for @samp{.insn} (@ref{s390 Formats}). 798For 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 806This directive places one or more 16-bit (.short), 32-bit (.long), or 80764-bit (.quad) values into the current section. If an ELF or TLS modifier 808is 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}. 812The following modifiers are available: 813@table @code 814@item @@got 815@itemx @@got12 816The @@got modifier can be used for .short, .long and .quad. The @@got12 817modifier is synonym to @@got. The symbol is added to the GOT. The symbol 818term is replaced with offset from the start of the GOT to the GOT slot for 819the symbol. 820@item @@gotoff 821The @@gotoff modifier can be used for .short, .long and .quad. The symbol 822term is replaced with the offset from the start of the GOT to the address 823of the symbol. 824@item @@gotplt 825The @@gotplt modifier can be used for .long and .quad. A procedure linkage 826table entry is generated for the symbol and a jump slot for the symbol 827is added to the GOT. The symbol term is replaced with the offset from the 828start of the GOT to the jump slot for the symbol. 829@item @@plt 830The @@plt modifier can be used for .long and .quad. A procedure linkage 831table entry us generated for the symbol. The symbol term is replaced with 832the address of the PLT entry for the symbol. 833@item @@pltoff 834The @@pltoff modifier can be used for .short, .long and .quad. The symbol 835term is replaced with the offset from the start of the PLT to the address 836of the symbol. 837@item @@tlsgd 838@itemx @@tlsldm 839The @@tlsgd and @@tlsldm modifier can be used for .long and .quad. A 840tls_index structure for the symbol is added to the GOT. The symbol term is 841replaced with the offset from the start of the GOT to the tls_index structure. 842@item @@gotntpoff 843@itemx @@indntpoff 844The @@gotntpoff and @@indntpoff modifier can be used for .long and .quad. 845The symbol is added to the static TLS block and the negated offset to the 846symbol in the static TLS block is added to the GOT. For @@gotntpoff the 847symbol term is replaced with the offset from the start of the GOT to the 848GOT slot, for @@indntpoff the symbol term is replaced with the address 849of the GOT slot. 850@item @@dtpoff 851The @@dtpoff modifier can be used for .long and .quad. The symbol term 852is replaced with the offset of the symbol relative to the start of the 853TLS block it is contained in. 854@item @@ntpoff 855The @@ntpoff modifier can be used for .long and .quad. The symbol term 856is replaced with the offset of the symbol relative to the TCB pointer. 857@end table 858 859For more information about the thread local storage modifiers see the 860ELF extension documentation @samp{ELF Handling For Thread-Local Storage}. 861 862@cindex @code{.ltorg} directive, s390 863@item .ltorg 864This directive causes the current contents of the literal pool to be 865dumped to the current location (@ref{s390 Literal Pool Entries}). 866 867@cindex @code{.machine} directive, s390 868@item .machine @var{STRING}[+@var{EXTENSION}]@dots{} 869 870This directive allows changing the machine for which code is 871generated. @code{string} may be any of the @code{-march=} 872selection options, or @code{push}, or @code{pop}. @code{.machine 873push} saves the currently selected cpu, which may be restored with 874@code{.machine pop}. Be aware that the cpu string has to be put 875into double quotes in case it contains characters not appropriate 876for identifiers. So you have to write @code{"z9-109"} instead of 877just @code{z9-109}. Extensions can be specified after the cpu 878name, separated by plus charaters. Valid extensions are: 879@code{htm}, 880@code{nohtm}, 881@code{vx}, 882@code{novx}. 883They extend the basic instruction set with features from a higher 884cpu level, or remove support for a feature from the given cpu 885level. 886 887Example: @code{z13+nohtm} allows all instructions of the z13 cpu 888except instructions from the HTM facility. 889 890@cindex @code{.machinemode} directive, s390 891@item .machinemode string 892This directive allows to change the architecture mode for which code 893is being generated. @code{string} may be @code{esa}, @code{zarch}, 894@code{zarch_nohighgprs}, @code{push}, or @code{pop}. 895@code{.machinemode zarch_nohighgprs} can be used to prevent the 896@code{highgprs} flag from being set in the ELF header of the output 897file. This is useful in situations where the code is gated with a 898runtime check which makes sure that the code is only executed on 899kernels providing the @code{highgprs} feature. 900@code{.machinemode push} saves the currently selected mode, which may 901be restored with @code{.machinemode pop}. 902@end table 903 904@node s390 Floating Point 905@section Floating Point 906@cindex floating point, s390 907@cindex s390 floating point 908 909The assembler recognizes both the @sc{ieee} floating-point instruction and 910the hexadecimal floating-point instructions. The floating-point constructors 911@samp{.float}, @samp{.single}, and @samp{.double} always emit the 912@sc{ieee} format. To assemble hexadecimal floating-point constants the 913@samp{.long} and @samp{.quad} directives must be used. 914