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