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