From 02c9cd040cdffb6c0dc1e4a3bbf18e974b6b6414 Mon Sep 17 00:00:00 2001 From: Kelvin Lawson Date: Tue, 1 Jun 2010 22:40:54 +0100 Subject: [PATCH] STM8: Add README for IAR EWSTM8 compiler. --- ports/stm8/README | 52 +++--- ports/stm8/README-IAR | 372 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 401 insertions(+), 23 deletions(-) create mode 100644 ports/stm8/README-IAR diff --git a/ports/stm8/README b/ports/stm8/README index 56225e8..c87bae5 100644 --- a/ports/stm8/README +++ b/ports/stm8/README @@ -7,10 +7,11 @@ License: BSD Revised --------------------------------------------------------------------------- -STM8 PORT +STM8 PORT - COSMIC COMPILER This folder contains a port of the Atomthreads real time kernel for the -STM8 processor architecture. +STM8 processor architecture. These instructions cover usage of Atomthreads +with the Cosmic compiler (CXSTM8). All of the cross-platform kernel code is contained in the top-level 'kernel' folder, while ports to specific CPU architectures are contained in @@ -43,10 +44,12 @@ provides an easy mechanism for building, downloading and running the test suite to prove the OS on your target. The port was carried out and tested on an STM8S105C6 running within an -STM8S-Discovery board, utilising the Cosmic compiler tools. It is possible -to use it with other processors in the STM8 range, as well as other -hardware platforms and compilers, with minimal changes. Platform and -compiler specific code has been kept to an absolute minimum. +STM8S-Discovery board, and supports both the Cosmic and IAR compiler tools. +It is possible to use it with other processors in the STM8 range, as well +as other hardware platforms and compilers, with minimal changes. Platform +and compiler specific code has been kept to an absolute minimum. This +README covers usage of Atomthreads with the Cosmic compiler. Instructions +for users of the IAR compiler are available in README-IAR. --------------------------------------------------------------------------- @@ -73,7 +76,7 @@ The core software prerequisites are therefore: Optionally, application build, program and debug can be carried out using ST's visual debug tool, STVD. -Use with alternative compiler tools may require some modification, but you +Use with alternative compiler tools will require some modification, but you can easily replace STVP by your own favourite programmer if required. @@ -255,10 +258,11 @@ RUNNING THE 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. -Run them individually using the STVP process described above. For example -to run the 'kern1.c' test use STVP to program and run it. +The full set of tests can be found in the top-level 'tests' folder. The +Makefile builds each of these tests as independent applications in the +'build' folder. Run them individually using the STVP process described +above. For example to run the 'kern1.c' test use STVP to program and run +it. To view the test results, watch the LED on the STM8S-Discovery. This will flash once per second if the test passed, and once every 1/8 second if the @@ -347,9 +351,9 @@ what level of stack the application code in question requires. At this time the maximum stack consumed by the test threads within the automated test modules is 95 bytes of stack, and the main test thread has -been seen to consume 161 bytes of stack. At this time the timer2 test is -the largest consumer of test thread stack (95 bytes) and the sem4 test -consumes the largest main thread stack (161 bytes). If your applications +been seen to consume 163 bytes of stack. At this time the timer2 test is +the largest consumer of test thread stack (95 bytes) and the sem3 test +consumes the largest main thread stack (163 bytes). If your applications have large amounts of local data or call several subroutines then you may find that you need larger than 128 bytes. @@ -468,7 +472,8 @@ memory. These registers are called c_x, c_y and c_lreg. The Atomthreads context switch for Cosmic/STM8 takes advantage of the fact that all CPU and virtual registers are automatically saved on the stack by -the compiler when calling out to C functions. +the compiler when calling out to C functions (and even then only if +necessary). For cooperative context switches (where a thread calls an OS kernel function to schedule itself out), any of these registers which should be @@ -479,18 +484,19 @@ routine, making cooperative switches potentially very cheap if few registers must be preserved. For preemptive switches (where an ISR has interrupted a thread and wishes -to switch to a new thread), the interrupt handler prologue also saves all -CPU and virtual registers. In this case all registers must always be saved +to switch to a new thread), the interrupt handler prologue automatically +saves all CPU registers (actually done automatically by the CPU) and all +of the virtual registers. In this case all registers must always be saved because the ISR has no knowledge of what registers the interrupted thread was using, so we cannot take advantage of the potential for saving fewer than the full set of registers that we achieve with cooperative switches. With the Cosmic compiler, interrupt handlers that call out to C functions -(as would happen on a thread switch) always save the CPU registers and -the virtual registers c_x and c_y. For the Atomthreads port we force -interrupt handlers to also save the virtual register c_lreg. This is to -ensure that the interrupted thread's c_lreg value is preserved across a -thread switch, but also ensures that longs can be used within the OS -kernel code called by interrupt handlers (c_lreg is used by the compiler +(as would happen on a thread switch) always save the CPU registers (done by +the CPU in fact) and the virtual registers c_x and c_y. For the Atomthreads +port we force interrupt handlers to also save the virtual register c_lreg. +This is to ensure that the interrupted thread's c_lreg value is preserved +across a thread switch, but also ensures that longs can be used within the +OS kernel code called by interrupt handlers (c_lreg is used by the compiler for handling longs and floats). An alternative scheme would be to not save c_lreg in all interrupt diff --git a/ports/stm8/README-IAR b/ports/stm8/README-IAR new file mode 100644 index 0000000..91320bd --- /dev/null +++ b/ports/stm8/README-IAR @@ -0,0 +1,372 @@ +--------------------------------------------------------------------------- + +Library: Atomthreads +Author: Kelvin Lawson +Website: http://atomthreads.com +License: BSD Revised + +--------------------------------------------------------------------------- + +STM8 PORT - IAR COMPILER + +This folder contains a port of the Atomthreads real time kernel for the +STM8 processor architecture. These instructions cover usage of Atomthreads +with the IAR Embedded Workbench compiler (EWSTM8). + +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. A port to a CPU architecture can comprise just one +or two modules which provide the architecture-specific functionality, such +as the context-switch routine which saves and restores processor registers +on a thread switch. In this case, the kernel port is split into two files: + + * atomport.c: Those functions which can be written in C + * atomport-asm-iar.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: + + * atomuser.h: Port-specific header required by the kernel for each port + +A few additional source files are also included here: + + * tests-main.c: Main application file (used for launching automated tests) + * uart.c: UART wrapper to allow use of stdio/printf() + * stm8s-periphs/*.*: Peripheral drivers as delivered by ST (no changes + to distributed code). + +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, downloading and running the test +suite to prove the OS on your target. + +The port was carried out and tested on an STM8S105C6 running within an +STM8S-Discovery board, and supports both the Cosmic and IAR compiler tools. +It is possible to use it with other processors in the STM8 range, as well +as other hardware platforms and compilers, with minimal changes. Platform +and compiler specific code has been kept to an absolute minimum. This +README covers usage of Atomthreads with the IAR compiler. Instructions for +users of the Cosmic compiler are available in README-COSMIC. + + +--------------------------------------------------------------------------- + +PREREQUISITES + +The port works out-of-the-box with the IAR compiler tools for building. +Applications are generated in .out form and can be programmed and debugged +using the IAR Embedded Workbench GUI. + +IAR Embedded Workbench for STM8 is a Windows-only application. For +users of other operating systems the IAR tools may work in environments +like Wine, but the USB programming tools are less likely to be supported. +Embedded Workbench for STM8 can, however, be run successfully within a VM +such as VirtualBox, including USB download and debug. + +The core software prerequisites are therefore: + * IAR Embedded Workbench STM8 + +Use with alternative compiler tools will require some modification, but you +can easily replace the EWSTM8 IDE by your own favourite programmer if +required. + + +--------------------------------------------------------------------------- + +BUILDING THE SOURCE + +A sample EWSTM8 project has been provided. This permits easy building, +programming and debugging within the EWSTM8 IDE. + +Unlike the Cosmic compiler port, there is currently no Makefile-based build +provided for use with EWSTM8. Only a sample IDE project is available. + + +--------------------------------------------------------------------------- + +BUILD VIA EWSTM8 PROJECT + +For building applications using the EWSTM8 IDE you can use the sample +project file atomthreads-sample-iar.ewp. This builds a sample full +application which runs the "sem1" automated test. Applications can be +downloaded directly to the target hardware (e.g. STM8S-Discovery) and run +via the integrated debugger. You can start the application running, and +confirm that the LED flashes once per second (if running on an +STM8S-Discovery) to ensure that the test has passed. + +This is also a good starting point for building your own applications: +simply modify the file tests-main.c which starts the test application. +You can run any of the other automated tests by replacing the file sem1.c +within the project by another of the tests within the atomthreads tests +folder. In time a Makefile will be provided that will build all of the +automated tests with one command. Currently the Makefile supports only the +Cosmic compiler. + + +--------------------------------------------------------------------------- + +BUILD VIA MAKEFILE + +The STM8 port Makefile currently only supports building for the Cosmic +compiler. An IAR-capable Makefile will be released soon. + + +--------------------------------------------------------------------------- + +STM8S-DISCOVERY SPECIFICS + +There are very minimal board-specific aspects to the STM8 port so it is +trivial to run Atomthreads on other STM8 platforms. + +The test applications make use of a LED to indicate test pass/fail status. +This is currently configured to use a bit in GPIOD, which on the Discovery +board maps to the board's only LED. You may change the port and register +bit in tests-main.c to utilise a different pin on other hardware platforms. +You may also completely omit the LED flashing in the test application if +you prefer to use the UART for monitoring test status. + +The test applications also make use of the UART to print out pass/fail +indications and other information. For this you should connect a serial +cable to the Discovery board via the external pin connectors. Use of +a UART is not required if you prefer to use the LED or some other method +of notifying test pass/fail status. + +To connect a serial cable to the Discovery you will need to connect to +the following pins on the external connectors: + Vcc: CN2 pin 8 + GND: CN2 pin 7 + UART TX: CN4 pin 10 (connect to RX at the PC end) + UART RX: CN4 pin 9 (connect to TX at the PC end) +Note that the board uses TTL levels so you may need to use a level +converter. External level converters may need to be powered using +a Vdd of 5v, which can be achieved by positioning JP1 on the Discovery. + +The STM8 device on the Discovery only offers UART2. If you are using a +different device or wish to use an alternative UART then you must change +the stm8s_conf.h file. + +If you are using a CPU other than the STM8S105C6 you should modify +the project C/C++ Compiler Preprocessor settings for both Debug and Release +projects to specify your CPU (currently set to STM8S105), and set the +target device in the project "General Options". You may also wish to enable +any CPU peripherals which you wish to use in the stm8s_conf.h file. + + +--------------------------------------------------------------------------- + +RUNNING THE 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 +test is built and run as a single individual application. To run the full +test suite with EWSTM8 you must modify the EWSTM8 sample project many +times, swapping out the 'sem1' test included by default. This is not +currently automated, so for the time being you must swap the test module, +build the project and run it, repeating this for each test. For example to +run the 'kern1.c' test you remove 'sem1.c' from the project and add +'kern1.c', then build the project and run on the target. + +A Makefile to build all applications in one command is planned, but for +the time being a Makefile is only available for the Cosmic compiler. + +To view the test results, watch the LED on the STM8S-Discovery. This will +flash once per second if the test passed, and once every 1/8 second if the +test failed. + +If you wish to use the UART, connect a serial debug cable to your target +platform (defaults to 9600bps 8N1). 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 several seconds, 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. It also +initialises the UART driver for use by stdout. + + +--------------------------------------------------------------------------- + +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, sets up a UART 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. + +Projects developed within EWSTM8 can be started using the sample project +atomthreads-sample-iar.ewp. If you wish to create your own EWSTM8 project +from scratch, then you should ensure you change the project settings for +both Debug and Release builds as follows: + +* General Options -> Target -> Device: CPU part (e.g. "STM8S105C6") +* C/C++ Compiler -> Diagnostics: Suppress "Pa050" +* C/C++ Compiler -> Preprocessor -> Defined Symbols: + CPU part (e.g. "STM8S105") + Thread stack-checking if required ("ATOM_STACK_CHECKING") + For example "STM8S105, ATOM_STACK_CHECKING" +* Assembler -> Diagnostics: Suppress "Pa050" +* Repeat above for Debug and Release projects (you may want to + disable ATOM_STACK_CHECKING for Release builds). + +Other options you may wish to change: + +* Tools -> Options -> Editor -> EOL Characters: "Preserve". This preserves + the line endings, bearing in mind that the Atomthreads kernels works + with many host operating system toolchains. +* Options -> Debugger -> "ST Link" (e.g. for STM8S Discovery) + +Add the .C and .S modules from the following folders: +* kernel +* ports/stm8 +* ports/stm8s-periphs + +Set include paths as appropriate. + + +--------------------------------------------------------------------------- + +RAM FOOTPRINT & STACK USAGE + +The Atomthreads kernel is written in well-structured pure C which is highly +portable and not targeted at any particular compiler or CPU architecture. +For this reason it is not highly optimised for the STM8 architecture, and +by its nature will likely have a higher text and data footprint than an +RTOS targeted at the STM8 architecture only. The emphasis here is on +C-based portable, readable and maintainable code which can run on any CPU +architecture, from the 8-bitters up. + +A good rule of thumb when using Atomthreads on the STM8 architecture is +that a minimum of 1KB RAM is required in order to support an application +with 4 or 5 threads and the idle thread. If a minimum of approximately +128 bytes per thread stack is acceptable then you will benefit from the +easy-to-read, portable implementation of an RTOS herein. + +The major consumer of RAM when using Atomthreads is your thread stacks. +Functionality that is shared between several kernel modules is farmed out +to separate functions, resulting in readable and maintainable code but +with some associated stack cost of calling out to subroutines. Further, +each thread stack is used for saving its own registers on a context +switch, and there is no separate interrupt stack which means that each +thread stack has to be able to cope with the maximum stack usage of the +kernel (and application) interrupt handlers. + +Clearly the stack requirement for each thread depends on what your +application code does, and what memory model is used etc, but generally +you should find that 128 bytes is enough to allow for the thread to be +switched out (and thus save its registers) while deep within a kernel +or application call stack, and similarly enough to provide stack for +interrupt handlers interrupting while the thread is deep within a kernel +or application call stack. You will need to increase this depending on +what level of stack the application code in question requires. + +At this time the maximum stack consumed by the test threads within the +automated test modules is 85 bytes of stack, and the main test thread has +been seen to consume 193 bytes of stack. At this time the queue9 test is +the largest consumer of test thread stack (85 bytes) and the sem8 test +consumes the largest main thread stack (193 bytes). If your applications +have large amounts of local data or call several subroutines then you may +find that you need larger than 128 bytes. + +You may monitor the stack usage of your application threads during runtime +by defining the macro ATOM_STACK_CHECKING and calling +atomThreadStackCheck(). This macro is defined by default in the EWSTM8 +Debug project so that the automated test modules can check for stack +overflows, but you may wish to undefine this in your application +when you are happy that the stack usage is acceptable. Enabling +ATOM_STACK_CHECKING will increase the size of your threads' TCBs +slightly, and will incur a minor CPU cycles overhead whenever threads are +created due to prefilling the thread stack with a known value. + +With careful consideration and few threads it would be possible to use +a platform with 512 bytes RAM, but not all of the automated test suite +would run on such a platform (some of the test modules use 6 threads: a +main thread together with 4 test threads and the idle thread). + + +--------------------------------------------------------------------------- + +INTERRUPT HANDLING + +Interrupt handlers use the stack of the thread which was running when the +interrupt occurred. If no thread rescheduling occurs during the ISR then +on exit from the ISR any data stacked by the ISR on the thread's stack is +popped off the stack and execution of the thread resumes. If a reschedule +during the ISR causes a context switch to a new thread, then the ISR's +data will remain on the thread's stack until the thread is scheduled back +in. + +Interrupt priorities (via the ITC_SPRx registers) are left in their +default power-on state, which disables interrupt nesting. Kernel changes +may be required to support interrupt nesting. + +Note that the STM8 programming manual currently describes the following +feature: + + "Fast interrupt handling through alternate register files (up to 4 + contexts) with standard stack compatible mode (for real time OS + kernels)" + +This feature was implemented by ST in the core but has to date never been +included in any STM8 products. If it is included in future products then +you will need to put the device in the stack compatible mode described. + + +--------------------------------------------------------------------------- + +WRITING NEW INTERRUPT HANDLERS + +All interrupt handlers which will call out to the OS kernel and potentially +cause a thread switch must call atomIntEnter() and atomIntExit(). An +example of this can be seen in the timer tick ISR in atomport.c. + +You may also implement fast interrupt handlers in the system which do not +call atomIntEnter()/atomIntExit(), however these ISRs cannot perform OS +functions such as posting semaphores or effecting a thread switch. + + +--------------------------------------------------------------------------- + +IAR COMPILER VIRTUAL REGISTERS + +The STM8 has only very few CPU registers, so the IAR compiler augments +them with sixteen "virtual" registers, which are simply locations in fast +memory. These registers are called ?b0 to ?b15. + +The Atomthreads context switch for IAR/STM8 takes advantage of the fact +that all CPU and most virtual registers are automatically saved on the +stack by the compiler when calling out to C functions (and even then only +if necessary). Only the virtual registers ?b8 to ?b15 are expected to be +preserved by called functions, so these are the only registers that +callers to the context switch routine will not automatically save if +necessary. + +For cooperative context switches (where a thread calls an OS kernel +function to schedule itself out), most registers will therefore already +be saved on a thread's stack if necessary. Only ?b8 to ?b15 actually have +to be saved in the context switch routine, making cooperative switches +potentially very cheap if few registers must be preserved. + +For preemptive switches (where an ISR has interrupted a thread and wishes +to switch to a new thread), the interrupt handler prologue automatically +saves all CPU registers (actually done automatically by the CPU) and the +virtual registers ?b0 to ?b7. Still only the registers ?b8 to ?b15 have to +be saved by the context-switch routine, but in this case ?b0 to ?b7 and the +CPU registers are always saved on the thread's stack by the ISR prologue. +This is because the ISR has no knowledge of what registers the interrupted +thread was using, so we cannot take advantage of the potential for saving +fewer than the full set of registers that we achieve with cooperative +switches. + + +---------------------------------------------------------------------------