readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX for Cortex-A5x
2
3 Using the ARM Compiler 6 & DS
4
51. Open the Azure RTOS Workspace
6
7In order to build the ThreadX library and the ThreadX demonstration first load
8the Azure RTOS Workspace, which is located inside your ThreadX installation
9directory.
10
11Note: the workspace and projects were made using DS-5, so DS will prompt you
12to migrate the projects. This is expected, so please do so.
13
142. Building the ThreadX run-time Library
15
16Building the ThreadX library is easy; simply select the Eclipse project file
17"tx" and then select the build button. You should now observe the compilation
18and assembly of the ThreadX library. This project build produces the ThreadX
19library file tx.a.
20
21
223. Demonstration System
23
24The ThreadX demonstration is designed to execute under the DS debugger on the
25VE-AEMv8x1 Bare Metal simulator.
26
27Building the demonstration is easy; simply open the workspace file, select the
28sample_threadx project, and select the build button. Next, right-click on the
29project and select "Debug As -> Debug Configurations". The debugger is setup
30for VE_AEMv8x1 Bare Metal Debug, so selecting "Debug" will launch the simulator,
31load the sample_threadx.axf ELF file and run to main. You are now ready to
32execute the ThreadX demonstration.
33
34
354. System Initialization
36
37The entry point in ThreadX for the Cortex-A5x using ARM tools is at label
38start64. This is defined within the ARM compiler's startup code. In addition,
39this is where all static and global pre-set C variable initialization processing
40takes place.
41
42The ThreadX tx_initialize_low_level.s file is responsible for determining the
43first available RAM address for use by the application, which is supplied as the
44sole input parameter to your application definition function, tx_application_define.
45
46
475. Register Usage and Stack Frames
48
49The 64-bit ARM compiler assumes that registers x0-x18 are scratch registers
50for each function. All other registers used by a C function must be preserved
51by the function. ThreadX takes advantage of this in situations where a context
52switch happens as a result of making a ThreadX service call (which is itself a
53C function). In such cases, the saved context of a thread is only the
54non-scratch registers.
55
56The following defines the saved context stack frames for context switches
57that occur as a result of interrupt handling or from thread-level API calls.
58All suspended threads have one of these two types of stack frames. The top
59of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the
60associated thread control block TX_THREAD.
61
62
63FP not enabled and TX_THREAD.tx_thread_fp_enable == 0:
64
65 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
66
67 0x000 SPSR DAIF
68 0x008 ELR 0
69 0x010 x28 x27
70 0x018 reserved x28
71 0x020 x26 x25
72 0x028 x27 x26
73 0x030 x24 x23
74 0x038 x25 x24
75 0x040 x22 x21
76 0x048 x23 x22
77 0x050 x20 x19
78 0x058 x21 x20
79 0x060 x18 x29
80 0x068 x19 x30
81 0x070 x16
82 0x078 x17
83 0x080 x14
84 0x088 x15
85 0x090 x12
86 0x098 x13
87 0x0A0 x10
88 0x0A8 x11
89 0x0B0 x8
90 0x0B8 x9
91 0x0C0 x6
92 0x0C8 x7
93 0x0D0 x4
94 0x0D8 x5
95 0x0E0 x2
96 0x0E8 x3
97 0x0F0 x0
98 0x0F8 x1
99 0x100 x29
100 0x108 x30
101
102
103FP enabled and TX_THREAD.tx_thread_fp_enable == 1:
104
105 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
106
107 0x000 SPSR DAIF
108 0x008 ELR 0
109 0x010 FPSR FPSR
110 0x018 FPCR FPCR
111 0x020 q30 q14
112 0x030 q31 q15
113 0x040 q28 q12
114 0x050 q29 q13
115 0x060 q26 q10
116 0x070 q27 q11
117 0x080 q24 q8
118 0x090 q25 q9
119 0x0A0 q22 x27
120 0x0A8 x28
121 0x0B0 q23 x25
122 0x0B8 x26
123 0x0C0 q20 x23
124 0x0C8 x24
125 0x0D0 q21 x21
126 0x0D8 x22
127 0x0E0 q18 x19
128 0x0E8 x20
129 0x0F0 q19 x29
130 0x0F8 x30
131 0x100 q16
132 0x110 q17
133 0x120 q14
134 0x130 q15
135 0x140 q12
136 0x150 q13
137 0x160 q10
138 0x170 q11
139 0x180 q8
140 0x190 q9
141 0x1A0 q6
142 0x1B0 q7
143 0x1C0 q4
144 0x1D0 q5
145 0x1E0 q2
146 0x1F0 q3
147 0x200 q0
148 0x210 q1
149 0x220 x28
150 0x228 reserved
151 0x230 x26
152 0x238 x27
153 0x240 x24
154 0x248 x25
155 0x250 x22
156 0x258 x23
157 0x260 x20
158 0x268 x21
159 0x270 x18
160 0x278 x19
161 0x280 x16
162 0x288 x17
163 0x290 x14
164 0x298 x15
165 0x2A0 x12
166 0x2A8 x13
167 0x2B0 x10
168 0x2B8 x11
169 0x2C0 x8
170 0x2C8 x9
171 0x2D0 x6
172 0x2D8 x7
173 0x2E0 x4
174 0x2E8 x5
175 0x2F0 x2
176 0x2F8 x3
177 0x300 x0
178 0x308 x1
179 0x310 x29
180 0x318 x30
181
182
183
1846. Improving Performance
185
186The distribution version of ThreadX is built without any compiler optimizations.
187This makes it easy to debug because you can trace or set breakpoints inside of
188ThreadX itself. Of course, this costs some performance. To make it run faster,
189you can change the project settings to the desired compiler optimization level.
190
191In addition, you can eliminate the ThreadX basic API error checking by
192compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
193defined.
194
195
1967. Interrupt Handling
197
198ThreadX provides complete and high-performance interrupt handling for Cortex-A5x
199targets. Interrupts handlers for the 64-bit mode of the Cortex-A5x have the following
200format:
201
202 .global irq_handler
203irq_handler:
204
205 STP x29, x30, [sp, #-16]!
206 BL _tx_thread_context_save
207
208 /* Your ISR call goes here! */
209 BL application_isr_handler
210
211 B _tx_thread_context_restore
212
213By default, ThreadX assumes EL3 level of execution. Running and taking exceptions in EL1
214and EL2 can be done by simply building the ThreadX library with either EL1 or EL2 defined.
215
216
2178. ThreadX Timer Interrupt
218
219ThreadX requires a periodic interrupt source to manage all time-slicing, thread sleeps,
220timeouts, and application timers. Without such a timer interrupt source, these services
221are not functional. However, all other ThreadX services are operational without a
222periodic timer source.
223
224
2259. ARM FP Support
226
227By default, FP support is disabled for each thread. If saving the context of the FP registers
228is needed, the following API call must be made from the context of the application thread - before
229the FP usage:
230
231void tx_thread_fp_enable(void);
232
233After this API is called in the application, FP registers will be saved/restored for this thread if it
234is preempted via an interrupt. All other suspension of the this thread will not require the FP registers
235to be saved/restored.
236
237To disable FP register context saving, simply call the following API:
238
239void tx_thread_fp_disable(void);
240
241
24210. Revision History
243
244For generic code revision information, please refer to the readme_threadx_generic.txt
245file, which is included in your distribution. The following details the revision
246information associated with this specific port of ThreadX:
247
24804-02-2021 Release 6.1.6 changes:
249 tx_port.h Updated macro definition
250
25109-30-2020 Initial ThreadX 6.1 version for Cortex-A5x using ARM tools.
252
253
254Copyright(c) 1996-2020 Microsoft Corporation
255
256
257https://azure.com/rtos
258
259
