ARM Software Development Toolkit Reference Guide

Version 2.50


Table of Contents

Preface
About this book
Organization
Further reading
ARM publications
Other publications
Typographical conventions
Feedback
Feedback on this book
Feedback on the ARM Software Development Toolkit
1. Introduction
1.1. About the ARM Software Development Toolkit
1.1.1. Components of the SDT
1.1.2. Components of C++ version 1.10
1.2. Supported platforms
1.3. What is new?
1.3.1. Functionality enhancements and new functionality
1.3.2. Changes in default behavior
1.3.3. Obsolete and deprecated features
2. The ARM Compilers
2.1. About the ARM compilers
2.1.1. Compiler variants
2.1.2. Source language modes
2.1.3. Compatibility between compilers
2.1.4. Library support
2.2. File usage
2.2.1. Naming conventions
2.2.2. Included files
2.3. Command syntax
2.3.1. Invoking the compiler
2.3.2. Procedure Call Standard options
2.3.3. Setting the source language
2.3.4. Specifying search paths
2.3.5. Setting preprocessor options
2.3.6. Specifying output format
2.3.7. Specifying the target processor and architecture
2.3.8. Generating debug information
2.3.9. Controlling code generation
2.3.10. Controlling warning messages
2.3.11. Specifying additional checks
2.3.12. Controlling error messages
2.3.13. Pragma emulation
3. ARM Compiler Reference
3.1. Compiler-specific features
3.1.1. Pragmas
3.1.2. Function declaration keywords
3.1.3. Variable declaration keywords
3.1.4. Type qualifiers
3.2. C and C++ implementation details
3.2.1. Character sets and identifiers
3.2.2. Basic data types
3.2.3. Operations on basic data types
3.2.4. Structured data types
3.3. Standard C implementation definition
3.3.1. Translation
3.3.2. Environment
3.3.3. Identifiers
3.3.4. Characters
3.3.5. Integers
3.3.6. Floating-point
3.3.7. Arrays and pointers
3.3.8. Registers
3.3.9. Structures, unions, enumerations, and bitfields
3.3.10. Qualifiers
3.3.11. Declarators
3.3.12. Statements
3.3.13. Preprocessing directives
3.3.14. Library functions
3.4. Standard C++ implementation definition
3.4.1. Integral conversion (section 4.7 of the Draft Standard)
3.4.2. Standard C++ library implementation definition
3.5. C and C++ language extensions
3.5.1. C Language Extensions
3.5.2. C and C++ language extensions
3.6. Predefined macros
3.7. Implementation limits
3.7.1. Draft Standard Limits
3.7.2. Internal limits
3.8. Limits for integral numbers
3.9. Limits for floating-point numbers
3.10. C++ language feature support
3.10.1. Major language feature support
3.10.2. Minor language feature support
4. The C and C++ Libraries
4.1. About the runtime libraries
4.1.1. The ANSI C library
4.1.2. The C++ library
4.1.3. The embedded C library
4.1.4. Library naming conventions
4.2. The ANSI C library
4.2.1. Using the ANSI C library
4.2.2. Retargeting the ANSI C library
4.3. The ARM C++ libraries
4.3.1. Using the libraries
4.3.2. Rebuilding the ARM C++ library
4.4. The embedded C library
4.4.1. Embedded C library functions
4.4.2. Embedded C library variants
4.4.3. Callouts from the embedded C library
4.4.4. __rt_trap
4.4.5. __rt_errno_addr
4.4.6. __rt_fp_status_addr
4.4.7. __rt_embeddedalloc_init
4.4.8. __rt_heapdescriptor
4.5. Target-dependent ANSI C library functions
4.5.1. clock
4.5.2. _clock_init
4.5.3. getenv
4.5.4. _getenv_init
4.5.5. remove
4.5.6. rename
4.5.7. system
4.5.8. time
4.6. Target-dependent I/O support functions
4.6.1. _sys_open
4.6.2. _sys_close
4.6.3. _sys_read
4.6.4. _sys_write
4.6.5. _sys_ensure
4.6.6. _sys_flen
4.6.7. _sys_iserror
4.6.8. _sys_istty
4.6.9. _sys_tmpnam
4.6.10. _ttywrch
4.7. Target-dependent kernel functions
4.7.1. __main
4.7.2. __rt_exit
4.7.3. __rt_command_string
4.7.4. __rt_trap
4.7.5. __rt_alloc
4.7.6. __rt_malloc
4.7.7. __rt_free
4.8. Target-dependent operating system functions
4.8.1. __osdep_traphandlers_init
4.8.2. __osdep_traphandlers_finalise
4.8.3. __osdep_heapsupport_init
4.8.4. __osdep_heapsupport_finalise
4.8.5. __osdep_heapsupport_extend
4.8.6. _hostos_error_string
4.8.7. _hostos_signal_string
5. Assembler
5.1. Command syntax
5.2. Format of source lines
5.3. Predefined register and coprocessor names
5.3.1. Predeclared register names
5.3.2. Predeclared program status register names
5.3.3. Predeclared floating-point register names
5.3.4. Predeclared coprocessor names
5.4. Built-in variables
5.5. ARM pseudo-instructions
5.5.1. ADR ARM pseudo-instruction
5.5.2. ADRL ARM pseudo-instruction
5.5.3. LDFD ARM pseudo-instruction
5.5.4. LDFS ARM pseudo-instruction
5.5.5. LDR ARM pseudo-instruction
5.5.6. NOP ARM pseudo-instruction
5.6. Thumb pseudo-instructions
5.6.1. ADR Thumb pseudo-instruction
5.6.2. LDR Thumb pseudo-instruction
5.6.3. MOV Thumb pseudo-instruction
5.6.4. NOP Thumb pseudo-instruction
5.7. Symbols
5.7.1. Symbol naming rules
5.7.2. Variables
5.7.3. Assembly time substitution of variables
5.7.4. Labels
5.7.5. Local labels
5.7.6. Numeric constants
5.8. Directives
5.8.1. Nesting directives
5.8.2. ! directive
5.8.3. # directive
5.8.4. % directive
5.8.5. & directive
5.8.6. * directive
5.8.7. = directive
5.8.8. [ or IF directive
5.8.9. | or ELSE directive
5.8.10. ] or ENDIF directive
5.8.11. ^ or MAP directive
5.8.12. ALIGN directive
5.8.13. AREA directive
5.8.14. ASSERT directive
5.8.15. CN directive
5.8.16. CODE16 directive
5.8.17. CODE32 directive
5.8.18. CP directive
5.8.19. DATA directive
5.8.20. DCB or = directive
5.8.21. DCD or & directive
5.8.22. DCDU directive
5.8.23. DCFD directive
5.8.24. DCFDU directive
5.8.25. DCFS directive
5.8.26. DCFSU directive
5.8.27. DCW directive
5.8.28. DCWU directive
5.8.29. ELSE directive
5.8.30. END directive
5.8.31. ENDIF directive
5.8.32. ENTRY directive
5.8.33. EQU or * directive
5.8.34. EXPORT or GLOBAL directive
5.8.35. EXTERN directive
5.8.36. FN directive
5.8.37. GBLA directive
5.8.38. GBLL directive
5.8.39. GBLS directive
5.8.40. GET or INCLUDE directive
5.8.41. GLOBAL directive
5.8.42. IF directive
5.8.43. IMPORT or EXTERN directive
5.8.44. INCBIN directive
5.8.45. INCLUDE directive
5.8.46. INFO or ! directive
5.8.47. KEEP directive
5.8.48. LCLA directive
5.8.49. LCLL directive
5.8.50. LCLS directive
5.8.51. LTORG directive
5.8.52. MACRO directive
5.8.53. MAP directive
5.8.54. MEND directive
5.8.55. MEXIT directive
5.8.56. NOFP directive
5.8.57. OPT directive
5.8.58. RLIST directive
5.8.59. RN directive
5.8.60. ROUT directive
5.8.61. SETA directive
5.8.62. SETL directive
5.8.63. SETS directive
5.8.64. SUBT directive
5.8.65. TTL directive
5.8.66. WEND directive
5.8.67. WHILE directive
5.9. Expressions and operators
5.9.1. String expressions
5.9.2. Numeric expressions
5.9.3. Register-relative and program-relative expressions
5.9.4. Logical expressions
5.9.5. Unary operators
5.9.6. Binary operators
6. Linker
6.1. About the linker
6.1.1. Input to armlink
6.1.2. Output from armlink
6.2. Command syntax
6.2.1. Summary of armlink options
6.2.2. armlink syntax
6.3. Building blocks for objects and images
6.4. Image file formats
6.4.1. ELF format
6.4.2. AIF format
6.4.3. Plain binary format
6.5. Image structure
6.5.1. Load and execution memory maps of an Image
6.6. Specifying an image memory map
6.6.1. Simple images
6.7. About scatter loading
6.7.1. Symbols defined for scatter loading
6.7.2. Command-line option
6.8. The scatter load description file
6.8.1. Describing the memory map to the linker
6.8.2. Structure of the description file
6.8.3. Resolving multiple matches
6.8.4. Obsolete features
6.9. Area placement and sorting rules
6.9.1. Ordering areas by attribute
6.9.2. Using FIRST and LAST to place areas
6.9.3. Aligning areas
6.10. Linker-defined symbols
6.10.1. Region-related symbols
6.10.2. Section-related symbols
6.10.3. Area-related symbols
6.11. Including library members
6.11.1. Processing the input file list
6.11.2. Including library members
6.12. Automatic inclusion of libraries
6.12.1. For ARM libraries
6.12.2. For Thumb libraries
6.13. Handling relocation directives
6.13.1. The subject field
6.13.2. The relocation value
6.13.3. PC-relative relocation
6.13.4. Additive relocation
6.13.5. Based area relocation
6.13.6. The relocation of instruction sequences
7. ARM Symbolic Debugger
7.1. About armsd
7.1.1. Selecting a debugger
7.1.2. Automatic command execution on startup
7.2. Command syntax
7.2.1. Command-line options
7.3. Running armsd
7.3.1. Symbols
7.3.2. Controlling execution
7.3.3. Reading and writing memory
7.3.4. Program context
7.3.5. Low-level debugging
7.3.6. Coprocessor support
7.3.7. Profiling commands
7.3.8. Miscellaneous commands
7.4. Alphabetical list of armsd commands
7.4.1. Annotating the command syntax
7.4.2. Names used in syntax descriptions
7.4.3. ! command
7.4.4. | command
7.4.5. alias
7.4.6. arguments
7.4.7. backtrace
7.4.8. break
7.4.9. call
7.4.10. coproc
7.4.11. context
7.4.12. cregisters
7.4.13. cregdef
7.4.14. cwrite
7.4.15. examine
7.4.16. find
7.4.17. fpregisters
7.4.18. go
7.4.19. getfile
7.4.20. help
7.4.21. in
7.4.22. istep
7.4.23. language
7.4.24. let
7.4.25. list
7.4.26. load
7.4.27. log
7.4.28. lsym
7.4.29. obey
7.4.30. out
7.4.31. pause
7.4.32. print
7.4.33. profclear
7.4.34. profoff
7.4.35. profon
7.4.36. profwrite
7.4.37. putfile
7.4.38. quit
7.4.39. readsyms
7.4.40. registers
7.4.41. reload
7.4.42. return
7.4.43. step
7.4.44. symbols
7.4.45. type
7.4.46. unbreak
7.4.47. unwatch
7.4.48. variable
7.4.49. watch
7.4.50. where
7.4.51. while
7.5. Specifying source-level objects
7.5.1. Variable names and context
7.5.2. Program locations
7.5.3. Expressions
7.5.4. Constants
7.6. Armsd variables
7.6.1. Summary of armsd variables
7.6.2. Accessing variables
7.6.3. Formatting integer results
7.6.4. Specifying the base for input of integer constants
7.7. Low-level debugging
7.7.1. Low-level symbols
7.7.2. Predefined symbols
7.8. armsd commands for EmbeddedICE
7.8.1. listconfig
7.8.2. loadagent
7.8.3. loadconfig
7.8.4. readsyms
7.8.5. selectconfig
7.9. Accessing the Debug Communications Channel
7.9.1. ccin
7.9.2. ccout
8. Toolkit Utilities
8.1. Functions of the toolkit utilities
8.2. The fromELF utility
8.2.1. fromELF command-line options
8.2.2. Multiple output formats
8.2.3. Image structure
8.3. ARM profiler
8.3.1. Profiler command-line options
8.3.2. Sample output
8.4. ARM librarian
8.4.1. Librarian command-line options
8.4.2. Examples
8.5. ARM object file decoder
8.5.1. Object file decoder command-line options
8.5.2. Example
8.6. ARM executable format decoder
8.6.1. Executable file decoder command-line options
8.6.2. Examples
8.7. ANSI to PCC C Translator
8.7.1. ANSI to PCC C command-line options
8.7.2. Translation details
8.7.3. Issues with topcc
8.8. The Flash downloader
8.8.1. The Flash downloader
9. ARM Procedure Call Standard
9.1. About the ARM Procedure Call Standard
9.1.1. APCS variants
9.2. APCS definition
9.2.1. APCS conformance
9.2.2. APCS register names and roles
9.2.3. The stack
9.2.4. The stack backtrace data structure
9.2.5. Function invocations and stack backtrace structures
9.2.6. Control arrival
9.2.7. Data representation and argument passing
9.2.8. Control return
9.3. C language calling conventions
9.3.1. Argument representation
9.3.2. Argument list marshalling
9.3.3. Non-simple value return
9.4. Function entry examples
9.4.1. Definitions
9.4.2. Establishing the static base
9.4.3. Creating the stack backtrace structure
9.4.4. Saving and restoring floating-point registers
9.4.5. Checking for stack limit violations
9.5. Function exit
10. Thumb Procedure Call Standard
10.1. About the Thumb Procedure Call Standard
10.2. TPCS definition
10.2.1. TPCS register names
10.2.2. The Stack
10.2.3. Control arrival
10.2.4. Data representation and argument passing
10.2.5. Control return
10.3. C language calling conventions
10.3.1. Argument representation
10.3.2. Argument list marshalling
10.3.3. Non-simple value return
10.4. Function entry examples
10.4.1. Definitions
10.4.2. Simple function entry
10.4.3. Checking for stack limit violations
10.5. Function exit
11. Floating-point Support
11.1. About floating-point support
11.1.1. Thumb
11.2. The ARM floating-point library
11.2.1. Usage
11.2.2. Combining hardfp and softfp systems
11.2.3. Floating-point library register usage
11.2.4. Type formats
11.3. Floating-point instructions
11.3.1. Floating-point data transfer: LDF and STF
11.3.2. Floating-point register transfer: FLT and FIX
11.3.3. Floating-point register transfer: status and control
11.3.4. Floating-point multiple data transfer: LFM and SFM
11.3.5. Floating-point comparisons: CMF and CNF
11.3.6. Floating-point binary operations
11.3.7. Floating-point unary operations
11.4. Configuring the FPA support code for a new environment
11.5. Controlling floating-point exceptions
11.5.1. Return value
11.5.2. Example
12. ARMulator
12.1. About the ARMulator
12.2. Modeling an ARM-based system
12.2.1. Model stubs
12.2.2. The ARMul_State state pointer
12.2.3. Handling armsd map files
12.2.4. Configuring models through ToolConf
12.2.5. ToolConf_Lookup
12.2.6. ToolConf_Cmp
12.3. Basic model interface
12.3.1. Late basic models
12.3.2. Early basic models
12.3.3. Basic model initialization function
12.3.4. ARMul_InstallMemoryInterface
12.4. The memory interface
12.4.1. Memory type variants
12.5. Memory model interface
12.5.1. Memory model initialization function
12.5.2. armul_ReadClock
12.5.3. armul_GetCycleLength
12.5.4. armul_ReadCycles
12.5.5. armul_MemAccess
12.5.6. ARMul_SetMemSize
12.5.7. ARMul_GetMemSize
12.6. Coprocessor model interface
12.6.1. The ARMul_CPInterface structure
12.6.2. ARMul_CoProAttach
12.6.3. init
12.6.4. ldc
12.6.5. stc
12.6.6. mrc
12.6.7. mcr
12.6.8. cdp
12.6.9. read
12.6.10. write
12.7. Operating system or debug monitor interface
12.7.1. The ARMul_OSInterface structure
12.7.2. init
12.7.3. handle_swi
12.7.4. exception
12.8. Using the floating-point emulator (FPE)
12.8.1. ARMul_FPEInstall
12.8.2. ARMul_FPEVersion
12.8.3. ARMul_FPEAddressInEmulator
12.9. Accessing ARMulator state
12.9.1. ARMul_GetMode
12.9.2. ARMul_GetReg
12.9.3. ARMul_SetReg
12.9.4. ARMul_GetR15 and ARMul_GetPC
12.9.5. ARMul_SetR15 and ARMul_SetPC
12.9.6. ARMul_GetCPSR
12.9.7. ARMul_SetCPSR
12.9.8. ARMul_GetSPSR
12.9.9. ARMul_SetSPSR
12.9.10. ARMul_CPRegBytes
12.9.11. ARMul_CPRead
12.9.12. ARMul_CPWrite
12.9.13. ARMul_SetConfig
12.10. Exceptions
12.10.1. ARMul_SetNirq and ARMul_SetNfiq
12.10.2. ARMul_SetNreset
12.10.3. ARMul_SWIHandler
12.11. Upcalls
12.11.1. Installing and removing upcalls
12.11.2. ExitUpcall
12.11.3. ModeChangeUpcall
12.11.4. TransChangeUpcall
12.11.5. ConfigChangeUpcall
12.11.6. InterruptUpcall
12.11.7. ExceptionUpcall
12.11.8. UnkRDIInfoUpcall
12.12. Memory access functions
12.12.1. Reading from a given address
12.12.2. Writing to a specified address
12.13. Event scheduling functions
12.13.1. armul_Hourglass
12.13.2. ARMul_HourglassSetRate
12.13.3. ARMul_ScheduleEvent
12.13.4. ARMul_ScheduleCoreEvent
12.14. ARMulator specific functions
12.14.1. ARMul_RaiseError
12.14.2. ARMul_Time
12.14.3. ARMul_Properties
12.14.4. ARMul_CondCheckInstr
12.14.5. ARMul_AddCounterDesc
12.14.6. ARMul_AddCounterValue
12.14.7. ARMul_HaltEmulation
12.14.8. ARMul_EndCondition
12.14.9. ARMul_DoProg
12.14.10. ARMul_DoInstr
12.15. Accessing the debugger
12.15.1. ARMul_DebugPrint
12.15.2. ARMul_ConsolePrint
12.15.3. ARMul_PrettyPrint
12.15.4. ARMul_DebugPause
12.15.5. ARMul_RDILog
12.15.6. ARMul_HostIf
12.16. Events
12.16.1. armul_EventUpcall
12.16.2. ARMul_RaiseEvent
13. ARM Image Format
13.1. Overview of the ARM Image Format
13.2. AIF variants
13.3. The layout of AIF
13.3.1. AIF image layout
13.3.2. Debugging data
13.3.3. AIF header
14. ARM Object Library Format
14.1. Overview of ARM Object Library Format
14.2. Endianness and alignment
14.2.1. Alignment
14.3. Library file format
14.3.1. Earlier versions of ARM object library format
14.3.2. LIB_DIRY
14.3.3. LIB_VRSN
14.3.4. LIB_DATA
14.4. Time stamps
14.4.1. LIB_TIME
14.5. Object code libraries
14.5.1. OFL_SYMT
14.5.2. OFL_TIME
15. ARM Object Format
15.1. ARM Object Format
15.1.1. Areas
15.1.2. Relocation directives
15.1.3. Byte sex or endianness
15.1.4. Alignment
15.2. Overall structure of an AOF file
15.2.1. Chunk file format
15.2.2. ARM object format
15.3. The AOF header chunk (OBJ_HEAD)
15.3.1. Attributes and alignment
15.4. The AREAS chunk (OBJ_AREA)
15.5. Relocation directives
15.6. Symbol Table Chunk Format (OBJ_SYMT)
15.6.1. Symbol attributes
15.7. The String Table Chunk (OBJ_STRT)
15.8. The Identification Chunk (OBJ_IDFN)

List of Tables

2.1. Include file search paths
3.1. Pragmas
3.2. Escape codes
3.3. Size and alignment of data types
3.4. Character codes
3.5. Mathematical functions
3.6. Signal function signals
3.7. perror() messages
3.8. Standard C++ library support
3.9. Predefined macros
3.10. Implementation limits
3.11. Internal limits
3.12. Integer ranges
3.13. Floating-point limits
3.14. Other floating-point characteristics
3.15. Major language feature support
3.16. Minor language feature support
4.1. Precompiled Thumb library variants
4.2. Precompiled ARM library variants
4.3. C library subdirectories
4.4. Supported C library functions
5.1. Directives and pseudo-instructions
5.2. Built-in variables
5.3. OPT directive settings
5.4. Operator precedence
5.5. Multiplicative operators
5.6. String manipulation operators
5.7. Shift operators
5.8. Addition and logical operators
5.9. Relational operators
5.10. Boolean operators
6.1. Comparing load and execution
6.2. Scatter load description
6.3. Region-related linker symbols
6.4. Additional symbols for ZI sections
6.5. Section-related linker symbols
6.6. Area-related linker symbols
7.1. Format descriptors
7.2. Values for displaydesc argument
7.3. Precedence of operators
7.4. armsd variables
7.5. armsd variables for EmbeddedICE
7.6. High-level symbols for low-level entities
9.1. APCS registers
9.2. APCS floating-point registers
9.3. Function exit
10.1. TPCS registers
11.1. Floating point library functions
11.2. Status register bit operations
12.1. Defined processor modes
12.2. Configuration bits and signals
12.3. Events from ARM processor core
12.4. Events from MMU and cache (not on StrongARM-110)
12.5. Events from prefetch unit (ARM810 only)
13.1. AIF header layout
14.1. Library File Chunks
14.2. The LIB_DIRY chunk
14.3. OFL_SYMT chunk layout
15.1. AOF chunks
15.2. Area attributes summary
15.3. Symbol attributes

Proprietary Notice

ARM, Thumb, StrongARM, and the ARM Powered logo are registered trademarks of ARM Limited.

Angel, ARMulator, EmbeddedICE, Multi-ICE, ARM7TDMI, ARM9TDMI, and TDMI are trademarks of ARM Limited.

All other products or services mentioned herein may be trademarks of their respective owners.

Neither the whole nor any part of the information contained in, or the product described in, this document may be adapted or reproduced in any material form except with the prior written permission of the copyright holder.

The product described in this document is subject to continuous developments and improvements. All particulars of the product and its use contained in this document are given by ARM in good faith. However, all warranties implied or expressed, including but not limited to implied warranties of merchantability, or fitness for purpose, are excluded.

This document is intended only to assist the reader in the use of the product. ARM Limited shall not be liable for any loss or damage arising from the use of any information in this document, or any error or omission in such information, or any incorrect use of the product.

Revision History
Revision AJan 1997Created from ARM DUI 0020. Includes major updates for SDT 2.10
Revision BJune 1997Updated for SDT 2.11
Revision CNov 1998Updated for SDT 2.50
Copyright © 1997, 1998 ARM Limited. All rights reserved.ARM DUI 0041C
Non-Confidential