From 3db57319415cc8d7ca844377ab0c5c62813a2f64 Mon Sep 17 00:00:00 2001 From: Kelvin Lawson Date: Wed, 6 Mar 2013 23:52:49 +0000 Subject: [PATCH] ARM README: Add details on porting to other platforms. --- ports/arm/README | 91 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 88 insertions(+), 3 deletions(-) diff --git a/ports/arm/README b/ports/arm/README index 31d28ae..ea1939e 100644 --- a/ports/arm/README +++ b/ports/arm/README @@ -6,12 +6,97 @@ License: BSD Revised --------------------------------------------------------------------------- -ARM PORT +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. -To Use: +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. -See the example project in the "platforms/qemu_integratorcp" directory. +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. + + +---------------------------------------------------------------------------