ARM Developer Suite ® Version 1.2 Debug Target Guide Copyright © 1999-2001 ARM Limited. All rights reserved.
ARM Developer Suite Debug Target Guide Copyright © 1999-2001 ARM Limited. All rights reserved. Release Information The following changes have been made to this book. Change History Date Issue Change October 1999 A Release 1.0 March 2000 B Release 1.0.1 November 2000 C Release 1.1 November 2001 D Release 1.2 Proprietary Notice Words and logos marked with ® or ™ are registered trademarks or trademarks owned by ARM Limited.
Contents ARM Developer Suite Debug Target Guide Preface About this book .............................................................................................. vi Feedback ....................................................................................................... x Chapter 1 Introduction 1.1 Chapter 2 ARMulator Basics 2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9 2.10 Chapter 3 About ARMulator .........................................................................................
Contents 3.3 3.4 3.5 Chapter 4 ARMulator Reference 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10 4.11 4.12 4.13 4.14 4.15 4.16 Chapter 5 Building a new model ................................................................................. 3-7 Configuring ARMulator to use a new model ............................................... 3-8 Configuring ARMulator to disable a model ............................................... 3-10 ARMulator models ...............................................................
Preface This preface introduces the ARM debug targets and their reference documentation. It contains the following sections: • About this book on page vi • Feedback on page x. ARM DUI0058D Copyright © 1999-2001 ARM Limited. All rights reserved.
Preface About this book This book provides reference information for the ARM Developer Suite (ADS). It describes: • ARMulator®, the ARM processor simulator • Semihosting SWIs, the means for your ARM programs to access facilities on your host computer. Intended audience This book is written for all developers who are using the ARM debuggers, armsd and AXD. It assumes that you are an experienced software developer, and that you are familiar with the ARM development tools as described in Getting Started.
Preface Typographical conventions The following typographical conventions are used in this book: italic Highlights important notes, introduces special terminology, denotes internal cross-references, and citations. bold Highlights interface elements, such as menu names. Also used for emphasis in descriptive lists, where appropriate, and for ARM processor signal names. monospace Denotes text that can be entered at the keyboard, such as commands, file and program names, and source code.
Preface Further reading This section lists publications from both ARM Limited and third parties that provide additional information on developing code for the ARM family of processors. ARM periodically provides updates and corrections to its documentation. See http://www.arm.com for current errata sheets and addenda. See also the ARM Frequently Asked Questions list at: http://www.arm.com/DevSupp/Sales+Support/faq.
Preface • ARM/Thumb® Procedure Call Specification (SWS ESPC 0002). This is supplied in PDF format in install_directory\PDF\specs\ATPCS.pdf. In addition, refer to the following documentation for specific information relating to ARM products: ARM DUI0058D • ARM Reference Peripheral Specification (ARM DDI 0062) • the ARM datasheet or technical reference manual for your hardware device. Copyright © 1999-2001 ARM Limited. All rights reserved.
Preface Feedback ARM Limited welcomes feedback on both the ARM Developer Suite, and its documentation. Feedback on the ARM Developer Suite If you have any problems with the ARM Developer Suite, please contact your supplier.
Chapter 1 Introduction This chapter introduces the debug support facilities provided in the ADS version 1.2. It contains the following section: • Debug target overview on page 1-2. ARM DUI0058D Copyright © 1999-2001 ARM Limited. All rights reserved.
Introduction 1.1 Debug target overview You can debug your prototype software using either of the debuggers described in AXD and armsd Debuggers Guide, or a third party debugger. The debugger runs on your host computer. It is connected to a target system that your prototype software runs on.
Introduction Execution halts at breakpoints, or when watchpoints are accessed. You can then examine the state of your system, alter it, and restart it. In this way you can avoid having any code other than your prototype software running on your target system. • If your target system has an Embedded Trace Macrocell, you can examine the operation of your system while it is running. For details see the documentation accompanying the hardware. 1.1.
Introduction 1-4 Copyright © 1999-2001 ARM Limited. All rights reserved.
Chapter 2 ARMulator Basics This chapter describes ARMulator, a collection of programs that provide software simulation of ARM processors. It contains the following sections: • About ARMulator on page 2-2 • ARMulator components on page 2-3 • Tracer on page 2-5 • Profiler on page 2-12 • ARMulator cycle types on page 2-14 • Pagetable module on page 2-19 • Default memory model on page 2-26 • Memory modelling with mapfiles on page 2-27 • Peripheral models on page 2-32.
ARMulator Basics 2.1 About ARMulator ARMulator is an instruction set simulator. It simulates the instruction sets and architecture of various ARM processors. To run software on ARMulator, you must access it either through the ARM symbolic debugger, armsd, through the ARM GUI debugger, AXD, or through a third party debugger. See AXD and armsd Debuggers Guide for details. ARMulator is suited to software development and benchmarking ARM-targeted software.
ARMulator Basics 2.2 ARMulator components ARMulator consists of a series of modules, implemented as Dynamic Link Libraries (.dll files) for Windows, or as Shared Objects (.so files for Linux or Solaris, .sl files for HPUX). The main modules are: • a model of the ARM processor core • a model of the memory used by the processor. There are alternative predefined modules for each of these parts. You can select the combination of processor and memory model you want to use.
ARMulator Basics 2.2.1 Configuring ARMulator You can configure some of the details of ARMulator from armsd, or from your GUI debugger (see AXD and armsd Debuggers Guide). The current configurations are announced in the debugger startup banner. To make other configuration adjustments you must edit copies of .ami files. Six .ami files are supplied with ADS: • bustypes.ami • default.ami • example1.ami • peripherals.ami • processors.ami • vfp.
ARMulator Basics 2.3 Tracer You can use Tracer to trace instructions, memory accesses, and events. The configuration file peripherals.ami controls what is traced (see ARMulator configuration files on page 4-63). This section contains the following subsections: • Debugger support for tracing • Interpreting trace file output on page 2-6 • Configuring Tracer on page 2-10. 2.3.1 Debugger support for tracing There is no direct debugger support for tracing.
ARMulator Basics 2.3.2 Interpreting trace file output This section describes how you interpret the output from Tracer.
ARMulator Basics Trace memory (M lines) M lines indicate: • memory accesses, for cores without on-chip memory • on-chip memory accesses, for cores with on-chip memory. They have the following format for general memory accesses: M[O][L][S] where: indicates the cycle type: S sequential N nonsequential. indicates either a read or a write operation: R read W write.
ARMulator Basics Trace instructions (I lines) The format of the trace instruction (I) lines is as follows: [ IT | IS ] [] For example: IT 00008044 e04ec00f SUB r12,r14,pc where: IT indicates that the instruction was taken. IS indicates that the instruction was skipped (almost all ARM instructions are conditional). shows the address of the instruction in hexadecimal format, for example 00008044.
ARMulator Basics Trace registers (R lines) The format of the event (R) lines is as follows: R =[,=[...]] For example: R r14=20000060, cpsr=200000d3 where: is a register that has a new value as a result of the current instruction is the new contents of . Trace bus (B lines) The format of bus (B) lines is the same as the format of M lines. B lines indicate off-chip memory accesses.
ARMulator Basics 2.3.3 Configuring Tracer Tracer has its own section in the ARMulator peripherals configuration file (peripherals.ami): { Default_Tracer=Tracer ;; Output options - can be plaintext to file, binary to file or to RDI log ;; window. (Checked in the order RDILog, File, BinFile.) RDILog=False File=armul.trc BinFile=armul.trc ;; Tracer options - what to trace TraceInstructions=True TraceRegisters=False OpcodeFetch=True ;;Normally True is useful, but sometimes it's too expensive.
ARMulator Basics TraceNonAccounted traces unaccounted RDI accesses to memory. That is, those accesses made by the debugger. TraceEvents traces events. For more information, see Tracing events below. TraceBus may be: TRUE FALSE Bus (off-chip accesses traced) Core (off-chip accesses not traced). Disassemble disassembles instructions. Simulation is much slower if you enable disassembly. TraceEIS if set TRUE, changes output to a format compatible with other simulators.
ARMulator Basics 2.4 Profiler Profiler is controlled by the debugger. For details see AXD and armsd Debuggers Guide. In addition to profiling program execution time, Profiler allows you to use the profiling mechanism to profile events, such as cache misses. When you turn profiling on from the debugger, you specify a number, n, to control the frequency of profiling. See Configuring Profiler on page 2-13 for details. Profiler can profile both C and assembler language functions.
ARMulator Basics 2.4.1 Configuring Profiler Profiler has its own section in peripherals.ami, the ARMulator peripherals configuration file: { Default_Profiler=Profiler ;; For example - to profile the PC value when cache misses happen, set: ;Type=Event ;Event=0x00010001 ;EventWord=pc ;;Alternatives for Type are ;; Event, Cycle, Microsecond. ;;If type is Event then alternatives for EventWord are ;; Word1,Word2,PC.
ARMulator Basics 2.5 ARMulator cycle types In addition to simulating instruction execution on ARM cores, ARMulator counts bus and processor cycles. You can access these counts as $statistics from your debugger. This section describes the meaning of the various types of cycles counted.
ARMulator Basics 2.5.1 Uncached von Neumann cores Table 2-1 shows the meanings of cycle types for uncached von Neumann cores. ARM7TDMI, for example, is an uncached von Neumann core. Table 2-1 Cycle type meanings for uncached von Neumann cores Cycle type SEQ signal nMREQ signal Meaning S_Cycles 1 1 Sequential cycles. See Sequential cycles for details. N_Cycles 0 1 Nonsequential cycles.
ARMulator Basics 2.5.2 Uncached Harvard cores Table 2-2 shows the meanings of cycle types for uncached Harvard cores. ARM9TDMI, for example, is an uncached Harvard core. Table 2-2 Cycle type meanings for uncached Harvard cores Cycle types Instruction bus Data bus Meaning Core cycles - - The total number of ticks of the core clock. This includes pipeline stalls due to interlocks and instructions that take more than one cycle.
ARMulator Basics 2.5.4 Cached cores with MMUs or PUs and AMBA AHB interfaces Table 2-4 shows the types of transfer that can occur on the Advanced High-speed Bus (AHB). ARM946E-S, for example, is a cached core with an AHB interface. For additional cycle types for these cores, see Internal cycle types for cached cores. Table 2-4 Cycle types on AMBA AHB interfaces 2.5.5 Cycle types Meaning IDLE The bus master does not want to use the bus.
ARMulator Basics 2.5.6 strongARM1 Table 2-6 shows the meaning of cycle types reported for strongARM1. Table 2-6 strongARM specific cycle types 2.5.7 Cycle types Meaning Core_Idle No instruction fetched from instruction cache. No data fetched from data cache. Core_IOnly Instruction fetched from instruction cache. No data fetched from data cache. Core_DOnly No instruction fetched from instruction cache. Data fetched from data cache. Core_ID Instruction fetched from instruction cache.
ARMulator Basics 2.6 Pagetable module This section contains the following subsections: • Overview of the pagetable module • Controlling the MMU or PU and cache on page 2-20 • Controlling registers 2 and 3 on page 2-20 • Memory regions on page 2-21 • Pagetable module and memory management units on page 2-23 • Pagetable module and protection units on page 2-24. 2.6.
ARMulator Basics 2.6.2 Controlling the MMU or PU and cache The first set of flags enables or disables features of the caches and MMU or PU: MMU=Yes AlignFaults=No Cache=Yes WriteBuffer=Yes Prog32=Yes Data32=Yes LateAbort=Yes BigEnd=No BranchPredict=Yes ICache=Yes HighExceptionVectors=No FastBus=No Each flag corresponds to a bit in the system control register, c1 of CP15. Some flags only apply to certain processors.
ARMulator Basics 2.6.4 Memory regions The rest of the Pagetables configuration section defines a set of memory regions. Each region has its own set of properties. By default, peripherals.
ARMulator Basics Cacheable specifies whether the region is to be marked as cacheable. If it is, reads from the region will be cached. Bufferable specifies whether the region is to be marked as bufferable. If it is, writes to the region will use the write buffer. Updateable applies only to the ARM610™ processor. It controls the U bit in the translation table entry. Domain applies only to processors with an MMU. It specifies the domain field of the table entry.
ARMulator Basics 2.6.5 Pagetable module and memory management units Processors such as ARM720T™ and ARM920T™ have an MMU. An MMU uses a set of page tables, stored in memory, to define memory regions. On reset, the pagetable module writes out a top-level page table to the address specified in the translation table base register. The table corresponds to the regions you define in the Pagetables section of peripherals.ami.
ARMulator Basics 2.6.6 Pagetable module and protection units Processors such as ARM740T™ and ARM940T™ have a PU. A PU uses a set of protection regions. The base and size of each protection region is stored in registers in the PU. On reset, the page table module initializes the PU. For example, the default configuration details given above define a single region, region 0. This region is marked as read/write, cacheable, and bufferable. It occupies the whole address range, 0 to 4GB.
ARMulator Basics ARM940T PU For an ARM940T, the PU is initialized as follows: • The P, D, W, and I bits are set in the configuration register, register 1, to enable the PU, the write buffer, the data cache and the instruction cache. • Both the cacheable registers, register 2, are initialized to 1, marking region 0 as cacheable for the I and D caches. This is displayed in the debugger as 0x0101, where: — the low byte (bits 0..7) represent the data cache cacheable register — the high byte (bits 8..
ARMulator Basics 2.7 Default memory model The default memory model, flatmem, is a model of a zero-wait state memory system. The simulated memory size is not fixed. Host memory is allocated in chunks of 64KB each time a new region of memory is accessed. The memory size is limited by the host computer, but in theory all 4GB of the address space is available. The default memory model does not generate aborts. The default memory model is used if you do not specify a mapfile in AXD.
ARMulator Basics 2.8 Memory modelling with mapfiles This section contains the following subsections: • Overview of memory modelling with mapfiles • Clock frequency • Selecting the mapfile memory model on page 2-28 • How the mapfile memory model calculates wait states on page 2-28 • Configuring the map memory model on page 2-29. 2.8.1 Overview of memory modelling with mapfiles mapfile is a memory model which you can configure yourself.
ARMulator Basics 2.8.3 Selecting the mapfile memory model Under armsd, the map memory model inserts itself automatically, if loaded, as the memory model to use whenever an armsd.map file exists in the directory where armsd is started. Under AXD, the map memory model is automatically inserted whenever a memory map file is specified. Specify map files using the Memory Maps tab of the ARMulator configuration dialog. 2.8.
ARMulator Basics 2.8.5 Configuring the map memory model You can configure the map memory model to model several different types of memory controller, by editing its entry in the peripherals.ami file: { Default_Mapfile=Mapfile AMBABusCounts=False ;SpotISCyles=True|False SpotISCyles=True ;ISTiming=Late|Early|Speculative ISTiming=Late } Counting AMBA™ decode cycles You can configure the model to insert an extra decode cycle for every nonsequential access from the processor.
ARMulator Basics Late This does not start the decode until the S-cycle. In effect all S-cycles that follow an I-cycle are treated as if they are N-cycles. See ARMulator cycle types on page 2-14 for details of merged I-S cycles. 2-30 Copyright © 1999-2001 ARM Limited. All rights reserved.
ARMulator Basics 2.9 Semihosting Semihosting provides code running on an ARM target use of facilities on a host computer that is running an ARM debugger. Examples of such facilities include the keyboard input, screen output, and disk I/O. See Chapter 5 Semihosting for further details. 2.9.1 Semihosting configuration The semihosting SWI handler configuration is controlled by a section in peripherals.ami. It has the following items: {Default_Semihost=Semihost ; Demon is only needed for validation.
ARMulator Basics 2.10 Peripheral models ARMulator includes several peripheral models. This section gives basic user information about them. This section contains the following subsections: • Configuring ARMulator to use the peripheral models • Interrupt controller on page 2-33 • Timer on page 2-34 • Watchdog on page 2-35 • Stack tracker on page 2-36 • Tube on page 2-36. 2.10.
ARMulator Basics 2.10.3 Interrupt controller The interrupt controller is an implementation of the reference interrupt controller (see Interrupt controller on page 4-75). The configuration of the interrupt controller model is controlled by a section in peripherals.ami. It has the following items: { Default_Intctrl=Intctrl Range:Base=0x0a000000 WAITS=0 } Range:Base specifies the area in memory into which the interrupt controller registers are mapped.
ARMulator Basics 2.10.4 Timer The timer is an implementation of the reference timer. It provides two counter-timers. For details see Timer on page 4-77. The configuration of the timer model is controlled by a section in peripherals.ami. It has the following items: {Default_Timer=Timer Range:Base=0x0a800000 ;Frequency of clock to controller.
ARMulator Basics 2.10.5 Watchdog Use Watchdog to prevent a failure in your program locking up your system. If your program fails to access Watchdog before a predetermined time, Watchdog halts ARMulator and returns control to the debugger. Note This is a generic model of a watchdog timer. It is supplied to help users model their system environment. It does not model any actual hardware supplied by ARM. The Watchdog configuration is controlled by a section in peripherals.ami.
ARMulator Basics 2.10.6 Stack tracker The stack tracker examines the contents of the stack pointer (r13) after each instruction. It keeps a record of the lowest value and from this it can work out the maximum size of the stack. ARMulator runs more slowly with stack tracking enabled. The StackUse model continually monitors the stack pointer and reports the amount of stack used in $statistics. It must be configured with the location of the stack. The stack tracker is disabled by default.
Chapter 3 Writing ARMulator models This chapter is intended to assist you in writing your own models to add to ARMulator. It contains the following sections: • The ARMulator extension kit on page 3-2 • Writing a new peripheral model on page 3-5 • Building a new model on page 3-7 • Configuring ARMulator to use a new model on page 3-8 • Configuring ARMulator to disable a model on page 3-10. ARM DUI0058D Copyright © 1999-2001 ARM Limited. All rights reserved.
Writing ARMulator models 3.1 The ARMulator extension kit You can add extra models to ARMulator without altering the existing models. Each model is self-contained, and communicates with ARMulator through defined interfaces. The definition of these interfaces is in Chapter 4 ARMulator Reference. 3.1.1 Location of files The ARMulator extension kit contains the source code of some models. You can make copes of these models, and modify the copies.
Writing ARMulator models 3.1.2 Supplied models ARMulator is supplied with source code for the following groups of models: • Basic models • Peripheral models on page 3-4 Basic models ARM DUI0058D tracer.c The tracer module can trace instruction execution and events from within ARMulator (see Tracer on page 4-57). You can link your own tracing code onto the tracer module. profiler.c The profiler module provides the profiling function (see Profiler on page 2-12).
Writing ARMulator models Peripheral models 3-4 intc.c See Interrupt controller on page 2-33. intc is a model of the interrupt controller peripheral described in the Reference Peripherals Specification (RPS). timer.c See Timer on page 2-34. timer is a model of the RPS timer peripheral. Two timers are provided. timer must be used in conjunction with an interrupt controller, but not necessarily intc. millisec.c A simple millisecond timer. watchdog.c Watchdog. See Watchdog on page 2-35.
Writing ARMulator models 3.2 Writing a new peripheral model This section contains the following subsections: • Using a sample model as a template • Return values • Initialization, finalization, and state macros on page 3-6 • Registering your model on page 3-6. 3.2.1 Using a sample model as a template To write a new model, the best procedure is to copy one of the supplied models and then edit the copy. To do this: 1. Select which model is closest to the model you want to write.
Writing ARMulator models 3.2.3 Initialization, finalization, and state macros To help you to write new ARMulator models, the following six macros are provided in minperip.h: • BEGIN_INIT() • END_INIT() • BEGIN_EXIT() • END_EXIT() • BEGIN_STATE_DECL() • END_STATE_DECL().
Writing ARMulator models 3.3 Building a new model To build your new model: 1. Change your current directory to: mymodel.b\targetwhere target is one of: • • • • 2. 3. intelrel linux86 gccsolaris cchppa. Build the model using the make utility installed on your system. This might be one of: • nmake for Windows • make for Linux, Solaris or HPUX. Depending on your system: • On Windows, mymodel.dll appears in: install_directory\ARMulate\armulext\mymodel.b\intelrel Move mymodel.
Writing ARMulator models 3.4 Configuring ARMulator to use a new model ARMulator determines which models to use by reading the .ami and .dsc configuration files. See ARMulator configuration files on page 4-63. Before a new model can be used by ARMulator, you must add a .dsc file for your model, and references to it must be added to the configuration files default.ami and peripherals.ami. The procedures are described in the following subsections: • Adding a .dsc file • Editing default.ami and peripherals.
Writing ARMulator models 3.4.2 Editing default.ami and peripherals.ami This description assumes that your model was based on Timer: 1. Load the default.ami file into a text editor, and find the following lines: {Timer=Default_Timer } 2. Add the reference to your model: {Timer=Default_Timer } {MyModel=Default_MyModel } 3. Save your edited default.ami file. 4. Load the peripherals.ami file into a text editor, and find the Timer section: { Default_Timer=Timer . . . } ARM DUI0058D 5.
Writing ARMulator models 3.5 Configuring ARMulator to disable a model You can disable a model by changing its entry in peripherals.ami. For example, to disable the Tube model: 1. Find the following lines in peripherals.ami: {Default_Tube=Tube Range:Base=0x0d800020 } 2. Change them to read: {Default_Tube=No_Tube Range:Base=0x0d800020 } This uses the nothing.c model to override the tube.c model. nothing ignores any configuration details such as Range:Base. 3-10 Copyright © 1999-2001 ARM Limited.
Chapter 4 ARMulator Reference This chapter gives reference information about ARMulator.
ARMulator Reference 4.1 ARMulator models ARMulator comprises a collection of models that simulate ARM-based hardware. They enable you to benchmark, develop, and debug software before your hardware is available. 4.1.1 Configuring models through ToolConf ARMulator models are configured through ToolConf. ToolConf is a database of tags and values that ARMulator reads from configuration files (.dsc and .ami files) during initialization (see ToolConf on page 4-68).
ARMulator Reference 4.2 Communicating with the core During initialization, all the models receive a pointer to an mdesc structure of type RDI_ModuleDesc *. They copy this structure into their own state as a field called coredesc. This is passed as the first parameter to most ARMulif (ARMulator interface) functions. ARMulator exports these functions to enable models to access the ARMulator state through this handle.
ARMulator Reference 4.2.1 Mode numbers A number of the following functions take an unsigned mode parameter to specify the processor mode. The mode numbers are defined in armdefs.h, and are listed here: • USER32MODE • FIQ32MODE • IRQ32MODE • SVC32MODE • ABORT32MODE • UNDEF32MODE • SYSTEM32MODE In addition, the special value CURRENTMODE is defined. This enables ARMulif_GetReg(), for example, to return registers of the current mode. 4-4 Copyright © 1999-2001 ARM Limited. All rights reserved.
ARMulator Reference 4.2.2 ARMulif_GetReg This function reads a register for a specified processor mode. Syntax ARMword ARMulif_GetReg(RDI_ModuleDesc *mdesc, ARMword mode, unsigned reg) where: mdesc is the handle for the core. mode is the processor mode. Values for mode are defined in armdefs.h (see Mode numbers on page 4-4). reg is the register to read. Valid values are 0 to 14 for registers r0 to r14, PC, or CPSR. Return The function returns the value in the given register for the specified mode.
ARMulator Reference 4.2.4 ARMulif_GetPC and ARMulif_GetR15 This function reads the pc. ARMulif_GetPC and ARMulif_GetR15 are synonyms. Syntax ARMword ARMulif_GetPC(RDI_ModuleDesc *mdesc) ARMword ARMulif_GetR15(RDI_ModuleDesc *mdesc) where: is the handle for the core. mdesc Return This function returns the value of the pc. 4.2.5 ARMulif_SetPC and ARMulif_SetR15 This function writes a value to the pc. ARMulif_SetPC and ARMulif_SetR15 are synonyms.
ARMulator Reference 4.2.6 ARMulif_GetCPSR This function reads the CPSR. Syntax ARMword ARMulif_GetCPSR(RDI_ModuleDesc *mdesc) where: is the handle for the core. mdesc Return The function returns the value of the CPSR. 4.2.7 ARMulif_SetCPSR This function writes a value to the CPSR. Syntax void ARMulif_SetCPSR(RDI_ModuleDesc *mdesc, ARMword value) where: ARM DUI0058D mdesc is the handle for the core. value is the value to be written to the CPSR. Copyright © 1999-2001 ARM Limited.
ARMulator Reference 4.2.8 ARMulif_GetSPSR This function returns the current contents of the SPSR for a specified processor mode. Syntax ARMword ARMulif_GetSPSR(RDI_ModuleDesc *mdesc, ARMword mode) where: mdesc is the handle for the core. mode is the processor mode for the SPSR you want to read. User mode ARMulif_GetSPSR returns the current contents of the CPSR if mode is USER32MODE. 4.2.9 ARMulif_SetSPSR This function writes a value to the SPSR for a specified processor mode.
ARMulator Reference 4.2.10 ARMulif_ThumbBit This function returns 1 if the core is in Thumb state, 0 if the core is in ARM state. Syntax unsigned ARMulif_ThumbBit(RDI_ModuleDesc *mdesc) where: is the handle for the core. mdesc 4.2.11 ARMulif_GetMode This function reads the current processor mode. Syntax unsigned ARMulif_GetMode(RDI_ModuleDesc *mdesc) where: mdesc ARM DUI0058D is the handle for the core. Copyright © 1999-2001 ARM Limited. All rights reserved.
ARMulator Reference 4.2.12 ARMulif_CPRead This function calls the read method for a coprocessor. Syntax int ARMulif_CPRead(RDI_ModuleDesc *mdesc, unsigned cpnum, unsigned reg, ARMword *data) where: mdesc is the handle for the core. cpnum is the number of the coprocessor. reg is the number of the coprocessor register to read from, as indexed by CRn in an LDC or STC instruction. data is a pointer for the data read from the coprocessor register.
ARMulator Reference 4.2.13 ARMulif_CPWrite This function calls the write method for a coprocessor. It also intercepts calls to write the FPE emulated registers. Syntax int ARMulif_CPWrite(RDI_ModuleDesc *mdesc, unsigned cpnum, unsigned reg, ARMword *data) where: mdesc is the handle for the core. cpnum is the number of the coprocessor. reg is the number of the coprocessor register to read from, as indexed by CRn in an LDC or STC instruction.
ARMulator Reference 4.3 Basic model interface This section has the following subsections: • Declaration of a private state data structure on page 4-13 • Model initialization on page 4-14 • Model finalization on page 4-14. For each model, you must write an initialization function. For additional functionality, you must register callbacks. Macros are provided in minperip.
ARMulator Reference 4.3.1 Declaration of a private state data structure Each model must store its state in a private data structure. Initialization and finalization macros are provided by ARMulif. These macros require the use of certain fields in this data structure.
ARMulator Reference 4.3.2 Model initialization The BEGIN_INIT() and END_INIT() macros form the start and finish of the initialization function for the model. The initialization function is called: • during ARMulator initialization • whenever a new image is downloaded from the debugger. The following local variables are provided in the initialization function: • bool coldboot TRUE if ARMulator is initializing, FALSE if a new image is being downloaded from the debugger.
ARMulator Reference 4.4 Coprocessor model interface The coprocessor model interface is defined in armul_copro.h. The basic coprocessor functions are: • ARMulif_InstallCoprocessorV5 on page 4-16 • LDC on page 4-17 • STC on page 4-18 • MRC on page 4-19 • MCR on page 4-20 • MRC on page 4-19 • MCR on page 4-20 • MCRR on page 4-21 • MRRC on page 4-22 • CDP on page 4-23.
ARMulator Reference 4.4.1 ARMulif_InstallCoprocessorV5 Use this function to register a coprocessor handler. This function is prototyped in armul_copro.h. Syntax unsigned ARMulif_InstallCoprocessorV5(RDI_ModuleDesc *mdesc, unsigned number, struct ARMul_CoprocessorV5 *cpv5, void *handle) where: mdesc is the handle for the core. number is the coprocessor number. cpv5 is a pointer to the coprocessor interface structure. handle is a pointer to private data to pass to each coprocessor function.
ARMulator Reference 4.4.2 LDC This function is called when an LDC instruction is recognized for a coprocessor. Syntax unsigned LDC(void *handle, int type, ARMword instr, ARMword *data) where: handle is the handle from ARMulif_InstallCoprocessorV5. type is the type of coprocessor access. This can be one of: ARMul_CP_FIRST indicates that this is the first time the coprocessor model has been called for this instruction.
ARMulator Reference 4.4.3 STC This function is called when an STC instruction is recognized for a coprocessor. Syntax unsigned STC(void *handle, int type, ARMword instr, ARMword *data) where: handle is the handle from ARMulif_InstallCoprocessorV5. type is the type of the coprocessor access. This can be one of: ARMul_CP_FIRST indicates that this is the first time the coprocessor model has been called for this instruction.
ARMulator Reference 4.4.4 MRC This function is called when an MRC instruction is recognized for a coprocessor. If the requested coprocessor register does not exist or cannot be written to, the function must return ARMul_CP_CANT. Syntax unsigned MRC(void *handle, int type, ARMword instr, ARMword *data) where: handle is the handle from ARMulif_InstallCoprocessorV5. type is the type of the coprocessor access.
ARMulator Reference 4.4.5 MCR This function is called when an MCR instruction is recognized for a coprocessor. If the requested coprocessor register does not exist or cannot be written to, the function must return ARMul_CP_CANT. Syntax unsigned MCR(void *handle, int type, ARMword instr, ARMword *data) where: handle is the handle from ARMulif_InstallCoprocessorV5. type is the type of the coprocessor access.
ARMulator Reference 4.4.6 MCRR This function is called when an MCRR instruction is recognized for a coprocessor. The function must return ARMul_CP_CANT if: • the requested coprocessor register does not exist • the requested coprocessor register cannot be written to • the coprocessor is ARM architecture v4T or earlier. Syntax unsigned MCRR(void *handle, int type, ARMword instr, ARMword *data) where: handle is the handle from ARMulif_InstallCoprocessorV5. type is the type of the coprocessor access.
ARMulator Reference 4.4.7 MRRC This function is called when an MRRC instruction is recognized for a coprocessor. The function must return ARMul_CP_CANT if: • the requested coprocessor register does not exist • the requested coprocessor register cannot be read from • the coprocessor is ARM architecture v4T or earlier. Syntax unsigned MRRC(void *handle, int type, ARMword instr, ARMword *data) where: handle is the handle from ARMulif_InstallCoprocessorV5. type is the type of the coprocessor access.
ARMulator Reference 4.4.8 CDP This function is called when a CDP instruction is recognized for a coprocessor. If the requested coprocessor operation is not supported, the function must return ARMul_CP_CANT. Syntax unsigned CDP(void *handle, int type, ARMword instr, ARMword *data) where: handle is the handle from ARMulif_InstallCoprocessorV5. type is the type of the coprocessor access.
ARMulator Reference 4.4.9 read This function enables a debugger to read a coprocessor register via RDI. The function reads the coprocessor register numbered reg and transfers its value to the location addressed by value. If the requested coprocessor register does not exist, or the register cannot be read, the function must return ARMul_CP_CANT. Syntax unsigned read(void *handle, int reg, ARMword instr, ARMword *value) where: handle is the handle from ARMulif_InstallCoprocessorV5.
ARMulator Reference 4.4.10 write This function enables a debugger to write to a coprocessor register via RDI. The function writes the value at the location addressed by value to the coprocessor register numbered reg. If the requested coprocessor does not exist or the register cannot be written, the function must return ARMul_CP_CANT. Syntax unsigned write(void *handle, int reg, ARMword instr, ARMword *value) where: handle is the handle from ARMulif_InstallCoprocessorV5.
ARMulator Reference 4.5 Exceptions The following functions enable a model to set or clear signals: • ARMulif_SetSignal • ARMulif_GetProperty on page 4-27. 4.5.1 ARMulif_SetSignal The ARMulif_SetSignal function is used to set the state of signals or properties. Syntax void ARMulif_SetSignal(RDI_ModuleDesc *mdesc, ARMSignalType sigType, SignalState sigState) where: mdesc is the handle for the core. sigtype is the signal to be set.
ARMulator Reference RDIPropID_ARMulProp_CycleDelta Wait the core for a specified number of cycles. RDIPropID_ARMulProp_Accuracy Select the modelling accuracy, as a percentage in the range 0% to 100%. Currently this only affects ARM10 models. A setting less than 50% turns of interlock modelling. ARMulator runs faster with interlock modelling turned off, but cycling count accuracy is reduced. sigstate For signals, you must give sigstate one of the following values: FALSE Signal off TRUE Signal on.
ARMulator Reference RDIPropID_ARMSignal_HighException TRUE if the vector table is at 0xFFFF0000. RDIPropID_ARMSignal_BranchPredictEnable (ARM10 only) RDIPropID_ARMSignal_LDRSetTBITDisable (ARM10 only) RDIPropID_ARMSignal_WaitForInterrupt (ARM10 and XScale only) RDIPropID_ARMulProp_CycleCount Count of the number of cycles executed since initialization. RDIPropID_ARMulProp_RDILog Current setting of the RDI log level. Generally, this is zero if logging is disabled, and nonzero if it is enabled.
ARMulator Reference 4.6 Events ARMulator has a mechanism for broadcasting and handling events. These events consist of an event number and a pair of words. The number identifies the event. The details depends on the event. The core ARMulator generates some example events, defined in armdefs.h.
ARMulator Reference Table 4-2 Events from the ARM processor core Event name Word 1 Word 2 Event number CoreEvent_Reset - - 0x1 CoreEvent_UndefinedInstr pc value Instruction 0x2 CoreEvent_SWI pc value SWI number 0x3 CoreEvent_PrefetchAbort pc value - 0x4 CoreEvent_DataAbort pc value Aborting address 0x5 CoreEvent_AddrExceptn pc value Aborting address 0x6 CoreEvent_IRQ pc value - 0x7 CoreEvent_FIQ pc value - 0x8 CoreEvent_Breakpoint pc value RDI_PointHandle 0x9 CoreEve
ARMulator Reference Table 4-4 Debug events Event name Word 1 Word 2 Event number DebugEvent_InToDebug - - 0x40001 DebugEvent_OutOfDebug - - 0x40002 DebugEvent_DebuggerChangedPC pc - 0x40003 Table 4-5 Config events ARM DUI0058D Event name Word 1 Word 2 Event number ConfigEvent_AllLoaded - - 0x50001 ConfigEvent_Reset - - 0x50002 ConfigEvent_VectorsLoaded - - 0x50003 ConfigEvent_EndiannessChanged 1 (big end) or 2 (little end) - 0x50005 Copyright © 1999-2001 ARM Limited.
ARMulator Reference 4.6.1 ARMulif_RaiseEvent This function invokes events. The events are passed to the user-supplied event handlers. Syntax void ARMulif_RaiseEvent(RDI_ModuleDesc *mdesc, ARMword event, ARMword data1, ARMword data2) where: 4-32 mdesc is the handle for the core. event is one of the event numbers defined in Table 4-1 on page 4-29, Table 4-2 on page 4-30, Table 4-3 on page 4-30, or Table 4-4 on page 4-31. data1 is the first word of the event. data2 is the second word of the event.
ARMulator Reference 4.7 Handlers ARMulator can be made to call back your model when some state values change. You do this by installing the relevant event handler. You must provide implementations of the event handlers if you want to use them in your own models. See the implementations in the ARM supplied models for examples. You can use event handlers to avoid having to check state values on every access.
ARMulator Reference 4.7.1 Exception handler This event handler is called whenever the ARM processor takes an exception. Syntax typedef unsigned GenericCallbackFunc(void *handle, void *data) where: handle is the handle passed to ARMulif_InstallExceptionHandler. data must be cast to (ARMul_Event *), and contain: ((ARMul_Event *)data)->event is the core event causing the exception (see Table 4-2 on page 4-30). ((ARMul_Event *)data)->data1 is the address of the hardware vector for the exception.
ARMulator Reference 4.7.2 Unknown RDI information handler The unknown RDI information function is called if ARMulator cannot handle an RDI_InfoProc request itself. It returns an RDIError value. This function can be used by a model extending the RDI interface between ARMulator and the debugger. For example, the profiler module (in profiler.c) provides the RDIProfile info calls.
ARMulator Reference RDICycles Models that have declared a statistics counter by trapping RDIRequestCyclesDesc must also respond to RDICycles by calling ARMul_AddCounterValue() (see General purpose functions on page 4-41) for each counter in turn, in the same order as they were declared. The above RDI info calls have already been dealt with by ARMulator, and are passed for information only, or so that models can add information to the reply.
ARMulator Reference 4.7.3 Event handler This handler catches ARMulator events (see Events on page 4-29). Syntax typedef unsigned GenericCallbackFunc(void *handle, void *data) where: handle is the handle passed to ARMulif_InstallEventHandler. data must be cast to (ARMul_Event *), and contain: ((ARMul_Event *)data)->event is one of the event numbers defined in Table 4-1 on page 4-29, Table 4-2 on page 4-30, and Table 4-3 on page 4-30. ((ARMul_Event *)data)->addr1 is the first word of the event.
ARMulator Reference 4.8 Memory access functions The memory system can be probed by a peripheral model using a set of functions for reading and writing memory. These functions access memory without inserting cycles on the bus. If your model inserts cycles on the bus, it must install itself as a memory model, possibly between the core and the real memory model. Note It is not possible to tell if these calls result in a data abort. 4.8.
ARMulator Reference 4.8.2 Writing to a specified address The following functions write the specified word, halfword, or byte at the specified address. Each function accesses memory without inserting cycles on the bus.
ARMulator Reference 4.9 Event scheduling functions The following functions enable you to schedule or remove events: • ARMulif_ScheduleTimedFunction • ARMulif_DescheduleTimedFunction. 4.9.1 ARMulif_ScheduleTimedFunction This function schedules events using memory system cycles. It enables a function to be called at a specified number of cycles in the future. Syntax void *ARMulif_ScheduleTimedFunction(RDI_ModuleDesc *mdesc, ARMul_TimedCallback *tcb) where: mdesc is the handle for the core.
ARMulator Reference 4.10 General purpose functions The following are general purpose ARMulator functions.
ARMulator Reference ARMul_BusPeripAccessRegistration This structure and type are declared in armul_bus.h, in install_directory\ARMulate\armulif. The declaration is as follows: typedef struct ARMul_BusPeripAccessRegistration { ARMul_BusPeripAccessFunc *access_func; void *access_handle; uint32 capabilities; /* See PeripAccessCapability_* below */ struct ARMul_Bus *bus; /* 0=> normal peripheral, earlier in list than anything it * overlaps with. */ unsigned priority; /* 0..
ARMulator Reference PeripAccessCapability This parameter defines the capabilities of the peripheral. It is the sum of the values of the individual capabilities (see Table 4-6). For example: • A value of 0x20020 means that the peripheral can handle word data accesses, but not bytes, halfwords, or double words, and understands the Endian signal. This value is predefined as PeripAccessCapability_Minimum.
ARMulator Reference 4.10.2 ARMulif_ReadBusRange You must supply a breg structure to register a peripheral. Call this function to initialize the fields in this structure. Syntax int ARMulif_ReadBusRange(struct RDI_ModuleDesc *mdesc, struct RDI_HostosInterface const *hostif, toolconf config, struct ARMul_BusPeripAccessRegistration *breg, uint32 default_base, uint32 default_size, char const *default_bus_name); where: mdesc is the handle for the core. hostif is the handle for the host interface.
ARMulator Reference 4.10.3 Hostif_RaiseError Several initialization and installation functions can return errors of type ARMul_Error. These errors must be passed through Hostif_RaiseError(). This is a printf-like function that formats the error message associated with an ARMul_Error error code. Hostif_RaiseError only prints the error message. After calling this function, the model must return with an appropriate error, such as RDIError_UnableToInitialise.
ARMulator Reference 4.10.5 ARMul_AddCounterDesc The ARMul_AddCounterDesc() function adds new counters to $statistics. Syntax int ARMul_AddCounterDesc(void *handle, ARMword *arg1, ARMword *arg2, const char *name) where: handle is no longer used. arg1/arg2 are the arguments passed to the UnkRDIInfoUpcall(). name is a string that names the statistic counter. The string must be less than 32 characters long. Return The function returns one of: RDIError_BufferFull • • RDIError_UnimplementedMessage.
ARMulator Reference 4.10.6 ARMul_AddCounterValue This function provides the facility for your model to supply statistics for the debugger to display. Syntax int ARMul_AddCounterValue(void *handle, ARMword *arg1, ARMword *arg2, bool is64, const ARMword *counter) where: handle is no longer used. arg1/arg2 are the arguments passed to the UnkRDIInfoUpcall(). is64 denotes whether the counter is a pair of 32-bit words making a 64-bit counter (least significant word first), or a single 32-bit value.
ARMulator Reference 4.10.7 ARMul_AddCounterValue64 This function provides the facility for your model to supply statistics for the debugger to display. Syntax int ARMul_AddCounterValue64(void *handle, ARMword *arg1, ARMword *arg2, const uint64 counterval) where: handle is no longer used. arg1/arg2 are the arguments passed to the UnkRDIInfoUpcall(). counterval is the current value of the counter. Return The function always returns RDIError_UnimplementedMessage.
ARMulator Reference 4.10.8 ARMulif_StopExecution This function stops simulator execution at the end of the current instruction, giving a reason code. Syntax void ARMulif_StopExecution(RDI_ModuleDesc *mdesc, unsigned reason) where: mdesc is the handle for the core. reason is an RDIError error value. The debugger interprets reason and issues a suitable message. Expected errors are: RDIError_NoError Program ran to a natural termination. RDIError_BreakpointReached Stop condition was a breakpoint.
ARMulator Reference 4.10.10 ARMulif_GetCoreClockFreq This function returns the CPUSPEED in Hertz. Syntax ARMTime ARMulif_GetCoreClockFreq(RDI_ModuleDesc *mdesc) where: mdesc 4-50 is the handle for the core. Copyright © 1999-2001 ARM Limited. All rights reserved.
ARMulator Reference 4.10.11 ARMulif_InstallHourglass Use this function to install an hourglass callback from ARMulator to your model. Syntax void *ARMulif_InstallHourglass(RDI_ModuleDesc *mdesc, armul_Hourglass *newHourglass, void *handle); where: is the handle for the core. mdesc newHourglass is a function of type armul_Hourglass. You can find the prototype for armul_Hourglass in armul_types.h , in install_directory\ARMulate\armulif.
ARMulator Reference 4.11 Accessing the debugger This section describes the input, output, and RDI functions that you can use to access the debugger. Several functions are provided to display messages in the host debugger. Under armsd, these functions print messages to the console. Under AXD, they display messages to the relevant window: • Hostif_DebugPrint • Hostif_ConsolePrint on page 4-53 • Hostif_PrettyPrint on page 4-53 • Hostif_DebugPause on page 4-56.
ARMulator Reference 4.11.2 Hostif_ConsolePrint This function prints the text specified in the format string to the ARMulator console. Under AXD, the text appears in the console window. Syntax void Hostif_ConsolePrint(const struct RDI_HostosInterface *hostif, const char *format, ...) where: hostif is the handle for the host interface. format is a pointer to a printf-style formatted output string. ... are a variable number of parameters associated with format.
ARMulator Reference 4.11.4 Hostif_ConsoleReadC This function reads a character from the ARMulator console. Syntax int Hostif_ConsoleReadC(const struct RDI_HostosInterface *hostif) where: hostif is the handle for the host interface. Return This function returns the ASCII value of the character read, or EOF. 4.11.5 Hostif_WriteC This function writes a character to the ARMulator console.
ARMulator Reference 4.11.6 Hostif_ConsoleRead This function reads a string from the ARMulator console. Reading terminates at a newline or if the end of the buffer is reached. Syntax char *Hostif_ConsoleRead(const struct RDI_HostosInterface *hostif, char *buffer, int len) where: hostif is the handle for the host interface. buffer is a pointer to a buffer to hold the string. len is the maximum length of the buffer. Return This function returns a pointer to a buffer, or NULL on error or end of file.
ARMulator Reference 4.11.8 Hostif_DebugPause This function waits for the user to press any key. Syntax void Hostif_DebugPause(const struct RDI_HostosInterface *hostif) where: hostif 4-56 is the handle for the host interface. Copyright © 1999-2001 ARM Limited. All rights reserved.
ARMulator Reference 4.12 Tracer This section describes the functions provided by the tracer module, tracer.c. Note These functions are not exported. If you want to use any of these functions in your model, you must build your model together with tracer.c. The default implementations of these functions can be changed by compiling tracer.c with EXTERNAL_DISPATCH defined. The formats of Trace_State and Trace_Packet are documented in tracer.h. 4.12.
ARMulator Reference 4.12.3 Tracer_Close This function is called at the end of tracing. Syntax void Tracer_Close(Trace_State *ts) Usage The file tracer.c uses this to close the trace file. 4.12.4 Tracer_Flush This function is called when tracing is disabled. Syntax extern void Tracer_Flush(Trace_State *ts) Usage The file tracer.c uses this to flush output to the trace file. 4-58 Copyright © 1999-2001 ARM Limited. All rights reserved.
ARMulator Reference 4.13 Map files The type and speed of memory in a simulated system can be detailed in a map file. A map file defines the number of regions of attached memory, and for each region: • the address range to which that region is mapped • the data bus width in bytes • the access time for the memory region. armsd expects the map file to be called armsd.map, in the current working directory. AXD accepts map files of any name.
ARMulator Reference width is the width of the data bus in bytes (that is, 1 for an 8-bit bus, 2 for a 16-bit bus, or 4 for a 32-bit bus). access describes the type of accesses that can be performed on this region of memory: r for read-only. w for write-only. rw for read-write. for no access. Any access causes a Data or Prefetch Abort.
ARMulator Reference Example 2 This example describes a typical embedded system with 32KB of on-chip memory, 16-bit ROM and 32KB of external DRAM: 00000000 00008000 00010000 7FFF8000 8000 8000 8000 8000 SRAM ROM DRAM Stack 4 2 2 2 rw 1/1 1/1 r 100/100 100/100 rw 150/100 150/100 rw 150/100 150/100 There are four regions of memory: • A fast region from 0 to 0x7FFF with a 32-bit data bus. This is labeled SRAM. • A slower region from 0x8000 to 0xFFFF with a 16-bit data bus.
ARMulator Reference Reading the memory statistics To read the memory statistics use the command: print $memory_statistics print $memstats is a short version of print $memory_statistics. Example 4-1 shows the form of reports given.
ARMulator Reference 4.14 ARMulator configuration files This section contains the following subsections: • Predefined tags on page 4-64 • Processors on page 4-64 • Changing the cache or TCM size of a synthesizable processor on page 4-66. ARMulator configuration files (.ami files) are ToolConf files. See ToolConf on page 4-68. Depending on your system, these are located in one of: • install_directory\Bin • install_directory/linux/bin • install_directory/solaris/bin • install_directory/hpux/bin.
ARMulator Reference 4.14.1 Predefined tags Before reading .ami files, ARMulator creates several tags itself, based on the settings you give to the debugger. These are given in Table 4-7. Preprocessing directives in .ami files use these tags to control the configuration. Table 4-7 Tags predefined by ARMulator 4.14.2 Tag Description CPUSpeed Set to the speed set in the configuration window of AXD, or in the -clock command line option for armsd. For example, CPUSpeed=30MHz.
ARMulator Reference Example 4-2 Processors in a toolconf file {Processors {TRACED_ARM10=ARM10200E ;CPUSPEED=400MHz ;Memory clock divisor. ;(The AHB runs this many times slower than the core.) MCCFG=4 {Flatmem {Peripherals {Tracer=Default_Tracer ;; Output options - can be plaintext to file, binary to file or to RDI log ;; window. (Checked in the order RDILog, File, BinFile.) RDILog=False File=armul.trc BinFile=armul.
ARMulator Reference Finding the configuration for a selected processor ARMulator uses the following algorithm to find a configuration for a selected processor: 1. Set the current region to be Processors. 2. Find the selected processor in the current region. 3. If the tag has a child, that child is the required configuration.
ARMulator Reference If you want to change the cache or TCM size of a processor that does not already have a section in processors.ami, you can add a section. For example, to change the instruction RAM size of the ARM926EJ-S from 64KB to 32KB: 1. Find the following lines at the end of your copy of the processors.ami file: {ARM926EJ-S=ARM926EJ-S-REV0 } ;End of Processors 2.
ARMulator Reference 4.15 ToolConf This section contains the following subsections: • Toolconf overview • File format on page 4-69 • Boolean flags in a ToolConf database on page 4-71 • SI units in a ToolConf database on page 4-72 • ToolConf_Lookup on page 4-73 • ToolConf_Cmp on page 4-74. 4.15.1 Toolconf overview ToolConf is a module within ARMulator. A ToolConf file is a tree-structured database consisting of tag and value pairs. Tags and values are strings, and are usually case-insensitive.
ARMulator Reference 4.15.2 File format The following are typical ToolConf database lines: TagA=ValueA TagA=NewValue Othertag Othertag=Othervalue ;; Lines starting with ; (semicolon) are comments. ; Tag=Value The first line creates a tag in the ToolConf called TagA, with value ValueA. The second line has no effect, as TagA already has a value. The third line creates a tag called Othertag, with no value. The fourth line gives the value Othervalue to Othertag.
ARMulator Reference Specifying children There are two ways of specifying children in a ToolConf database. One is more suited to specifying large children: { TagP=ValueP TagC1=ValueC1 TagC2=ValueC2 } This creates a tag called TagP, with the value ValueP, and a child database. Two tags are given values in the child. The other is more suited to specifying small children: TagP:TagC=ValueC This creates a tag called TagP, with no value. TagP has a child in which one tag is created, TagC, with value ValueC.
ARMulator Reference A condition is evaluated from left to right, on the contents of the configuration at that point. Table 4-8 shows the operators that can be used in ToolConf conditional expressions. Table 4-8 Operators in ToolConf preprocessor expressions Operator Example Description none Tag Test for existence of tag definition == Tag==Value Case-insensitive string equality test != Tag!=Value Case-insensitive string inequality test (...
ARMulator Reference 4.15.4 SI units in a ToolConf database Some values can be specified using SI (Système Internationale) units, for example: ClockSpeed=10MHz MemorySize=2Gb The scaling factor is set by the prefix to the unit. ARMulator only accepts k, M, or G prefixes for kilo, mega, and giga. These correspond to scalings of 103, 106, and 109, or 210, 220, and 230. ARMulator decides which scaling to use according to context. 4-72 Copyright © 1999-2001 ARM Limited. All rights reserved.
ARMulator Reference 4.15.5 ToolConf_Lookup This function performs a lookup on a specified tag in an .ami or .dsc file. If the tag is found, its associated value is returned. Otherwise, NULL is returned. Syntax const char *ToolConf_Lookup(toolconf hashv, tag_t tag) where: hashv is the database to perform the lookup on. tag is the tag to search for in the database. The tag is case-dependent.
ARMulator Reference 4.15.6 ToolConf_Cmp This function performs a case-insensitive comparison of two ToolConf database tag values. Syntax int ToolConf_Cmp(const char *s1, const char *s2) where: s1 is a pointer to the first string value to compare. s2 is a pointer to the second string value to compare. Return The function returns: • 1, if the strings are identical • 0, if the strings are different. Example if (ToolConf_Cmp(option, "8192")) 4-74 Copyright © 1999-2001 ARM Limited.
ARMulator Reference 4.16 Reference peripherals Two reference peripherals are detailed here: • Interrupt controller • Timer on page 4-77. 4.16.1 Interrupt controller The base address of the interrupt controller, IntBase, is configurable (see Interrupt controller on page 2-33). Table 4-10 shows the location of individual registers.
ARMulator Reference Interrupt controller defined bits The FIQ interrupt controller is one bit wide. It is located on bit 0. Table 4-11 gives details of the interrupt sources associated with bits 1 to 5 in the IRQ interrupt controller registers. You can use bit 0 for a duplicate FIQ input.
ARMulator Reference 4.16.2 Timer The base address of the timer, TimerBase, is configurable (see Timer on page 2-34). See Table 4-12 for the location of individual registers.
ARMulator Reference Timer clear registers Timer clear registers are write-only. Writing to one of them clears an interrupt generated by the corresponding timer. Timer control registers See Table 4-14 and Table 4-13 for details of timer register bits. Only bits 7, 6, 3, and 2 are used. You must write all others as zeroes. Table 4-13 Clock prescaling using bits 2 and 3 Bit 3 Bit 2 Clock divided by Stages of prescale 0 0 1 0 0 1 16 4 1 0 256 8 1 1 Undefined - The counter counts downwards.
Chapter 5 Semihosting This chapter describes the semihosting mechanism. Semihosting provides code running on an ARM target use of facilities on a host computer that is running an ARM debugger. Examples of such facilities include the keyboard input, screen output, and disk I/O.
Semihosting 5.1 Semihosting Semihosting is a mechanism for ARM targets to communicate input/output requests from application code to a host computer running a debugger. This mechanism could be used, for example, to allow functions in the C library, such as printf() and scanf(), to use the screen and keyboard of the host rather than having a screen and keyboard on the target system. This is useful because development hardware often does not have all the input and output facilities of the final system.
Semihosting The semihosting SWI interface is common across all debug agents provided by ARM. Semihosted operations will work under ARMulator, RealMonitor, Angel, or Multi-ICE without any requirement for porting. For further information on semihosting and the C libraries, see the C and C++ Libraries chapter in ADS Compilers and Libraries Guide. See also the Writing Code for ROM chapter in ADS Developer Guide. 5.1.
Semihosting If you are calling SWIs from assembly language code it is best to use the operation names that are defined in semihost.h. You can define the operation names with an EQU directive. For example: SYS_OPEN SYS_CLOSE EQU 0x01 EQU 0x02 Changing the semihosting SWI numbers It is strongly recommended that you do not change the semihosting SWI numbers 0x123456 (ARM) or 0xAB (Thumb).
Semihosting 5.2 Semihosting implementation The functionality provided by semihosting is basically the same on all debug hosts. The implementation of semihosting, however, differs between hosts. 5.2.1 ARMulator When a semihosting SWI is encountered, ARMulator traps the SWI directly and the instruction in the SWI entry in the vector table is not executed. To turn the support for semihosting off in ARMulator, change Default_Semihost in the default.ami file to No_Semihost.
Semihosting 5.2.4 Multi-ICE When using Multi-ICE in default configuration, semihosting is implemented as follows: 1. 2. On ARM7 processors: a. A breakpoint is set on the SWI vector. b. When this breakpoint is hit, Multi-ICE examines the SWI number. c. If the SWI is recognized as a semihosting SWI, Multi-ICE emulates it and transparently restarts execution of the application. If the SWI is not recognized as a semihosting SWI, Multi-ICE halts the processor and reports an error.
Semihosting Multi-ICE handles the semihosted SWI and then examines the contents of lr and returns to the instruction following the SWI instruction in your code. Regardless of the value of $vector_catch, all exceptions and interrupts are trapped and reported as an error condition. For details of how to modify debugger internal variables, see the appropriate debugger documentation. 5.2.
Semihosting 5.3 Adding an application SWI handler It can be useful to have both the semihosted SWIs and your own application-specific SWIs available. In such cases you must ensure that the two SWI mechanisms cooperate correctly. The way to ensure this depends upon the debug agent in use. 5.3.1 ARMulator To get your own handler and the semihosting handler to cooperate, simply install your SWI handler into the SWI entry in the vector table. No other actions are required.
Semihosting Caution It is essential that the actual position $semihosting_vector points to within the application handler is correct. See exception handling in the ADS Developer Guide for writing SWI handlers. The following example SWI handler can detect if it fails to handle a SWI. In this case, it branches to an error handler: ; r0 = 1 if SWI handled CMP r0, #1 BNE NoSuchSWI LDMFD sp!, {r0} MSR spsr_cxsf, r0 LDMFD sp!, {r0-r12,pc}^ ; ; ; ; ; Test if SWI has been handled. Call unknown SWI handler.
Semihosting Vector Table Program Memory 0x100 0x104 0x108 0x00 Reset 0x04 Undefined 0x08 Software Interrupt ... 0x0c Prefetch Abort ... 0x10 Data Abort 0x14 Reserved 0x18 IRQ 0x1c FIQ SWI Handler CMP r0,#1 LDMFD sp!, {...} MOVEQS pc,lr Semi_SWI MOVS pc,lr ...
Semihosting 5.4 Semihosting SWIs The SWIs listed in Table 5-1 implement the semihosted operations. These operations are used by C library functions such as printf() and scanf(). They can be treated as ATPCS function calls. However, except for r0 that contains the return status, they restore the registers they are called with before returning. Some targets provide additional semihosting calls. See the ARM Firmware Suite (AFS) documentation for details of SWIs provided by AFS.
Semihosting Table 5-1 Semihosting SWIs (continued) SWI Description SYS_HEAPINFO (0x16) on page 5-25 Get the system heap parameters SYS_ELAPSED (0x30) on page 5-26 Get the number of target ticks since execution started SYS_TICKFREQ (0x31) on page 5-26 Determine the tick frequency Note When used with Angel, these SWIs use the serializer and the global register block, and they can take a significant length of time to process. 5.4.1 SYS_OPEN (0x01) Open a file on the host system.
Semihosting Return On exit, r0 contains: • a nonzero handle if the call is successful • –1 if the call is not successful. ARM DUI0058D Copyright © 1999-2001 ARM Limited. All rights reserved.
Semihosting 5.4.2 SYS_CLOSE (0x02) Closes a file on the host system. The handle must reference a file that was opened with SYS_OPEN. Entry On entry, r1 contains a pointer to a one-word argument block: word 1 This is a file handle referring to an open file. Return On exit, r0 contains: • 0 if the call is successful • –1 if the call is not successful. 5.4.3 SYS_WRITEC (0x03) Writes a character byte, pointed to by r1, to the debug channel.
Semihosting 5.4.5 SYS_WRITE (0x05) Writes the contents of a buffer to a specified file at the current file position. The file position is specified either: • explicitly, by a SYS_SEEK • implicitly as one byte beyond the previous SYS_READ or SYS_WRITE request. The file position is at the start of the file when the file is opened, and is lost when the file is closed. Perform the file operation as a single action whenever possible.
Semihosting 5.4.6 SYS_READ (0x06) Reads the contents of a file into a buffer. The file position is specified either: • explicitly by a SYS_SEEK • implicitly one byte beyond the previous SYS_READ or SYS_WRITE request. The file position is at the start of the file when the file is opened, and is lost when the file is closed. Perform the file operation as a single action whenever possible.For example, do not split a read of 16KB into four 4KB chunks unless there is no alternative.
Semihosting 5.4.7 SYS_READC (0x07) Reads a byte from the console. Entry Register r1 must contain zero. There are no other parameters or values possible. Return On exit, r0 contains the byte read from the console. 5.4.8 SYS_ISERROR (0x08) Determines whether the return code from another semihosting call is an error status or not. This call is passed a parameter block containing the error code to examine.
Semihosting 5.4.9 SYS_ISTTY (0x09) Checks whether a file is connected to an interactive device. Entry On entry, r1 contains a pointer to a one-word argument block: word 1 This is a handle for a previously opened file object. Return On exit, r0 contains: • 1 if the handle identifies an interactive device • 0 if the handle identifies a file • a value other than 1 or 0 if an error occurs. 5.4.10 SYS_SEEK (0x0A) Seeks to a specified position in a file using an offset specified from the start of the file.
Semihosting 5.4.11 SYS_FLEN (0x0C) Returns the length of a specified file. Entry On entry, r1 contains a pointer to a one-word argument block: word 1 This is a handle for a previously opened, seekable file object. Return On exit, r0 contains: • the current length of the file object, if the call is successful • –1 if an error occurs. 5.4.12 SYS_TMPNAM (0x0D) Returns a temporary name for a file identified by a system file identifier.
Semihosting 5.4.13 SYS_REMOVE (0x0E) Caution Deletes a specified file on the host filing system. Entry On entry, r1 contains a pointer to a two-word argument block: word 1 This points to a null-terminated string that gives the pathname of the file to be deleted. word 2 This is the length of the string. Return On exit, r0 contains: • 0 if the delete is successful • a nonzero, host-specific error code if the delete fails. 5.4.14 SYS_RENAME (0x0F) Renames a specified file.
Semihosting 5.4.15 SYS_CLOCK (0x10) Returns the number of centiseconds since the execution started. Values returned by this SWI can be of limited use for some benchmarking purposes because of communication overhead or other agent-specific factors. For example, with Multi-ICE the request is passed back to the host for execution. This can lead to unpredictable delays in transmission and process scheduling.
Semihosting 5.4.17 SYS_SYSTEM (0x12) Passes a command to the host command-line interpreter. This enables you to execute a system command such as dir, ls, or pwd. The terminal I/O is on the host, and is not visible to the target. Caution The command passed to the host is actually executed on the host. Ensure that any command passed will have no unintended consequences.
Semihosting 5.4.18 SYS_ERRNO (0x13) Returns the value of the C library errno variable associated with the host implementation of the semihosting SWIs. The errno variable can be set by a number of C library semihosted functions, including: • SYS_REMOVE • SYS_OPEN • SYS_CLOSE • SYS_READ • SYS_WRITE • SYS_SEEK. Whether errno is set or not, and to what value, is entirely host-specific, except where the ANSI C standard defines the behavior. Entry There are no parameters. Register r1 must be zero.
Semihosting 5.4.19 SYS_GET_CMDLINE (0x15) Returns the command line used to call the executable. Entry On entry, r1 points to a two-word data block to be used for returning the command string and its length: word 1 This is a pointer to a buffer of at least the size specified in word two. word 2 This is the length of the buffer in bytes. Return On exit: • Register r1 points to a two-word data block: word 1 This is a pointer to null-terminated string of the command line.
Semihosting 5.4.20 SYS_HEAPINFO (0x16) Returns the system stack and heap parameters. The values returned are typically those used by the C library during initialization. For ARMulator, the values returned are the those provided in peripherals.ami. For Multi-ICE, the values returned are the image location and the top of memory. The C library can override these values (see ADS Compilers and Libraries Guide for more information on memory management in the C library).
Semihosting 5.4.21 SYS_ELAPSED (0x30) Returns the number of elapsed target ticks since the support code started execution. Use SYS_TICKFREQ to determine the tick frequency. Entry On entry, r1 points to a two-word data block to be used for returning the number of elapsed ticks: word 1 The least significant word in the doubleword value. word 2 The most significant word. Return On exit, : • r0 contains –1 if r1 does point to a doubleword containing the number of elapsed ticks.
Semihosting 5.5 Debug agent interaction SWIs In addition to the C library semihosted functions described in Semihosting SWIs on page 5-11, the following SWIs support interaction with the debug agent: • The ReportException SWI. This SWI is used by the semihosting support code as a way to report an exception to the debugger. • The EnterSVC SWI. This SWI sets the processor to Supervisor mode. • The reason_LateStartup SWI. This SWI is obsolete and no longer supported. These are described below. 5.5.
Semihosting After executing the SWI, the current link register will be r14_SVC, not r14_USR. If the value of r14_USR is required after the call, it must be pushed onto the stack before the call and popped afterwards, as for a BL function call. 5-28 Copyright © 1999-2001 ARM Limited. All rights reserved.
Semihosting 5.5.2 angel_SWIreason_ReportException (0x18) This SWI can be called by an application to report an exception to the debugger directly. The most common use is to report that execution has completed, using ADP_Stopped_ApplicationExit. Entry On entry r1 is set to one of the values listed in Table 5-3 and Table 5-4. These values are defined in adp.h.
Semihosting Table 5-4 Software reason codes (continued) Name (#defined in adp.h) Hexadecimal value ADP_Stopped_RunTimeErrorUnknown *0x20023 ADP_Stopped_InternalError *0x20024 ADP_Stopped_UserInterruption 0x20025 ADP_Stopped_ApplicationExit 0x20026 ADP_Stopped_StackOverflow *0x20027 ADP_Stopped_DivisionByZero *0x20028 ADP_Stopped_OSSpecific *0x20029 * next to values in Table 5-4 on page 5-29 indicates that the value is not supported by the ARM debuggers.
Glossary The items in this glossary are listed in alphabetical order, with any symbols and numerics appearing at the end. ADP See Angel Debug Protocol. ADS See ARM Developer Suite. Advanced Microcontroller Bus Architecture On-chip communications standard for high-performance 32-bit and 16-bit embedded microcontrollers. AMBA See Advanced Microcontroller Bus Architecture. Angel Angel is a program that enables you to develop and debug applications running on ARM-based hardware.
Glossary ARM eXtended Debugger The ARM eXtended Debugger (AXD) is the latest debugger software from ARM that enables you to make use of a debug agent in order to examine and control the execution of software running on a debug target. AXD is supplied in both Windows and UNIX versions. ARM Symbolic Debugger An interactive source-level debugger providing high-level debugging support for languages such as C, and low-level support for assembly language.
Glossary Memory management unit Hardware that controls caches and access permissions to blocks of memory, and translates virtual to physical addresses. MMU See Memory Management Unit. Multi-ICE Multi-processor in-circuit emulator. ARM registered trademark. Processor An actual processor, real or emulated running on the target. A processor always has at least one context of execution. Processor Status Register See Program Status Register.
Glossary a debug agent controlling an ARM processor through hardware debug support (for example, Multi-ICE). Saved Program Status Register See Program Status Register Semihosting A mechanism whereby the target communicates I/O requests made in the application code to the host system, rather than attempting to support the I/O itself. Software Interrupt SWI. An instruction that causes the processor to call a programer-specified subroutine. Used by ARM to handle semihosting.
Index The items in this index are listed in alphabetical order, with symbols and numerics appearing at the end. The references given are to page numbers. A AddCounterDesc 4-46 AddCounterValue 4-47, 4-48 adp.h 5-29 ADP_Stopped_ApplicationExit 5-29 Angel adding SWI handler 5-8 debug agent interaction SWIs 5-27 Enter SVC mode 5-27 Report Exception SWI 5-29 semihosting SWIs 5-11 angel_SWIreason_EnterSVC 5-27 angel_SWIreason_ReportException 5-29 armflat.c ARMulator model 2-26 armmap.
Index Counters, ARMulator 4-35 CPRead, ARMulator function 4-10 CPWrite, ARMulator function 4-11 ARMul_ConsolePrint 4-53, 4-54, 4-55 ARMul_CPRead 4-10 ARMul_CPWrite 4-11 ARMul_DebugPause 4-56 ARMul_DebugPrint 4-52 ARMul_GetCPSR 4-7 ARMul_GetMode 4-9 ARMul_GetPC 4-6 ARMul_GetReg 4-5 ARMul_GetR15 4-6 ARMul_GetSPSR 4-8 ARMul_PrettyPrint 4-53, 4-54, 4-55 ARMul_RaiseError 4-45 ARMul_RaiseEvent 4-32 ARMul_ReadByte 4-38 ARMul_ReadHalfWord 4-38 ARMul_ReadWord 4-38 ARMul_ScheduleEvent 4-40 ARMul_SetCPSR 4-7 ARMul_S
Index profiler.
Index WriteWord, ARMulator function 4-39 write, ARMulator function 4-25 Z Zero wait state memory model 2-26 Symbols $memory_statistics 4-62 $statistics variable 4-35 $top_of_memory debugger variable 5-25 $vector_catch debugger variable 5-29 Index-4 Copyright © 1999-2001 ARM Limited. All rights reserved.
