1@c Copyright (C) 1996-2014 Free Software Foundation, Inc. 2@c This is part of the GAS manual. 3@c For copying conditions, see the file as.texinfo. 4 5@ifset GENERIC 6@page 7@node ARM-Dependent 8@chapter ARM Dependent Features 9@end ifset 10 11@ifclear GENERIC 12@node Machine Dependencies 13@chapter ARM Dependent Features 14@end ifclear 15 16@cindex ARM support 17@cindex Thumb support 18@menu 19* ARM Options:: Options 20* ARM Syntax:: Syntax 21* ARM Floating Point:: Floating Point 22* ARM Directives:: ARM Machine Directives 23* ARM Opcodes:: Opcodes 24* ARM Mapping Symbols:: Mapping Symbols 25* ARM Unwinding Tutorial:: Unwinding 26@end menu 27 28@node ARM Options 29@section Options 30@cindex ARM options (none) 31@cindex options for ARM (none) 32 33@table @code 34 35@cindex @code{-mcpu=} command line option, ARM 36@item -mcpu=@var{processor}[+@var{extension}@dots{}] 37This option specifies the target processor. The assembler will issue an 38error message if an attempt is made to assemble an instruction which 39will not execute on the target processor. The following processor names are 40recognized: 41@code{arm1}, 42@code{arm2}, 43@code{arm250}, 44@code{arm3}, 45@code{arm6}, 46@code{arm60}, 47@code{arm600}, 48@code{arm610}, 49@code{arm620}, 50@code{arm7}, 51@code{arm7m}, 52@code{arm7d}, 53@code{arm7dm}, 54@code{arm7di}, 55@code{arm7dmi}, 56@code{arm70}, 57@code{arm700}, 58@code{arm700i}, 59@code{arm710}, 60@code{arm710t}, 61@code{arm720}, 62@code{arm720t}, 63@code{arm740t}, 64@code{arm710c}, 65@code{arm7100}, 66@code{arm7500}, 67@code{arm7500fe}, 68@code{arm7t}, 69@code{arm7tdmi}, 70@code{arm7tdmi-s}, 71@code{arm8}, 72@code{arm810}, 73@code{strongarm}, 74@code{strongarm1}, 75@code{strongarm110}, 76@code{strongarm1100}, 77@code{strongarm1110}, 78@code{arm9}, 79@code{arm920}, 80@code{arm920t}, 81@code{arm922t}, 82@code{arm940t}, 83@code{arm9tdmi}, 84@code{fa526} (Faraday FA526 processor), 85@code{fa626} (Faraday FA626 processor), 86@code{arm9e}, 87@code{arm926e}, 88@code{arm926ej-s}, 89@code{arm946e-r0}, 90@code{arm946e}, 91@code{arm946e-s}, 92@code{arm966e-r0}, 93@code{arm966e}, 94@code{arm966e-s}, 95@code{arm968e-s}, 96@code{arm10t}, 97@code{arm10tdmi}, 98@code{arm10e}, 99@code{arm1020}, 100@code{arm1020t}, 101@code{arm1020e}, 102@code{arm1022e}, 103@code{arm1026ej-s}, 104@code{fa606te} (Faraday FA606TE processor), 105@code{fa616te} (Faraday FA616TE processor), 106@code{fa626te} (Faraday FA626TE processor), 107@code{fmp626} (Faraday FMP626 processor), 108@code{fa726te} (Faraday FA726TE processor), 109@code{arm1136j-s}, 110@code{arm1136jf-s}, 111@code{arm1156t2-s}, 112@code{arm1156t2f-s}, 113@code{arm1176jz-s}, 114@code{arm1176jzf-s}, 115@code{mpcore}, 116@code{mpcorenovfp}, 117@code{cortex-a5}, 118@code{cortex-a7}, 119@code{cortex-a8}, 120@code{cortex-a9}, 121@code{cortex-a15}, 122@code{cortex-r4}, 123@code{cortex-r4f}, 124@code{cortex-r5}, 125@code{cortex-r7}, 126@code{cortex-m4}, 127@code{cortex-m3}, 128@code{cortex-m1}, 129@code{cortex-m0}, 130@code{cortex-m0plus}, 131@code{ep9312} (ARM920 with Cirrus Maverick coprocessor), 132@code{i80200} (Intel XScale processor) 133@code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) 134and 135@code{xscale}. 136The special name @code{all} may be used to allow the 137assembler to accept instructions valid for any ARM processor. 138 139In addition to the basic instruction set, the assembler can be told to 140accept various extension mnemonics that extend the processor using the 141co-processor instruction space. For example, @code{-mcpu=arm920+maverick} 142is equivalent to specifying @code{-mcpu=ep9312}. 143 144Multiple extensions may be specified, separated by a @code{+}. The 145extensions should be specified in ascending alphabetical order. 146 147Some extensions may be restricted to particular architectures; this is 148documented in the list of extensions below. 149 150Extension mnemonics may also be removed from those the assembler accepts. 151This is done be prepending @code{no} to the option that adds the extension. 152Extensions that are removed should be listed after all extensions which have 153been added, again in ascending alphabetical order. For example, 154@code{-mcpu=ep9312+nomaverick} is equivalent to specifying @code{-mcpu=arm920}. 155 156 157The following extensions are currently supported: 158@code{crypto} (Cryptography Extensions for v8-A architecture, implies @code{fp+simd}), 159@code{fp} (Floating Point Extensions for v8-A architecture), 160@code{idiv} (Integer Divide Extensions for v7-A and v7-R architectures), 161@code{iwmmxt}, 162@code{iwmmxt2}, 163@code{maverick}, 164@code{mp} (Multiprocessing Extensions for v7-A and v7-R architectures), 165@code{os} (Operating System for v6M architecture), 166@code{sec} (Security Extensions for v6K and v7-A architectures), 167@code{simd} (Advanced SIMD Extensions for v8-A architecture, implies @code{fp}), 168@code{virt} (Virtualization Extensions for v7-A architecture, implies 169@code{idiv}), 170and 171@code{xscale}. 172 173@cindex @code{-march=} command line option, ARM 174@item -march=@var{architecture}[+@var{extension}@dots{}] 175This option specifies the target architecture. The assembler will issue 176an error message if an attempt is made to assemble an instruction which 177will not execute on the target architecture. The following architecture 178names are recognized: 179@code{armv1}, 180@code{armv2}, 181@code{armv2a}, 182@code{armv2s}, 183@code{armv3}, 184@code{armv3m}, 185@code{armv4}, 186@code{armv4xm}, 187@code{armv4t}, 188@code{armv4txm}, 189@code{armv5}, 190@code{armv5t}, 191@code{armv5txm}, 192@code{armv5te}, 193@code{armv5texp}, 194@code{armv6}, 195@code{armv6j}, 196@code{armv6k}, 197@code{armv6z}, 198@code{armv6zk}, 199@code{armv6-m}, 200@code{armv6s-m}, 201@code{armv7}, 202@code{armv7-a}, 203@code{armv7ve}, 204@code{armv7-r}, 205@code{armv7-m}, 206@code{armv7e-m}, 207@code{armv8-a}, 208@code{iwmmxt} 209and 210@code{xscale}. 211If both @code{-mcpu} and 212@code{-march} are specified, the assembler will use 213the setting for @code{-mcpu}. 214 215The architecture option can be extended with the same instruction set 216extension options as the @code{-mcpu} option. 217 218@cindex @code{-mfpu=} command line option, ARM 219@item -mfpu=@var{floating-point-format} 220 221This option specifies the floating point format to assemble for. The 222assembler will issue an error message if an attempt is made to assemble 223an instruction which will not execute on the target floating point unit. 224The following format options are recognized: 225@code{softfpa}, 226@code{fpe}, 227@code{fpe2}, 228@code{fpe3}, 229@code{fpa}, 230@code{fpa10}, 231@code{fpa11}, 232@code{arm7500fe}, 233@code{softvfp}, 234@code{softvfp+vfp}, 235@code{vfp}, 236@code{vfp10}, 237@code{vfp10-r0}, 238@code{vfp9}, 239@code{vfpxd}, 240@code{vfpv2}, 241@code{vfpv3}, 242@code{vfpv3-fp16}, 243@code{vfpv3-d16}, 244@code{vfpv3-d16-fp16}, 245@code{vfpv3xd}, 246@code{vfpv3xd-d16}, 247@code{vfpv4}, 248@code{vfpv4-d16}, 249@code{fpv4-sp-d16}, 250@code{fp-armv8}, 251@code{arm1020t}, 252@code{arm1020e}, 253@code{arm1136jf-s}, 254@code{maverick}, 255@code{neon}, 256@code{neon-vfpv4}, 257@code{neon-fp-armv8}, 258and 259@code{crypto-neon-fp-armv8}. 260 261In addition to determining which instructions are assembled, this option 262also affects the way in which the @code{.double} assembler directive behaves 263when assembling little-endian code. 264 265The default is dependent on the processor selected. For Architecture 5 or 266later, the default is to assembler for VFP instructions; for earlier 267architectures the default is to assemble for FPA instructions. 268 269@cindex @code{-mthumb} command line option, ARM 270@item -mthumb 271This option specifies that the assembler should start assembling Thumb 272instructions; that is, it should behave as though the file starts with a 273@code{.code 16} directive. 274 275@cindex @code{-mthumb-interwork} command line option, ARM 276@item -mthumb-interwork 277This option specifies that the output generated by the assembler should 278be marked as supporting interworking. 279 280@cindex @code{-mimplicit-it} command line option, ARM 281@item -mimplicit-it=never 282@itemx -mimplicit-it=always 283@itemx -mimplicit-it=arm 284@itemx -mimplicit-it=thumb 285The @code{-mimplicit-it} option controls the behavior of the assembler when 286conditional instructions are not enclosed in IT blocks. 287There are four possible behaviors. 288If @code{never} is specified, such constructs cause a warning in ARM 289code and an error in Thumb-2 code. 290If @code{always} is specified, such constructs are accepted in both 291ARM and Thumb-2 code, where the IT instruction is added implicitly. 292If @code{arm} is specified, such constructs are accepted in ARM code 293and cause an error in Thumb-2 code. 294If @code{thumb} is specified, such constructs cause a warning in ARM 295code and are accepted in Thumb-2 code. If you omit this option, the 296behavior is equivalent to @code{-mimplicit-it=arm}. 297 298@cindex @code{-mapcs-26} command line option, ARM 299@cindex @code{-mapcs-32} command line option, ARM 300@item -mapcs-26 301@itemx -mapcs-32 302These options specify that the output generated by the assembler should 303be marked as supporting the indicated version of the Arm Procedure. 304Calling Standard. 305 306@cindex @code{-matpcs} command line option, ARM 307@item -matpcs 308This option specifies that the output generated by the assembler should 309be marked as supporting the Arm/Thumb Procedure Calling Standard. If 310enabled this option will cause the assembler to create an empty 311debugging section in the object file called .arm.atpcs. Debuggers can 312use this to determine the ABI being used by. 313 314@cindex @code{-mapcs-float} command line option, ARM 315@item -mapcs-float 316This indicates the floating point variant of the APCS should be 317used. In this variant floating point arguments are passed in FP 318registers rather than integer registers. 319 320@cindex @code{-mapcs-reentrant} command line option, ARM 321@item -mapcs-reentrant 322This indicates that the reentrant variant of the APCS should be used. 323This variant supports position independent code. 324 325@cindex @code{-mfloat-abi=} command line option, ARM 326@item -mfloat-abi=@var{abi} 327This option specifies that the output generated by the assembler should be 328marked as using specified floating point ABI. 329The following values are recognized: 330@code{soft}, 331@code{softfp} 332and 333@code{hard}. 334 335@cindex @code{-eabi=} command line option, ARM 336@item -meabi=@var{ver} 337This option specifies which EABI version the produced object files should 338conform to. 339The following values are recognized: 340@code{gnu}, 341@code{4} 342and 343@code{5}. 344 345@cindex @code{-EB} command line option, ARM 346@item -EB 347This option specifies that the output generated by the assembler should 348be marked as being encoded for a big-endian processor. 349 350@cindex @code{-EL} command line option, ARM 351@item -EL 352This option specifies that the output generated by the assembler should 353be marked as being encoded for a little-endian processor. 354 355@cindex @code{-k} command line option, ARM 356@cindex PIC code generation for ARM 357@item -k 358This option specifies that the output of the assembler should be marked 359as position-independent code (PIC). 360 361@cindex @code{--fix-v4bx} command line option, ARM 362@item --fix-v4bx 363Allow @code{BX} instructions in ARMv4 code. This is intended for use with 364the linker option of the same name. 365 366@cindex @code{-mwarn-deprecated} command line option, ARM 367@item -mwarn-deprecated 368@itemx -mno-warn-deprecated 369Enable or disable warnings about using deprecated options or 370features. The default is to warn. 371 372@cindex @code{-mccs} command line option, ARM 373@item -mccs 374Turns on CodeComposer Studio assembly syntax compatibility mode. 375 376@end table 377 378 379@node ARM Syntax 380@section Syntax 381@menu 382* ARM-Instruction-Set:: Instruction Set 383* ARM-Chars:: Special Characters 384* ARM-Regs:: Register Names 385* ARM-Relocations:: Relocations 386* ARM-Neon-Alignment:: NEON Alignment Specifiers 387@end menu 388 389@node ARM-Instruction-Set 390@subsection Instruction Set Syntax 391Two slightly different syntaxes are support for ARM and THUMB 392instructions. The default, @code{divided}, uses the old style where 393ARM and THUMB instructions had their own, separate syntaxes. The new, 394@code{unified} syntax, which can be selected via the @code{.syntax} 395directive, and has the following main features: 396 397@itemize @bullet 398@item 399Immediate operands do not require a @code{#} prefix. 400 401@item 402The @code{IT} instruction may appear, and if it does it is validated 403against subsequent conditional affixes. In ARM mode it does not 404generate machine code, in THUMB mode it does. 405 406@item 407For ARM instructions the conditional affixes always appear at the end 408of the instruction. For THUMB instructions conditional affixes can be 409used, but only inside the scope of an @code{IT} instruction. 410 411@item 412All of the instructions new to the V6T2 architecture (and later) are 413available. (Only a few such instructions can be written in the 414@code{divided} syntax). 415 416@item 417The @code{.N} and @code{.W} suffixes are recognized and honored. 418 419@item 420All instructions set the flags if and only if they have an @code{s} 421affix. 422@end itemize 423 424@node ARM-Chars 425@subsection Special Characters 426 427@cindex line comment character, ARM 428@cindex ARM line comment character 429The presence of a @samp{@@} anywhere on a line indicates the start of 430a comment that extends to the end of that line. 431 432If a @samp{#} appears as the first character of a line then the whole 433line is treated as a comment, but in this case the line could also be 434a logical line number directive (@pxref{Comments}) or a preprocessor 435control command (@pxref{Preprocessing}). 436 437@cindex line separator, ARM 438@cindex statement separator, ARM 439@cindex ARM line separator 440The @samp{;} character can be used instead of a newline to separate 441statements. 442 443@cindex immediate character, ARM 444@cindex ARM immediate character 445Either @samp{#} or @samp{$} can be used to indicate immediate operands. 446 447@cindex identifiers, ARM 448@cindex ARM identifiers 449*TODO* Explain about /data modifier on symbols. 450 451@node ARM-Regs 452@subsection Register Names 453 454@cindex ARM register names 455@cindex register names, ARM 456*TODO* Explain about ARM register naming, and the predefined names. 457 458@node ARM-Relocations 459@subsection ARM relocation generation 460 461@cindex data relocations, ARM 462@cindex ARM data relocations 463Specific data relocations can be generated by putting the relocation name 464in parentheses after the symbol name. For example: 465 466@smallexample 467 .word foo(TARGET1) 468@end smallexample 469 470This will generate an @samp{R_ARM_TARGET1} relocation against the symbol 471@var{foo}. 472The following relocations are supported: 473@code{GOT}, 474@code{GOTOFF}, 475@code{TARGET1}, 476@code{TARGET2}, 477@code{SBREL}, 478@code{TLSGD}, 479@code{TLSLDM}, 480@code{TLSLDO}, 481@code{TLSDESC}, 482@code{TLSCALL}, 483@code{GOTTPOFF}, 484@code{GOT_PREL} 485and 486@code{TPOFF}. 487 488For compatibility with older toolchains the assembler also accepts 489@code{(PLT)} after branch targets. On legacy targets this will 490generate the deprecated @samp{R_ARM_PLT32} relocation. On EABI 491targets it will encode either the @samp{R_ARM_CALL} or 492@samp{R_ARM_JUMP24} relocation, as appropriate. 493 494@cindex MOVW and MOVT relocations, ARM 495Relocations for @samp{MOVW} and @samp{MOVT} instructions can be generated 496by prefixing the value with @samp{#:lower16:} and @samp{#:upper16} 497respectively. For example to load the 32-bit address of foo into r0: 498 499@smallexample 500 MOVW r0, #:lower16:foo 501 MOVT r0, #:upper16:foo 502@end smallexample 503 504@node ARM-Neon-Alignment 505@subsection NEON Alignment Specifiers 506 507@cindex alignment for NEON instructions 508Some NEON load/store instructions allow an optional address 509alignment qualifier. 510The ARM documentation specifies that this is indicated by 511@samp{@@ @var{align}}. However GAS already interprets 512the @samp{@@} character as a "line comment" start, 513so @samp{: @var{align}} is used instead. For example: 514 515@smallexample 516 vld1.8 @{q0@}, [r0, :128] 517@end smallexample 518 519@node ARM Floating Point 520@section Floating Point 521 522@cindex floating point, ARM (@sc{ieee}) 523@cindex ARM floating point (@sc{ieee}) 524The ARM family uses @sc{ieee} floating-point numbers. 525 526@node ARM Directives 527@section ARM Machine Directives 528 529@cindex machine directives, ARM 530@cindex ARM machine directives 531@table @code 532 533@c AAAAAAAAAAAAAAAAAAAAAAAAA 534 535@cindex @code{.2byte} directive, ARM 536@cindex @code{.4byte} directive, ARM 537@cindex @code{.8byte} directive, ARM 538@item .2byte @var{expression} [, @var{expression}]* 539@itemx .4byte @var{expression} [, @var{expression}]* 540@itemx .8byte @var{expression} [, @var{expression}]* 541These directives write 2, 4 or 8 byte values to the output section. 542 543@cindex @code{.align} directive, ARM 544@item .align @var{expression} [, @var{expression}] 545This is the generic @var{.align} directive. For the ARM however if the 546first argument is zero (ie no alignment is needed) the assembler will 547behave as if the argument had been 2 (ie pad to the next four byte 548boundary). This is for compatibility with ARM's own assembler. 549 550@cindex @code{.arch} directive, ARM 551@item .arch @var{name} 552Select the target architecture. Valid values for @var{name} are the same as 553for the @option{-march} commandline option. 554 555Specifying @code{.arch} clears any previously selected architecture 556extensions. 557 558@cindex @code{.arch_extension} directive, ARM 559@item .arch_extension @var{name} 560Add or remove an architecture extension to the target architecture. Valid 561values for @var{name} are the same as those accepted as architectural 562extensions by the @option{-mcpu} commandline option. 563 564@code{.arch_extension} may be used multiple times to add or remove extensions 565incrementally to the architecture being compiled for. 566 567@cindex @code{.arm} directive, ARM 568@item .arm 569This performs the same action as @var{.code 32}. 570 571@c BBBBBBBBBBBBBBBBBBBBBBBBBB 572 573@cindex @code{.bss} directive, ARM 574@item .bss 575This directive switches to the @code{.bss} section. 576 577@c CCCCCCCCCCCCCCCCCCCCCCCCCC 578 579@cindex @code{.cantunwind} directive, ARM 580@item .cantunwind 581Prevents unwinding through the current function. No personality routine 582or exception table data is required or permitted. 583 584@cindex @code{.code} directive, ARM 585@item .code @code{[16|32]} 586This directive selects the instruction set being generated. The value 16 587selects Thumb, with the value 32 selecting ARM. 588 589@cindex @code{.cpu} directive, ARM 590@item .cpu @var{name} 591Select the target processor. Valid values for @var{name} are the same as 592for the @option{-mcpu} commandline option. 593 594Specifying @code{.cpu} clears any previously selected architecture 595extensions. 596 597@c DDDDDDDDDDDDDDDDDDDDDDDDDD 598 599@cindex @code{.dn} and @code{.qn} directives, ARM 600@item @var{name} .dn @var{register name} [@var{.type}] [[@var{index}]] 601@itemx @var{name} .qn @var{register name} [@var{.type}] [[@var{index}]] 602 603The @code{dn} and @code{qn} directives are used to create typed 604and/or indexed register aliases for use in Advanced SIMD Extension 605(Neon) instructions. The former should be used to create aliases 606of double-precision registers, and the latter to create aliases of 607quad-precision registers. 608 609If these directives are used to create typed aliases, those aliases can 610be used in Neon instructions instead of writing types after the mnemonic 611or after each operand. For example: 612 613@smallexample 614 x .dn d2.f32 615 y .dn d3.f32 616 z .dn d4.f32[1] 617 vmul x,y,z 618@end smallexample 619 620This is equivalent to writing the following: 621 622@smallexample 623 vmul.f32 d2,d3,d4[1] 624@end smallexample 625 626Aliases created using @code{dn} or @code{qn} can be destroyed using 627@code{unreq}. 628 629@c EEEEEEEEEEEEEEEEEEEEEEEEEE 630 631@cindex @code{.eabi_attribute} directive, ARM 632@item .eabi_attribute @var{tag}, @var{value} 633Set the EABI object attribute @var{tag} to @var{value}. 634 635The @var{tag} is either an attribute number, or one of the following: 636@code{Tag_CPU_raw_name}, @code{Tag_CPU_name}, @code{Tag_CPU_arch}, 637@code{Tag_CPU_arch_profile}, @code{Tag_ARM_ISA_use}, 638@code{Tag_THUMB_ISA_use}, @code{Tag_FP_arch}, @code{Tag_WMMX_arch}, 639@code{Tag_Advanced_SIMD_arch}, @code{Tag_PCS_config}, 640@code{Tag_ABI_PCS_R9_use}, @code{Tag_ABI_PCS_RW_data}, 641@code{Tag_ABI_PCS_RO_data}, @code{Tag_ABI_PCS_GOT_use}, 642@code{Tag_ABI_PCS_wchar_t}, @code{Tag_ABI_FP_rounding}, 643@code{Tag_ABI_FP_denormal}, @code{Tag_ABI_FP_exceptions}, 644@code{Tag_ABI_FP_user_exceptions}, @code{Tag_ABI_FP_number_model}, 645@code{Tag_ABI_align_needed}, @code{Tag_ABI_align_preserved}, 646@code{Tag_ABI_enum_size}, @code{Tag_ABI_HardFP_use}, 647@code{Tag_ABI_VFP_args}, @code{Tag_ABI_WMMX_args}, 648@code{Tag_ABI_optimization_goals}, @code{Tag_ABI_FP_optimization_goals}, 649@code{Tag_compatibility}, @code{Tag_CPU_unaligned_access}, 650@code{Tag_FP_HP_extension}, @code{Tag_ABI_FP_16bit_format}, 651@code{Tag_MPextension_use}, @code{Tag_DIV_use}, 652@code{Tag_nodefaults}, @code{Tag_also_compatible_with}, 653@code{Tag_conformance}, @code{Tag_T2EE_use}, 654@code{Tag_Virtualization_use} 655 656The @var{value} is either a @code{number}, @code{"string"}, or 657@code{number, "string"} depending on the tag. 658 659Note - the following legacy values are also accepted by @var{tag}: 660@code{Tag_VFP_arch}, @code{Tag_ABI_align8_needed}, 661@code{Tag_ABI_align8_preserved}, @code{Tag_VFP_HP_extension}, 662 663@cindex @code{.even} directive, ARM 664@item .even 665This directive aligns to an even-numbered address. 666 667@cindex @code{.extend} directive, ARM 668@cindex @code{.ldouble} directive, ARM 669@item .extend @var{expression} [, @var{expression}]* 670@itemx .ldouble @var{expression} [, @var{expression}]* 671These directives write 12byte long double floating-point values to the 672output section. These are not compatible with current ARM processors 673or ABIs. 674 675@c FFFFFFFFFFFFFFFFFFFFFFFFFF 676 677@anchor{arm_fnend} 678@cindex @code{.fnend} directive, ARM 679@item .fnend 680Marks the end of a function with an unwind table entry. The unwind index 681table entry is created when this directive is processed. 682 683If no personality routine has been specified then standard personality 684routine 0 or 1 will be used, depending on the number of unwind opcodes 685required. 686 687@anchor{arm_fnstart} 688@cindex @code{.fnstart} directive, ARM 689@item .fnstart 690Marks the start of a function with an unwind table entry. 691 692@cindex @code{.force_thumb} directive, ARM 693@item .force_thumb 694This directive forces the selection of Thumb instructions, even if the 695target processor does not support those instructions 696 697@cindex @code{.fpu} directive, ARM 698@item .fpu @var{name} 699Select the floating-point unit to assemble for. Valid values for @var{name} 700are the same as for the @option{-mfpu} commandline option. 701 702@c GGGGGGGGGGGGGGGGGGGGGGGGGG 703@c HHHHHHHHHHHHHHHHHHHHHHHHHH 704 705@cindex @code{.handlerdata} directive, ARM 706@item .handlerdata 707Marks the end of the current function, and the start of the exception table 708entry for that function. Anything between this directive and the 709@code{.fnend} directive will be added to the exception table entry. 710 711Must be preceded by a @code{.personality} or @code{.personalityindex} 712directive. 713 714@c IIIIIIIIIIIIIIIIIIIIIIIIII 715 716@cindex @code{.inst} directive, ARM 717@item .inst @var{opcode} [ , @dots{} ] 718@itemx .inst.n @var{opcode} [ , @dots{} ] 719@itemx .inst.w @var{opcode} [ , @dots{} ] 720Generates the instruction corresponding to the numerical value @var{opcode}. 721@code{.inst.n} and @code{.inst.w} allow the Thumb instruction size to be 722specified explicitly, overriding the normal encoding rules. 723 724@c JJJJJJJJJJJJJJJJJJJJJJJJJJ 725@c KKKKKKKKKKKKKKKKKKKKKKKKKK 726@c LLLLLLLLLLLLLLLLLLLLLLLLLL 727 728@item .ldouble @var{expression} [, @var{expression}]* 729See @code{.extend}. 730 731@cindex @code{.ltorg} directive, ARM 732@item .ltorg 733This directive causes the current contents of the literal pool to be 734dumped into the current section (which is assumed to be the .text 735section) at the current location (aligned to a word boundary). 736@code{GAS} maintains a separate literal pool for each section and each 737sub-section. The @code{.ltorg} directive will only affect the literal 738pool of the current section and sub-section. At the end of assembly 739all remaining, un-empty literal pools will automatically be dumped. 740 741Note - older versions of @code{GAS} would dump the current literal 742pool any time a section change occurred. This is no longer done, since 743it prevents accurate control of the placement of literal pools. 744 745@c MMMMMMMMMMMMMMMMMMMMMMMMMM 746 747@cindex @code{.movsp} directive, ARM 748@item .movsp @var{reg} [, #@var{offset}] 749Tell the unwinder that @var{reg} contains an offset from the current 750stack pointer. If @var{offset} is not specified then it is assumed to be 751zero. 752 753@c NNNNNNNNNNNNNNNNNNNNNNNNNN 754@c OOOOOOOOOOOOOOOOOOOOOOOOOO 755 756@cindex @code{.object_arch} directive, ARM 757@item .object_arch @var{name} 758Override the architecture recorded in the EABI object attribute section. 759Valid values for @var{name} are the same as for the @code{.arch} directive. 760Typically this is useful when code uses runtime detection of CPU features. 761 762@c PPPPPPPPPPPPPPPPPPPPPPPPPP 763 764@cindex @code{.packed} directive, ARM 765@item .packed @var{expression} [, @var{expression}]* 766This directive writes 12-byte packed floating-point values to the 767output section. These are not compatible with current ARM processors 768or ABIs. 769 770@anchor{arm_pad} 771@cindex @code{.pad} directive, ARM 772@item .pad #@var{count} 773Generate unwinder annotations for a stack adjustment of @var{count} bytes. 774A positive value indicates the function prologue allocated stack space by 775decrementing the stack pointer. 776 777@cindex @code{.personality} directive, ARM 778@item .personality @var{name} 779Sets the personality routine for the current function to @var{name}. 780 781@cindex @code{.personalityindex} directive, ARM 782@item .personalityindex @var{index} 783Sets the personality routine for the current function to the EABI standard 784routine number @var{index} 785 786@cindex @code{.pool} directive, ARM 787@item .pool 788This is a synonym for .ltorg. 789 790@c QQQQQQQQQQQQQQQQQQQQQQQQQQ 791@c RRRRRRRRRRRRRRRRRRRRRRRRRR 792 793@cindex @code{.req} directive, ARM 794@item @var{name} .req @var{register name} 795This creates an alias for @var{register name} called @var{name}. For 796example: 797 798@smallexample 799 foo .req r0 800@end smallexample 801 802@c SSSSSSSSSSSSSSSSSSSSSSSSSS 803 804@anchor{arm_save} 805@cindex @code{.save} directive, ARM 806@item .save @var{reglist} 807Generate unwinder annotations to restore the registers in @var{reglist}. 808The format of @var{reglist} is the same as the corresponding store-multiple 809instruction. 810 811@smallexample 812@exdent @emph{core registers} 813 .save @{r4, r5, r6, lr@} 814 stmfd sp!, @{r4, r5, r6, lr@} 815@exdent @emph{FPA registers} 816 .save f4, 2 817 sfmfd f4, 2, [sp]! 818@exdent @emph{VFP registers} 819 .save @{d8, d9, d10@} 820 fstmdx sp!, @{d8, d9, d10@} 821@exdent @emph{iWMMXt registers} 822 .save @{wr10, wr11@} 823 wstrd wr11, [sp, #-8]! 824 wstrd wr10, [sp, #-8]! 825or 826 .save wr11 827 wstrd wr11, [sp, #-8]! 828 .save wr10 829 wstrd wr10, [sp, #-8]! 830@end smallexample 831 832@anchor{arm_setfp} 833@cindex @code{.setfp} directive, ARM 834@item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}] 835Make all unwinder annotations relative to a frame pointer. Without this 836the unwinder will use offsets from the stack pointer. 837 838The syntax of this directive is the same as the @code{add} or @code{mov} 839instruction used to set the frame pointer. @var{spreg} must be either 840@code{sp} or mentioned in a previous @code{.movsp} directive. 841 842@smallexample 843.movsp ip 844mov ip, sp 845@dots{} 846.setfp fp, ip, #4 847add fp, ip, #4 848@end smallexample 849 850@cindex @code{.secrel32} directive, ARM 851@item .secrel32 @var{expression} [, @var{expression}]* 852This directive emits relocations that evaluate to the section-relative 853offset of each expression's symbol. This directive is only supported 854for PE targets. 855 856@cindex @code{.syntax} directive, ARM 857@item .syntax [@code{unified} | @code{divided}] 858This directive sets the Instruction Set Syntax as described in the 859@ref{ARM-Instruction-Set} section. 860 861@c TTTTTTTTTTTTTTTTTTTTTTTTTT 862 863@cindex @code{.thumb} directive, ARM 864@item .thumb 865This performs the same action as @var{.code 16}. 866 867@cindex @code{.thumb_func} directive, ARM 868@item .thumb_func 869This directive specifies that the following symbol is the name of a 870Thumb encoded function. This information is necessary in order to allow 871the assembler and linker to generate correct code for interworking 872between Arm and Thumb instructions and should be used even if 873interworking is not going to be performed. The presence of this 874directive also implies @code{.thumb} 875 876This directive is not neccessary when generating EABI objects. On these 877targets the encoding is implicit when generating Thumb code. 878 879@cindex @code{.thumb_set} directive, ARM 880@item .thumb_set 881This performs the equivalent of a @code{.set} directive in that it 882creates a symbol which is an alias for another symbol (possibly not yet 883defined). This directive also has the added property in that it marks 884the aliased symbol as being a thumb function entry point, in the same 885way that the @code{.thumb_func} directive does. 886 887@cindex @code{.tlsdescseq} directive, ARM 888@item .tlsdescseq @var{tls-variable} 889This directive is used to annotate parts of an inlined TLS descriptor 890trampoline. Normally the trampoline is provided by the linker, and 891this directive is not needed. 892 893@c UUUUUUUUUUUUUUUUUUUUUUUUUU 894 895@cindex @code{.unreq} directive, ARM 896@item .unreq @var{alias-name} 897This undefines a register alias which was previously defined using the 898@code{req}, @code{dn} or @code{qn} directives. For example: 899 900@smallexample 901 foo .req r0 902 .unreq foo 903@end smallexample 904 905An error occurs if the name is undefined. Note - this pseudo op can 906be used to delete builtin in register name aliases (eg 'r0'). This 907should only be done if it is really necessary. 908 909@cindex @code{.unwind_raw} directive, ARM 910@item .unwind_raw @var{offset}, @var{byte1}, @dots{} 911Insert one of more arbitary unwind opcode bytes, which are known to adjust 912the stack pointer by @var{offset} bytes. 913 914For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to 915@code{.save @{r0@}} 916 917@c VVVVVVVVVVVVVVVVVVVVVVVVVV 918 919@cindex @code{.vsave} directive, ARM 920@item .vsave @var{vfp-reglist} 921Generate unwinder annotations to restore the VFP registers in @var{vfp-reglist} 922using FLDMD. Also works for VFPv3 registers 923that are to be restored using VLDM. 924The format of @var{vfp-reglist} is the same as the corresponding store-multiple 925instruction. 926 927@smallexample 928@exdent @emph{VFP registers} 929 .vsave @{d8, d9, d10@} 930 fstmdd sp!, @{d8, d9, d10@} 931@exdent @emph{VFPv3 registers} 932 .vsave @{d15, d16, d17@} 933 vstm sp!, @{d15, d16, d17@} 934@end smallexample 935 936Since FLDMX and FSTMX are now deprecated, this directive should be 937used in favour of @code{.save} for saving VFP registers for ARMv6 and above. 938 939@c WWWWWWWWWWWWWWWWWWWWWWWWWW 940@c XXXXXXXXXXXXXXXXXXXXXXXXXX 941@c YYYYYYYYYYYYYYYYYYYYYYYYYY 942@c ZZZZZZZZZZZZZZZZZZZZZZZZZZ 943 944@end table 945 946@node ARM Opcodes 947@section Opcodes 948 949@cindex ARM opcodes 950@cindex opcodes for ARM 951@code{@value{AS}} implements all the standard ARM opcodes. It also 952implements several pseudo opcodes, including several synthetic load 953instructions. 954 955@table @code 956 957@cindex @code{NOP} pseudo op, ARM 958@item NOP 959@smallexample 960 nop 961@end smallexample 962 963This pseudo op will always evaluate to a legal ARM instruction that does 964nothing. Currently it will evaluate to MOV r0, r0. 965 966@cindex @code{LDR reg,=<label>} pseudo op, ARM 967@item LDR 968@smallexample 969 ldr <register> , = <expression> 970@end smallexample 971 972If expression evaluates to a numeric constant then a MOV or MVN 973instruction will be used in place of the LDR instruction, if the 974constant can be generated by either of these instructions. Otherwise 975the constant will be placed into the nearest literal pool (if it not 976already there) and a PC relative LDR instruction will be generated. 977 978@cindex @code{ADR reg,<label>} pseudo op, ARM 979@item ADR 980@smallexample 981 adr <register> <label> 982@end smallexample 983 984This instruction will load the address of @var{label} into the indicated 985register. The instruction will evaluate to a PC relative ADD or SUB 986instruction depending upon where the label is located. If the label is 987out of range, or if it is not defined in the same file (and section) as 988the ADR instruction, then an error will be generated. This instruction 989will not make use of the literal pool. 990 991@cindex @code{ADRL reg,<label>} pseudo op, ARM 992@item ADRL 993@smallexample 994 adrl <register> <label> 995@end smallexample 996 997This instruction will load the address of @var{label} into the indicated 998register. The instruction will evaluate to one or two PC relative ADD 999or SUB instructions depending upon where the label is located. If a 1000second instruction is not needed a NOP instruction will be generated in 1001its place, so that this instruction is always 8 bytes long. 1002 1003If the label is out of range, or if it is not defined in the same file 1004(and section) as the ADRL instruction, then an error will be generated. 1005This instruction will not make use of the literal pool. 1006 1007@end table 1008 1009For information on the ARM or Thumb instruction sets, see @cite{ARM 1010Software Development Toolkit Reference Manual}, Advanced RISC Machines 1011Ltd. 1012 1013@node ARM Mapping Symbols 1014@section Mapping Symbols 1015 1016The ARM ELF specification requires that special symbols be inserted 1017into object files to mark certain features: 1018 1019@table @code 1020 1021@cindex @code{$a} 1022@item $a 1023At the start of a region of code containing ARM instructions. 1024 1025@cindex @code{$t} 1026@item $t 1027At the start of a region of code containing THUMB instructions. 1028 1029@cindex @code{$d} 1030@item $d 1031At the start of a region of data. 1032 1033@end table 1034 1035The assembler will automatically insert these symbols for you - there 1036is no need to code them yourself. Support for tagging symbols ($b, 1037$f, $p and $m) which is also mentioned in the current ARM ELF 1038specification is not implemented. This is because they have been 1039dropped from the new EABI and so tools cannot rely upon their 1040presence. 1041 1042@node ARM Unwinding Tutorial 1043@section Unwinding 1044 1045The ABI for the ARM Architecture specifies a standard format for 1046exception unwind information. This information is used when an 1047exception is thrown to determine where control should be transferred. 1048In particular, the unwind information is used to determine which 1049function called the function that threw the exception, and which 1050function called that one, and so forth. This information is also used 1051to restore the values of callee-saved registers in the function 1052catching the exception. 1053 1054If you are writing functions in assembly code, and those functions 1055call other functions that throw exceptions, you must use assembly 1056pseudo ops to ensure that appropriate exception unwind information is 1057generated. Otherwise, if one of the functions called by your assembly 1058code throws an exception, the run-time library will be unable to 1059unwind the stack through your assembly code and your program will not 1060behave correctly. 1061 1062To illustrate the use of these pseudo ops, we will examine the code 1063that G++ generates for the following C++ input: 1064 1065@verbatim 1066void callee (int *); 1067 1068int 1069caller () 1070{ 1071 int i; 1072 callee (&i); 1073 return i; 1074} 1075@end verbatim 1076 1077This example does not show how to throw or catch an exception from 1078assembly code. That is a much more complex operation and should 1079always be done in a high-level language, such as C++, that directly 1080supports exceptions. 1081 1082The code generated by one particular version of G++ when compiling the 1083example above is: 1084 1085@verbatim 1086_Z6callerv: 1087 .fnstart 1088.LFB2: 1089 @ Function supports interworking. 1090 @ args = 0, pretend = 0, frame = 8 1091 @ frame_needed = 1, uses_anonymous_args = 0 1092 stmfd sp!, {fp, lr} 1093 .save {fp, lr} 1094.LCFI0: 1095 .setfp fp, sp, #4 1096 add fp, sp, #4 1097.LCFI1: 1098 .pad #8 1099 sub sp, sp, #8 1100.LCFI2: 1101 sub r3, fp, #8 1102 mov r0, r3 1103 bl _Z6calleePi 1104 ldr r3, [fp, #-8] 1105 mov r0, r3 1106 sub sp, fp, #4 1107 ldmfd sp!, {fp, lr} 1108 bx lr 1109.LFE2: 1110 .fnend 1111@end verbatim 1112 1113Of course, the sequence of instructions varies based on the options 1114you pass to GCC and on the version of GCC in use. The exact 1115instructions are not important since we are focusing on the pseudo ops 1116that are used to generate unwind information. 1117 1118An important assumption made by the unwinder is that the stack frame 1119does not change during the body of the function. In particular, since 1120we assume that the assembly code does not itself throw an exception, 1121the only point where an exception can be thrown is from a call, such 1122as the @code{bl} instruction above. At each call site, the same saved 1123registers (including @code{lr}, which indicates the return address) 1124must be located in the same locations relative to the frame pointer. 1125 1126The @code{.fnstart} (@pxref{arm_fnstart,,.fnstart pseudo op}) pseudo 1127op appears immediately before the first instruction of the function 1128while the @code{.fnend} (@pxref{arm_fnend,,.fnend pseudo op}) pseudo 1129op appears immediately after the last instruction of the function. 1130These pseudo ops specify the range of the function. 1131 1132Only the order of the other pseudos ops (e.g., @code{.setfp} or 1133@code{.pad}) matters; their exact locations are irrelevant. In the 1134example above, the compiler emits the pseudo ops with particular 1135instructions. That makes it easier to understand the code, but it is 1136not required for correctness. It would work just as well to emit all 1137of the pseudo ops other than @code{.fnend} in the same order, but 1138immediately after @code{.fnstart}. 1139 1140The @code{.save} (@pxref{arm_save,,.save pseudo op}) pseudo op 1141indicates registers that have been saved to the stack so that they can 1142be restored before the function returns. The argument to the 1143@code{.save} pseudo op is a list of registers to save. If a register 1144is ``callee-saved'' (as specified by the ABI) and is modified by the 1145function you are writing, then your code must save the value before it 1146is modified and restore the original value before the function 1147returns. If an exception is thrown, the run-time library restores the 1148values of these registers from their locations on the stack before 1149returning control to the exception handler. (Of course, if an 1150exception is not thrown, the function that contains the @code{.save} 1151pseudo op restores these registers in the function epilogue, as is 1152done with the @code{ldmfd} instruction above.) 1153 1154You do not have to save callee-saved registers at the very beginning 1155of the function and you do not need to use the @code{.save} pseudo op 1156immediately following the point at which the registers are saved. 1157However, if you modify a callee-saved register, you must save it on 1158the stack before modifying it and before calling any functions which 1159might throw an exception. And, you must use the @code{.save} pseudo 1160op to indicate that you have done so. 1161 1162The @code{.pad} (@pxref{arm_pad,,.pad}) pseudo op indicates a 1163modification of the stack pointer that does not save any registers. 1164The argument is the number of bytes (in decimal) that are subtracted 1165from the stack pointer. (On ARM CPUs, the stack grows downwards, so 1166subtracting from the stack pointer increases the size of the stack.) 1167 1168The @code{.setfp} (@pxref{arm_setfp,,.setfp pseudo op}) pseudo op 1169indicates the register that contains the frame pointer. The first 1170argument is the register that is set, which is typically @code{fp}. 1171The second argument indicates the register from which the frame 1172pointer takes its value. The third argument, if present, is the value 1173(in decimal) added to the register specified by the second argument to 1174compute the value of the frame pointer. You should not modify the 1175frame pointer in the body of the function. 1176 1177If you do not use a frame pointer, then you should not use the 1178@code{.setfp} pseudo op. If you do not use a frame pointer, then you 1179should avoid modifying the stack pointer outside of the function 1180prologue. Otherwise, the run-time library will be unable to find 1181saved registers when it is unwinding the stack. 1182 1183The pseudo ops described above are sufficient for writing assembly 1184code that calls functions which may throw exceptions. If you need to 1185know more about the object-file format used to represent unwind 1186information, you may consult the @cite{Exception Handling ABI for the 1187ARM Architecture} available from @uref{http://infocenter.arm.com}. 1188