RealView ® CompilationTools Compiler and Libraries Guide

Version 2.2


Table of Contents

Preface
About this book
Intended audience
Using this book
Typographical conventions
Further reading
Feedback
Feedback on RealView Compilation Tools
Feedback on this book
1. Introduction
1.1. About RVCT
1.1.1. Using the examples
1.2. The ARM compiler and libraries
1.2.1. The ARM compiler
1.2.2. The C and C++ libraries
1.2.3. Compatibility with legacy objectsand libraries
2. Using the ARM Compiler
2.1. About the ARM compiler
2.1.1. Standards and compatibility
2.1.2. Invoking the ARM compiler
2.1.3. Multifile compilation
2.1.4. Linker feedback
2.1.5. Inline and embedded assembly language
2.1.6. Semihosting
2.1.7. Library support
2.2. File usage
2.2.1. Naming conventions
2.2.2. Included files
2.2.3. Precompiled header files
2.3. armcc command syntax
2.3.1. Command-line options
2.3.2. Invoking the ARMcompiler
2.3.3. Setting the sourcelanguage
2.3.4. Specifying search paths
2.3.5. PCH processing options
2.3.6. Setting preprocessor options
2.3.7. Syntax-checking
2.3.8. C++ Language configuration and objectgeneration
2.3.9. Specifying output format
2.3.10. Specifying the target processor orarchitecture
2.3.11. Generating debug information
2.3.12. Controlling code generation
2.3.13. Adding symbol versions
2.3.14. Default object extension
2.3.15. Diagnostic messages
2.3.16. Using AAPCS options
3. ARM Compiler Reference
3.1. Compiler-specific features
3.1.1. Pragmas
3.1.2. Function keywords
3.1.3. Operators
3.1.4. Intrinsic functions
3.1.5. Variable declarationkeywords
3.1.6. Eight-byte alignment features
3.2. Language extensions
3.2.1. C and C++ language extensions
3.2.2. C language extensions
3.2.3. C++ language extensions
3.3. C and C++ implementation details
3.3.1. Character sets and identifiers
3.3.2. Basic data types
3.3.3. Operations on basic data types
3.3.4. Structures, unions,enumerations, and bitfields
3.3.5. Variadic macros
3.3.6. Using the ::operator new function
3.3.7. Tentative arrays
3.3.8. Old-style C parameters in C++ functions
3.3.9. Anachronisms
3.3.10. Template instantiation
3.3.11. Namespaces
3.3.12. C++ exception handling
3.3.13. Extern inline functions
3.4. GNU extensions to the ARM compiler
3.4.1. Alignment
3.4.2. Alternate keywords
3.4.3. Assembler labels
3.4.4. Attribute syntax
3.4.5. Builtin functions
3.4.6. C++ comments
3.4.7. Case ranges
3.4.8. Cast of a union
3.4.9. Character escapes
3.4.10. Compound literals
3.4.11. Conditionals
3.4.12. Designated inits
3.4.13. Dollar signs
3.4.14. Function attributes
3.4.15. Function names
3.4.16. Function prototypes
3.4.17. Hex floats
3.4.18. Incomplete enums
3.4.19. Initializers
3.4.20. Inline
3.4.21. Local labels
3.4.22. Long long
3.4.23. Lvalues
3.4.24. Multiline strings
3.4.25. Pointer arithmetic
3.4.26. Return and frame addresses
3.4.27. Statement expressions
3.4.28. Subscripting struct
3.4.29. Type attributes
3.4.30. typeof
3.4.31. Unnamed fields
3.4.32. Variable attributes
3.4.33. Variadic macros
3.4.34. Zero length arrays
3.5. Predefined macros
4. Inline and Embedded Assemblers
4.1. Inline assembler
4.1.1. Inline assembler syntax
4.1.2. Restrictions on inline assembly operations
4.1.3. Virtual registers
4.1.4. Constants
4.1.5. Instruction expansion
4.1.6. Condition flags
4.1.7. Operands
4.1.8. Function calls and branches
4.1.9. Labels
4.1.10. Differences from previous versionsof the ARM C/C++ compilers
4.2. Embedded assembler
4.2.1. Embedded assembler syntax
4.2.2. Restrictions on embedded assembly
4.2.3. Differences between expressions inembedded assembly and C or C++
4.2.4. Generation of embedded assembly functions
4.2.5. The __cpp keyword
4.2.6. Manual overloadresolution
4.2.7. Keywords for related base classes
4.2.8. Keywords for member function classes
4.2.9. Calling non-static member functions
4.2.10. Differences from previous versionsof the ARM C/C++ compilers
4.3. Legacy inline assembler that accessessp, lr, or pc
4.3.1. Accessing sp (r13), lr (r14), andpc (r15) in legacy code
4.4. Differences between inline and embeddedassembly code
5. The C and C++ Libraries
5.1. About the runtime libraries
5.1.1. Features of the C andC++ libraries
5.1.2. Namespaces
5.1.3. Build options and libraryvariants
5.1.4. Library directorystructure
5.1.5. Using the VFP supportlibraries
5.1.6. Thumb C libraries
5.2. Writing reentrant and thread-safecode
5.2.1. Introduction to reentrancy and thread-safety
5.2.2. Use of static data in the C libraries
5.2.3. The __user_libspace static data area
5.2.4. Managing locks in multithreaded applications
5.2.5. Using the ARM C libraries with a multithreadedapplication
5.2.6. Thread-safety in the ARM C libraries
5.2.7. Thread-safety in theARM C++ libraries
5.3. Building an application with the Clibrary
5.3.1. Using the libraries with an application
5.3.2. Building an application for a semihostedenvironment
5.3.3. Building an application for a nonsemihostedenvironment
5.4. Building an application without theC library
5.4.1. Integer and FP helper functions
5.4.2. Bare machine integer C
5.4.3. Bare machine C with floating-point
5.4.4. Exploiting the C library
5.4.5. The standalone C library functions
5.5. Tailoring the C library to a new executionenvironment
5.5.1. How C and C++ programs use the libraryfunctions
5.5.2. __rt_entry
5.5.3. Exiting from the program
5.5.4. __rt_exit()
5.5.5. __rt_lib_init()
5.5.6. __rt_lib_shutdown()
5.6. Tailoring static data access
5.7. Tailoring locale and CTYPE
5.7.1. Selecting locale at link time
5.7.2. Selecting locale at runtime
5.7.3. Macros and utility functions
5.7.4. _get_lc_ctype()
5.7.5. _get_lc_collate()
5.7.6. _get_lc_monetary()
5.7.7. _get_lc_numeric()
5.7.8. _get_lc_time()
5.7.9. _get_lconv()
5.7.10. localeconv()
5.7.11. setlocale()
5.7.12. _findlocale()
5.7.13. __LC_CTYPE_DEF
5.7.14. __LC_COLLATE_DEF
5.7.15. __LC_TIME_DEF
5.7.16. __LC_NUMERIC_DEF
5.7.17. __LC_MONETARY_DEF
5.7.18. __LC_INDEX_END
5.7.19. The lconv structure
5.8. Tailoring error signaling, error handling,and program exit
5.8.1. _sys_exit()
5.8.2. errno
5.8.3. __rt_errno_addr()
5.8.4. __raise()
5.8.5. __rt_raise()
5.8.6. __default_signal_handler()
5.8.7. _ttywrch()
5.8.8. __rt_fp_status_addr()
5.9. Tailoring storage management
5.9.1. Avoiding the ARM-suppliedheap and heap-using functions
5.9.2. Support for malloc
5.9.3. Creating your own storage-managementsystem
5.9.4. __Heap_Descriptor
5.9.5. __Heap_Initialize()
5.9.6. __Heap_DescSize()
5.9.7. __Heap_ProvideMemory()
5.9.8. __Heap_Alloc()
5.9.9. __Heap_Free()
5.9.10. __Heap_Realloc()
5.9.11. __Heap_Stats()
5.9.12. __Heap_Valid()
5.9.13. __Heap_Full()
5.9.14. __Heap_Broken()
5.10. Tailoring the runtime memory model
5.10.1. The memory models
5.10.2. Controlling the runtime memory model
5.10.3. Writing your own memory model
5.10.4. __user_initial_stackheap()
5.10.5. __user_heap_extend()
5.10.6. __user_heap_extent()
5.10.7. __user_stack_slop()
5.10.8. __rt_stackheap_init()
5.10.9. __rt_stack_overflow()
5.10.10. __rt_heap_extend()
5.10.11. __rt_stack_postlongjmp()
5.11. Tailoring the input/output functions
5.11.1. Dependencies on low-levelfunctions
5.11.2. Target-dependent input/outputsupport functions
5.11.3. _sys_open()
5.11.4. _sys_close()
5.11.5. _sys_read()
5.11.6. _sys_write()
5.11.7. _sys_ensure()
5.11.8. _sys_flen()
5.11.9. _sys_seek()
5.11.10. _sys_istty()
5.11.11. _sys_tmpnam()
5.11.12. _sys_command_string()
5.12. Tailoring other C library functions
5.12.1. clock()
5.12.2. _clock_init()
5.12.3. time()
5.12.4. remove()
5.12.5. rename()
5.12.6. system()
5.12.7. getenv()
5.12.8. _getenv_init()
5.13. Selecting real-time division
5.14. ISO implementation definition
5.14.1. ISO C library implementation definition
5.14.2. Standard C++ libraryimplementation definition
5.15. C library extensions
5.15.1. atoll()
5.15.2. strtoll()
5.15.3. strtoull()
5.15.4. printf()
5.15.5. snprintf()
5.15.6. vsnprintf()
5.15.7. lldiv()
5.15.8. llabs()
5.15.9. alloca()
5.15.10. _fisatty()
5.15.11. __heapstats()
5.15.12. __heapvalid()
5.16. Library naming conventions
6. Floating-point Support
6.1. About floating-point support
6.2. The software floating-point library,fplib
6.2.1. Features of the floating-point library,fplib
6.2.2. Arithmetic on numbersin a particular format
6.2.3. Conversions betweenfloats, doubles, and ints
6.2.4. Conversions between long longs andother number formats
6.2.5. Floating-point comparisons
6.2.6. C99 functions
6.3. Controlling the floating-point environment
6.3.1. __ieee_status()
6.3.2. __fp_status()
6.3.3. Microsoft compatibility functions
6.3.4. C99 compatible functions
6.3.5. ARM compiler extensions to the C99interface
6.4. The math library, mathlib
6.4.1. Range reduction in mathlib
6.4.2. Determine the typeof a floating-point number (fpclassify)
6.4.3. Determine if a numberis finite (isfinite)
6.4.4. Determine if a numberis infinite (isinf)
6.4.5. Determine if anumber is a NaN (isnan)
6.4.6. Determine if a numberis normal (isnormal)
6.4.7. Return the signbit of a number (signbit)
6.4.8. Copy sign functions(copysign, copysignf)
6.4.9. Comparison macros(isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered)
6.4.10. Inverse hyperbolicfunctions (acosh, asinh, atanh)
6.4.11. Cube root (cbrt)
6.4.12. Error functions (erf, erfc)
6.4.13. One less than exp(x )(expm1)
6.4.14. Gamma function (gamma, gamma_r)
6.4.15. Hypotenuse function (hypot)
6.4.16. Bessel functions of the first kind(j0, j1, jn)
6.4.17. The logarithm of the gamma function(lgamma, lgamma_r)
6.4.18. Logarithm of onemore than x (log1p)
6.4.19. IEEE 754 remainder function (remainder)
6.4.20. IEEE round-to-integeroperation (rint)
6.4.21. Return the fraction part of a number(significand)
6.4.22. Bessel functions of the second kind(y0, y1, yn)
6.4.23. Legacy, Exponentof a number (ilogb, ilogbf, ilogbl)
6.4.24. Legacy, Determineif a number is finite (finite)
6.4.25. Legacy, Determineif a number is a NaN (isnan)
6.5. IEEE 754 arithmetic
6.5.1. Basic data types
6.5.2. Arithmetic and rounding
6.5.3. Exceptions
7. Semihosting
7.1. About semihosting
7.1.1. What is semihosting?
7.1.2. The SWI interface
7.2. Semihosting implementation
7.2.1. RealView ARMulator ISS
7.2.2. RealView ICE
7.2.3. Multi-ICE
7.2.4. RealMonitor
7.2.5. Angel
7.3. Semihosting SWIs
7.3.1. SYS_OPEN (0x01)
7.3.2. SYS_CLOSE (0x02)
7.3.3. SYS_WRITEC (0x03)
7.3.4. SYS_WRITE0 (0x04)
7.3.5. SYS_WRITE (0x05)
7.3.6. SYS_READ (0x06)
7.3.7. SYS_READC (0x07)
7.3.8. SYS_ISERROR (0x08)
7.3.9. SYS_ISTTY (0x09)
7.3.10. SYS_SEEK (0x0A)
7.3.11. SYS_FLEN (0x0C)
7.3.12. SYS_TMPNAM (0x0D)
7.3.13. SYS_REMOVE (0x0E)
7.3.14. SYS_RENAME (0x0F)
7.3.15. SYS_CLOCK (0x10)
7.3.16. SYS_TIME (0x11)
7.3.17. SYS_SYSTEM (0x12)
7.3.18. SYS_ERRNO (0x13)
7.3.19. SYS_GET_CMDLINE(0x15)
7.3.20. SYS_HEAPINFO (0x16)
7.3.21. SYS_ELAPSED (0x30)
7.3.22. SYS_TICKFREQ (0x31)
7.4. Debug agent interaction SWIs
7.4.1. angel_SWIreason_EnterSVC (0x17)
7.4.2. angel_SWIreason_ReportException (0x18)
A. Via File Syntax
A.1. Overview of via files
A.1.1. Via file evaluation
A.2. Syntax
B. Standard C Implementation Definition
B.1. Implementation definition
B.1.1. Translation
B.1.2. Environment
B.1.3. Identifiers
B.1.4. Characters
B.1.5. Integers
B.1.6. Floating-point
B.1.7. Arrays and pointers
B.1.8. Registers
B.1.9. Structures, unions, enumerations,and bitfields
B.1.10. Qualifiers
B.1.11. Declarators
B.1.12. Statements
B.1.13. Preprocessing directives
B.1.14. Library functions
C. Standard C++ Implementation Definition
C.1. Integral conversion
C.2. Calling a pure virtual function
C.3. Major features of language support
C.4. Standard C++ library implementationdefinition
D. C and C++ Compiler Implementation Limits
D.1. C++ ISO/IEC standard limits
D.2. Internal limits
D.3. Limits for integral numbers
D.4. Limits for floating-point numbers
E. Using Older Options
E.1. Mapping old compiler options to thenew release
E.1.1. Warning messages in RVCT v2.2
E.1.2. Getting more information
Glossary

List of Tables

2.1. Startup configuration based on old tool names
2.2. Startup configuration as adjusted by filename extension
2.3. Startup configuration as adjusted by overriding options
2.4. Example configuration
2.5. Include file search paths
2.6. Severity of diagnostic messages
3.1. Pragmas recognized by the ARM compiler
3.2. Character escape codes
3.3. Size and alignment of data types
3.4. Supported GNU extensions
3.5. Predefined macros
4.1. Differences between inline and embedded assembler
5.1. Functions that are thread-safe
5.2. Functions that are not thread-safe
5.3. Direct semihosting SWI dependencies
5.4. Indirect semihosting SWI dependencies
5.5. Published API definitions
5.6. C library callouts
5.7. Default ISO8859-1 locales
5.8. Default Shift-JIS and UTF-8 locales
5.9. Implementing locale categories
5.10. Macros and functions for locale blocks
5.11. Trap and error handling
5.12. Heap functions
5.13. Memory model initialization
5.14. Memory model functions
5.15. Input/output dependencies
5.16. I/O support functions
5.17. ISO C library functions
5.18. Mathematical functions
5.19. Signal functions
5.20. perror() messages
5.21. C++ requirements on the C library
5.22. Standard C++ library differences
5.23. C library extensions
6.1. Arithmetic routines
6.2. Number format conversion routines
6.3. Conversion routines involving long long format
6.4. Floating-point comparison routines
6.5. C99 routines
6.6. Status word bit modification
6.7. Rounding mode control
6.8. _controlfp argument macros
6.9. FE_EX_INTYPE_MASK operand type flags
6.10. FE_EX_OUTTYPE_MASK operand type flags
6.11. FE_EX_FN_MASK operation type flags
6.12. FE_EX_CMPRET_MASK comparison type flags
6.13. Comparison macros
6.14. Sample single-precision floating-point values
6.15. Sample double-precision floating-point values
7.1. Semihosting SWIs
7.2. Value of mode
7.3. Hardware vector reason codes
7.4. Software reason codes
C.1. Major feature support for language
D.1. Implementation limits
D.2. Internal limits
D.3. Integer ranges
D.4. Floating-point limits
D.5. Other floating-point characteristics
E.1. Mapping of compiler options

Proprietary Notice

Words and logos marked with ® or ™ are registered trademarks or trademarksowned by ARM Limited. Other brands and names mentioned herein maybe the trademarks of their respective owners.

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

The product described in this document is subject to continuousdevelopments and improvements. All particulars of the product andits use contained in this document are given by ARM in good faith.However, all warranties implied or expressed, including but notlimited to implied warranties of merchantability, or fitness forpurpose, are excluded.

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

ConfidentialityStatus

This document is Non-Confidential. The right to use, copyand disclose this document may be subject to license restrictionsin accordance with the terms of the agreement entered into by ARMand the party that ARM delivered this document to.

Product Status

The information in this document is final, that is for a developedproduct.

Revision History
Revision A August2002 Release 1.2
Revision B January2003 Release 2.0
Revision C September2003 Release 2.0.1 for RVDS v2.0
Revision D January2004 Release 2.1 for RVDS v2.1
Revision E December2004 Release 2.2 for RVDS v2.2
Revision F May2005 Release 2.2 for RVDS v2.2 SP1
Copyright © 2002-2005 ARM Limited. All rights reserved. ARM DUI 0205F
Non-Confidential