ARM Software Development Toolkit Version 2.11 Reference Guide Document Number: ARM DUI 0041B Issued: June 1997 Copyright Advanced RISC Machines Ltd (ARM) 1997 ENGLAND GERMANY Advanced RISC Machines Limited Advanced RISC Machines Limited Beta Draft Fulbourn Road Otto-Hahn Str. 13b Cherry Hinton 85521 Ottobrunn-Riemerling Cambridge CB1 4JN Munich England Germany Telephone:+44 1223 400400 Telephone:+49 (0) 89 608 75545 Facsimile:+44 1223 400410 Facsimile:+49 (0) 89 608 75599 Email:[email protected] Email:[email protected] JAPAN USA Advanced RISC Machines K.K. ARM USA Incorporated KSP West Bldg, 3F 300D, 3-2-1 Sakado Suite 5 Takatsu-ku, Kawasaki-shi 985 University Avenue Kanagawa Los Gatos 213 Japan CA 95030 USA Telephone:+81 44 850 1301 Telephone:+1 408 399 5199 Facsimile:+81 44 850 1308 Facsimile:+1 408 399 8854 Email:[email protected] Email:[email protected] World Wide Web Address: http://www.arm.com Proprietary Notice 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 or merchantability, or fitness for purpose, are excluded. This document is intended only to assist the reader in the use of the product. ARM Ltd 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. Trademarks ARM, the ARM Powered logo, and EmbeddedICE are trademarks of Advanced RISC Machines Ltd. Windows 95 is a registered trademark of Microsoft Corporation. Windows NT is a trademark of Microsoft Corporation. Change Log Issue Date By Change A Jan 97 BJH Created from ARM DUI 0020; includes major updates for SDT 210. B June 97 BJH Updated for SDT 211. Beta Draft ii Reference Manual ARM DUI 0041B Preface This preface introduces the ARM Software Development Toolkit and its documentation. About This Manual iv Typographical Conventions v Release Components vi Feedback vii Reference Guide Preface-iii ARM DUI 0041B Preface About This Manual Overview This manual covers the following topics: • the components of the ARM Software Development Toolkit • reference information on each of the ARM Software Tools • procedure call standards • file formats Note This manual does not cover device-specific issues. Please refer to the appropriate ARM device datasheet. Organization This Reference Guide is organized into the following parts: Part 1 Toolkit Reference Gives reference information on the individual tools in the toolkit. For example: file-naming conventions, command-line options, variables, procedure call standards, and utilities. Part 2 Debug Reference Gives reference information on ARM’s debugging tools. For example: Angel, ARMulators, and ARM Symbolic Debugger. Part 3 File Format Reference Gives information on the file formats in use in the toolkit. For example: ARM Object Format, ARM Image Format, ARM Object Library Format, ELF. Preface-iv Reference Guide ARM DUI 0041B Preface Typographical Conventions Typographical conventions The following typographical conventions are used in this manual: typewriter Denotes text that may be entered at the keyboard: commands, file and program names, and assembler and C source. typewriter Denotes a permitted abbreviation for a command or option. The underlined text may be entered instead of the full command or option name. typewriter-italic Shows text which must be substituted with user-supplied information. This is most often used in syntax descriptions. Oblique Highlights important notes and ARM-specific terminology. Thumb Boxes like this contain information that applies specifically to Thumb-aware variants of the ARM Software Development Toolkit. Filenames Unless otherwise stated, filenames are quoted in MS-DOS format, for example: EXAMPLES\BASICASM\GCD1.S If you are using the UNIX platform, you must translate them into their UNIX equivalent: examples/basicasm/gcd1.s Reference Guide Preface-v ARM DUI 0041B Preface Release Components Programming and modeling tools The following tools are described in full in the relevant chapters of this manual. Please note that your release of the Toolkit may not include all the tools mentioned below; see the Release Notes for a definitive list of the tools supplied with your release. armcc The ARM C compiler See Chapter 1, C Compilers tcc The Thumb C compiler See Chapter 1, C Compilers armasm The ARM assembler See Chapter 2, Assembler tasm The Thumb assembler See Chapter 2, Assembler armlink The ARM linker See Chapter 3, Linker decaof The ARM–Thumb object-file decoder/ See Chapter 7, Toolkit Utilities disassembler decaxf The ARM Executable format decoder. See Chapter 7, Toolkit Utilities armlib The ARM object-file librarian See Chapter 7, Toolkit Utilities armsd The ARM command-line debugger See Chapter 10, ARM Debugger Retargetable libraries Three retargetable libraries are supplied: • The ARM ANSI C library, supplied in both source form and as an object library. • The ARM embedded C library, supplied in both source form and as an object library. For further information see Chapter 4, Rebuilding the C Library. Thumb The Thumb 16-bit ANSI C library is provided as an object library in both little-endian and big-endian forms. Preface-vi Reference Guide ARM DUI 0041B Preface Feedback Feedback on the ARM Software Development Toolkit If you have comments or suggestions about the ARM Software Development Toolkit, please contact your supplier, giving: • details of which platform and release of the ARM software tools you are using • a small sample code fragment which illustrates your comment • precise description of your comment or suggestion Feedback on this manual If you have feedback on this manual, please contact your supplier, giving: • the manual’s title • the manual’s document number • the page number(s) to which your comments refer • a concise explanation of the comment General suggestions for additions and improvements are also welcome. Reference Guide Preface-vii ARM DUI 0041B Contents Preface iii Part 1: Tools Reference 1 C Compilers 1-1 1.1 Introduction 1-2 1.2 About the ARM C Compilers 1-3 1.3 File Usage 1-4 1.4 Command Syntax 1-7 1.5 Implementation Details 1-20 1.6 Standard Implementation Definition 1-27 1.7 C Language Extensions 1-40 1.8 Inline Assembler 1-41 1.9 Compiler-specific Features 1-46 Reference Guide Contents-i ARM DUI 0041B Contents 2 Assembler 2-1 2.1 Overview 2-2 2.2 Command Syntax 2-2 2.3 Assembly Language Overview 2-6 2.4 Expressions and Operators 2-13 2.5 Directives 2-17 2.6 Symbolic Capabilities 2-23 2.7 Conditional Assembly: [, | and ] 2-25 2.8 Repetitive Assembly: WHILE and WEND 2-26 2.9 Macros 2-26 3 Linker 3-1 3.1 Introduction 3-2 3.2 Command Syntax 3-4 3.3 Library Module Inclusion 3-12 3.4 Area Placement and Sorting Rules 3-13 3.5 Linker Predefined Symbols 3-14 3.6 Handling Relocation Directives 3-16 3.7 Automatic Inclusion of C libraries 3-19 4 Rebuilding the C Library 4-1 4.1 Introduction to the Runtime Libraries 4-2 4.2 Constructing a Makefile 4-4 4.3 Building a Target-specific Library 4-5 4.4 Retargeting the Library 4-6 4.5 Details of Target-dependent Code 4-9 5 ARM Procedure Call Standard 5-1 5.1 Introduction 5-2 5.2 Defining the APCS 5-3 5.3 APCS Variants 5-11 5.4 C Language Calling Conventions 5-13 5.5 Function Entry 5-15 5.6 The APCS in Non-user ARM Modes 5-23 6 Thumb Procedure Call Standard 6-1 6.1 Introduction 6-2 6.2 Register Names 6-3 6.3 The Stack 6-4 6.4 Control Arrival and Return 6-5 6.5 C Language Calling Conventions 6-7 6.6 Function Entry 6-8 6.7 Function Exit 6-10 Contents-ii Reference Guide ARM DUI 0041B Contents 7 Toolkit Utilities 7-1 7.1 Introduction 7-2 7.2 ARM Profiler 7-3 7.3 ARM Librarian 7-6 7.4 ARM Object Format Decoder 7-7 7.5 ARM Executable Format Decoder 7-8 7.6 ANSI to PCC C Translator 7-9 Part 2: Debug Reference 8 Angel 8-1 8.1 Introduction 8-2 8.2 Structure 8-2 8.3 Angel C Library Support (SWIs) 8-3 8.4 ROM Applications and Late Debugger Start-up 8-8 8.5 Breakpoints and Undefined Instructions 8-9 8.6 Communications Architecture for Angel 8-10 8.7 Reliability and Retransmission 8-12 8.8 Channels Layer and Buffer Management 8-16 8.9 Device Driver Layer 8-20 8.10 Support for user application devices 8-28 8.11 Fusion IP stack for Angel 8-34 8.12 Serialization, Stacks and Modes 8-38 9 ARMulator 9-1 9.1 About the ARMulator 9-2 9.2 Modelling an ARM-based System 9-2 9.3 Basic Model Interface 9-4 9.4 Memory Model Interface 9-5 9.5 Coprocessor Model Interface 9-10 9.6 Operating System or Low-level Monitor Interface 9-13 9.7 Accessing the ARMulator’s State 9-15 9.8 Accessing the Debugger 9-26 9.9 Events 9-28 10 ARM Debugger 10-1 10.1 Command Language 10-2 10.2 Command-line Options 10-4 10.3 Commands Overview 10-6 10.4 Commands List 10-10 10.5 Specifying Source-level Objects 10-25 10.6 Variables 10-29 10.7 Low-level Debugging 10-33 10.8 armsd commands for EmbeddedICE 10-35 10.9 Angel and armsd 10-36 Reference Guide Contents-iii ARM DUI 0041B Contents 11 Remote Debugging 11-1 11.1 ARM Remote Debug Interface 11-2 11.2 RDI Functions 11-3 11.3 Error Codes 11-19 11.4 Angel Debug Protocol (ADP) 11-21 Part 3: File Format Reference 12 ARM Image Format 12-1 12.1 Overview of ARM Image