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{arm966e-r0}, 90@code{arm966e}, 91@code{arm10t}, 92@code{arm10e}, 93@code{arm1020}, 94@code{arm1020t}, 95@code{arm1020e}, 96@code{arm1026ej-s}, 97@code{arm1136j-s}, 98@code{arm1136jf-s}, 99@code{arm1176jz-s}, 100@code{arm1176jzf-s}, 101@code{mpcore}, 102@code{mpcorenovfp}, 103@code{ep9312} (ARM920 with Cirrus Maverick coprocessor), 104@code{i80200} (Intel XScale processor) 105@code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) 106and 107@code{xscale}. 108The special name @code{all} may be used to allow the 109assembler to accept instructions valid for any ARM processor. 110 111In addition to the basic instruction set, the assembler can be told to 112accept various extension mnemonics that extend the processor using the 113co-processor instruction space. For example, @code{-mcpu=arm920+maverick} 114is equivalent to specifying @code{-mcpu=ep9312}. The following extensions 115are currently supported: 116@code{+maverick} 117@code{+iwmmxt} 118and 119@code{+xscale}. 120 121@cindex @code{-march=} command line option, ARM 122@item -march=@var{architecture}[+@var{extension}@dots{}] 123This option specifies the target architecture. The assembler will issue 124an error message if an attempt is made to assemble an instruction which 125will not execute on the target architecture. The following architecture 126names are recognized: 127@code{armv1}, 128@code{armv2}, 129@code{armv2a}, 130@code{armv2s}, 131@code{armv3}, 132@code{armv3m}, 133@code{armv4}, 134@code{armv4xm}, 135@code{armv4t}, 136@code{armv4txm}, 137@code{armv5}, 138@code{armv5t}, 139@code{armv5txm}, 140@code{armv5te}, 141@code{armv5texp}, 142@code{armv6}, 143@code{armv6j}, 144@code{armv6k}, 145@code{armv6z}, 146@code{armv6zk}, 147@code{iwmmxt} 148and 149@code{xscale}. 150If both @code{-mcpu} and 151@code{-march} are specified, the assembler will use 152the setting for @code{-mcpu}. 153 154The architecture option can be extended with the same instruction set 155extension options as the @code{-mcpu} option. 156 157@cindex @code{-mfpu=} command line option, ARM 158@item -mfpu=@var{floating-point-format} 159 160This option specifies the floating point format to assemble for. The 161assembler will issue an error message if an attempt is made to assemble 162an instruction which will not execute on the target floating point unit. 163The following format options are recognized: 164@code{softfpa}, 165@code{fpe}, 166@code{fpe2}, 167@code{fpe3}, 168@code{fpa}, 169@code{fpa10}, 170@code{fpa11}, 171@code{arm7500fe}, 172@code{softvfp}, 173@code{softvfp+vfp}, 174@code{vfp}, 175@code{vfp10}, 176@code{vfp10-r0}, 177@code{vfp9}, 178@code{vfpxd}, 179@code{arm1020t}, 180@code{arm1020e}, 181@code{arm1136jf-s} 182and 183@code{maverick}. 184 185In addition to determining which instructions are assembled, this option 186also affects the way in which the @code{.double} assembler directive behaves 187when assembling little-endian code. 188 189The default is dependent on the processor selected. For Architecture 5 or 190later, the default is to assembler for VFP instructions; for earlier 191architectures the default is to assemble for FPA instructions. 192 193@cindex @code{-mthumb} command line option, ARM 194@item -mthumb 195This option specifies that the assembler should start assembling Thumb 196instructions; that is, it should behave as though the file starts with a 197@code{.code 16} directive. 198 199@cindex @code{-mthumb-interwork} command line option, ARM 200@item -mthumb-interwork 201This option specifies that the output generated by the assembler should 202be marked as supporting interworking. 203 204@cindex @code{-mapcs} command line option, ARM 205@item -mapcs @code{[26|32]} 206This option specifies that the output generated by the assembler should 207be marked as supporting the indicated version of the Arm Procedure. 208Calling Standard. 209 210@cindex @code{-matpcs} command line option, ARM 211@item -matpcs 212This option specifies that the output generated by the assembler should 213be marked as supporting the Arm/Thumb Procedure Calling Standard. If 214enabled this option will cause the assembler to create an empty 215debugging section in the object file called .arm.atpcs. Debuggers can 216use this to determine the ABI being used by. 217 218@cindex @code{-mapcs-float} command line option, ARM 219@item -mapcs-float 220This indicates the floating point variant of the APCS should be 221used. In this variant floating point arguments are passed in FP 222registers rather than integer registers. 223 224@cindex @code{-mapcs-reentrant} command line option, ARM 225@item -mapcs-reentrant 226This indicates that the reentrant variant of the APCS should be used. 227This variant supports position independent code. 228 229@cindex @code{-mfloat-abi=} command line option, ARM 230@item -mfloat-abi=@var{abi} 231This option specifies that the output generated by the assembler should be 232marked as using specified floating point ABI. 233The following values are recognized: 234@code{soft}, 235@code{softfp} 236and 237@code{hard}. 238 239@cindex @code{-eabi=} command line option, ARM 240@item -meabi=@var{ver} 241This option specifies which EABI version the produced object files should 242conform to. 243The following values are recognised: 244@code{gnu} 245and 246@code{4}. 247 248@cindex @code{-EB} command line option, ARM 249@item -EB 250This option specifies that the output generated by the assembler should 251be marked as being encoded for a big-endian processor. 252 253@cindex @code{-EL} command line option, ARM 254@item -EL 255This option specifies that the output generated by the assembler should 256be marked as being encoded for a little-endian processor. 257 258@cindex @code{-k} command line option, ARM 259@cindex PIC code generation for ARM 260@item -k 261This option specifies that the output of the assembler should be marked 262as position-independent code (PIC). 263 264@end table 265 266 267@node ARM Syntax 268@section Syntax 269@menu 270* ARM-Chars:: Special Characters 271* ARM-Regs:: Register Names 272@end menu 273 274@node ARM-Chars 275@subsection Special Characters 276 277@cindex line comment character, ARM 278@cindex ARM line comment character 279The presence of a @samp{@@} on a line indicates the start of a comment 280that extends to the end of the current line. If a @samp{#} appears as 281the first character of a line, the whole line is treated as a comment. 282 283@cindex line separator, ARM 284@cindex statement separator, ARM 285@cindex ARM line separator 286The @samp{;} character can be used instead of a newline to separate 287statements. 288 289@cindex immediate character, ARM 290@cindex ARM immediate character 291Either @samp{#} or @samp{$} can be used to indicate immediate operands. 292 293@cindex identifiers, ARM 294@cindex ARM identifiers 295*TODO* Explain about /data modifier on symbols. 296 297@node ARM-Regs 298@subsection Register Names 299 300@cindex ARM register names 301@cindex register names, ARM 302*TODO* Explain about ARM register naming, and the predefined names. 303 304@node ARM Floating Point 305@section Floating Point 306 307@cindex floating point, ARM (@sc{ieee}) 308@cindex ARM floating point (@sc{ieee}) 309The ARM family uses @sc{ieee} floating-point numbers. 310 311 312 313@node ARM Directives 314@section ARM Machine Directives 315 316@cindex machine directives, ARM 317@cindex ARM machine directives 318@table @code 319 320@cindex @code{align} directive, ARM 321@item .align @var{expression} [, @var{expression}] 322This is the generic @var{.align} directive. For the ARM however if the 323first argument is zero (ie no alignment is needed) the assembler will 324behave as if the argument had been 2 (ie pad to the next four byte 325boundary). This is for compatibility with ARM's own assembler. 326 327@cindex @code{req} directive, ARM 328@item @var{name} .req @var{register name} 329This creates an alias for @var{register name} called @var{name}. For 330example: 331 332@smallexample 333 foo .req r0 334@end smallexample 335 336@cindex @code{unreq} directive, ARM 337@item .unreq @var{alias-name} 338This undefines a register alias which was previously defined using the 339@code{req} directive. For example: 340 341@smallexample 342 foo .req r0 343 .unreq foo 344@end smallexample 345 346An error occurs if the name is undefined. Note - this pseudo op can 347be used to delete builtin in register name aliases (eg 'r0'). This 348should only be done if it is really necessary. 349 350@cindex @code{code} directive, ARM 351@item .code @code{[16|32]} 352This directive selects the instruction set being generated. The value 16 353selects Thumb, with the value 32 selecting ARM. 354 355@cindex @code{thumb} directive, ARM 356@item .thumb 357This performs the same action as @var{.code 16}. 358 359@cindex @code{arm} directive, ARM 360@item .arm 361This performs the same action as @var{.code 32}. 362 363@cindex @code{force_thumb} directive, ARM 364@item .force_thumb 365This directive forces the selection of Thumb instructions, even if the 366target processor does not support those instructions 367 368@cindex @code{thumb_func} directive, ARM 369@item .thumb_func 370This directive specifies that the following symbol is the name of a 371Thumb encoded function. This information is necessary in order to allow 372the assembler and linker to generate correct code for interworking 373between Arm and Thumb instructions and should be used even if 374interworking is not going to be performed. The presence of this 375directive also implies @code{.thumb} 376 377@cindex @code{thumb_set} directive, ARM 378@item .thumb_set 379This performs the equivalent of a @code{.set} directive in that it 380creates a symbol which is an alias for another symbol (possibly not yet 381defined). This directive also has the added property in that it marks 382the aliased symbol as being a thumb function entry point, in the same 383way that the @code{.thumb_func} directive does. 384 385@cindex @code{.ltorg} directive, ARM 386@item .ltorg 387This directive causes the current contents of the literal pool to be 388dumped into the current section (which is assumed to be the .text 389section) at the current location (aligned to a word boundary). 390@code{GAS} maintains a separate literal pool for each section and each 391sub-section. The @code{.ltorg} directive will only affect the literal 392pool of the current section and sub-section. At the end of assembly 393all remaining, un-empty literal pools will automatically be dumped. 394 395Note - older versions of @code{GAS} would dump the current literal 396pool any time a section change occurred. This is no longer done, since 397it prevents accurate control of the placement of literal pools. 398 399@cindex @code{.pool} directive, ARM 400@item .pool 401This is a synonym for .ltorg. 402 403@cindex @code{.fnstart} directive, ARM 404@item .unwind_fnstart 405Marks the start of a function with an unwind table entry. 406 407@cindex @code{.fnend} directive, ARM 408@item .unwind_fnend 409Marks the end of a function with an unwind table entry. The unwind index 410table entry is created when this directive is processed. 411 412If no personality routine has been specified then standard personality 413routine 0 or 1 will be used, depending on the number of unwind opcodes 414required. 415 416@cindex @code{.cantunwind} directive, ARM 417@item .cantunwind 418Prevents unwinding through the current function. No personality routine 419or exception table data is required or permitted. 420 421@cindex @code{.personality} directive, ARM 422@item .personality @var{name} 423Sets the personality routine for the current function to @var{name}. 424 425@cindex @code{.personalityindex} directive, ARM 426@item .personalityindex @var{index} 427Sets the personality routine for the current function to the EABI standard 428routine number @var{index} 429 430@cindex @code{.handlerdata} directive, ARM 431@item .handlerdata 432Marks the end of the current function, and the start of the exception table 433entry for that function. Anything between this directive and the 434@code{.fnend} directive will be added to the exception table entry. 435 436Must be preceded by a @code{.personality} or @code{.personalityindex} 437directive. 438 439@cindex @code{.save} directive, ARM 440@item .save @var{reglist} 441Generate unwinder annotations to restore the registers in @var{reglist}. 442The format of @var{reglist} is the same as the corresponding store-multiple 443instruction. 444 445@smallexample 446@exdent @emph{core registers} 447 .save @{r4, r5, r6, lr@} 448 stmfd sp!, @{r4, r5, r6, lr@} 449@exdent @emph{FPA registers} 450 .save f4, 2 451 sfmfd f4, 2, [sp]! 452@exdent @emph{VFP registers} 453 .save @{d8, d9, d10@} 454 fstmdf sp!, @{d8, d9, d10@} 455@exdent @emph{iWMMXt registers} 456 .save @{wr10, wr11@} 457 wstrd wr11, [sp, #-8]! 458 wstrd wr10, [sp, #-8]! 459or 460 .save wr11 461 wstrd wr11, [sp, #-8]! 462 .save wr10 463 wstrd wr10, [sp, #-8]! 464@end smallexample 465 466@cindex @code{.pad} directive, ARM 467@item .pad #@var{count} 468Generate unwinder annotations for a stack adjustment of @var{count} bytes. 469A positive value indicates the function prologue allocated stack space by 470decrementing the stack pointer. 471 472@cindex @code{.movsp} directive, ARM 473@item .movsp @var{reg} 474Tell the unwinder that @var{reg} contains the current stack pointer. 475 476@cindex @code{.setfp} directive, ARM 477@item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}] 478Make all unwinder annotations relaive to a frame pointer. Without this 479the unwinder will use offsets from the stack pointer. 480 481The syntax of this directive is the same as the @code{sub} or @code{mov} 482instruction used to set the frame pointer. @var{spreg} must be either 483@code{sp} or mentioned in a previous @code{.movsp} directive. 484 485@smallexample 486.movsp ip 487mov ip, sp 488@dots{} 489.setfp fp, ip, #4 490sub fp, ip, #4 491@end smallexample 492 493@cindex @code{.unwind_raw} directive, ARM 494@item .raw @var{offset}, @var{byte1}, @dots{} 495Insert one of more arbitary unwind opcode bytes, which are known to adjust 496the stack pointer by @var{offset} bytes. 497 498For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to 499@code{.save @{r0@}} 500 501@end table 502 503@node ARM Opcodes 504@section Opcodes 505 506@cindex ARM opcodes 507@cindex opcodes for ARM 508@code{@value{AS}} implements all the standard ARM opcodes. It also 509implements several pseudo opcodes, including several synthetic load 510instructions. 511 512@table @code 513 514@cindex @code{NOP} pseudo op, ARM 515@item NOP 516@smallexample 517 nop 518@end smallexample 519 520This pseudo op will always evaluate to a legal ARM instruction that does 521nothing. Currently it will evaluate to MOV r0, r0. 522 523@cindex @code{LDR reg,=<label>} pseudo op, ARM 524@item LDR 525@smallexample 526 ldr <register> , = <expression> 527@end smallexample 528 529If expression evaluates to a numeric constant then a MOV or MVN 530instruction will be used in place of the LDR instruction, if the 531constant can be generated by either of these instructions. Otherwise 532the constant will be placed into the nearest literal pool (if it not 533already there) and a PC relative LDR instruction will be generated. 534 535@cindex @code{ADR reg,<label>} pseudo op, ARM 536@item ADR 537@smallexample 538 adr <register> <label> 539@end smallexample 540 541This instruction will load the address of @var{label} into the indicated 542register. The instruction will evaluate to a PC relative ADD or SUB 543instruction depending upon where the label is located. If the label is 544out of range, or if it is not defined in the same file (and section) as 545the ADR instruction, then an error will be generated. This instruction 546will not make use of the literal pool. 547 548@cindex @code{ADRL reg,<label>} pseudo op, ARM 549@item ADRL 550@smallexample 551 adrl <register> <label> 552@end smallexample 553 554This instruction will load the address of @var{label} into the indicated 555register. The instruction will evaluate to one or two PC relative ADD 556or SUB instructions depending upon where the label is located. If a 557second instruction is not needed a NOP instruction will be generated in 558its place, so that this instruction is always 8 bytes long. 559 560If the label is out of range, or if it is not defined in the same file 561(and section) as the ADRL instruction, then an error will be generated. 562This instruction will not make use of the literal pool. 563 564@end table 565 566For information on the ARM or Thumb instruction sets, see @cite{ARM 567Software Development Toolkit Reference Manual}, Advanced RISC Machines 568Ltd. 569 570@node ARM Mapping Symbols 571@section Mapping Symbols 572 573The ARM ELF specification requires that special symbols be inserted 574into object files to mark certain features: 575 576@table @code 577 578@cindex @code{$a} 579@item $a 580At the start of a region of code containing ARM instructions. 581 582@cindex @code{$t} 583@item $t 584At the start of a region of code containing THUMB instructions. 585 586@cindex @code{$d} 587@item $d 588At the start of a region of data. 589 590@end table 591 592The assembler will automatically insert these symbols for you - there 593is no need to code them yourself. Support for tagging symbols ($b, 594$f, $p and $m) which is also mentioned in the current ARM ELF 595specification is not implemented. This is because they have been 596dropped from the new EABI and so tools cannot rely upon their 597presence. 598 599