Assembly control directives, Macro and Mend on | ARM VERSION 1.2

Directives Reference

7.4Assembly control directives

This section describes the following directives:

•MACRO and MEND on page 7-27

•MEXIT on page 7-29

•IF, ELSE, and ENDIF on page 7-30

•WHILE and WEND on page 7-32.

7.4.1Nesting directives

The following structures can be nested to a total depth of 256:

•MACRO definitions

•WHILE...WEND loops

•IF...ELSE...ENDIF conditional structures

•INCLUDE file inclusions.

The limit applies to all structures taken together, however they are nested. The limit is not 256 of each type of structure.

7-26

Copyright © 2000, 2001 ARM Limited. All rights reserved.

ARM DUI 0068B

Image 308

ARM VERSION 1.2 manual Assembly control directives, Macro and Mend on, Mexit on, IF, ELSE, and Endif on While and Wend on

Contents

ARM Developer Suite Copyright 2000, 2001 ARM Limited. All rights reserved ARM Developer SuiteAssembler Guide ARM Developer Suite Assembler Guide Glossary About this book on Feedback on Using this book About this bookIntended audience This book is organized into the following chapters Typographical conventions ItalicFurther reading ARM publications ARM Reference Peripheral Specification ARM DDI Other publications Feedback on this book FeedbackFeedback on the ARM Developer Suite ARM DUI 0068B Introduction About the ARM Developer Suite assemblers on About the ARM Developer Suite assemblers ARM Developer Suite ADS has Writing ARM and Thumb Assembly Language Or run the module in AXD with interleaving on See IntroductionCode examples Overview of the ARM architecture Architecture versionsARM and Thumb state ARM processors always start executing code in ARM state General-purpose, 32-bit registers Processor modeRegisters Program counter pc Data processing instructions ARM instruction set overviewBranch instructions Status register access instructions Single register load and store instructionsMultiple register load and store instructions Semaphore instructions Register access Access to the inline barrel shifterARM instruction capabilities Following general points apply to ARM instructions Following general points apply to Thumb instructions Thumb instruction set overviewThumb instruction capabilities Access to the barrel shifter Differences between Thumb and ARM instruction sets Single register load and store instructions Structure of assembly language modules Layout of assembly language source filesGeneral form of source lines in assembly language is Case rules Comments LabelsLocal labels Constants Is a base between 2 Xxx is a number in that base An example ARM assembly language module ELF sections and the Area directive Entry directive Application executionApplication termination END directive Calling subroutines BX instruction An example Thumb assembly language moduleCODE32 and CODE16 directives Using the C preprocessor Example 2-4 Preprocessing an assembly language source file Conditional execution ALU status flags Execution conditions Examples Using conditional execution in ARM state Example of the use of conditional execution Conditional branches only Converting to Thumb Branch prediction and caches Loading constants into registers Direct loading with MOV and MVN Right, 2 bits Direct loading with MOV in Thumb state Loading with LDR Rd, =const Placing literal pools Loading floating-point constants Loading addresses into registers Direct loading with ADR and Adrl ADR Implementing a jump table with ADR Example 2-7 ARM code jump table Example 2-8 Thumb code jump table Loading addresses with LDR Rd, = label R1, =Darea + = LDR R1,PC, #offset into Literal Pool Increments r1 by An LDR Rd, =label example string copyingAddress registers. For example, the instruction Load register Load and store multiple register instructions ARM LDM and STM instructions SyntaxSyntax of the LDM instructions is Where Usage LDM and STM addressing modes Implementing stacks with LDM and STM Descending or ascending Stacking registers for nested subroutines Block copy with LDM and STM Example 2-11 Block copy Movs Thumb LDM and STM instructions LDM and STMPush and POP Thumb-state block copy example LSR Using macros Test-and-branch macro exampleThis macro can be invoked as follows After substitution this becomes Unsigned integer division macro example Register that holds the divisorAfter the instructions are executed, it holds the remainder If only the remainder is required Ratio DivMod r0,r5,r4,r2 Describing data structures with MAP and Field directives Relative maps Register-based maps Program-relative maps Finding the end of the allocated data Forcing correct alignment EndOfChars Using register-based MAP and Field directives Defining register-based symbols Setting up a C-type structure Is equivalent to the C code 2-27 for an explanation of these Making faster access possibleIf you want the equivalent of the C code This example, the MAP directive is Not Field MAP Using two register-based structures Avoiding problems with MAP and Field directives ArrayBase RN r9 Using frame directives Symbols on Expressions, literals, and operators on Command syntax Specifies that the content of inputfile is read-only Position-independent. The default is /noropiSpecifies that the content of inputfile is read-write Position-independent. The default is /norwpi Assembled for the wrong target FPU Selection of libraries, accordinglyValid options are Selects no floating-point option. This makes your assembled Command-line options Sets the maximum source cache size to n. The default is 8MBObject file, for use by the debugger see Keep on Allow unaligned LDRs First pass and reads them from memory on the second pass As \n and \tRegister names Turns off warning messages Assembler Reference Format of source lines Predefined register and coprocessor names Predeclared register namesPredeclared program status register names Predeclared floating-point register names Expressions or conditions, for example Built-in variablesLists the built-in variables defined by the ARM assembler Determining the armasm version at assembly time Symbols Symbol naming rulesNumeric constants on Labels on Variables Numeric constants Assembly time substitution of variables Gbls Program-relative labels DCD and Dcdu on Dcfd and Dcfdu on Dcfs and Dcfsu onDCQ and Dcqu on DCW and Dcwu on Register-relative labels Syntax of a local label is Syntax of a reference to a local label is Assembler Reference Expressions, literals, and operators This section contains the following subsections String expressions String literalsExample String literals Numeric expressions Is a sequence of characters using only the digits 0 to n Numeric literalsNumeric literals can take any of the following forms Numeric code of the character Floating-point literals Floating-point literals can take any of the following forms Register-relative and program-relative expressions Logical expressionsLogical literals There are only two logical literals Operator precedence String manipulation Operator precedence in C Precedence Unary operators Operator Usage Description Example of use of SBOFFSET1912 and SBOFFSET11 String manipulation operators Binary operatorsMultiplicative operators Addition, subtraction, and logical operators Shift operatorsSHR is a logical shift and does not propagate the sign bit Relational operators Boolean operators 10 shows the Boolean operators ARM DUI 0068B ARM Instruction Reference Add with carry, Add All Logical Branch Move not All ARM condition codes Q flag ARM memory access instructions LDR and STR, words and unsigned bytes onLDR and STR, halfwords and signed bytes on LDR and STR, doublewords on Otherwise, a 32-bit word is transferred Where Is either LDR Load Register or STR Store RegisterLDR and STR, words and unsigned bytes Zero offset Pre-indexed offsetProgram-relative Post-indexed offset Flexible offset syntax Address alignment for word transfers Loading to r15 Saving from r15 Architectures LDR and STR, halfwords and signed bytes Must be within ±255 bytes of the current instruction Is an offset applied to the value in Rn see Offset syntaxOffset syntax Is often a numeric constant see examples below Offset syntax is the same for LDR and STR, doublewords on Address alignment for halfword transfersYou cannot load halfwords or bytes to r15 Incorrect example LDR and STR, doublewords Is an optional condition code see Conditional execution onMust be an even numbered register, and not r14 Pre-indexed without writeback Not be the same as Rd or Rd+1 Address alignment Incorrect examples Is either LDM or STM Is any one of the followingIncrement address after each transfer Increment address before each transfer Non word-aligned addresses Loading or storing the base register, with writeback 5 PLD Is the register on which the memory address is based Alignment Both Rd and Rm Is swapped with the contents of the memory location6 SWP ARM general data processing instructions Flexible second operand LSR and LSL Bits of the register are set to Carry flag Instruction substitution 2 ADD, SUB, RSB, ADC, SBC, and RSC Is one of ADD, SUB, RSB, ADC, SBC, or RSCIs the ARM register for the result Is the ARM register holding the first operand Multiword arithmetic examples Condition flagsUse of r15 These instructions subtract one 96-bit integer from another Is one of AND, ORR, EOR, or BIC 3 AND, ORR, EOR, and BICLogical AND, OR, Exclusive or and Bit Clear Orreq Is the ARM register for the result MOV and MVNMove and Move Not Mvnne CMP and CMN Compare and Compare Negative CMN TST and TEQ Test and Test Equivalence TEQ 7 CLZ Count Leading ZeroesIs the ARM register for the result. Rd must not be r15 Is the operand register UMULL, UMLAL, Smull and Smlal on ARM multiply instructionsMUL and MLA on MUL and MLA MUL UMULL, UMLAL, Smull and Smlal Is one of UMULL, UMLAL, SMULL, or Smlal Umull SMULxy Use the top end bits 3116 of RmUse the top end bits 3116 of Rs Are the ARM registers holding the values to be multiplied Smulbt SMLAxy Is the ARM register holding the value to be added Smlatb Are the ARM registers holding the operands SMULWyUse the top end bits 3116 of Rs Is the ARM register holding the value to be added SMLAWyAre the ARM registers holding the values to be multiplied Smlawt SMLALxy Smlaltt 8 MIA, MIAPH, and MIAxy Current processorsUse the top end bits 3116 of Rm R15 cannot be used for either Rm or Rs These instructions are only available in XScale ARM saturating arithmetic instructions QADD, QSUB, QDADD, and QdsubIs one of QADD, QSUB, QDADD, or Qdsub Are the ARM registers holding the operands Qadd ARM branch instructions Branch, and Branch with Link 2 BX 3 BLX Blxmi ARM coprocessor instructions MCR, MCR2, Mcrr on 1 CDP, CDP2 Are ARM source registers. They must not be r15 Is p n, where n is an integer in the range2 MCR, MCR2, Mcrr 3 MRC, MRC2 Affected Mrrc 5 LDC, STC Is either LDC or STCIs an optional suffix specifying a long transfer Is the coprocessor register to load or save Architectures 6 LDC2, STC2 Is either LDC2 or STC2 Architectures Miscellaneous ARM instructions 1 SWI Software interrupt 2 MRS WhereIs the destination register. Rd must not be r15 Is either Cpsr or Spsr See MRS on 3 MSRIs either Cpsr or Spsr MSR CPSRf, r5 Bkpt Breakpoint Are general-purpose registers 5 MAR, MRAFor current processors ARM pseudo-instructions ADR ARM pseudo-instructiononAdrl ARM pseudo-instructionon LDR ARM pseudo-instruction on ADR ARM pseudo-instruction Is an optional condition codeIs the register to load Non word-aligned address within ±255 bytes Word-aligned address within 256KB Adrl ARM pseudo-instructionNon word-aligned address within 64KB R4,start + = ADD R4,pc,#0xe800 LDR ARM pseudo-instruction R3,=0xff0 Loads Into = MOV r3,#0xff0 NOP ARM pseudo-instruction Thumb Instruction Reference Add with carry Rotate right Thumb memory access instructions LDR and STR, immediate offset onLDR and STR, register offset on LDR and STR, pc or sp relative on Where Is either LDR and STR, immediate offsetLoad register Store register Address alignment for word and halfword transfers LDR and STR, register offset Strsh LDR and STR, pc or sp relative 4 in the range 0 to R2,pc,#1016 POP reglist POP reglist, pc These instructions do not affect the flags Ldmia and Stmia Load and store multiple registersLoad multiple, increment after Store multiple, increment after R3!, r0,r4 Thumb arithmetic instructions ADD and SUB, sp onADD, pc or sp relative on ADC, SBC, and MUL on 255 to +255 ADD and SUB, low registersTo +7 These instructions update the N, Z, C, and V flags Restrictions 2 ADD, high or low registers Is a register containing the second operand ADD and SUB, sp Range -508 to +508 4 ADD, pc or sp relative Is the destination register. Rd must be in the range r0- r7Is either sp or pc Range Where Is one of ADC, SBC, or MUL 5 ADC, SBC, and MUL Thumb general data processing instructions CMP and CMN on page 5-26 Compare and Compare NegativeMOV, MVN, and NEG on page 5-28 Move, Move NOT, and Negate TST on page 5-30 Test bits Where Is one of AND, ORR, EOR, or BIC 1 AND, ORR, EOR, and BICBitwise logical operations Range r0- r7 2 ASR, LSL, LSR, and ROR Register-controlled shift Immediate shift Where Is the register containing the first operand Examples Where Is the destination register 4 MOV, MVN, and NEGMove, Move NOT, and Negate Is the source register Condition flags Where Is the register containing the first operand 5 TSTTest bits Rn and Rm must be in the range r0-r7 Thumb branch instructions 1 B Is an optional condition code see -2 on3-23 for more information Label must be within Condition codes for Thumb B instruction 2 BL Long branch with Link 3 BX 4 BLX Branch with Link, and optionally exchange instruction setInstruction clears the T flag in the CPSR. Code at BLX label always causes a change to ARM state Thumb software interrupt and breakpoint instructions Bkpt on Bkpt immed8 Thumb pseudo-instructions ADR Thumb pseudo-instruction 1KB. expr must be defined locally, it cannot be imported Assembler generates the instruction LDR Thumb pseudo-instructionIf the value of expr is within range of a MOV instruction, =labelname NOP Thumb pseudo-instruction Syntax for NOP is ARM DUI 0068B Vector Floating-point Programming Absolute value Vector All Negate Vector All VFP architectures Vector floating-point coprocessorReference Manual Floating-point registers Register banks Vectors Vector wrap-aroundVector stride Restriction on vector length Vector and scalar operations Control of scalar, vector and mixed operationsScalar operations Vector operations VFP and condition codes Vector Floating-point Programming VFP system registers FPSCR, the floating-point status and control register 0b000 FPEXC, the floating-point exception register FPSID, the floating-point system ID registerModifying individual bits of a VFP system register See FMRX, FMXR, and Fmstat on Effects of using flush-to-zero mode Flush-to-zero modeWhen to use flush-to-zero mode Operations not affected by flush-to-zero mode VFP instructions Fmrrs and Fmsrr onFMRX, FMXR, and Fmstat on Ftosi and Ftoui onPage Fabsd d3, d5 Fnegsmi s15, s15 Fadd and Fsub Is the VFP register for the resultIs the VFP register holding the first operand Is the VFP register holding the second operand Fcmp Floating-point compare Fcmp is always scalarWith zero instruction Fcmp instructions can produce Invalid Operation exceptions Is a single-precision VFP register holding the operand FcvtdsIs a double-precision VFP register for the result Is a double-precision VFP register holding the operand FcvtsdIs a single-precision VFP register for the result Fdiv FLD and FST Floating-point load and storePrecision specified in precision Address used for the transfer Fldsne Fldm and Fstm Unspecified precision Following instructions are equivalent FMAC, FNMAC, FMSC, and Fnmsc Must be one of FMAC, FNMAC, FMSC, or Fnmsc Fnmscsle Fmdrr and Fmrrd Is the VFP double-precision registerAre ARM registers. Do not use r15 These instructions do not produce any exceptions These instructions are used together as matched pairs FMDHR, FMDLR, FMRDH, and FmrdlIs the ARM register. Rd must not be r15 Fmrs and Fmsr Is the VFP single-precision register Are the ARM registers. Do not use r15 Fmrrs and FmsrrAre two consecutive VFP single-precision registers FMRX, FMXR, and Fmstat Is the ARM register Fmul and Fnmul Fsito and Fuito Fsqrt Is the VFP register holding the operand Ftosi and Ftoui Is a single-precision VFP register for the integer result VFP pseudo-instruction There is one VFP pseudo-instructionFLD pseudo-instruction Can be S for single-precision, or D for double-precision D1,=3.12E106 Loads 3.12E106 into d1 VFP directives and vector notation Vfpassert Scalar on Vfpassert Vector on Vfpassert Scalar VFP directives and vector notation on Vfpassert Vector on Where Is the vector length Is the vector stride VFP directives and vector notation on Vfpassert Scalar on R10,FPSCR ARM DUI 0068B Assembly control directives on Conditional assembly, looping, inclusions, and macros Alphabetical list of directives Location of descriptions of directives Symbol definition directives This section describes the following directivesGBLA, GBLL, and Gbls on Declare a global arithmetic, logical, or string variable GBLA, GBLL, and Gbls Armasm -pd objectsize Seta 0xFF -o objectfile sourcefile LCLA, LCLL, and Lcls SETA, SETL, and Sets Rlist Names on 5 CN CN directive defines a name for a coprocessor registerCoprocessor names on Evaluates to a coprocessor register number from 0 to 6 CP Evaluates to a coprocessor number from 0 to DN and SN 8 FN Evaluates to a floating-point register number from 0 to DCQ and Dcqu on Data definition directivesDCD and Dcdu on Ltorg 2 MAP Is a numeric or program-relative expressionSet to this address During the first pass of the assembler Storage counter FieldBy the value of expr Space Expressions on 5 DCB To 255 see Numeric expressions onQuoted string. The characters of the string are loaded into Consecutive bytes of store DCD and Dcdu Numeric expression see Numeric expressions onProgram-relative expression DCW and Dcwu on DCQ and Dcqu on Dcdo Dcfd and Dcfdu Dcfs and Dcfsu 10 DCI Is a numeric expression see Numeric expressions on DCQ and Dcqu DCD and Dcdu on DCW and Dcwu on DCW and Dcwu To 65535 see Numeric expressions onDCD and Dcdu on DCQ and Dcqu on Data Assembly control directives Macro and Mend onMexit on IF, ELSE, and Endif on While and Wend on Macro and Mend BGE Using a macro to produce assembly-time diagnostics Mexit 4 IF, ELSE, and Endif See Relational operators on Example 7-3 Assembly conditional on a variable being defined While and Wend Frame Register on Frame Restore on Frame description directivesFrame Address on Frame POP on Frame Push on Is sp unless the function uses a separate frame pointer Can omit it There are two alternative syntaxes for Frame POP Is the number of bytes that the stack pointer moves Frame Push There are two alternative syntaxes for Frame Push Frame Register Is the register in which the value is preserved Frame Restore Frame Save Frame State Restore on Function or Proc on Frame State Remember Frame State Restore Frame State Remember on Function or Proc on Function or Proc Endfunc or Endp Is an assertion that can evaluate to either True or False Reporting directivesAssert Info Is an expression that evaluates to a string Specify the -listassembler option to turn on listing Where Is the OPT directive setting. -2 lists valid settings3 OPT OPT Is the subtitle TTL and SubtIs the title Miscellaneous directives CODE16 and CODE32 onExport or Global on GET or Include on Align Cacheable, CODE, ALIGN=3 Area Example,CODE,READONLY An example code section CODE16 and CODE32 4 END Entry Entry directive declares an entry point to a program Is the symbolic name to assign to the value 6 EQUAddress, or a 32-bit integer constant Is optional. type can be any one Export or Global Exportas Extern GET or Include Nesting directives on File, or library. The symbol name is case-sensitive GlobalSee Export or Global on Import See GET or Include on IncbinInclude Symbols are kept except register-relative symbols Keep Assembly fails NofpRequire Require directive specifies a dependency between sections REQUIRE8 and PRESERVE8 19 RN Evaluates to a register number from 0 to Rout See ARM Developer Suite Among other things, computer softwareThumb state Platforms Used to find errors in the application program flow Default thread runsSee also Saved Processor Status Register Otherwise stated See also Ropi See also RwpiSee Read Only Position Independent See Read Write Position Independent Normally set to zero on reset Block of software code or data for an ImageBy ARM to handle semihosting See Saved Processor Status Register Index Align Gbll Adrl Symbols Index-6