1 Microsoft's Azure RTOS ThreadX SMP for Cortex-A5
2
3 Thumb & 32-bit Mode
4
5 Using the ARM Compiler 5 & DS
6
71. Import the ThreadX Projects
8
9In order to build the ThreadX SMP library and the ThreadX SMP demonstration, first import
10the 'tx' and 'sample_threadx' projects (located in the "example_build" directory)
11into your DS workspace.
12
13
142. Building the ThreadX SMP run-time Library
15
16Building the ThreadX SMP 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 SMP library. This project build produces the ThreadX SMP
19library file tx.a.
20
21
223. Demonstration System
23
24The ThreadX SMP demonstration is designed to execute under the DS debugger on the
25VE_Cortex-A5x4 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, expand the demo ThreadX
29project folder in the Project Explorer window, right-click on the 'sample_threadx.launch'
30file, click 'Debug As', and then click 'sample_threadx' from the submenu. This will cause the
31debugger to load the sample_threadx.axf ELF file and run to main. You are now ready
32to execute the ThreadX demonstration.
33
34
354. System Initialization
36
37The entry point in ThreadX for the Cortex-A5 using AC5 tools is at label
38Reset_Handler in startup.s. After the basic core initialization is complete,
39control will transfer to __main, which is where all static and global pre-set
40C variable initialization processing takes place.
41
42The ThreadX tx_initialize_low_level.s file is responsible for setting up
43various system data structures, the vector area, and a periodic timer interrupt
44source. By default, the vector area is defined to be located in the Init area,
45which is defined at the top of tx_initialize_low_level.s. This area is typically
46located at 0. In situations where this is impossible, the vectors at the beginning
47of the Init area should be copied to address 0.
48
49This is also where initialization of a periodic timer interrupt source
50should take place.
51
52In addition, _tx_initialize_low_level determines the first available
53address for use by the application, which is supplied as the sole input
54parameter to your application definition function, tx_application_define.
55
56
575. Register Usage and Stack Frames
58
59The AC5 compiler assumes that registers r0-r3 (a1-a4) and r12 (ip) are scratch
60registers for each function. All other registers used by a C function must
61be preserved by the function. ThreadX takes advantage of this in situations
62where a context switch happens as a result of making a ThreadX service call
63(which is itself a C function). In such cases, the saved context of a thread
64is only the non-scratch registers.
65
66The following defines the saved context stack frames for context switches
67that occur as a result of interrupt handling or from thread-level API calls.
68All suspended threads have one of these two types of stack frames. The top
69of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the
70associated thread control block TX_THREAD.
71
72
73
74 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
75
76 0x00 1 0
77 0x04 CPSR CPSR
78 0x08 r0 (a1) r4 (v1)
79 0x0C r1 (a2) r5 (v2)
80 0x10 r2 (a3) r6 (v3)
81 0x14 r3 (a4) r7 (v4)
82 0x18 r4 (v1) r8 (v5)
83 0x1C r5 (v2) r9 (v6)
84 0x20 r6 (v3) r10 (v7)
85 0x24 r7 (v4) r11 (fp)
86 0x28 r8 (v5) r14 (lr)
87 0x2C r9 (v6)
88 0x30 r10 (v7)
89 0x34 r11 (fp)
90 0x38 r12 (ip)
91 0x3C r14 (lr)
92 0x40 PC
93
94
956. Improving Performance
96
97The distribution version of ThreadX is built without any compiler
98optimizations. This makes it easy to debug because you can trace or set
99breakpoints inside of ThreadX itself. Of course, this costs some
100performance. To make it run faster, you can change the build_threadx.bat file to
101remove the -g option and enable all compiler optimizations.
102
103In addition, you can eliminate the ThreadX basic API error checking by
104compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
105defined.
106
107
1087. Interrupt Handling
109
110ThreadX provides complete and high-performance interrupt handling for Cortex-A5
111targets. There are a certain set of requirements that are defined in the
112following sub-sections:
113
114
1157.1 Vector Area
116
117The Cortex-A5 vectors start at address zero. The demonstration system startup
118Init area contains the vectors and is loaded at address zero. On actual
119hardware platforms, this area might have to be copied to address 0.
120
121
1227.2 IRQ ISRs
123
124ThreadX fully manages standard and vectored IRQ interrupts. ThreadX also supports nested
125IRQ interrupts. The following sub-sections define the IRQ capabilities.
126
127
1287.2.1 Standard IRQ ISRs
129
130The standard ARM IRQ mechanism has a single interrupt vector at address 0x18. This IRQ
131interrupt is managed by the __tx_irq_handler code in tx_initialize_low_level. The following
132is the default IRQ handler defined in tx_initialize_low_level.s:
133
134 EXPORT __tx_irq_handler
135 EXPORT __tx_irq_processing_return
136__tx_irq_handler
137;
138; /* Jump to context save to save system context. */
139 B _tx_thread_context_save ; Jump to the context save
140__tx_irq_processing_return
141;
142; /* At this point execution is still in the IRQ mode. The CPSR, point of
143; interrupt, and all C scratch registers are available for use. Note
144; that IRQ interrupts are still disabled upon return from the context
145; save function. */
146;
147; /* Application ISR call(s) go here! */
148;
149; /* Jump to context restore to restore system context. */
150 B _tx_thread_context_restore
151
152
1537.2.2 Vectored IRQ ISRs
154
155The vectored ARM IRQ mechanism has multiple interrupt vectors at addresses specified
156by the particular implementation. The following is an example IRQ handler defined in
157tx_initialize_low_level.s:
158
159 EXPORT __tx_irq_example_handler
160__tx_irq_example_handler
161;
162; /* Call context save to save system context. */
163
164 STMDB sp!, {r0-r3} ; Save some scratch registers
165 MRS r0, SPSR ; Pickup saved SPSR
166 SUB lr, lr, #4 ; Adjust point of interrupt
167 STMDB sp!, {r0, r10, r12, lr} ; Store other scratch registers
168 BL _tx_thread_vectored_context_save ; Call the vectored IRQ context save
169;
170; /* At this point execution is still in the IRQ mode. The CPSR, point of
171; interrupt, and all C scratch registers are available for use. Note
172; that IRQ interrupts are still disabled upon return from the context
173; save function. */
174;
175; /* Application ISR call goes here! */
176;
177; /* Jump to context restore to restore system context. */
178 B _tx_thread_context_restore
179
180
1817.2.3 Nested IRQ Support
182
183By default, nested IRQ interrupt support is not enabled. To enable nested
184IRQ support, the entire library should be built with TX_ENABLE_IRQ_NESTING
185defined. With this defined, two new IRQ interrupt management services are
186available, namely _tx_thread_irq_nesting_start and _tx_thread_irq_nesting_end.
187These function should be called between the IRQ context save and restore
188calls.
189
190Execution between the calls to _tx_thread_irq_nesting_start and
191_tx_thread_irq_nesting_end is enabled for IRQ nesting. This is achieved
192by switching from IRQ mode to SYS mode and enabling IRQ interrupts.
193The SYS mode stack is used during the SYS mode operation, which was
194setup in tx_initialize_low_level.s. When nested IRQ interrupts are no longer required,
195calling the _tx_thread_irq_nesting_end service disables nesting by disabling
196IRQ interrupts and switching back to IRQ mode in preparation for the IRQ
197context restore service.
198
199The following is an example of enabling IRQ nested interrupts in a standard
200IRQ handler:
201
202 EXPORT __tx_irq_handler
203 EXPORT __tx_irq_processing_return
204__tx_irq_handler
205;
206; /* Jump to context save to save system context. */
207 B _tx_thread_context_save
208__tx_irq_processing_return
209;
210; /* Enable nested IRQ interrupts. NOTE: Since this service returns
211; with IRQ interrupts enabled, all IRQ interrupt sources must be
212; cleared prior to calling this service. */
213 BL _tx_thread_irq_nesting_start
214;
215; /* Application ISR call(s) go here! */
216;
217; /* Disable nested IRQ interrupts. The mode is switched back to
218; IRQ mode and IRQ interrupts are disable upon return. */
219 BL _tx_thread_irq_nesting_end
220;
221; /* Jump to context restore to restore system context. */
222 B _tx_thread_context_restore
223
224
2257.3 FIQ Interrupts
226
227By default, Cortex-A5 FIQ interrupts are left alone by ThreadX. Of course, this
228means that the application is fully responsible for enabling the FIQ interrupt
229and saving/restoring any registers used in the FIQ ISR processing. To globally
230enable FIQ interrupts, the application should enable FIQ interrupts at the
231beginning of each thread or before any threads are created in tx_application_define.
232In addition, the application must ensure that no ThreadX service calls are made
233from default FIQ ISRs, which is located in tx_initialize_low_level.s.
234
235
2367.3.1 Managed FIQ Interrupts
237
238Full ThreadX management of FIQ interrupts is provided if the ThreadX sources
239are built with the TX_ENABLE_FIQ_SUPPORT defined. If the library is built
240this way, the FIQ interrupt handlers are very similar to the IRQ interrupt
241handlers defined previously. The following is default FIQ handler
242defined in tx_initialize_low_level.s:
243
244
245 EXPORT __tx_fiq_handler
246 EXPORT __tx_fiq_processing_return
247__tx_fiq_handler
248;
249; /* Jump to fiq context save to save system context. */
250 B _tx_thread_fiq_context_save
251__tx_fiq_processing_return:
252;
253; /* At this point execution is still in the FIQ mode. The CPSR, point of
254; interrupt, and all C scratch registers are available for use. */
255;
256; /* Application FIQ handlers can be called here! */
257;
258; /* Jump to fiq context restore to restore system context. */
259 B _tx_thread_fiq_context_restore
260
261
2627.3.1.1 Nested FIQ Support
263
264By default, nested FIQ interrupt support is not enabled. To enable nested
265FIQ support, the entire library should be built with TX_ENABLE_FIQ_NESTING
266defined. With this defined, two new FIQ interrupt management services are
267available, namely _tx_thread_fiq_nesting_start and _tx_thread_fiq_nesting_end.
268These function should be called between the FIQ context save and restore
269calls.
270
271Execution between the calls to _tx_thread_fiq_nesting_start and
272_tx_thread_fiq_nesting_end is enabled for FIQ nesting. This is achieved
273by switching from FIQ mode to SYS mode and enabling FIQ interrupts.
274The SYS mode stack is used during the SYS mode operation, which was
275setup in tx_initialize_low_level.s. When nested FIQ interrupts are no longer required,
276calling the _tx_thread_fiq_nesting_end service disables nesting by disabling
277FIQ interrupts and switching back to FIQ mode in preparation for the FIQ
278context restore service.
279
280The following is an example of enabling FIQ nested interrupts in the
281typical FIQ handler:
282
283
284 EXPORT __tx_fiq_handler
285 EXPORT __tx_fiq_processing_return
286__tx_fiq_handler
287;
288; /* Jump to fiq context save to save system context. */
289 B _tx_thread_fiq_context_save
290__tx_fiq_processing_return
291;
292; /* At this point execution is still in the FIQ mode. The CPSR, point of
293; interrupt, and all C scratch registers are available for use. */
294;
295; /* Enable nested FIQ interrupts. NOTE: Since this service returns
296; with FIQ interrupts enabled, all FIQ interrupt sources must be
297; cleared prior to calling this service. */
298 BL _tx_thread_fiq_nesting_start
299;
300; /* Application FIQ handlers can be called here! */
301;
302; /* Disable nested FIQ interrupts. The mode is switched back to
303; FIQ mode and FIQ interrupts are disable upon return. */
304 BL _tx_thread_fiq_nesting_end
305;
306; /* Jump to fiq context restore to restore system context. */
307 B _tx_thread_fiq_context_restore
308
309
3108. ThreadX Timer Interrupt
311
312ThreadX requires a periodic interrupt source to manage all time-slicing,
313thread sleeps, timeouts, and application timers. Without such a timer
314interrupt source, these services are not functional. However, all other
315ThreadX services are operational without a periodic timer source.
316
317To add the timer interrupt processing, simply make a call to
318_tx_timer_interrupt in the IRQ processing. An example of this can be
319found in the file tx_initialize_low_level.s in the Integrator sub-directories.
320
321
3229. Thumb/Cortex-A5 Mixed Mode
323
324By default, ThreadX is setup for running in Cortex-A5 32-bit mode. This is
325also true for the demonstration system. It is possible to build any
326ThreadX file and/or the application in Thumb mode. If any Thumb code
327is used the entire ThreadX source- both C and assembly - should be built
328with the "-apcs /interwork" option.
329
330
33110. VFP Support
332
333By default, VFP support is disabled for each thread. If saving the context of the VFP registers
334is needed, the following API call must be made from the context of the application thread - before
335the VFP usage:
336
337void tx_thread_vfp_enable(void);
338
339After this API is called in the application, VFP registers will be saved/restored for this thread if it
340is preempted via an interrupt. All other suspension of the this thread will not require the VFP registers
341to be saved/restored.
342
343To disable VFP register context saving, simply call the following API:
344
345void tx_thread_vfp_disable(void);
346
347
34811. Revision History
349
350For generic code revision information, please refer to the readme_threadx_generic.txt
351file, which is included in your distribution. The following details the revision
352information associated with this specific port of ThreadX:
353
35404-02-2021 Release 6.1.6 changes:
355 tx_port.h Updated macro definition
356
35709-30-2020 Initial ThreadX 6.1 version for Cortex-A5 using AC5 tools.
358
359
360Copyright(c) 1996-2020 Microsoft Corporation
361
362
363https://azure.com/rtos
364
365
