From ee591c7a51b54ac1326bf39c3848bb2175bcdf54 Mon Sep 17 00:00:00 2001 From: Philipp Klaus Krause Date: Thu, 23 Jun 2016 10:31:01 +0200 Subject: [PATCH] Refactor STM8 documentation --- ports/stm8/README-COSMIC | 232 +---------------------------------- ports/stm8/README-IAR | 184 +-------------------------- ports/stm8/README-RAISONANCE | 182 +-------------------------- ports/stm8/README-SDCC | 45 ++++++- 4 files changed, 53 insertions(+), 590 deletions(-) diff --git a/ports/stm8/README-COSMIC b/ports/stm8/README-COSMIC index b980265..789c557 100644 --- a/ports/stm8/README-COSMIC +++ b/ports/stm8/README-COSMIC @@ -13,44 +13,10 @@ This folder contains a port of the Atomthreads real time kernel for the 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 -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: +Compiler-agnostic aspects of the usage of Atomthreads can be found in README. - * atomport.c: Those functions which can be written in C - * atomport-asm-cosmic.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: - - * atomport.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) - * stm8_interrupt_vector.c: List of interrupt handlers for vector table - * 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 the Cosmic, Raisonance 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 other compilers are available in README-IAR -and README-RAISONANCE. +Instructions for users of the other compilers are available in README-SDCC, +README-IAR and README-RAISONANCE. --------------------------------------------------------------------------- @@ -212,49 +178,6 @@ device and start it running. Other programming tools may exist but are not apparent in the toolset delivered for use the STM8S Discovery platform. - ---------------------------------------------------------------------------- - -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 RX: CN4 pin 11 (connect to TX at the PC end) - UART TX: CN4 pin 10 (connect to RX 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 change the -PART macro from "STM8S105" to your target CPU. This can be changed in the -cosmic.mak Makefile. If you are using the STVD project it should be -changed in the project preprocessor settings for both Debug and Release -builds. You may also wish to enable any CPU peripherals which you wish to -use in the stm8s_conf.h file. - - --------------------------------------------------------------------------- RUNNING THE AUTOMATED TESTS @@ -322,155 +245,6 @@ both Debug and Release builds as follows: 0x7BF for application usage, and 0x7C0 to 0x7FF for startup stack. ---------------------------------------------------------------------------- - -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 95 bytes of stack, and the main test thread has -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. - -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 Makefile -so that the automated test modules can check for stack overflows, but you -may wish to undefine this in your application Makefiles 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). - -The RAM layout used for the automated test applications is as follows: - -RAM Top: -* Startup Stack (64 bytes) -* Data & BSS area (thread stacks, other application data) -RAM Bottom. - -This is not prescribed, you may use whichever layout you wish for your -applications. - -The startup stack area starts at the top of RAM and is only used for first -initialisation of the OS and main thread. This uses 64 bytes and could be -reused once the OS is started, but for the purposes of the automated test -applications it is not reused. Generally you would ensure that this is -reused in your own application code. - -The application's data starts at the bottom of RAM, and this includes all -of the thread stacks which are statically allocated arrays. The idle -thread, main thread, and automated test thread stacks are allocated here. - -The default layout provided with Atomthreads matches the STM8S-Discovery -with 2KB RAM. The linker file reserves the first 0x7C0 bytes for data -areas. The region from here up to the end of RAM (0x800) is used for the -the 64 byte startup stack. - -As mentioned previously, this RAM layout is only the one utilised by the -test applications. You may choose whatever layout you like. - -Note that on this platform data can be placed at address 0x0, but the -Atomthreads kernel performs validity checks on pointers to ensure they -are not NULL pointers (point to address 0x0). For this reason the -example projects (STVD and Makefile) force the linker to not use address -0x0 and instead start the page0 space at 0x2. This ensures that the -linker does not place any data at address 0x0, and hence all NULL-ptr -checks are still suitable checks for valid pointers. This does, however, -waste 2 bytes. For your own projects you can force this within STVD by -editing the project linker settings (Input -> Zero Page start at 0x2) -or by editing the linker .LKF file as can be seen in atomthreads.lkf. - - ---------------------------------------------------------------------------- - -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. - -With the Cosmic compiler port it is also necessary to add the @svlreg -modifier to any interrupt handlers which call out to the OS kernel. -Alternatively you may use the INTERRUPT macro from atomport-private.h which -always adds the @svlreg modifier. This modifier ensures that the c_lreg -virtual register is saved on the interrupted thread's stack for any -preemptive context switches. It also ensures that longs are available for -use within any OS kernel code called as part of the interrupt handling. - -You may also implement fast interrupt handlers in the system which do not -call atomIntEnter()/atomIntExit() and which do not need the @svlreg -modifier, however these ISRs cannot perform OS functions such as posting -semaphores or effecting a thread switch. - - --------------------------------------------------------------------------- COSMIC COMPILER VIRTUAL REGISTERS diff --git a/ports/stm8/README-IAR b/ports/stm8/README-IAR index c4f34ba..24f0026 100644 --- a/ports/stm8/README-IAR +++ b/ports/stm8/README-IAR @@ -13,43 +13,10 @@ 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: +Compiler-agnostic aspects of the usage of Atomthreads can be found in README. - * 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: - - * atomport.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 the Cosmic, Raisonance 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 other compilers are available in README-COSMIC and -README-RAISONANCE. +Instructions for users of the other compilers are available in README-SDCC, +README-COSMIC and README-RAISONANCE. --------------------------------------------------------------------------- @@ -188,50 +155,6 @@ device and start it running. Other programming tools may exist but are not apparent in the toolset delivered for use the STM8S Discovery platform. - ---------------------------------------------------------------------------- - -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 RX: CN4 pin 11 (connect to TX at the PC end) - UART TX: CN4 pin 10 (connect to RX 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 change the -PART macro from "STM8S105" to your target CPU. This can be changed in the -iar.mak Makefile. If you are using the EWSTM8 project it should be -changed in the project C/C++ Compiler Preprocessor settings for both Debug -and Release builds, and you must also change the target device in the -project's "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 @@ -311,107 +234,6 @@ Add the .C and .S modules from the following folders: 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 diff --git a/ports/stm8/README-RAISONANCE b/ports/stm8/README-RAISONANCE index a3772cf..7e9876e 100644 --- a/ports/stm8/README-RAISONANCE +++ b/ports/stm8/README-RAISONANCE @@ -13,43 +13,10 @@ 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). -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: +Compiler-agnostic aspects of the usage of Atomthreads can be found in README. - * atomport.c: Those functions which can be written in C - * atomport-asm-raisonance.s: 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: - - * atomport.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 the Cosmic, Raisonance 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 Raisonance compiler. -Instructions for users of the other compilers are available in README-IAR -and README-COSMIC. +Instructions for users of the other compilers are available in README-SDCC, +README-IAR and README-COSMIC. --------------------------------------------------------------------------- @@ -204,49 +171,6 @@ device and start it running. Other programming tools may exist but are not apparent in the toolset delivered for use the STM8S Discovery platform. - ---------------------------------------------------------------------------- - -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 RX: CN4 pin 11 (connect to TX at the PC end) - UART TX: CN4 pin 10 (connect to RX 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 change the -PART macro from "STM8S105" to your target CPU. This can be changed in the -raisonance.mak Makefile. If you are using the STVD project it should be -changed in the project preprocessor settings for both Debug and Release -builds. You may also wish to enable any CPU peripherals which you wish to -use in the stm8s_conf.h file. - - --------------------------------------------------------------------------- RUNNING THE AUTOMATED TESTS @@ -318,106 +242,6 @@ 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). ---------------------------------------------------------------------------- - -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 95 bytes of stack, and the main test thread has -been seen to consume 163 bytes of stack. At this time the queue9 test is -the largest consumer of test thread stack (95 bytes) and the sem1 test -consumes the largest main thread stack (137 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 Makefile -so that the automated test modules can check for stack overflows, but you -may wish to undefine this in your application Makefiles 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. - --------------------------------------------------------------------------- diff --git a/ports/stm8/README-SDCC b/ports/stm8/README-SDCC index 54c29ac..59e9f77 100644 --- a/ports/stm8/README-SDCC +++ b/ports/stm8/README-SDCC @@ -1,18 +1,61 @@ --------------------------------------------------------------------------- +Author: Dr. Philipp Klaus Krause + +--------------------------------------------------------------------------- + STM8 PORT - SMALL DEVICE C 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 Small Device C Compiler (SDCC). + +This README covers usage of Atomthreads with SDCC. +Instructions for users of the other compilers are available in README-COSMIC, +README-IAR and README-RAISONANCE. + + --------------------------------------------------------------------------- PREREQUISITES - * SDCC +The port works out-of-the-box with SDCC and GNU make for +building. + + * SDCC 3.6.0 or later * Programming software (e.g. stm8flash) + --------------------------------------------------------------------------- BUILD VIA MAKEFILE * make -f sdcc.mak +All objects are built into the 'build-sdcc' folder under ports/stm8. +The build process builds separate target applications for each automated +test, and appropriate .ihx 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 sdcc.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 + +Applications can be written onto the STM8S-Discovery board using: + + * stm8flash -c stlink -p stm8s105c6 -w + + +---------------------------------------------------------------------------