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