ARM Software Development Toolkit Version 2.0 Reference Manual Document Number: ARM DUI 0020D Issued: June 1995 Copyright Advanced RISC Machines Ltd (ARM) 1995 Beta Draft EUROPE JAPAN USA Advanced RISC Machines Limited Advanced RISC Machines K.K. ARM USA Fulbourn Road KSP West Bldg, 3F 300D, 3-2-1 Sakado, Suite 5, 985 University Avenue Cherry Hinton Takatsu-ku, Kawasaki-shi Los Gatos Cambridge CB1 4JN Kanagawa, 213 Japan California 95030 Telephone: +44 1223 400400 Telephone: +81 44 850 1301 Telephone: +1 408 399 5199 Facsimile: +44 1223 400410 Facsimile: +81 44 850 1308 Facsimile: +1 408 399 8854 Email: [email protected] Email: [email protected] Email: [email protected] Proprietary Notice ARM, the ARM Powered logo and EmbeddedICE are trademarks of Advanced RISC Machines Ltd. Neither the whole nor any part of the information contained in, or the product described in, this manual may be adapted or reproduced in any material form except with the prior written permission of the copyright holder. The product described in this manual is subject to continuous developments and improvements. All particulars of the product and its use contained in this manual 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 manual 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 manual, or any error or omission in such information, or any incorrect use of the product. Change Log Issue Date By Change Prelim1 Nov 94 BJH/EH Created B01 Jan 95 AW Changes to reflect review comments; change of title B00 Feb 95 AW B01 comments incorporated C April 95 PB Updated, profiler chapter added D June 95 BJH/PO Edited Beta Draft ii Reference Manual ARM DUI 0020D Contents 1 Introduction 1-1 1.1 About This Manual 1-2 1.2 Release Components 1-3 1.3 Feedback 1-4 2 C Compiler 2-1 2.1 Introduction 2-2 2.2 About the ARM C Compiler 2-3 2.3 Invoking the Compiler 2-4 2.4 Using the ARM C Compiler 2-5 2.5 Keyword Options 2-8 2.6 Flag Options 2-10 2.7 Processor Selection Options 2-16 2.8 Implementation Details 2-17 2.9 Standard Implementation Definition 2-24 2.10 Portability 2-37 2.11 ANSI C vs K&R C 2-42 2.12 PCC Compatibility Mode 2-47 2.13 Machine-Specific Features 2-50 2.14 Floating Point Support 2-56 2.15 ARM/Thumb interworking 2-57 Reference Manual Contents-1 ARM DUI 0020D Contents 3 Assembler 3-1 3.1 Overview 3-2 3.2 Command Line Options 3-2 3.3 Assembly Language Overview 3-6 3.4 Directives 3-11 3.5 Symbolic Capabilities 3-18 3.6 Expressions and Operators 3-21 3.7 Conditional Assembly—[, | and ] 3-24 3.8 Repetitive Assembly—WHILE and WEND 3-24 3.9 Macros 3-25 4 ARM Instruction Set 4-1 4.1 The ARM Instruction Set—Overview 4-2 4.2 Branch Instructions—B and BL 4-7 4.3 Data Processing Instructions 4-8 4.4 PSR Transfer—MSR and MRS 4-11 4.5 Unsigned Word/Byte Data Transfer—LDR and STR 4-12 4.6 Halfword and Signed Data Transfer: LDRH, STRH, LDRSB, LDRSH4-13 4.7 Block Data Transfer—LDM and STM 4-14 4.8 Multiply Instructions—MUL, MLA 4-16 4.9 Long Multiply Instructions—MULL, MLAL 4-17 4.10 Single Data Swap—SWP 4-17 4.11 ARM to Thumb State Exchange—BX 4-18 4.12 Software Interrupt/Supervisor Call—SWI 4-19 4.13 Pseudo-Instructions—ADR and NOP 4-20 4.14 Generic Coprocessor Instructions 4-21 4.15 Floating Point Instructions 4-23 5 Thumb Instruction Set 5-1 5.1 Thumb Instruction Set—Overview 5-2 5.2 Branch Instructions—B and BL 5-5 5.3 Data-processing Instructions 5-7 5.4 Single Data Transfer Instructions—LDR and STR 5-11 5.5 Block Data Transfer Instructions—LDMIA and STMIA 5-14 5.6 Stack Operations—PUSH and POP 5-15 5.7 Thumb to ARM State Exchange—BX 5-16 5.8 Software Interrupt 5-16 5.9 Pseudo Instructions — MOV and NOP 5-17 Contents-2 Reference Manual ARM DUI 0020D Contents 6 Linker 6-1 6.1 Introduction 6-2 6.2 Using the Linker 6-3 6.3 Library Module Inclusion 6-10 6.4 Area Placement and Sorting Rules 6-11 6.5 Linker Pre-Defined Symbols 6-12 6.6 The Handling of Relocation Directives 6-13 6.7 ARM Object Format 6-15 6.8 Plain Binary Format 6-16 6.9 ARM Image Format 6-16 6.10 Extended Intellec Hex Format (IHF) 6-18 6.11 ARM Shared Library Format 6-18 6.12 Overlays 6-28 6.13 The Overlay Manager 6-32 6.14 Scatter Loading 6-41 7 Symbolic Debugger 7-1 7.1 About armsd 7-2 7.2 Line-Speed Negotiation 7-2 7.3 Command-line Options 7-3 7.4 Command Language 7-6 7.5 Specifying Source-level Objects 7-6 7.6 Accessing Variables 7-11 7.7 Symbols 7-14 7.8 Accessing and Executing Programs 7-15 7.9 Controlling Execution 7-17 7.10 Program Context 7-22 7.11 Low-level Debugging 7-23 7.12 Coprocessor Support 7-30 7.13 Miscellaneous Commands 7-32 7.14 Automatic Command Execution on Startup 7-35 7.15 Performance simulation using armsd 7-35 7.16 Semihosting under EmbeddedICE 7-41 8 ARM Profiler 8-1 8.1 About armprof 8-2 8.2 Command-line Options 8-2 8.3 Profiler output 8-3 9 ARM Librarian 9-1 9.1 About armlib 9-2 9.2 Command Line Options 9-2 Reference Manual Contents-3 ARM DUI 0020D Contents 10 ARM Object Format Decoder 10-1 10.1 About decaof 10-2 10.2 Command-line Options 10-2 11 ANSI to PCC C Translator 11-1 11.1 About topcc 11-2 11.2 Command Line Options 11-2 11.3 Translation Details 11-3 11.4 Issues with topcc 11-4 12 ARM Tool Reconfiguration Utility 12-1 12.1 About reconfig 12-2 12.2 Tool Reconfiguration 12-2 12.3 Using reconfig 12-8 12.4 Reconfiguration Errors 12-10 13 ARM make Utility 13-1 13.1 About armmake 13-2 13.2 Command-line Options 13-3 13.3 Makefile Format for armmake 13-4 13.4 Command Execution 13-6 13.5 Advanced Features 13-7 13.6 Miscellaneous Features 13-9 14 ARMulator 14-1 14.1 About the ARMulator 14-2 14.2 Modelling an ARM-Based System 14-2 14.3 ARMulator Release Components 14-3 14.4 Building an ARMulator Variant 14-4 14.5 Memory Interfacing 14-4 14.6 ANSI C Library 14-5 14.7 The ARMulator Environment 14-5 14.8 Memory Models 14-6 14.9 Co-processor Modelling 14-12 14.10 Modelling an Operating System or Low Level Monitor 14-16 14.11 Accessing ARMulator’s State 14-17 14.12 ARMulator Signals 14-18 14.13 Processor Selection 14-18 14.14 Event Handling 14-18 14.15 The ARM Debug Monitor 14-19 Contents-4 Reference Manual ARM DUI 0020D Contents 15 C Library 15-1 15.1 An Introduction to the Run-Time Libraries 15-2 15.2 Porting the ARM C Library 15-3 15.3 Source Organisation 15-4 15.4 Building a Target-Specific Library 15-6 15.5 Retargeting the Library 15-7 15.6 Details of Target-Dependent Code 15-10 16 Software Floating Point 16-1 16.1 Introduction 16-2 16.2 The ARM Floating Point Library 16-2 16.3 Usage 16-3 16.4 Interworking Between hardfp and softfp Systems 16-3 16.5 Calling the Floating Point Library from Assembler 16-3 16.6 Controlling Floating Point Exceptions from C 16-6 16.7 Formats 16-10 17 Demon 17-1 17.1 Introduction 17-2 17.2 Target Memory Map 17-3 17.3 Standard Monitor SWIs 17-4 17.4 The Implementation of Demon for the PIE Card 17-8 18 EmbeddedICE 18-1 18.1 The Effect of EmbeddedICE on the Debuggee 18-2 18.2 Vector Breakpoints 18-2 18.3 Configuration Data 18-2 18.4 Accessing the EmbeddedICE Macrocell Directly 18-3 18.5 Floating Point and Other Coprocessors 18-4 19 ARM Procedure Call Standard 19-1 19.1 Introduction 19-2 19.2 The ARM Procedure Call Standard 19-3 19.3 APCS Variants 19-11 19.4 C Language Calling Conventions 19-14 19.5 Function Entry 19-16 19.6 The APCS in Non-User ARM Modes 19-25 Reference Manual Contents-5 ARM DUI 0020D Contents 20 Thumb Procedure Call Standard 20-1 20.1 Introduction 20-2 20.2 Register Names 20-3 20.3 The Stack 20-4 20.4 Control Arrival and Return 20-6 20.5 C Language Calling Conventions 20-8 20.6 Function Entry 20-9 20.7 Function Exit 20-12 21 File Formats 21-1 21.1 ARM Image Format 21-2 21.2 ARM Object Format 21-10 21.3 ARM Object Library Format 21-26 21.4 ARM Symbolic Debug Table Format 21-32 22 Remote Debugging 22-1 22.1 ARM Remote Debug Interface 22-2 22.2 ARM Remote Debug Protocol 22-21 Contents-6 Reference Manual ARM DUI 0020D 1 Introduction This chapter introduces the ARM Software Development Toolkit and its documentation.