c-arm.texi revision 256281
1@c Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 2@c Free Software Foundation, Inc. 3@c This is part of the GAS manual. 4@c For copying conditions, see the file as.texinfo. 5 6@ifset GENERIC 7@page 8@node ARM-Dependent 9@chapter ARM Dependent Features 10@end ifset 11 12@ifclear GENERIC 13@node Machine Dependencies 14@chapter ARM Dependent Features 15@end ifclear 16 17@cindex ARM support 18@cindex Thumb support 19@menu 20* ARM Options:: Options 21* ARM Syntax:: Syntax 22* ARM Floating Point:: Floating Point 23* ARM Directives:: ARM Machine Directives 24* ARM Opcodes:: Opcodes 25* ARM Mapping Symbols:: Mapping Symbols 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{arm9e}, 85@code{arm926e}, 86@code{arm926ej-s}, 87@code{arm946e-r0}, 88@code{arm946e}, 89@code{arm946e-s}, 90@code{arm966e-r0}, 91@code{arm966e}, 92@code{arm966e-s}, 93@code{arm968e-s}, 94@code{arm10t}, 95@code{arm10tdmi}, 96@code{arm10e}, 97@code{arm1020}, 98@code{arm1020t}, 99@code{arm1020e}, 100@code{arm1022e}, 101@code{arm1026ej-s}, 102@code{arm1136j-s}, 103@code{arm1136jf-s}, 104@code{arm1156t2-s}, 105@code{arm1156t2f-s}, 106@code{arm1176jz-s}, 107@code{arm1176jzf-s}, 108@code{mpcore}, 109@code{mpcorenovfp}, 110@code{cortex-a8}, 111@code{cortex-r4}, 112@code{cortex-m3}, 113@code{ep9312} (ARM920 with Cirrus Maverick coprocessor), 114@code{i80200} (Intel XScale processor) 115@code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) 116and 117@code{xscale}. 118The special name @code{all} may be used to allow the 119assembler to accept instructions valid for any ARM processor. 120 121In addition to the basic instruction set, the assembler can be told to 122accept various extension mnemonics that extend the processor using the 123co-processor instruction space. For example, @code{-mcpu=arm920+maverick} 124is equivalent to specifying @code{-mcpu=ep9312}. The following extensions 125are currently supported: 126@code{+maverick} 127@code{+iwmmxt} 128and 129@code{+xscale}. 130 131@cindex @code{-march=} command line option, ARM 132@item -march=@var{architecture}[+@var{extension}@dots{}] 133This option specifies the target architecture. The assembler will issue 134an error message if an attempt is made to assemble an instruction which 135will not execute on the target architecture. The following architecture 136names are recognized: 137@code{armv1}, 138@code{armv2}, 139@code{armv2a}, 140@code{armv2s}, 141@code{armv3}, 142@code{armv3m}, 143@code{armv4}, 144@code{armv4xm}, 145@code{armv4t}, 146@code{armv4txm}, 147@code{armv5}, 148@code{armv5t}, 149@code{armv5txm}, 150@code{armv5te}, 151@code{armv5texp}, 152@code{armv6}, 153@code{armv6j}, 154@code{armv6k}, 155@code{armv6z}, 156@code{armv6zk}, 157@code{armv7}, 158@code{armv7-a}, 159@code{armv7-r}, 160@code{armv7-m}, 161@code{iwmmxt} 162and 163@code{xscale}. 164If both @code{-mcpu} and 165@code{-march} are specified, the assembler will use 166the setting for @code{-mcpu}. 167 168The architecture option can be extended with the same instruction set 169extension options as the @code{-mcpu} option. 170 171@cindex @code{-mfpu=} command line option, ARM 172@item -mfpu=@var{floating-point-format} 173 174This option specifies the floating point format to assemble for. The 175assembler will issue an error message if an attempt is made to assemble 176an instruction which will not execute on the target floating point unit. 177The following format options are recognized: 178@code{softfpa}, 179@code{fpe}, 180@code{fpe2}, 181@code{fpe3}, 182@code{fpa}, 183@code{fpa10}, 184@code{fpa11}, 185@code{arm7500fe}, 186@code{softvfp}, 187@code{softvfp+vfp}, 188@code{vfp}, 189@code{vfp10}, 190@code{vfp10-r0}, 191@code{vfp9}, 192@code{vfpxd}, 193@code{arm1020t}, 194@code{arm1020e}, 195@code{arm1136jf-s} 196and 197@code{maverick}. 198 199In addition to determining which instructions are assembled, this option 200also affects the way in which the @code{.double} assembler directive behaves 201when assembling little-endian code. 202 203The default is dependent on the processor selected. For Architecture 5 or 204later, the default is to assembler for VFP instructions; for earlier 205architectures the default is to assemble for FPA instructions. 206 207@cindex @code{-mthumb} command line option, ARM 208@item -mthumb 209This option specifies that the assembler should start assembling Thumb 210instructions; that is, it should behave as though the file starts with a 211@code{.code 16} directive. 212 213@cindex @code{-mthumb-interwork} command line option, ARM 214@item -mthumb-interwork 215This option specifies that the output generated by the assembler should 216be marked as supporting interworking. 217 218@cindex @code{-mapcs} command line option, ARM 219@item -mapcs @code{[26|32]} 220This option specifies that the output generated by the assembler should 221be marked as supporting the indicated version of the Arm Procedure. 222Calling Standard. 223 224@cindex @code{-matpcs} command line option, ARM 225@item -matpcs 226This option specifies that the output generated by the assembler should 227be marked as supporting the Arm/Thumb Procedure Calling Standard. If 228enabled this option will cause the assembler to create an empty 229debugging section in the object file called .arm.atpcs. Debuggers can 230use this to determine the ABI being used by. 231 232@cindex @code{-mapcs-float} command line option, ARM 233@item -mapcs-float 234This indicates the floating point variant of the APCS should be 235used. In this variant floating point arguments are passed in FP 236registers rather than integer registers. 237 238@cindex @code{-mapcs-reentrant} command line option, ARM 239@item -mapcs-reentrant 240This indicates that the reentrant variant of the APCS should be used. 241This variant supports position independent code. 242 243@cindex @code{-mfloat-abi=} command line option, ARM 244@item -mfloat-abi=@var{abi} 245This option specifies that the output generated by the assembler should be 246marked as using specified floating point ABI. 247The following values are recognized: 248@code{soft}, 249@code{softfp} 250and 251@code{hard}. 252 253@cindex @code{-eabi=} command line option, ARM 254@item -meabi=@var{ver} 255This option specifies which EABI version the produced object files should 256conform to. 257The following values are recognized: 258@code{gnu}, 259@code{4} 260and 261@code{5}. 262 263@cindex @code{-EB} command line option, ARM 264@item -EB 265This option specifies that the output generated by the assembler should 266be marked as being encoded for a big-endian processor. 267 268@cindex @code{-EL} command line option, ARM 269@item -EL 270This option specifies that the output generated by the assembler should 271be marked as being encoded for a little-endian processor. 272 273@cindex @code{-k} command line option, ARM 274@cindex PIC code generation for ARM 275@item -k 276This option specifies that the output of the assembler should be marked 277as position-independent code (PIC). 278 279@end table 280 281 282@node ARM Syntax 283@section Syntax 284@menu 285* ARM-Chars:: Special Characters 286* ARM-Regs:: Register Names 287* ARM-Relocations:: Relocations 288@end menu 289 290@node ARM-Chars 291@subsection Special Characters 292 293@cindex line comment character, ARM 294@cindex ARM line comment character 295The presence of a @samp{@@} on a line indicates the start of a comment 296that extends to the end of the current line. If a @samp{#} appears as 297the first character of a line, the whole line is treated as a comment. 298 299@cindex line separator, ARM 300@cindex statement separator, ARM 301@cindex ARM line separator 302The @samp{;} character can be used instead of a newline to separate 303statements. 304 305@cindex immediate character, ARM 306@cindex ARM immediate character 307Either @samp{#} or @samp{$} can be used to indicate immediate operands. 308 309@cindex identifiers, ARM 310@cindex ARM identifiers 311*TODO* Explain about /data modifier on symbols. 312 313@node ARM-Regs 314@subsection Register Names 315 316@cindex ARM register names 317@cindex register names, ARM 318*TODO* Explain about ARM register naming, and the predefined names. 319 320@node ARM Floating Point 321@section Floating Point 322 323@cindex floating point, ARM (@sc{ieee}) 324@cindex ARM floating point (@sc{ieee}) 325The ARM family uses @sc{ieee} floating-point numbers. 326 327@node ARM-Relocations 328@subsection ARM relocation generation 329 330@cindex data relocations, ARM 331@cindex ARM data relocations 332Specific data relocations can be generated by putting the relocation name 333in parentheses after the symbol name. For example: 334 335@smallexample 336 .word foo(TARGET1) 337@end smallexample 338 339This will generate an @samp{R_ARM_TARGET1} relocation against the symbol 340@var{foo}. 341The following relocations are supported: 342@code{GOT}, 343@code{GOTOFF}, 344@code{TARGET1}, 345@code{TARGET2}, 346@code{SBREL}, 347@code{TLSGD}, 348@code{TLSLDM}, 349@code{TLSLDO}, 350@code{GOTTPOFF} 351and 352@code{TPOFF}. 353 354For compatibility with older toolchains the assembler also accepts 355@code{(PLT)} after branch targets. This will generate the deprecated 356@samp{R_ARM_PLT32} relocation. 357 358@cindex MOVW and MOVT relocations, ARM 359Relocations for @samp{MOVW} and @samp{MOVT} instructions can be generated 360by prefixing the value with @samp{#:lower16:} and @samp{#:upper16} 361respectively. For example to load the 32-bit address of foo into r0: 362 363@smallexample 364 MOVW r0, #:lower16:foo 365 MOVT r0, #:upper16:foo 366@end smallexample 367 368@node ARM Directives 369@section ARM Machine Directives 370 371@cindex machine directives, ARM 372@cindex ARM machine directives 373@table @code 374 375@cindex @code{align} directive, ARM 376@item .align @var{expression} [, @var{expression}] 377This is the generic @var{.align} directive. For the ARM however if the 378first argument is zero (ie no alignment is needed) the assembler will 379behave as if the argument had been 2 (ie pad to the next four byte 380boundary). This is for compatibility with ARM's own assembler. 381 382@cindex @code{req} directive, ARM 383@item @var{name} .req @var{register name} 384This creates an alias for @var{register name} called @var{name}. For 385example: 386 387@smallexample 388 foo .req r0 389@end smallexample 390 391@cindex @code{unreq} directive, ARM 392@item .unreq @var{alias-name} 393This undefines a register alias which was previously defined using the 394@code{req}, @code{dn} or @code{qn} directives. For example: 395 396@smallexample 397 foo .req r0 398 .unreq foo 399@end smallexample 400 401An error occurs if the name is undefined. Note - this pseudo op can 402be used to delete builtin in register name aliases (eg 'r0'). This 403should only be done if it is really necessary. 404 405@cindex @code{dn} and @code{qn} directives, ARM 406@item @var{name} .dn @var{register name} [@var{.type}] [@var{[index]}] 407@item @var{name} .qn @var{register name} [@var{.type}] [@var{[index]}] 408 409The @code{dn} and @code{qn} directives are used to create typed 410and/or indexed register aliases for use in Advanced SIMD Extension 411(Neon) instructions. The former should be used to create aliases 412of double-precision registers, and the latter to create aliases of 413quad-precision registers. 414 415If these directives are used to create typed aliases, those aliases can 416be used in Neon instructions instead of writing types after the mnemonic 417or after each operand. For example: 418 419@smallexample 420 x .dn d2.f32 421 y .dn d3.f32 422 z .dn d4.f32[1] 423 vmul x,y,z 424@end smallexample 425 426This is equivalent to writing the following: 427 428@smallexample 429 vmul.f32 d2,d3,d4[1] 430@end smallexample 431 432Aliases created using @code{dn} or @code{qn} can be destroyed using 433@code{unreq}. 434 435@cindex @code{code} directive, ARM 436@item .code @code{[16|32]} 437This directive selects the instruction set being generated. The value 16 438selects Thumb, with the value 32 selecting ARM. 439 440@cindex @code{thumb} directive, ARM 441@item .thumb 442This performs the same action as @var{.code 16}. 443 444@cindex @code{arm} directive, ARM 445@item .arm 446This performs the same action as @var{.code 32}. 447 448@cindex @code{force_thumb} directive, ARM 449@item .force_thumb 450This directive forces the selection of Thumb instructions, even if the 451target processor does not support those instructions 452 453@cindex @code{thumb_func} directive, ARM 454@item .thumb_func 455This directive specifies that the following symbol is the name of a 456Thumb encoded function. This information is necessary in order to allow 457the assembler and linker to generate correct code for interworking 458between Arm and Thumb instructions and should be used even if 459interworking is not going to be performed. The presence of this 460directive also implies @code{.thumb} 461 462This directive is not neccessary when generating EABI objects. On these 463targets the encoding is implicit when generating Thumb code. 464 465@cindex @code{thumb_set} directive, ARM 466@item .thumb_set 467This performs the equivalent of a @code{.set} directive in that it 468creates a symbol which is an alias for another symbol (possibly not yet 469defined). This directive also has the added property in that it marks 470the aliased symbol as being a thumb function entry point, in the same 471way that the @code{.thumb_func} directive does. 472 473@cindex @code{.ltorg} directive, ARM 474@item .ltorg 475This directive causes the current contents of the literal pool to be 476dumped into the current section (which is assumed to be the .text 477section) at the current location (aligned to a word boundary). 478@code{GAS} maintains a separate literal pool for each section and each 479sub-section. The @code{.ltorg} directive will only affect the literal 480pool of the current section and sub-section. At the end of assembly 481all remaining, un-empty literal pools will automatically be dumped. 482 483Note - older versions of @code{GAS} would dump the current literal 484pool any time a section change occurred. This is no longer done, since 485it prevents accurate control of the placement of literal pools. 486 487@cindex @code{.pool} directive, ARM 488@item .pool 489This is a synonym for .ltorg. 490 491@cindex @code{.fnstart} directive, ARM 492@item .unwind_fnstart 493Marks the start of a function with an unwind table entry. 494 495@cindex @code{.fnend} directive, ARM 496@item .unwind_fnend 497Marks the end of a function with an unwind table entry. The unwind index 498table entry is created when this directive is processed. 499 500If no personality routine has been specified then standard personality 501routine 0 or 1 will be used, depending on the number of unwind opcodes 502required. 503 504@cindex @code{.cantunwind} directive, ARM 505@item .cantunwind 506Prevents unwinding through the current function. No personality routine 507or exception table data is required or permitted. 508 509@cindex @code{.personality} directive, ARM 510@item .personality @var{name} 511Sets the personality routine for the current function to @var{name}. 512 513@cindex @code{.personalityindex} directive, ARM 514@item .personalityindex @var{index} 515Sets the personality routine for the current function to the EABI standard 516routine number @var{index} 517 518@cindex @code{.handlerdata} directive, ARM 519@item .handlerdata 520Marks the end of the current function, and the start of the exception table 521entry for that function. Anything between this directive and the 522@code{.fnend} directive will be added to the exception table entry. 523 524Must be preceded by a @code{.personality} or @code{.personalityindex} 525directive. 526 527@cindex @code{.save} directive, ARM 528@item .save @var{reglist} 529Generate unwinder annotations to restore the registers in @var{reglist}. 530The format of @var{reglist} is the same as the corresponding store-multiple 531instruction. 532 533@smallexample 534@exdent @emph{core registers} 535 .save @{r4, r5, r6, lr@} 536 stmfd sp!, @{r4, r5, r6, lr@} 537@exdent @emph{FPA registers} 538 .save f4, 2 539 sfmfd f4, 2, [sp]! 540@exdent @emph{VFP registers} 541 .save @{d8, d9, d10@} 542 fstmdx sp!, @{d8, d9, d10@} 543@exdent @emph{iWMMXt registers} 544 .save @{wr10, wr11@} 545 wstrd wr11, [sp, #-8]! 546 wstrd wr10, [sp, #-8]! 547or 548 .save wr11 549 wstrd wr11, [sp, #-8]! 550 .save wr10 551 wstrd wr10, [sp, #-8]! 552@end smallexample 553 554@cindex @code{.vsave} directive, ARM 555@item .vsave @var{vfp-reglist} 556Generate unwinder annotations to restore the VFP registers in @var{vfp-reglist} 557using FLDMD. Also works for VFPv3 registers 558that are to be restored using VLDM. 559The format of @var{vfp-reglist} is the same as the corresponding store-multiple 560instruction. 561 562@smallexample 563@exdent @emph{VFP registers} 564 .vsave @{d8, d9, d10@} 565 fstmdd sp!, @{d8, d9, d10@} 566@exdent @emph{VFPv3 registers} 567 .vsave @{d15, d16, d17@} 568 vstm sp!, @{d15, d16, d17@} 569@end smallexample 570 571Since FLDMX and FSTMX are now deprecated, this directive should be 572used in favour of @code{.save} for saving VFP registers for ARMv6 and above. 573 574@cindex @code{.pad} directive, ARM 575@item .pad #@var{count} 576Generate unwinder annotations for a stack adjustment of @var{count} bytes. 577A positive value indicates the function prologue allocated stack space by 578decrementing the stack pointer. 579 580@cindex @code{.movsp} directive, ARM 581@item .movsp @var{reg} [, #@var{offset}] 582Tell the unwinder that @var{reg} contains an offset from the current 583stack pointer. If @var{offset} is not specified then it is assumed to be 584zero. 585 586@cindex @code{.setfp} directive, ARM 587@item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}] 588Make all unwinder annotations relaive to a frame pointer. Without this 589the unwinder will use offsets from the stack pointer. 590 591The syntax of this directive is the same as the @code{sub} or @code{mov} 592instruction used to set the frame pointer. @var{spreg} must be either 593@code{sp} or mentioned in a previous @code{.movsp} directive. 594 595@smallexample 596.movsp ip 597mov ip, sp 598@dots{} 599.setfp fp, ip, #4 600sub fp, ip, #4 601@end smallexample 602 603@cindex @code{.unwind_raw} directive, ARM 604@item .raw @var{offset}, @var{byte1}, @dots{} 605Insert one of more arbitary unwind opcode bytes, which are known to adjust 606the stack pointer by @var{offset} bytes. 607 608For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to 609@code{.save @{r0@}} 610 611@cindex @code{.cpu} directive, ARM 612@item .cpu @var{name} 613Select the target processor. Valid values for @var{name} are the same as 614for the @option{-mcpu} commandline option. 615 616@cindex @code{.arch} directive, ARM 617@item .arch @var{name} 618Select the target architecture. Valid values for @var{name} are the same as 619for the @option{-march} commandline option. 620 621@cindex @code{.object_arch} directive, ARM 622@item .object_arch @var{name} 623Override the architecture recorded in the EABI object attribute section. 624Valid values for @var{name} are the same as for the @code{.arch} directive. 625Typically this is useful when code uses runtime detection of CPU features. 626 627@cindex @code{.fpu} directive, ARM 628@item .fpu @var{name} 629Select the floating point unit to assemble for. Valid values for @var{name} 630are the same as for the @option{-mfpu} commandline option. 631 632@cindex @code{.eabi_attribute} directive, ARM 633@item .eabi_attribute @var{tag}, @var{value} 634Set the EABI object attribute number @var{tag} to @var{value}. The value 635is either a @code{number}, @code{"string"}, or @code{number, "string"} 636depending on the tag. 637 638@end table 639 640@node ARM Opcodes 641@section Opcodes 642 643@cindex ARM opcodes 644@cindex opcodes for ARM 645@code{@value{AS}} implements all the standard ARM opcodes. It also 646implements several pseudo opcodes, including several synthetic load 647instructions. 648 649@table @code 650 651@cindex @code{NOP} pseudo op, ARM 652@item NOP 653@smallexample 654 nop 655@end smallexample 656 657This pseudo op will always evaluate to a legal ARM instruction that does 658nothing. Currently it will evaluate to MOV r0, r0. 659 660@cindex @code{LDR reg,=<label>} pseudo op, ARM 661@item LDR 662@smallexample 663 ldr <register> , = <expression> 664@end smallexample 665 666If expression evaluates to a numeric constant then a MOV or MVN 667instruction will be used in place of the LDR instruction, if the 668constant can be generated by either of these instructions. Otherwise 669the constant will be placed into the nearest literal pool (if it not 670already there) and a PC relative LDR instruction will be generated. 671 672@cindex @code{ADR reg,<label>} pseudo op, ARM 673@item ADR 674@smallexample 675 adr <register> <label> 676@end smallexample 677 678This instruction will load the address of @var{label} into the indicated 679register. The instruction will evaluate to a PC relative ADD or SUB 680instruction depending upon where the label is located. If the label is 681out of range, or if it is not defined in the same file (and section) as 682the ADR instruction, then an error will be generated. This instruction 683will not make use of the literal pool. 684 685@cindex @code{ADRL reg,<label>} pseudo op, ARM 686@item ADRL 687@smallexample 688 adrl <register> <label> 689@end smallexample 690 691This instruction will load the address of @var{label} into the indicated 692register. The instruction will evaluate to one or two PC relative ADD 693or SUB instructions depending upon where the label is located. If a 694second instruction is not needed a NOP instruction will be generated in 695its place, so that this instruction is always 8 bytes long. 696 697If the label is out of range, or if it is not defined in the same file 698(and section) as the ADRL instruction, then an error will be generated. 699This instruction will not make use of the literal pool. 700 701@end table 702 703For information on the ARM or Thumb instruction sets, see @cite{ARM 704Software Development Toolkit Reference Manual}, Advanced RISC Machines 705Ltd. 706 707@node ARM Mapping Symbols 708@section Mapping Symbols 709 710The ARM ELF specification requires that special symbols be inserted 711into object files to mark certain features: 712 713@table @code 714 715@cindex @code{$a} 716@item $a 717At the start of a region of code containing ARM instructions. 718 719@cindex @code{$t} 720@item $t 721At the start of a region of code containing THUMB instructions. 722 723@cindex @code{$d} 724@item $d 725At the start of a region of data. 726 727@end table 728 729The assembler will automatically insert these symbols for you - there 730is no need to code them yourself. Support for tagging symbols ($b, 731$f, $p and $m) which is also mentioned in the current ARM ELF 732specification is not implemented. This is because they have been 733dropped from the new EABI and so tools cannot rely upon their 734presence. 735 736