ARM Software Development Toolkit Reference Guide

Version 2.50

Home

ARM Software Development Toolkit Reference Guide

Version 2.50

Copyright © 1997, 1998 ARM Limited. All rights reserved.

Proprietary notices

Table of Contents

About this book

Organization

Further reading

ARM publications
Other publications

Typographical conventions

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.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.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 Figures

3.1. Conventional structure example
6.1. Building blocks for an image
6.2. Load and execution memory maps
6.3. Simple image with one execution region
6.4. Simple image with two execution regions
6.5. Scatter loaded memory map
8.1. Flash Download dialog
8.2. Entering a start address
9.1. Stack backtrace structure
11.1. IEEE single precision floating-point format
11.2. IEEE double precision floating-point format
11.3. Cumulative exception flags byte
11.4. Exception trap enable byte
12.1. Minimal ARMulator model
12.2. Veneer model hierarchy
12.3. Inserting into a cache hierarchy
15.1. Relocation directive

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 A	Jan 1997	Created from ARM DUI 0020. Includes major updates for SDT 2.10
Revision B	June 1997	Updated for SDT 2.11
Revision C	Nov 1998	Updated for SDT 2.50

Copyright © 1997, 1998 ARM Limited. All rights reserved.	ARM DUI 0041C
Non-Confidential
PDF version

Home