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