From 65edc4ab09b28aec08eecdf40b3b6f4b48ae156e Mon Sep 17 00:00:00 2001 From: Kelvin Lawson Date: Mon, 18 Mar 2013 23:34:38 +0000 Subject: [PATCH] ARM: Review READMEs. --- ports/arm/README | 71 +++++++++++--------- ports/arm/platforms/qemu_integratorcp/README | 36 +++++----- 2 files changed, 57 insertions(+), 50 deletions(-) diff --git a/ports/arm/README b/ports/arm/README index ea1939e..86b5545 100644 --- a/ports/arm/README +++ b/ports/arm/README @@ -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. --------------------------------------------------------------------------- diff --git a/ports/arm/platforms/qemu_integratorcp/README b/ports/arm/platforms/qemu_integratorcp/README index 5a084dd..7d96ba9 100644 --- a/ports/arm/platforms/qemu_integratorcp/README +++ b/ports/arm/platforms/qemu_integratorcp/README @@ -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.