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