mirror of
https://github.com/kelvinlawson/atomthreads.git
synced 2026-01-14 03:43:14 +01:00
ARM: Review READMEs.
This commit is contained in:
Kelvin Lawson
@@ -14,15 +14,18 @@ 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
|
||||
(BSP) folders. This allows the common ARM code 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.
|
||||
UARTs but share the same core OS context-switching routines etc.
|
||||
|
||||
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.
|
||||
platform-specific folders such as this contain the Makefile to build the
|
||||
project for that platform, so you may wish to head straight there if you
|
||||
wish to quickly get started building and running Atomthreads on ARM. The
|
||||
qemu_integratorcp platform is designed for the Integrator/CP platform with
|
||||
ARM926EJ-S processor, and can be run within QEMU for quick evaluation of
|
||||
Atomthreads without real hardware.
|
||||
|
||||
|
||||
---------------------------------------------------------------------------
|
||||
@@ -31,7 +34,7 @@ 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
|
||||
suite applications. You will normally make your own main() function
|
||||
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
|
||||
@@ -43,13 +46,14 @@ FILES IN THE COMMON ARM PORT FOLDER
|
||||
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.
|
||||
printf() and friends with GCC toolchains typically requires a heap, and
|
||||
thus a heap is supported in this file via the _sbrk() function. 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 left out of the build because they are defined with
|
||||
weak linkage.
|
||||
|
||||
|
||||
---------------------------------------------------------------------------
|
||||
@@ -60,24 +64,24 @@ 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
|
||||
* Startup code: see Reset_Handler in startup.s. Typically this will be (at
|
||||
least in the first few instructions) 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.
|
||||
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
|
||||
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
|
||||
@@ -86,17 +90,18 @@ from the qemu_integratorcp sample platform):
|
||||
* 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).
|
||||
layout unless your toolchain does not provide a suitable syscalls.c and
|
||||
you wish to use heap. In that case you will (at least initially) be
|
||||
using the heap implementation _sbrk() in syscalls.c in the common ARM
|
||||
port which expects "heap_top" and "end" (heap_base) to be defined by the
|
||||
linker script. These names 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.
|
||||
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.
|
||||
|
||||
|
||||
---------------------------------------------------------------------------
|
||||
|
||||
@@ -16,10 +16,11 @@ 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
|
||||
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.
|
||||
allows the sharing of common ARM port code between 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:
|
||||
|
||||
@@ -63,7 +64,7 @@ The port works out-of-the-box with the GCC tools (for building) and QEMU
|
||||
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
|
||||
that the Makefile for this platform assumes that your GCC binary is named
|
||||
"arm-none-eabi-gcc".
|
||||
|
||||
Currently we assume that the toolchain will provide some header files like
|
||||
@@ -91,8 +92,8 @@ 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.
|
||||
Running the entire automated test suite in one command via "make qemutests"
|
||||
also requires the "expect" program.
|
||||
|
||||
|
||||
---------------------------------------------------------------------------
|
||||
@@ -108,9 +109,9 @@ carry out the full build using the following:
|
||||
|
||||
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.
|
||||
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:
|
||||
@@ -126,7 +127,7 @@ both the kernel and port documentation from this folder using:
|
||||
|
||||
---------------------------------------------------------------------------
|
||||
|
||||
IntegratorCP SPECIFICS
|
||||
Integrator/CP 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
|
||||
@@ -147,9 +148,10 @@ 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.
|
||||
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.
|
||||
@@ -169,11 +171,11 @@ 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.
|
||||
changes, and is much faster than downloading 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.
|
||||
A single command runs every single test application, and automatically
|
||||
parses the (simulated) UART output to verify that each test case passes.
|
||||
|
||||
This requires two applications on your development PC: expect and QEMU.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user