From 4e7c9c4c529b33d300914cc29166c608ae9aad7f Mon Sep 17 00:00:00 2001 From: Kelvin Lawson Date: Tue, 5 Mar 2013 02:28:38 +0000 Subject: [PATCH] ARM/IntegratorCP: Add platform README. Other ports, rename old atomuser.h (now atomport.h). --- ports/arm/platforms/qemu_integratorcp/README | 213 ++++++++++++++++++- ports/avr/README | 2 +- ports/stm8/README-COSMIC | 2 +- ports/stm8/README-IAR | 2 +- ports/stm8/README-RAISONANCE | 2 +- 5 files changed, 215 insertions(+), 6 deletions(-) diff --git a/ports/arm/platforms/qemu_integratorcp/README b/ports/arm/platforms/qemu_integratorcp/README index 7df10a7..5a084dd 100644 --- a/ports/arm/platforms/qemu_integratorcp/README +++ b/ports/arm/platforms/qemu_integratorcp/README @@ -2,11 +2,220 @@ Library: Atomthreads QEMU ARM Integrator/CP (ARM926EJ-S) Platform. Author: Natie van Rooyen +Website: http://atomthreads.com License: BSD Revised --------------------------------------------------------------------------- QEMU ARM Integrator/CP (ARM926EJ-S) Platform -The "qemu_integratorcp" platform contains sources for building a sample -Atomthreads application for the ARM Integrator/CP (ARM926EJ-S) platform. +The "qemu_integratorcp" platform folder contains sources for building a +sample Atomthreads application for the ARM Integrator/CP (ARM926EJ-S) +platform running under QEMU. + +All of the cross-platform kernel code is contained in the top-level +'kernel' folder, while ports to specific CPU architectures are contained in +the 'ports' folder tree. To support multiple ARM boards/platforms using a +single common ARM architecture port, the ARM port contains platform +sub-folders in which the board/platform-specific code is situated. This +allows many different ARM boards with different interrupt controllers, UARTs +etc but which all reuse the same common core ARM context-switching code. + +This platform contains a few key platform-specific files: + + * startup.s: Interrupt vector table and basic startup assembly code + * modules.c: Low level initialisation for this platform + * uart.c: Simple UART implementation for debug purposes + +The common ARM architecture port that is used across all platforms contains +the basic code for thread-switching on all ARM platforms: + + * atomport.c: Those functions which can be written in C + * atomport-asm.s: The main register save/restore assembler routines + +Each Atomthreads port requires also a header file which describes various +architecture-specific details such as appropriate types for 8-bit, 16-bit +etc variables, the port's system tick frequency, and macros for performing +interrupt lockouts / critical sections: + + * atomport.h: Port-specific header required by the kernel for each port + +A couple of additional source files are also included in the common ARM port: + + * tests-main.c: Main application file (used for launching automated tests) + * syscalls.c: Simple implementation of open/close/read/write for stdio + +Atomthreads includes a suite of automated tests which prove the key OS +functionality, and can be used with any architecture ports. This port +provides an easy mechanism for building and quickly running the test suite +using QEMU to prove the OS without requiring any target hardware. + +This platform folder has been tested on a variety of GCC ARM toolchains, +including hosted and non-hosted. + + +--------------------------------------------------------------------------- + +GCC TOOLCHAIN + +The port works out-of-the-box with the GCC tools (for building) and QEMU +(for simulation). It can be built on any OS for which GCC is available, and +was tested using the CodeSourcery toolchain (2009q3 non-Linux but others +should be supported) and self-built toolchains such as hosted toolchains +built by build_arm_toolchain.sh (see http://navaro.nl for details). Note +that the Makefile for this platform assumes your GCC binary is named +"arm-none-eabi-gcc". + +Currently we assume that the toolchain will provide some header files like +stdint.h. Not all toolchains will include this, in which case you simply +need to add definitions for int32_t and friends in atomport.h, in place of +the include declaration for stdint.h. + +Some toolchains provide newlib syscalls.c which implement stdio +functionality via open, close, read, write. Hosted toolchains will +automatically provide versions of these which work with QEMU, and no UART +driver will be needed to view the stdio printf()s etc. If these are not +provided by by the compiler toolchain then backup implementations are +implemented within the common ARM port folder (see ports/arm/syscalls.c) +and a UART driver is implemented here in uart.c. + +Similarly some toolchains provide startup assembly code via +_mainCRTStartup(). If this is not provided by the toolchain then a backup +version is used within modules.c. + + +--------------------------------------------------------------------------- + +OTHER PREREQUISITES + +QEMU is used for simulation of the target and versions 0.14.1, 1.2.0 & +1.4.0 were tested. + +Running the entire automated test suite via "make qemutests" also requires +the "expect" program. + + +--------------------------------------------------------------------------- + +BUILDING THE SOURCE + +A Makefile is provided for building the kernel, port, platform and +automated tests. Make sure the ARM GCC toolchain is in the path +(e.g. "PATH=$PATH:/opt/arm-2009q3/bin && export path") as well as QEMU and +carry out the full build using the following: + + * make all + +All objects are built into the 'build' folder under +ports/arm/platforms/qemu_integrator_cp. The build process builds separate +target applications for each automated test, and appropriate ELF files can be +found in the build folder ready for running on the target or within QEMU. +Each test is built and run as a separate application. + + +All built objects etc can be cleaned using: + + * make clean + + +The Atomthreads sources are documented using Doxygen markup. You can build +both the kernel and port documentation from this folder using: + + * make doxygen + + +--------------------------------------------------------------------------- + +IntegratorCP SPECIFICS + +The test applications make use of the Integrator's UART to print out +pass/fail indications and other information. For this you should connect a +serial debug cable to the board or when running in QEMU you will see the +UART messages on the console when running the test applications. + + +--------------------------------------------------------------------------- + +AUTOMATED TESTS + +Atomthreads contains a set of generic kernel tests which can be run on any +port to prove that all core functionality is working on your target. + +The full set of tests can be found in the top-level 'tests' folder. Each of +these tests is built as an independent application in the 'build' folder. + +These can be run on the target or within QEMU using the instructions below. + +To view the test results, connect a serial debug cable to your target +platform or view the console if using QEMU. On starting, the test applications +print out "Go" on the UART. Once the test is complete they will print +out "Pass" or "Fail", along with other information if the test failed. + +Most of the tests complete within a few seconds, but some (particularly +the stress tests) can take longer, so be patient. + +The full suite of tests endeavours to exercise as much of the kernel code +as possible, and can be used for quick confirmation of core OS +functionality if you ever need to make a change to the kernel or port. + +The test application main() is contained in tests-main.c. This initialises +the OS, creates a main thread, and calls out to the test modules. + + +--------------------------------------------------------------------------- + +RUNNING TESTS WITHIN THE QEMU SIMULATOR + +It is possible to run the full automated test suite in a simulator without +programming the test applications into real hardware. This is very useful +for quick verification of the entire test suite after making any software +changes, and is much faster than download each test application to a real +target. + +A single command runs every single test application, and checks the +(simulated) UART output to verify that each test case passes. + +This requires two applications on your development PC: expect and QEMU. + +To run all tests in one command, type: + + * make qemutests + +This will run every single test application within the simulator and quit +immediately if any one test fails. + +The ability to run these automated tests in one command (and without real +hardware) allows you to easily include the OS test suite in your nightly +build or continous integration system and quickly find out if any of your +local changes have caused any of the operating system tests to fail. + + +--------------------------------------------------------------------------- + +DEBUGGING WITH QEMU + +You may also use QEMU in combination with GDB to debug your built +applications. To do this you should start QEMU with "-S -s" options e.g.: + + * qemu-system-arm -M integratorcp -semihosting -nographic -kernel app.elf + +You can now start GDB and attach to the target: + + * arm-none-eabi-gdb + * file app.elf + * target remote localhost:1234 + + +--------------------------------------------------------------------------- + +WRITING APPLICATIONS + +The easiest way to start a new application which utilises the Atomthreads +scheduler is to base your main application startup on tests-main.c. This +initialises the OS and calls out to the test module entry functions. You +can generally simply replace the call to the test modules by a call to your +own application startup code. + + +--------------------------------------------------------------------------- + diff --git a/ports/avr/README b/ports/avr/README index 059f3cb..8948c64 100644 --- a/ports/avr/README +++ b/ports/avr/README @@ -27,7 +27,7 @@ architecture-specific details such as appropriate types for 8-bit, 16-bit etc variables, the port's system tick frequency, and macros for performing interrupt lockouts / critical sections: - * atomuser.h: Port-specific header required by the kernel for each port + * atomport.h: Port-specific header required by the kernel for each port A couple of additional source files are also included here: diff --git a/ports/stm8/README-COSMIC b/ports/stm8/README-COSMIC index c77d813..b980265 100644 --- a/ports/stm8/README-COSMIC +++ b/ports/stm8/README-COSMIC @@ -28,7 +28,7 @@ architecture-specific details such as appropriate types for 8-bit, 16-bit etc variables, the port's system tick frequency, and macros for performing interrupt lockouts / critical sections: - * atomuser.h: Port-specific header required by the kernel for each port + * atomport.h: Port-specific header required by the kernel for each port A few additional source files are also included here: diff --git a/ports/stm8/README-IAR b/ports/stm8/README-IAR index c535fb1..c4f34ba 100644 --- a/ports/stm8/README-IAR +++ b/ports/stm8/README-IAR @@ -28,7 +28,7 @@ architecture-specific details such as appropriate types for 8-bit, 16-bit etc variables, the port's system tick frequency, and macros for performing interrupt lockouts / critical sections: - * atomuser.h: Port-specific header required by the kernel for each port + * atomport.h: Port-specific header required by the kernel for each port A few additional source files are also included here: diff --git a/ports/stm8/README-RAISONANCE b/ports/stm8/README-RAISONANCE index 5ae8226..a3772cf 100644 --- a/ports/stm8/README-RAISONANCE +++ b/ports/stm8/README-RAISONANCE @@ -28,7 +28,7 @@ architecture-specific details such as appropriate types for 8-bit, 16-bit etc variables, the port's system tick frequency, and macros for performing interrupt lockouts / critical sections: - * atomuser.h: Port-specific header required by the kernel for each port + * atomport.h: Port-specific header required by the kernel for each port A few additional source files are also included here: