atomthreads/ports/stm8/README-RAISONANCE

---------------------------------------------------------------------------

Library:      Atomthreads
Author:       Kelvin Lawson <info@atomthreads.com>
Website:      http://atomthreads.com
License:      BSD Revised

---------------------------------------------------------------------------

STM8 PORT - RAISONANCE 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 Raisonance compiler (RCSTM8).

Compiler-agnostic aspects of the usage of Atomthreads can be found in README.

Instructions for users of the other compilers are available in README-SDCC,
README-IAR and README-COSMIC.


---------------------------------------------------------------------------

PREREQUISITES

The port works out-of-the-box with the Raisonance compiler tools for
building. Applications are generated in .hex form and can be programmed
with any supporting programming software, including the free STVP (visual
programmer tool). At this time there does not appear to be a command-line
programmer application suitable for use with STM8.

The Raisonance compiler and STVP are currently Windows-only applications.
For users of other operating systems the Raisonance compiler may work in 
environments like Wine, but the USB programming tools are less likely to
be supported. Both the compiler and the USB programming tool for
STM8S-Discovery (STVP) can, however, be run successfully within a VM such
as VirtualBox.

The core software prerequisites are therefore:
 * Raisonance STM8 compiler
 * Programming software (e.g. ST's STVP tool)

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
can easily replace STVP by your own favourite programmer if required.


---------------------------------------------------------------------------

MEMORY MODEL

The sample build configurations use the Small memory model. All global
variables are placed in the Data section rather than page0, which allows
for large arrays such as thread stacks which would not fit in page0.


---------------------------------------------------------------------------

BUILDING THE SOURCE

You may build Atomthreads using whichever build environment you desire. For
your convenience we provide both a ready-rolled Makefile-based build system
and an STVD visual debugger project. The STVD project permits easy
building, programming and debugging, but does not easily support building
a wide range of application builds within the same project, which is
useful for building the numerous automated tests. For the automated tests
you may find it easier to use the Makefile which automatically builds all
automated tests.


---------------------------------------------------------------------------

BUILD VIA STVD PROJECT

For building applications using STVD you can use the sample workspace
atomthreads-sample-stvd.stw which contains both Cosmic compiler and
Raisonance compiler based projects. You can also import the 
Raisonance-only project file atomthreads-sample-raisonance.stp directly.
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. Press the
exclamation button to run, 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. This is rather painful using a GUI interface due to the large
number of test files, and you may prefer to use the Makefile-based system
instead which builds all automated tests in one command.


---------------------------------------------------------------------------

BUILD VIA MAKEFILE

A Makefile is also provided for building the kernel, port and automated
tests. This is particularly useful for building the automated tests
because many different independent applications need to be built which is
not easily achieved within the STVD environment.

For a Windows system you can obtain a Make application suitable for use
with the Raisonance compiler from:

 * http://www.cosmic-software.com/comp_utils/GNU_Make.zip

Assuming you install the above into C:\Program Files\GNU_MAKE, you
should set up your environment variables as follows:

 * set PATH=%PATH%;C:\Program Files\GNU_MAKE;C:\Program Files\Raisonance\Ride\bin
 * set MAKE_MODE=DOS


The full build is carried out using simply:

 * make -f raisonance.mak

All objects are built into the 'build-raisonance' folder under ports/stm8.
The build process builds separate target applications for each automated
test, and appropriate .aof or .hex files can be found in the build folder
ready for downloading to and running on the target. Because of the limited
resources on the STM8, and the large amount of automated tests, each test
is built and run as a separate application.


All built objects etc can be cleaned using:

 * make -f raisonance.mak clean


The Atomthreads sources are documented using Doxygen markup. You can build
both the kernel and STM8 port documentation from this folder using:

 * make -f raisonance.mak doxygen


---------------------------------------------------------------------------

PROGRAMMING MAKEFILE-BUILT APPLICATIONS TO THE TARGET DEVICE

When developing within STVD, programs can be downloaded directly to the
target. If, however, you are building applications separately using a
Makefile or similar, then you are not able to program the application
using STVD. None of the tools delivered by ST appear to be designed to
cater for those who build applications externally, but it is possible using
STVP.

The following development workflow can be used (note that these settings
apply to the STM8S-Discovery):

 * Build app using Makefile.
 * Open STVP and configure to use Swim ST-Link for CPU STM8105C6.
 * Open application .hex file and program using "Program All Tabs".

Unfortunately STVP does not have a command to reset and start the CPU
running, but it can be forced into doing so by reconfiguring the
programmer:

 * Select "Configure ST Visual Programmer" from the Configure menu.

Your application should now be programmed and running.

If you wish to program and run another application then you can open and
program it in STVP, then use the Configure menu again to reset the
device and start it running.

Other programming tools may exist but are not apparent in the toolset
delivered for use the STM8S Discovery platform.

---------------------------------------------------------------------------

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. 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.

You may also build the tests using the STVD project, but to run each
different test you must manually remove the previous test module (e.g.
kern1.c) and replace it with one of other tests, which can be quite time
consuming compared to building all tests in one command via the Makefile.

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 STVD can be started using the sample project
atomthreads-sample-raisonance.stp. If you wish to create your own STVD
project from scratch, then you should ensure you change the project settings
for both Debug and Release builds as follows:

* Toolset: "Raisonance"
* MCU Selection: Appropriate for your platform (STM8S10C56 for Discovery)
* C Compiler Memory Model: "Small"
* C Compiler Preprocessor Definitions: CPU part (e.g. "STM8S105")
* C Compiler Preprocessor Definitions: Enable thread stack checking if
  desired by adding "ATOM_STACK_CHECKING", for example the full
  preprocessor line for Discovery might be: "STM8S105 ATOM_STACK_CHECKING"
* Linker Input: You may need to change the DATA setion to start from 0x1
  rather than 0x0 to prevent the linker from placing OS data at address
  0x0 (which would cause NULL-pointer checks to fail). So far this has
  not actually proved necessary, however.

Note that for an RTOS like this the Raisonance compiler must place all
functions in reentrant mode, however it does this by default on the STM8
platform so no user action is required (unlike when targeting the STM7
platform with Raisonance).


---------------------------------------------------------------------------

RAISONANCE COMPILER VIRTUAL REGISTERS

The STM8 has only very few CPU registers, so the Raisonance compiler
augments them with four "virtual" registers, which are simply locations in
fast memory. These registers are called BH, BL, CH and CL.

The Atomthreads context switch for Raisonance/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 (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
preserved across the function call are automatically saved on the stack by
the compiler before the context switch is even called. This means that no
CPU or virtual registers 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 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.


---------------------------------------------------------------------------