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{armv7a}, 159@code{armv7r}, 160@code{armv7m}, 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 recognised: 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@end menu 288 289@node ARM-Chars 290@subsection Special Characters 291 292@cindex line comment character, ARM 293@cindex ARM line comment character 294The presence of a @samp{@@} on a line indicates the start of a comment 295that extends to the end of the current line. If a @samp{#} appears as 296the first character of a line, the whole line is treated as a comment. 297 298@cindex line separator, ARM 299@cindex statement separator, ARM 300@cindex ARM line separator 301The @samp{;} character can be used instead of a newline to separate 302statements. 303 304@cindex immediate character, ARM 305@cindex ARM immediate character 306Either @samp{#} or @samp{$} can be used to indicate immediate operands. 307 308@cindex identifiers, ARM 309@cindex ARM identifiers 310*TODO* Explain about /data modifier on symbols. 311 312@node ARM-Regs 313@subsection Register Names 314 315@cindex ARM register names 316@cindex register names, ARM 317*TODO* Explain about ARM register naming, and the predefined names. 318 319@node ARM Floating Point 320@section Floating Point 321 322@cindex floating point, ARM (@sc{ieee}) 323@cindex ARM floating point (@sc{ieee}) 324The ARM family uses @sc{ieee} floating-point numbers. 325 326 327 328@node ARM Directives 329@section ARM Machine Directives 330 331@cindex machine directives, ARM 332@cindex ARM machine directives 333@table @code 334 335@cindex @code{align} directive, ARM 336@item .align @var{expression} [, @var{expression}] 337This is the generic @var{.align} directive. For the ARM however if the 338first argument is zero (ie no alignment is needed) the assembler will 339behave as if the argument had been 2 (ie pad to the next four byte 340boundary). This is for compatibility with ARM's own assembler. 341 342@cindex @code{req} directive, ARM 343@item @var{name} .req @var{register name} 344This creates an alias for @var{register name} called @var{name}. For 345example: 346 347@smallexample 348 foo .req r0 349@end smallexample 350 351@cindex @code{unreq} directive, ARM 352@item .unreq @var{alias-name} 353This undefines a register alias which was previously defined using the 354@code{req} directive. For example: 355 356@smallexample 357 foo .req r0 358 .unreq foo 359@end smallexample 360 361An error occurs if the name is undefined. Note - this pseudo op can 362be used to delete builtin in register name aliases (eg 'r0'). This 363should only be done if it is really necessary. 364 365@cindex @code{code} directive, ARM 366@item .code @code{[16|32]} 367This directive selects the instruction set being generated. The value 16 368selects Thumb, with the value 32 selecting ARM. 369 370@cindex @code{thumb} directive, ARM 371@item .thumb 372This performs the same action as @var{.code 16}. 373 374@cindex @code{arm} directive, ARM 375@item .arm 376This performs the same action as @var{.code 32}. 377 378@cindex @code{force_thumb} directive, ARM 379@item .force_thumb 380This directive forces the selection of Thumb instructions, even if the 381target processor does not support those instructions 382 383@cindex @code{thumb_func} directive, ARM 384@item .thumb_func 385This directive specifies that the following symbol is the name of a 386Thumb encoded function. This information is necessary in order to allow 387the assembler and linker to generate correct code for interworking 388between Arm and Thumb instructions and should be used even if 389interworking is not going to be performed. The presence of this 390directive also implies @code{.thumb} 391 392@cindex @code{thumb_set} directive, ARM 393@item .thumb_set 394This performs the equivalent of a @code{.set} directive in that it 395creates a symbol which is an alias for another symbol (possibly not yet 396defined). This directive also has the added property in that it marks 397the aliased symbol as being a thumb function entry point, in the same 398way that the @code{.thumb_func} directive does. 399 400@cindex @code{.ltorg} directive, ARM 401@item .ltorg 402This directive causes the current contents of the literal pool to be 403dumped into the current section (which is assumed to be the .text 404section) at the current location (aligned to a word boundary). 405@code{GAS} maintains a separate literal pool for each section and each 406sub-section. The @code{.ltorg} directive will only affect the literal 407pool of the current section and sub-section. At the end of assembly 408all remaining, un-empty literal pools will automatically be dumped. 409 410Note - older versions of @code{GAS} would dump the current literal 411pool any time a section change occurred. This is no longer done, since 412it prevents accurate control of the placement of literal pools. 413 414@cindex @code{.pool} directive, ARM 415@item .pool 416This is a synonym for .ltorg. 417 418@cindex @code{.fnstart} directive, ARM 419@item .unwind_fnstart 420Marks the start of a function with an unwind table entry. 421 422@cindex @code{.fnend} directive, ARM 423@item .unwind_fnend 424Marks the end of a function with an unwind table entry. The unwind index 425table entry is created when this directive is processed. 426 427If no personality routine has been specified then standard personality 428routine 0 or 1 will be used, depending on the number of unwind opcodes 429required. 430 431@cindex @code{.cantunwind} directive, ARM 432@item .cantunwind 433Prevents unwinding through the current function. No personality routine 434or exception table data is required or permitted. 435 436@cindex @code{.personality} directive, ARM 437@item .personality @var{name} 438Sets the personality routine for the current function to @var{name}. 439 440@cindex @code{.personalityindex} directive, ARM 441@item .personalityindex @var{index} 442Sets the personality routine for the current function to the EABI standard 443routine number @var{index} 444 445@cindex @code{.handlerdata} directive, ARM 446@item .handlerdata 447Marks the end of the current function, and the start of the exception table 448entry for that function. Anything between this directive and the 449@code{.fnend} directive will be added to the exception table entry. 450 451Must be preceded by a @code{.personality} or @code{.personalityindex} 452directive. 453 454@cindex @code{.save} directive, ARM 455@item .save @var{reglist} 456Generate unwinder annotations to restore the registers in @var{reglist}. 457The format of @var{reglist} is the same as the corresponding store-multiple 458instruction. 459 460@smallexample 461@exdent @emph{core registers} 462 .save @{r4, r5, r6, lr@} 463 stmfd sp!, @{r4, r5, r6, lr@} 464@exdent @emph{FPA registers} 465 .save f4, 2 466 sfmfd f4, 2, [sp]! 467@exdent @emph{VFP registers} 468 .save @{d8, d9, d10@} 469 fstmdf sp!, @{d8, d9, d10@} 470@exdent @emph{iWMMXt registers} 471 .save @{wr10, wr11@} 472 wstrd wr11, [sp, #-8]! 473 wstrd wr10, [sp, #-8]! 474or 475 .save wr11 476 wstrd wr11, [sp, #-8]! 477 .save wr10 478 wstrd wr10, [sp, #-8]! 479@end smallexample 480 481@cindex @code{.pad} directive, ARM 482@item .pad #@var{count} 483Generate unwinder annotations for a stack adjustment of @var{count} bytes. 484A positive value indicates the function prologue allocated stack space by 485decrementing the stack pointer. 486 487@cindex @code{.movsp} directive, ARM 488@item .movsp @var{reg} 489Tell the unwinder that @var{reg} contains the current stack pointer. 490 491@cindex @code{.setfp} directive, ARM 492@item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}] 493Make all unwinder annotations relaive to a frame pointer. Without this 494the unwinder will use offsets from the stack pointer. 495 496The syntax of this directive is the same as the @code{sub} or @code{mov} 497instruction used to set the frame pointer. @var{spreg} must be either 498@code{sp} or mentioned in a previous @code{.movsp} directive. 499 500@smallexample 501.movsp ip 502mov ip, sp 503@dots{} 504.setfp fp, ip, #4 505sub fp, ip, #4 506@end smallexample 507 508@cindex @code{.unwind_raw} directive, ARM 509@item .raw @var{offset}, @var{byte1}, @dots{} 510Insert one of more arbitary unwind opcode bytes, which are known to adjust 511the stack pointer by @var{offset} bytes. 512 513For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to 514@code{.save @{r0@}} 515 516@cindex @code{.cpu} directive, ARM 517@item .cpu @var{name} 518Select the target processor. Valid values for @var{name} are the same as 519for the @option{-mcpu} commandline option. 520 521@cindex @code{.arch} directive, ARM 522@item .arch @var{name} 523Select the target architecture. Valid values for @var{name} are the same as 524for the @option{-march} commandline option. 525 526@cindex @code{.fpu} directive, ARM 527@item .fpu @var{name} 528Select the floating point unit to assemble for. Valid values for @var{name} 529are the same as for the @option{-mfpu} commandline option. 530 531@cindex @code{.eabi_attribute} directive, ARM 532@item .eabi_attribute @var{tag}, @var{value} 533Set the EABI object attribute number @var{tag} to @var{value}. The value 534is either a @code{number}, @code{"string"}, or @code{number, "string"} 535depending on the tag. 536 537@end table 538 539@node ARM Opcodes 540@section Opcodes 541 542@cindex ARM opcodes 543@cindex opcodes for ARM 544@code{@value{AS}} implements all the standard ARM opcodes. It also 545implements several pseudo opcodes, including several synthetic load 546instructions. 547 548@table @code 549 550@cindex @code{NOP} pseudo op, ARM 551@item NOP 552@smallexample 553 nop 554@end smallexample 555 556This pseudo op will always evaluate to a legal ARM instruction that does 557nothing. Currently it will evaluate to MOV r0, r0. 558 559@cindex @code{LDR reg,=<label>} pseudo op, ARM 560@item LDR 561@smallexample 562 ldr <register> , = <expression> 563@end smallexample 564 565If expression evaluates to a numeric constant then a MOV or MVN 566instruction will be used in place of the LDR instruction, if the 567constant can be generated by either of these instructions. Otherwise 568the constant will be placed into the nearest literal pool (if it not 569already there) and a PC relative LDR instruction will be generated. 570 571@cindex @code{ADR reg,<label>} pseudo op, ARM 572@item ADR 573@smallexample 574 adr <register> <label> 575@end smallexample 576 577This instruction will load the address of @var{label} into the indicated 578register. The instruction will evaluate to a PC relative ADD or SUB 579instruction depending upon where the label is located. If the label is 580out of range, or if it is not defined in the same file (and section) as 581the ADR instruction, then an error will be generated. This instruction 582will not make use of the literal pool. 583 584@cindex @code{ADRL reg,<label>} pseudo op, ARM 585@item ADRL 586@smallexample 587 adrl <register> <label> 588@end smallexample 589 590This instruction will load the address of @var{label} into the indicated 591register. The instruction will evaluate to one or two PC relative ADD 592or SUB instructions depending upon where the label is located. If a 593second instruction is not needed a NOP instruction will be generated in 594its place, so that this instruction is always 8 bytes long. 595 596If the label is out of range, or if it is not defined in the same file 597(and section) as the ADRL instruction, then an error will be generated. 598This instruction will not make use of the literal pool. 599 600@end table 601 602For information on the ARM or Thumb instruction sets, see @cite{ARM 603Software Development Toolkit Reference Manual}, Advanced RISC Machines 604Ltd. 605 606@node ARM Mapping Symbols 607@section Mapping Symbols 608 609The ARM ELF specification requires that special symbols be inserted 610into object files to mark certain features: 611 612@table @code 613 614@cindex @code{$a} 615@item $a 616At the start of a region of code containing ARM instructions. 617 618@cindex @code{$t} 619@item $t 620At the start of a region of code containing THUMB instructions. 621 622@cindex @code{$d} 623@item $d 624At the start of a region of data. 625 626@end table 627 628The assembler will automatically insert these symbols for you - there 629is no need to code them yourself. Support for tagging symbols ($b, 630$f, $p and $m) which is also mentioned in the current ARM ELF 631specification is not implemented. This is because they have been 632dropped from the new EABI and so tools cannot rely upon their 633presence. 634 635