qpcpp/3rd_party/threadx/stm32f4xx_iar/readme_threadx.txt

     Express Logic's ThreadX for ST's STM32F4 Discovery Evaluation Board (Cortex-M4) 

                               Using the IAR Tools


                               *** DEMO VERSION ***


0. About This Version

This version of ThreadX is for demonstration purposes only and may not
be used for any product development, either directly or indirectly. In 
addition, this demonstration may not be used for any competitive purpose.


1.  Installation

ThreadX for ST's STM32F4 Discovery (Cortex-M4) is pre-installed in the evaluation 
package.


2.  Building the ThreadX run-time Library

This demonstration version contains a pre-built ThreadX library, tx.a. The library is 
intended for demonstration purposes only and thus has the following limitations:

                10 Threads
                10 Timers
                10 Event Flag Groups
                10 Mutexes
                10 Queues
                10 Semaphores
                10 Block Pool
                10 Byte Pool


3.  Demonstration System

The ThreadX demonstration is designed to execute on the STM32F4 Discovery evaluation 
board under the IAR Windows-based debugger.

Building the demonstration is easy; simply make the demo_threadx.ewp project 
the "active project" in the IAR Embedded Workbench and select the "Make" button.

You should observe the compilation of demo_threadx.c (which is the demonstration 
application) and linking with tx.a. The resulting file demo_threadx.out is a binary 
file that can be downloaded and executed on the STM32F4 Discovery evaluation board using 
the IAR debugger.


4.  System Initialization

The entry point in ThreadX for the  (Cortex-M4) using IAR tools is at label 
Reset_Handler. This is defined within the STM32 startup code, namely
the file startup_stm32f429xx.s. From this entry point, the IAR startup code
at __iar_program_start is called. This is where all static and global preset 
C variable initialization processing takes place.

The ThreadX tx_initialize_low_level.s file is responsible for setting up 
various system data structures, and a periodic timer interrupt source. 

The _tx_initialize_low_level function inside of tx_initialize_low_level.s
also determines the first available address for use by the application, which 
is supplied as the sole input parameter to your application definition function, 
tx_application_define. To accomplish this, a section is created in 
tx_initialize_low_level.s called FREE_MEM, which must be located after all 
other RAM sections in memory. 


5.  Register Usage and Stack Frames

The following defines the saved context stack frames for context switches
that occur as a result of interrupt handling or from thread-level API calls.
All suspended threads have the same stack frame in the Cortex-M4 version of
ThreadX. The top of the suspended thread's stack is pointed to by 
tx_thread_stack_ptr in the associated thread control block TX_THREAD.

Non-FPU Stack Frame:

  Stack Offset     Stack Contents 

     0x00               LR          Interrupted LR (LR at time of PENDSV)
     0x04               r4          
     0x08               r5          
     0x0C               r6          
     0x10               r7          
     0x14               r8          
     0x18               r9          
     0x1C               r10 (sl)    
     0x20               r11         
     0x24               r0          (Hardware stack starts here!!)
     0x28               r1          
     0x2C               r2          
     0x30               r3          
     0x34               r12         
     0x38               lr          
     0x3C               pc          
     0x40               xPSR        

FPU Stack Frame (only interrupted thread with FPU enabled):

  Stack Offset     Stack Contents 

     0x00               LR          Interrupted LR (LR at time of PENDSV)
     0x04               s0
     0x08               s1
     0x0C               s2
     0x10               s3
     0x14               s4
     0x18               s5
     0x1C               s6
     0x20               s7
     0x24               s8
     0x28               s9
     0x2C               s10
     0x30               s11
     0x34               s12
     0x38               s13
     0x3C               s14
     0x40               s15
     0x44               s16
     0x48               s17
     0x4C               s18
     0x50               s19
     0x54               s20
     0x58               s21
     0x5C               s22
     0x60               s23
     0x64               s24
     0x68               s25
     0x6C               s26
     0x70               s27
     0x74               s28
     0x78               s29
     0x7C               s30
     0x80               s31
     0x84               fpscr
     0x88               r4          
     0x8C               r5          
     0x90               r6          
     0x94               r7          
     0x98               r8          
     0x9C               r9          
     0xA0               r10 (sl)    
     0xA4               r11         
     0xA8               r0          (Hardware stack starts here!!)
     0xAC               r1          
     0xB0               r2          
     0xB4               r3          
     0xB8               r12         
     0xBC               lr          
     0xC0               pc          
     0xC4               xPSR        

6.  Improving Performance

The distribution version of ThreadX is built without any compiler 
optimizations. This makes it easy to debug because you can trace or set 
breakpoints inside of ThreadX itself. Of course, this costs some 
performance. To make it run faster, you can change the ThreadX library
project to enable various compiler optimizations. 

In addition, you can eliminate the ThreadX basic API error checking by 
compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING 
defined. 


7.  Interrupt Handling

The Cortex-M4 vectors start at the label __vector_table and is defined in cstartup_M.s. 
The application may modify the vector area according to its needs.


7.2 Managed Interrupts

From version 5.6 going forward, ISRs for Cortex-M using the IAR tools can be written
completely in C (or assembly language) without any calls to _tx_thread_context_save or 
_tx_thread_context_restore. These ISRs are allowed access to the ThreadX API that is
available to ISRs.

ISRs written in C will take the form (where "your_C_isr" is an entry in the vector table):

void    your_C_isr(void)
{

    /* ISR processing goes here, including any needed function calls.  */
}

ISRs written in assembly language will take the form:

        PUBLIC  your_assembly_isr
your_assembly_isr:

    PUSH    {lr}

    ; ISR processing goes here, including any needed function calls.

    POP     {lr}
    BX      lr

Backward compatibility to the previous style assembly ISRs is maintained, which was of 
the form:

        PUBLIC  __legacy_isr_handler
__legacy_isr_handler:
        PUSH    {lr}
        BL  _tx_thread_context_save
        
;    /* Do interrupt handler work here */
;    /* .... */

        B       _tx_thread_context_restore


8.  IAR Thread-safe Library Support

Thread-safe support for the IAR tools is easily enabled by building the ThreadX library
and the application with TX_ENABLE_IAR_LIBRARY_SUPPORT. Also, the linker control file
should have the following line added (if not already in place):

initialize by copy with packing = none { section __DLIB_PERTHREAD }; // Required in a multi-threaded application

The project options "General Options -> Library Configuration" should also have the 
"Enable thread support in library" box selected.


9. VFP Support

When applicable, ThreadX for the STM32F4 Discovery (Cortex-M4) supports lazy VFP support, which
means that applications threads can simply use the VFP and ThreadX automatically maintains
the VFP registers as part of the thread context - no additional setup by the application 
is required.
 

10.  Revision History

08/01/2017  Initial ThreadX version for STM32F4 Discovery (Cortex-M4) using IAR's ARM tools.


Copyright(c) 1996-2017 Express Logic, Inc.


Express Logic, Inc.
11323 West Bernardo Court
San Diego, CA  92127

www.expresslogic.com