A PIC-PID Example
=================

Contents
1	INTRODUCTION
1.1	Quick Start
1.1.1	Building under Windows
1.1.2	Building under Unix
1.1.3	Executing the ROM image
1.2	Terms and abbreviations
2	THE EXAMPLE IN DETAIL
2.1	The kernel
2.1.1	Module services
2.1.2	Registering services
2.1.3	Calling services
2.1.4	Locating service modules
2.1.5	The CLI
2.1.6	Accessing the static base
2.2	Linking the kernel
2.2.1	Placement of data
2.2.2	The symdefs file
2.3	Application modules
2.3.1	The module header
2.3.2	The kernel entry vector
2.3.3	Linking an application module
2.4	Making a ROM image
2.5     Debugging the example


1 INTRODUCTION

This example system consists of a kernel at a fixed address in ROM (or FLASH) 
together with a collection of application modules that extend the functionality 
of the kernel. There is a separate RAM space managed by the kernel.

Application modules are poured into the memory following the kernel. The address 
at which a module might be loaded is unknown when the module is linked. Modules 
must, therefore, be position-independent (ROPI, PIC).

A module implements a set of named services. When the kernel starts, it scans 
the ROM (or FLASH) looking for module registration functions. Each module 
registration function calls the kernel to register one or more named services.

Services can be multiply instated and can call one another via the kernel. When 
a service is called, the kernel creates an instance of its static data and then 
passes control to the service, which may call back to the kernel. Modules must, 
therefore, have position-independent data (RWPI, PID).

The kernel is not position-independent and cannot be instated more than once.  
The kernel is linked at a fixed address. When it is linked, the linker creates 
a list of symbol definitions to input to the link steps that create application 
modules. When an application module calls the kernel, it does so by calling a 
fixed address defined when the kernel was linked.

1.1 Quick Start

To build and run this example, use the following ready-made scripts:

1.1.1 Building under Windows

Execute the following batch files sequence:
    clean
    bldkern
    bldapps
    bldrom

1.1.2 Building under Unix

Execute the Makefile with make

1.1.3 Executing the ROM image

The ROM image may be loaded into an ARM debugger (armsd or AXD) and 
executed under the ARMulator or on real target hardware.

For example, to execute the ROM image with armsd under the ARMulator use:
    getfile romimage 0x8000
    pc=0x8000
    sp=0x80000
    go

For AXD:
    select 慒ile->Load Memory From File