atomthreads

---------------------------------------------------------------------------

Library:      Atomthreads ARM Port
Author:       Natie van Rooyen <natie@navaro.nl>
License:      BSD Revised

---------------------------------------------------------------------------

ARM PORT

This folder contains a port of the Atomthreads real time kernel for the
ARM processor architecture. This port was tested on the ARMv5 and ARMv7 
architectures.

The same common/core port can be used on a wide variety of ARM devices
but platform-specific code has been separated out into multiple "platform"
folders. This allows the common ARM port to be shared among several
different ARM platforms and boards. For example different ARM devices and
platforms might use different interrupt controllers, timer subsystems and
UARTs.

An example platform is in the "platforms/qemu_integratorcp" folder. The
Makefile for all ARM ports is in the platform-specific folders, so you
may wish to head straight there for full instructions on how to build
and use Atomthreads on a particular ARM platform.


---------------------------------------------------------------------------

FILES IN THE COMMON ARM PORT FOLDER

 * tests-main.c: Contains a sample Atomthreads application starting at
   main() that initialises the operating system and runs the automated test
   suite applications. You will make your own main() function or similar
   suitable for your application, possibly using this as a basis.
 * atomport-asm.s: Contains the main assembler code that forms the portion
   of the core ARM architecture port that must be implemented in assembler
   (e.g. register save/restore for thread context-switching).
 * atomport.c: Contains the main C code that forms the portion of the core
   ARM architecture port that can be implemented in C (e.g. prefilling the
   stack context for new threads).
 * syscalls.c: Contains the open/close/read/write/heap-management
   functions typically required if you want to do anything with stdio
   (e.g. printf() calls etc). This is a very simple implementation that
   always writes to the UART regardless of which file is "opened". Use of
   printf() and friends with GCC toolchains typically requires heap, which
   is supported via the _sbrk() function in here. Your linker script should
   specify where the heap starts and stops using "end" and "heap_top"
   definitions respectively. Note that in QEMU environments this may not be
   required as some "semi-hosted" toolchains implement these functions and
   the UART driver for you. In that case these functions will be ignored
   because they are defined with weak linkage.


---------------------------------------------------------------------------

PORTING TO NEW ARM PLATFORMS

To port Atomthreads to your ARM platform you must provide the following
functionality in your platform folder (in all cases example filenames are
from the qemu_integratorcp sample platform):

 * Startup code: see Reset_Handler in startup.s. Typically this will be
   at least initially some assembly code, and will set up the initial
   stack pointer, perform any copying of segments from flash to RAM,
   zero the BSS section etc, before branching to the main application
   function (e.g. main()). At some point during initialisation the timer
   tick interrupt required by the OS should be started (100 ticks per
   second) and this might be done here in the very early startup code.
   Note that some compiler toolchains will provide a portion of the C
   startup code e.g. the function _mainCRTStartup() provided by some
   GCC toolchains.
 * Interrupt vector table: see __interrupt_vector_table in startup.s.
   Typically this will contain at least an entry for the startup/reset
   code, and an entry for the hardware IRQ handler. In order to share
   common code amongst all platforms, the hardware IRQ handler
   (archIRQHandler()) is actually implemented in the common ARM port
   folder but calls back out to a dispatcher function in your platform
   folder to determine the source of the interrupt and handle
   it appropriately. Your platform folder should contain this dispatcher
   function (__interrupt_dispatcher). It must support at least the timer
   interrupt service routine (atomTimerTick()) required by the OS. The
   dispatcher also handles other hardware interrupt sources; it determines
   the source of the IRQ and calls out to the appropriate ISR for that 
   interrupt.
 * Linker script: Here you should specify the location of the interrupt
   vector table within RAM, location of code/text segment etc. The
   Atomthreads ARM port does not dictate particular section names or
   layout unless your toolchain does not provide a suitable syscalls.c
   and you instead get the heap _sbrk() implementation from Atomthreads'
   sample syscalls.c which expects "heap_top" and "end" (heap_base) to
   be defined by the linker script (which can be easily changed in
   ports/arm/syscalls.c if necessary).
 * UART driver: You should provide at least a UART write routine If you
   would like to see debug statements, for example to see the results of
   running the automated test suite. See uart.c for a simple example.
   Note that for QEMU targets some semihosted toolchains will implement
   this for you, in which case you won't need either
   ports/arm/syscalls.c or a UART driver.


---------------------------------------------------------------------------