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