From 248e1318fbe0fc86b3518f6955354a3171fabb64 Mon Sep 17 00:00:00 2001 From: Kelvin Lawson Date: Thu, 21 Jan 2010 21:42:10 +0000 Subject: [PATCH] Add README for all source folders --- README | 25 ++++++++++++++++++++++ kernel/README | 32 ++++++++++++++++++++++++++++ ports/avr/README | 7 +++++++ tests/README | 54 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 118 insertions(+) create mode 100644 kernel/README create mode 100644 tests/README diff --git a/README b/README index 313b773..79ab9b2 100644 --- a/README +++ b/README @@ -20,3 +20,28 @@ architecture-specific file. --------------------------------------------------------------------------- +DOCUMENTATION: + +All documentation is contained within the source files, commented using +Doxygen markup. Pre-generated documentation can be accessed at +http://atomthreads.com. + +See also the README file contained within each folder of the source tree. + +--------------------------------------------------------------------------- + +GETTING STARTED: + +Building of the sources is carried out from the ports tree. For example to +make a software build for the AVR architecture see ports/avr/README. + +--------------------------------------------------------------------------- + +SOURCE TREE: + + * kernel Core kernel sources + * tests Automated test suite + * ports CPU architecture ports + +--------------------------------------------------------------------------- + diff --git a/kernel/README b/kernel/README new file mode 100644 index 0000000..3d33f3f --- /dev/null +++ b/kernel/README @@ -0,0 +1,32 @@ +--------------------------------------------------------------------------- + +Library: Atomthreads +Author: Kelvin Lawson +Website: http://atomthreads.com +License: BSD Revised + +--------------------------------------------------------------------------- + +KERNEL SOURCES + +This folder contains the core Atomthreads operating system modules. + + * atomkernel.c: Core scheduler facilities + * atommutex.c: Mutual exclusion + * atomqueue.c: Queue / message-passing + * atomsem.c: Semaphore + * atomtimer.c: Timer facilities and system clock management + +Each module source file contains detailed documentation including an +introduction to usage of the module and full descriptions of each API. +Refer to the sources for further documentation. + +--------------------------------------------------------------------------- + +BUILDING THE KERNEL + +The kernel is built from the architecture port folder. Build instructions +are included in the README file for each port. + +--------------------------------------------------------------------------- + diff --git a/ports/avr/README b/ports/avr/README index aa90dc1..8ea6e1a 100644 --- a/ports/avr/README +++ b/ports/avr/README @@ -1,5 +1,12 @@ --------------------------------------------------------------------------- +Library: Atomthreads +Author: Kelvin Lawson +Website: http://atomthreads.com +License: BSD Revised + +--------------------------------------------------------------------------- + AVR/ATMEGA PORT This folder contains a port of the Atomthreads real time kernel for the diff --git a/tests/README b/tests/README new file mode 100644 index 0000000..e343a7a --- /dev/null +++ b/tests/README @@ -0,0 +1,54 @@ +--------------------------------------------------------------------------- + +Library: Atomthreads +Author: Kelvin Lawson +Website: http://atomthreads.com +License: BSD Revised + +--------------------------------------------------------------------------- + +AUTOMATED TEST SUITE + +This folder contains a set of automated tests which can be used to prove +reliable operation of all kernel facilities. + +Each kernel module has an associated set of test modules which are +designed to thoroughly exercise and prove all APIs and usage scenarios. +Tests are run on the embedded target device and can therefore be used to +gain confidence in ports to your target hardware or CPU architecture. +Developers of new CPU architecture ports can take advantage of the thorough +coverage provided by these tests to considerably speed up development and +validation time. + +--------------------------------------------------------------------------- + +HOW TO RUN THE TESTS + +The automated test suite is built automatically from the architecture port +folder. Instructions are included in the README file for each port, which +describes the process for building test applications as well as downloading +to and running the tests on the target device. + +--------------------------------------------------------------------------- + +WRITING ADDITIONAL TESTS + +If you wish to write additional tests you can base them on the file +test-template.c. This contains an empty test function with the correct +API for use by port test launchers. + +The test functions return the number of failures which can be used by the +port's test launcher application to report the test result. Tests can, +however, also call ATOMLOG() to print details out on a UART or similar +if such a facility is available on the port in question. These log +messages can be omitted from an architecture port if desired. + +When writing generic tests to run on all CPU architectures, bear in mind +that Atomthreads can run on tiny 8-bit devices with limited RAM and other +resources. For this reason it aids portaibility if tests are broken up into +modules which do not consume large amounts of processor resource. For +example the number of test threads should ideally be kept low in order to +allow smaller systems to accommodate the thread stack requirements. + +--------------------------------------------------------------------------- +