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