1                       Microsoft's Azure RTOS ThreadX for ARMv7-M
2                            (Cortex-M3, Cortex-M4, Cortex-M7)
3                              Using IAR EWARM Tools
4
5
61.  Building the ThreadX run-time Library
7
8Building the ThreadX library is easy. First, open the Azure RTOS workspace
9azure_rtos.eww. Next, make the TX project the "active project" in the
10IAR Embedded Workbench and select the "Make" button. You should observe
11assembly and compilation of a series of ThreadX source files. This
12results in the ThreadX run-time library file tx.a, which is needed by
13the application.
14
15
162.  Demonstration System
17
18The ThreadX demonstration is designed to execute under the IAR debugger under
19simulation.
20
21Building the demonstration is easy; simply open the threadx.www workspace file,
22make the sample_threadx.ewp project the "active project" in the IAR Embedded
23Workbench, and select the "Make" button.
24
25You should observe the compilation of sample_threadx.c (which is the demonstration
26application) and linking with tx.a. The resulting file sample_threadx.out is a
27binary ELF file that can be downloaded and executed on the IAR Windows-based
28Cortex-M simulator.
29
30
313.  System Initialization
32
33The entry point in ThreadX for the Cortex-M using IAR tools is at label
34__iar_program_start. This is defined within the IAR compiler's startup code.
35In addition, this is where all static and global preset C variable
36initialization processing takes place.
37
38The ThreadX tx_initialize_low_level.s file is responsible for setting up
39various system data structures, and a periodic timer interrupt source.
40By default, the vector area is defined at the top of cstartup_M.s, which is
41a slightly modified from the base IAR file.
42
43The _tx_initialize_low_level function inside of tx_initialize_low_level.s
44also determines the first available address for use by the application, which
45is supplied as the sole input parameter to your application definition function,
46tx_application_define. To accomplish this, a section is created in
47tx_initialize_low_level.s called FREE_MEM, which must be located after all
48other RAM sections in memory.
49
50
514.  Register Usage and Stack Frames
52
53The following defines the saved context stack frames for context switches
54that occur as a result of interrupt handling or from thread-level API calls.
55All suspended threads have the same stack frame in the Cortex-M version of
56ThreadX. The top of the suspended thread's stack is pointed to by
57tx_thread_stack_ptr in the associated thread control block TX_THREAD.
58
59Non-FPU Stack Frame:
60
61    Stack Offset    Stack Contents
62
63    0x00            lr          Interrupted lr (lr at time of PENDSV)
64    0x04            r4          Software stacked GP registers
65    0x08            r5
66    0x0C            r6
67    0x10            r7
68    0x14            r8
69    0x18            r9
70    0x1C            r10
71    0x20            r11
72    0x24            r0          Hardware stacked registers
73    0x28            r1
74    0x2C            r2
75    0x30            r3
76    0x34            r12
77    0x38            lr
78    0x3C            pc
79    0x40            xPSR
80
81FPU Stack Frame (only interrupted thread with FPU enabled):
82
83    Stack Offset    Stack Contents
84
85    0x00            lr          Interrupted lr (lr at time of PENDSV)
86    0x04            s16         Software stacked FPU registers
87    0x08            s17
88    0x0C            s18
89    0x10            s19
90    0x14            s20
91    0x18            s21
92    0x1C            s22
93    0x20            s23
94    0x24            s24
95    0x28            s25
96    0x2C            s26
97    0x30            s27
98    0x34            s28
99    0x38            s29
100    0x3C            s30
101    0x40            s31
102    0x44            r4          Software stacked registers
103    0x48            r5
104    0x4C            r6
105    0x50            r7
106    0x54            r8
107    0x58            r9
108    0x5C            r10
109    0x60            r11
110    0x64            r0          Hardware stacked registers
111    0x68            r1
112    0x6C            r2
113    0x70            r3
114    0x74            r12
115    0x78            lr
116    0x7C            pc
117    0x80            xPSR
118    0x84            s0          Hardware stacked FPU registers
119    0x88            s1
120    0x8C            s2
121    0x90            s3
122    0x94            s4
123    0x98            s5
124    0x9C            s6
125    0xA0            s7
126    0xA4            s8
127    0xA8            s9
128    0xAC            s10
129    0xB0            s11
130    0xB4            s12
131    0xB8            s13
132    0xBC            s14
133    0xC0            s15
134    0xC4            fpscr
135
136
1375.  Improving Performance
138
139The distribution version of ThreadX is built without any compiler
140optimizations. This makes it easy to debug because you can trace or set
141breakpoints inside of ThreadX itself. Of course, this costs some
142performance. To make it run faster, you can change the ThreadX library
143project to enable various compiler optimizations.
144
145In addition, you can eliminate the ThreadX basic API error checking by
146compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
147defined.
148
149
1506.  Interrupt Handling
151
152The Cortex-M vectors start at the label __vector_table and is defined in cstartup_M.s.
153The application may modify the vector area according to its needs.
154
155
1566.1 Managed Interrupts
157
158ISRs for Cortex-M using the IAR tools can be written completely in C (or assembly
159language) without any calls to _tx_thread_context_save or _tx_thread_context_restore.
160These ISRs are allowed access to the ThreadX API that is available to ISRs.
161
162ISRs written in C will take the form (where "your_C_isr" is an entry in the vector table):
163
164void    your_C_isr(void)
165{
166
167    /* ISR processing goes here, including any needed function calls.  */
168}
169
170ISRs written in assembly language will take the form:
171
172        PUBLIC  your_assembly_isr
173your_assembly_isr:
174
175    PUSH    {r0, lr}
176
177    ; ISR processing goes here, including any needed function calls.
178
179    POP     {r0, lr}
180    BX      lr
181
182
1837.  IAR Thread-safe Library Support
184
185Thread-safe support for the IAR tools is easily enabled by building the ThreadX library
186and the application with TX_ENABLE_IAR_LIBRARY_SUPPORT. Also, the linker control file
187should have the following line added (if not already in place):
188
189initialize by copy with packing = none { section __DLIB_PERTHREAD }; // Required in a multi-threaded application
190
191The project options "General Options -> Library Configuration" should also have the
192"Enable thread support in library" box selected.
193
194
1958. VFP Support
196
197ThreadX for Cortex-M supports automatic ("lazy") VFP support, which means that applications threads
198can simply use the VFP and ThreadX automatically maintains the VFP registers as part of the thread
199context - no additional setup by the application.
200
201
2029.  Revision History
203
204For generic code revision information, please refer to the readme_threadx_generic.txt
205file, which is included in your distribution. The following details the revision
206information associated with this specific port of ThreadX:
207
20806-02-2021  Initial ThreadX version 6.1.7 for Cortex-M using IAR's ARM tools.
209
210
211Copyright(c) 1996-2021 Microsoft Corporation
212
213
214https://azure.com/rtos
215
216