readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX for ARMv7-M
2 (Cortex-M3, Cortex-M4, Cortex-M7)
3 Using ARM Compiler 5 (AC5)
4
5
61. Building the ThreadX run-time Library
7
8Navigate to the "example_build" directory. Ensure that
9you have setup your path and other environment variables necessary for the AC5
10compiler. At this point you may run the build_threadx.bat batch file. This will
11build the ThreadX run-time environment in the "example_build" directory.
12
13You should observe assembly and compilation of a series of ThreadX source
14files. At the end of the batch file, they are all combined into the
15run-time library file: tx.a. This file must be linked with your
16application in order to use ThreadX.
17
18
192. Demonstration System
20
21The ThreadX demonstration is designed to execute under the ARM DS Cortex-M
22simulator.
23
24Building the demonstration is easy; simply execute the build_threadx_sample.bat
25batch file while inside the "example_build" directory.
26
27You should observe the compilation of sample_threadx.c (which is the demonstration
28application) and linking with tx.a. The resulting file sample_threadx.axf
29is a binary file that can be downloaded and executed on the ARM DS Cortex-M
30simulator.
31
32
333. System Initialization
34
35The entry point in ThreadX for the Cortex-M using AC5 tools is at label
36__main. This is defined within the AC5 compiler's startup code. In
37addition, this is where all static and global pre-set C variable
38initialization processing takes place.
39
40The ThreadX tx_initialize_low_level.s file is responsible for setting up
41various system data structures, the vector area, and a periodic timer interrupt
42source.
43
44In addition, _tx_initialize_low_level determines the first available
45address for use by the application, which is supplied as the sole input
46parameter to your application definition function, tx_application_define.
47
48
494. Register Usage and Stack Frames
50
51The following defines the saved context stack frames for context switches
52that occur as a result of interrupt handling or from thread-level API calls.
53All suspended threads have the same stack frame in the Cortex-M version of
54ThreadX. The top of the suspended thread's stack is pointed to by
55tx_thread_stack_ptr in the associated thread control block TX_THREAD.
56
57Non-FPU Stack Frame:
58
59 Stack Offset Stack Contents
60
61 0x00 lr Interrupted lr (lr at time of PENDSV)
62 0x04 r4 Software stacked GP registers
63 0x08 r5
64 0x0C r6
65 0x10 r7
66 0x14 r8
67 0x18 r9
68 0x1C r10
69 0x20 r11
70 0x24 r0 Hardware stacked registers
71 0x28 r1
72 0x2C r2
73 0x30 r3
74 0x34 r12
75 0x38 lr
76 0x3C pc
77 0x40 xPSR
78
79FPU Stack Frame (only interrupted thread with FPU enabled):
80
81 Stack Offset Stack Contents
82
83 0x00 lr Interrupted lr (lr at time of PENDSV)
84 0x04 s16 Software stacked FPU registers
85 0x08 s17
86 0x0C s18
87 0x10 s19
88 0x14 s20
89 0x18 s21
90 0x1C s22
91 0x20 s23
92 0x24 s24
93 0x28 s25
94 0x2C s26
95 0x30 s27
96 0x34 s28
97 0x38 s29
98 0x3C s30
99 0x40 s31
100 0x44 r4 Software stacked registers
101 0x48 r5
102 0x4C r6
103 0x50 r7
104 0x54 r8
105 0x58 r9
106 0x5C r10
107 0x60 r11
108 0x64 r0 Hardware stacked registers
109 0x68 r1
110 0x6C r2
111 0x70 r3
112 0x74 r12
113 0x78 lr
114 0x7C pc
115 0x80 xPSR
116 0x84 s0 Hardware stacked FPU registers
117 0x88 s1
118 0x8C s2
119 0x90 s3
120 0x94 s4
121 0x98 s5
122 0x9C s6
123 0xA0 s7
124 0xA4 s8
125 0xA8 s9
126 0xAC s10
127 0xB0 s11
128 0xB4 s12
129 0xB8 s13
130 0xBC s14
131 0xC0 s15
132 0xC4 fpscr
133
134
1355. Improving Performance
136
137The distribution version of ThreadX is built without any compiler
138optimizations. This makes it easy to debug because you can trace or set
139breakpoints inside of ThreadX itself. Of course, this costs some
140performance. To make it run faster, you can change the ThreadX library
141project to enable various compiler optimizations.
142
143In addition, you can eliminate the ThreadX basic API error checking by
144compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
145defined.
146
147
1486. Interrupt Handling
149
150ThreadX provides complete and high-performance interrupt handling for Cortex-M
151targets. There are a certain set of requirements that are defined in the
152following sub-sections:
153
154
1556.1 Vector Area
156
157The Cortex-M vectors start at the label __tx_vectors. The application may modify
158the vector area according to its needs.
159
160
1616.2 Managed Interrupts
162
163ISRs for Cortex-M can be written completely in C (or assembly language) without any
164calls to _tx_thread_context_save or _tx_thread_context_restore. These ISRs are allowed
165access to the ThreadX API that is available to ISRs.
166
167ISRs written in C will take the form (where "your_C_isr" is an entry in the vector table):
168
169void your_C_isr(void)
170{
171
172 /* ISR processing goes here, including any needed function calls. */
173}
174
175ISRs written in assembly language will take the form:
176
177 EXPORT your_assembly_isr
178your_assembly_isr
179
180 PUSH {r0, lr}
181
182 ; ISR processing goes here, including any needed function calls.
183
184 POP {r0, lr}
185 BX lr
186
187
1887. FPU Support
189
190ThreadX for Cortex-M supports automatic ("lazy") VFP support, which means that applications threads
191can simply use the VFP and ThreadX automatically maintains the VFP registers as part of the thread
192context - no additional setup by the application.
193
194
1958. Revision History
196
197For generic code revision information, please refer to the readme_threadx_generic.txt
198file, which is included in your distribution. The following details the revision
199information associated with this specific port of ThreadX:
200
20106-02-2021 Initial ThreadX version 6.1.7 for Cortex-M using AC5 tools.
202
203
204Copyright(c) 1996-2021 Microsoft Corporation
205
206
207https://azure.com/rtos
208
209
