SWI Example
===========

This directory contains an example of SWI handling.

The files provided are:

main.c    - contains the main() function, which installs the SWI vector in the 
            exception table, then calls some SWIs (0, 1, 2 & 3) via __swi()

ahandle.s - is the top-level SWI handler, written in assembler.  It is entered 
            via the SWI vector of the execption table.  Both ARM & Thumb SWIs 
            are identified and passed to chandle.c for processing.

chandle.c - is a second-level SWI handler, called from ahandle.s.  
            SWIs 0, 1, 2 & 3 execute some simple arithmetic.

swi.h     - contains the definitions of __swi(0), __swi(1), __swi(2) & __swi(3).
            __swi(3) has an associated __value_in_regs structure for returning 
            values in registers.


To build this example, use the supplied makefile or CodeWarrior project file.
Alternatively, to build from the command-line, use:

armasm -g ahandle.s
armcc -c -g -O1 main.c
armcc -c -g -O1 chandle.c
armlink ahandle.o main.o chandle.o -o swi.axf

This produces an ELF executable file (swi.axf) which can be loaded into an 
ARM debugger.

For an overview of the principles of a SWI handler, see the Developer Guide, 
chapter 6.



Appendix 1 - Cached Cores
=========================

If you are using a processor with separate instruction and data caches, 
such as StrongARM, or ARM940T, you must ensure that cache coherence problems 
do not prevent the new contents of the vectors from being used. 
The data cache (or at least the entries containing the modified vectors) must 
be cleaned to ensure the new vector contents are written to main memory. You 
must then flush the instruction cache to ensure that the new vector contents 
are read from main memory.  For details of cache clean and flush operations, 
see the datasheet for your target processor.



Appendix 2 - Multi-ICE & Semihosting
====================================

This example has been written for running on ARMulator, and you may experience 
some problems running it on real hardware.  To enable semihosting, Multi-ICE 
must set a breakpoint, by default on the SWI entry of the vector table.  
However, if a software breakpoint is set, this may be accidentally overwritten 
when the SWI handler is installed by the program.  This problem can be avoided 
by changing the address at which Multi-ICE places the breakpoint.  For details 
on how to do this and more background information please refer to:
Multi-ICE 2.2 - User Guide (Chapter 4)
and
RealView Compilation Tools - Developer Guide (Chapter 6).
