Keep | ARM VERSION 1.2 instruction

Directives Reference

7.7.15KEEP

The KEEP directive instructs the assembler to retain local symbols in the symbol table in the object file.

Syntax

KEEP {symbol}

where:
symbol	is the name of the local symbol to keep. If symbol is not specified, all local
	symbols are kept except register-relative symbols.

Usage

By default, the only symbols that the assembler describes in its output object file are:

•exported symbols

•symbols that are relocated against.

Use KEEP to preserve local symbols that can be used to help debugging. Kept symbols appear in the ARM debuggers and in linker map files.

KEEP cannot preserve register-relative symbols (see MAP on page 7-15).

Example

label	ADC	r2,r3,r4
	KEEP	label	; makes label available to debuggers
	ADD	r2,r2,r5

7-64

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

ARM DUI 0068B

Image 346

ARM VERSION 1.2 manual Keep, Symbols are kept except register-relative symbols

Contents

ARM Developer Suite Assembler Guide ARM Developer SuiteCopyright 2000, 2001 ARM Limited. All rights reserved ARM Developer Suite Assembler Guide Glossary About this book on Feedback on Intended audience Using this bookAbout this book This book is organized into the following chapters Further reading Typographical conventionsItalic ARM publications ARM Reference Peripheral Specification ARM DDI Other publications Feedback on the ARM Developer Suite FeedbackFeedback on this book 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 Code examples IntroductionOr run the module in AXD with interleaving on See ARM and Thumb state Overview of the ARM architectureArchitecture versions ARM processors always start executing code in ARM state Registers Processor modeGeneral-purpose, 32-bit registers Program counter pc Branch instructions ARM instruction set overviewData processing instructions Multiple register load and store instructions Status register access instructionsSingle register load and store instructions Semaphore instructions ARM instruction capabilities Register accessAccess to the inline barrel shifter Following general points apply to ARM instructions Thumb instruction capabilities Thumb instruction set overviewFollowing general points apply to Thumb instructions Access to the barrel shifter Differences between Thumb and ARM instruction sets Single register load and store instructions General form of source lines in assembly language is Structure of assembly language modulesLayout of assembly language source files Case rules Local labels LabelsComments 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 Application termination Entry directiveApplication execution END directive Calling subroutines CODE32 and CODE16 directives An example Thumb assembly language moduleBX instruction 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 Address registers. For example, the instruction An LDR Rd, =label example string copyingIncrements r1 by Load register Load and store multiple register instructions Syntax of the LDM instructions is ARM LDM and STM instructionsSyntax 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 Push and POP Thumb LDM and STM instructionsLDM and STM Thumb-state block copy example LSR This macro can be invoked as follows Using macrosTest-and-branch macro example After substitution this becomes After the instructions are executed, it holds the remainder Unsigned integer division macro exampleRegister that holds the divisor 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 If you want the equivalent of the C code Making faster access possible2-27 for an explanation of these 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-write Specifies that the content of inputfile is read-onlyPosition-independent. The default is /noropi Position-independent. The default is /norwpi Valid options are Assembled for the wrong target FPUSelection of libraries, accordingly Selects no floating-point option. This makes your assembled Object file, for use by the debugger see Keep on Command-line optionsSets the maximum source cache size to n. The default is 8MB Allow unaligned LDRs Register names First pass and reads them from memory on the second passAs \n and \t Turns off warning messages Assembler Reference Format of source lines Predeclared program status register names Predefined register and coprocessor namesPredeclared register names Predeclared floating-point register names Lists the built-in variables defined by the ARM assembler Built-in variablesExpressions or conditions, for example Determining the armasm version at assembly time Numeric constants on SymbolsSymbol naming rules Labels on Variables Numeric constants Assembly time substitution of variables Gbls DCQ and Dcqu on DCW and Dcwu on Program-relative labelsDCD and Dcdu on Dcfd and Dcfdu on Dcfs and Dcfsu 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 Example String expressionsString literals String literals Numeric expressions Numeric literals can take any of the following forms Is a sequence of characters using only the digits 0 to nNumeric literals Numeric code of the character Floating-point literals Floating-point literals can take any of the following forms Logical literals Register-relative and program-relative expressionsLogical expressions 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 Multiplicative operators Binary operatorsString manipulation operators SHR is a logical shift and does not propagate the sign bit Shift operatorsAddition, subtraction, and logical operators 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 LDR and STR, halfwords and signed bytes on ARM memory access instructionsLDR and STR, words and unsigned bytes on LDR and STR, doublewords on LDR and STR, words and unsigned bytes Where Is either LDR Load Register or STR Store RegisterOtherwise, a 32-bit word is transferred Program-relative Zero offsetPre-indexed offset 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 Offset syntax Must be within ±255 bytes of the current instructionIs an offset applied to the value in Rn see Offset syntax Is often a numeric constant see examples below You cannot load halfwords or bytes to r15 Offset syntax is the same for LDR and STR, doublewords onAddress alignment for halfword transfers Incorrect example Must be an even numbered register, and not r14 LDR and STR, doublewordsIs an optional condition code see Conditional execution on Pre-indexed without writeback Not be the same as Rd or Rd+1 Address alignment Incorrect examples Increment address after each transfer Is either LDM or STMIs any one of the following 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 6 SWP Is swapped with the contents of the memory locationBoth Rd and Rm ARM general data processing instructions Flexible second operand LSR and LSL Bits of the register are set to Carry flag Instruction substitution Is the ARM register for the result 2 ADD, SUB, RSB, ADC, SBC, and RSCIs one of ADD, SUB, RSB, ADC, SBC, or RSC Is the ARM register holding the first operand Use of r15 Condition flagsMultiword arithmetic examples These instructions subtract one 96-bit integer from another Logical AND, OR, Exclusive or and Bit Clear 3 AND, ORR, EOR, and BICIs one of AND, ORR, EOR, or BIC Orreq Move and Move Not MOV and MVNIs the ARM register for the result Mvnne CMP and CMN Compare and Compare Negative CMN TST and TEQ Test and Test Equivalence TEQ Is the ARM register for the result. Rd must not be r15 7 CLZCount Leading Zeroes Is the operand register MUL and MLA on ARM multiply instructionsUMULL, UMLAL, Smull and Smlal on MUL and MLA MUL UMULL, UMLAL, Smull and Smlal Is one of UMULL, UMLAL, SMULL, or Smlal Umull Use the top end bits 3116 of Rs SMULxyUse the top end bits 3116 of Rm Are the ARM registers holding the values to be multiplied Smulbt SMLAxy Is the ARM register holding the value to be added Smlatb Use the top end bits 3116 of Rs SMULWyAre the ARM registers holding the operands Are the ARM registers holding the values to be multiplied SMLAWyIs the ARM register holding the value to be added Smlawt SMLALxy Smlaltt Use the top end bits 3116 of Rm 8 MIA, MIAPH, and MIAxyCurrent processors R15 cannot be used for either Rm or Rs These instructions are only available in XScale Is one of QADD, QSUB, QDADD, or Qdsub ARM saturating arithmetic instructionsQADD, QSUB, QDADD, and 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 2 MCR, MCR2, Mcrr Is p n, where n is an integer in the rangeAre ARM source registers. They must not be r15 3 MRC, MRC2 Affected Mrrc Is an optional suffix specifying a long transfer 5 LDC, STCIs either LDC or STC 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 Is the destination register. Rd must not be r15 2 MRSWhere Is either Cpsr or Spsr Is either Cpsr or Spsr 3 MSRSee MRS on MSR CPSRf, r5 Bkpt Breakpoint For current processors 5 MAR, MRAAre general-purpose registers Adrl ARM pseudo-instructionon ARM pseudo-instructionsADR ARM pseudo-instructionon LDR ARM pseudo-instruction on Is the register to load ADR ARM pseudo-instructionIs an optional condition code Non word-aligned address within ±255 bytes Non word-aligned address within 64KB Adrl ARM pseudo-instructionWord-aligned address within 256KB 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 LDR and STR, register offset on Thumb memory access instructionsLDR and STR, immediate offset on LDR and STR, pc or sp relative on Load register Where Is eitherLDR and STR, immediate offset 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 Load multiple, increment after Ldmia and StmiaLoad and store multiple registers Store multiple, increment after R3!, r0,r4 ADD, pc or sp relative on Thumb arithmetic instructionsADD and SUB, sp on ADC, SBC, and MUL on To +7 ADD and SUB, low registers255 to +255 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 Is either sp or pc 4 ADD, pc or sp relativeIs the destination register. Rd must be in the range r0- r7 Range Where Is one of ADC, SBC, or MUL 5 ADC, SBC, and MUL MOV, MVN, and NEG on page 5-28 Move, Move NOT, and Negate Thumb general data processing instructionsCMP and CMN on page 5-26 Compare and Compare Negative TST on page 5-30 Test bits Bitwise logical operations Where Is one of AND, ORR, EOR, or BIC1 AND, ORR, EOR, and BIC Range r0- r7 2 ASR, LSL, LSR, and ROR Register-controlled shift Immediate shift Where Is the register containing the first operand Examples Move, Move NOT, and Negate Where Is the destination register4 MOV, MVN, and NEG Is the source register Condition flags Test bits Where Is the register containing the first operand5 TST Rn and Rm must be in the range r0-r7 Thumb branch instructions 3-23 for more information 1 BIs an optional condition code see -2 on Label must be within Condition codes for Thumb B instruction 2 BL Long branch with Link 3 BX Instruction clears the T flag in the CPSR. Code at 4 BLXBranch with Link, and optionally exchange instruction set 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 If the value of expr is within range of a MOV instruction, LDR Thumb pseudo-instructionAssembler generates the instruction =labelname NOP Thumb pseudo-instruction Syntax for NOP is ARM DUI 0068B Vector Floating-point Programming Absolute value Vector All Negate Vector All Reference Manual Vector floating-point coprocessorVFP architectures Floating-point registers Register banks Vector stride VectorsVector wrap-around Restriction on vector length Scalar operations Vector and scalar operationsControl of scalar, vector and mixed operations Vector operations VFP and condition codes Vector Floating-point Programming VFP system registers FPSCR, the floating-point status and control register 0b000 Modifying individual bits of a VFP system register FPEXC, the floating-point exception registerFPSID, the floating-point system ID register See FMRX, FMXR, and Fmstat on When to use flush-to-zero mode Flush-to-zero modeEffects of using flush-to-zero mode Operations not affected by flush-to-zero mode FMRX, FMXR, and Fmstat on VFP instructionsFmrrs and Fmsrr on Ftosi and Ftoui onPage Fabsd d3, d5 Fnegsmi s15, s15 Is the VFP register holding the first operand Fadd and FsubIs the VFP register for the result Is the VFP register holding the second operand With zero instruction FcmpFloating-point compare Fcmp is always scalar Fcmp instructions can produce Invalid Operation exceptions Is a double-precision VFP register for the result FcvtdsIs a single-precision VFP register holding the operand Is a single-precision VFP register for the result FcvtsdIs a double-precision VFP register holding the operand Fdiv Precision specified in precision FLD and FSTFloating-point load and store 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 Are ARM registers. Do not use r15 Fmdrr and FmrrdIs the VFP double-precision register These instructions do not produce any exceptions Is the ARM register. Rd must not be r15 FMDHR, FMDLR, FMRDH, and FmrdlThese instructions are used together as matched pairs Fmrs and Fmsr Is the VFP single-precision register Are two consecutive VFP single-precision registers Fmrrs and FmsrrAre the ARM registers. Do not use r15 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 FLD pseudo-instruction VFP pseudo-instructionThere is one VFP 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 GBLA, GBLL, and Gbls on Symbol definition directivesThis section describes the following directives 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 Coprocessor names on 5 CNCN directive defines a name for a coprocessor register 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 DCD and Dcdu on Data definition directivesDCQ and Dcqu on Ltorg Set to this address 2 MAPIs a numeric or program-relative expression During the first pass of the assembler By the value of expr FieldStorage counter Space Expressions on Quoted string. The characters of the string are loaded into 5 DCBTo 255 see Numeric expressions on Consecutive bytes of store Program-relative expression DCD and DcduNumeric expression see Numeric expressions on 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 DCD and Dcdu on DCQ and Dcqu on DCW and DcwuTo 65535 see Numeric expressions on Data Mexit on Assembly control directivesMacro and Mend 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 Address on Frame Register on Frame Restore onFrame description directives 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 Assert Reporting directivesIs an assertion that can evaluate to either True or False Info Is an expression that evaluates to a string 3 OPT Where Is the OPT directive setting. -2 lists valid settingsSpecify the -listassembler option to turn on listing OPT Is the title TTL and SubtIs the subtitle Export or Global on Miscellaneous directivesCODE16 and CODE32 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 Address, or a 32-bit integer constant Is the symbolic name to assign to the value6 EQU Is optional. type can be any one Export or Global Exportas Extern GET or Include Nesting directives on See Export or Global on File, or library. The symbol name is case-sensitiveGlobal Import Include IncbinSee GET or Include on Symbols are kept except register-relative symbols Keep Require Assembly failsNofp Require directive specifies a dependency between sections REQUIRE8 and PRESERVE8 19 RN Evaluates to a register number from 0 to Rout Thumb state See ARM Developer SuiteAmong other things, computer software Platforms See also Saved Processor Status Register Used to find errors in the application program flowDefault thread runs Otherwise stated See Read Only Position Independent See also RopiSee also Rwpi See Read Write Position Independent By ARM to handle semihosting Normally set to zero on resetBlock of software code or data for an Image See Saved Processor Status Register Index Align Gbll Adrl Symbols Index-6