readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX for ARMv7-M
2 (Cortex-M3, Cortex-M4, Cortex-M7)
3 Using the GNU Tools
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 ARM
10GNU compiler. At this point you may run the build_threadx.bat batch file.
11This will build the ThreadX run-time environment in the "example_build"
12directory.
13
14You should observe assembly and compilation of a series of ThreadX source
15files. At the end of the batch file, they are all combined into the
16run-time library file: tx.a. This file must be linked with your
17application in order to use ThreadX.
18
19
202. Demonstration System
21
22The ThreadX demonstration is designed to execute on Cortex-M evaluation boards
23or on a dedicated simulator.
24
25Building the demonstration is easy, simply execute the build_threadx_sample.bat
26batch file while inside the "example_build" directory.
27
28You should observe the compilation of sample_threadx.c (which is the demonstration
29application) and linking with tx.a. The resulting file sample_threadx.out is a binary
30file that can be downloaded and executed on the a simulator, or downloaded to a board.
31
32
333. System Initialization
34
35The entry point in ThreadX for the Cortex-M using gnu tools uses the standard GNU
36Cortex-M reset sequence. From the reset vector the C runtime will be initialized.
37
38The ThreadX tx_initialize_low_level.S file is responsible for setting up
39various system data structures, the vector area, and a periodic timer interrupt
40source.
41
42In addition, _tx_initialize_low_level determines the first available
43address for use by the application, which is supplied as the sole input
44parameter to your application definition function, tx_application_define.
45
46
474. Register Usage and Stack Frames
48
49The following defines the saved context stack frames for context switches
50that occur as a result of interrupt handling or from thread-level API calls.
51All suspended threads have the same stack frame in the Cortex-M version of
52ThreadX. The top of the suspended thread's stack is pointed to by
53tx_thread_stack_ptr in the associated thread control block TX_THREAD.
54
55Non-FPU Stack Frame:
56
57 Stack Offset Stack Contents
58
59 0x00 lr Interrupted lr (lr at time of PENDSV)
60 0x04 r4 Software stacked GP registers
61 0x08 r5
62 0x0C r6
63 0x10 r7
64 0x14 r8
65 0x18 r9
66 0x1C r10
67 0x20 r11
68 0x24 r0 Hardware stacked registers
69 0x28 r1
70 0x2C r2
71 0x30 r3
72 0x34 r12
73 0x38 lr
74 0x3C pc
75 0x40 xPSR
76
77FPU Stack Frame (only interrupted thread with FPU enabled):
78
79 Stack Offset Stack Contents
80
81 0x00 lr Interrupted lr (lr at time of PENDSV)
82 0x04 s16 Software stacked FPU registers
83 0x08 s17
84 0x0C s18
85 0x10 s19
86 0x14 s20
87 0x18 s21
88 0x1C s22
89 0x20 s23
90 0x24 s24
91 0x28 s25
92 0x2C s26
93 0x30 s27
94 0x34 s28
95 0x38 s29
96 0x3C s30
97 0x40 s31
98 0x44 r4 Software stacked registers
99 0x48 r5
100 0x4C r6
101 0x50 r7
102 0x54 r8
103 0x58 r9
104 0x5C r10
105 0x60 r11
106 0x64 r0 Hardware stacked registers
107 0x68 r1
108 0x6C r2
109 0x70 r3
110 0x74 r12
111 0x78 lr
112 0x7C pc
113 0x80 xPSR
114 0x84 s0 Hardware stacked FPU registers
115 0x88 s1
116 0x8C s2
117 0x90 s3
118 0x94 s4
119 0x98 s5
120 0x9C s6
121 0xA0 s7
122 0xA4 s8
123 0xA8 s9
124 0xAC s10
125 0xB0 s11
126 0xB4 s12
127 0xB8 s13
128 0xBC s14
129 0xC0 s15
130 0xC4 fpscr
131
132
1335. Improving Performance
134
135The distribution version of ThreadX is built without any compiler optimizations.
136This makes it easy to debug because you can trace or set breakpoints inside of
137ThreadX itself. Of course, this costs some performance. To make it run faster,
138you can change the build_threadx.bat file to remove the -g option and enable
139all compiler optimizations.
140
141In addition, you can eliminate the ThreadX basic API error checking by
142compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
143defined.
144
145
1466. Interrupt Handling
147
148ThreadX provides complete and high-performance interrupt handling for Cortex-M
149targets. There are a certain set of requirements that are defined in the
150following sub-sections:
151
152
1536.1 Vector Area
154
155The Cortex-M vectors start at the label __tx_vectors or similar. The application may modify
156the vector area according to its needs. There is code in tx_initialize_low_level() that will
157configure the vector base register.
158
159
1606.2 Managed Interrupts
161
162A ThreadX managed interrupt is defined below. By following these conventions, the
163application ISR is then allowed access to various ThreadX services from the ISR.
164Here is the standard template for managed ISRs in ThreadX:
165
166
167 .global __tx_IntHandler
168 .thumb_func
169__tx_IntHandler:
170; VOID InterruptHandler (VOID)
171; {
172 PUSH {r0, lr}
173
174; /* Do interrupt handler work here */
175; /* BL <your interrupt routine in C> */
176
177 POP {r0, lr}
178 BX lr
179; }
180
181
182Note: the Cortex-M requires exception handlers to be thumb labels, this implies bit 0 set.
183To accomplish this, the declaration of the label has to be preceded by the assembler directive
184.thumb_func to instruct the linker to create thumb labels. The label __tx_IntHandler needs to
185be inserted in the correct location in the interrupt vector table. This table is typically
186located in either your runtime startup file or in the tx_initialize_low_level.S file.
187
188
1897. FPU Support
190
191ThreadX for Cortex-M supports automatic ("lazy") VFP support, which means that applications threads
192can simply use the VFP and ThreadX automatically maintains the VFP registers as part of the thread
193context - no additional setup by the application.
194
195
1968. Revision History
197
198For generic code revision information, please refer to the readme_threadx_generic.txt
199file, which is included in your distribution. The following details the revision
200information associated with this specific port of ThreadX:
201
20206-02-2021 Initial ThreadX version 6.1.7 for Cortex-M using GNU tools.
203
204
205Copyright(c) 1996-2021 Microsoft Corporation
206
207
208https://azure.com/rtos
209
210
