1 Microsoft's Azure RTOS ThreadX for Cortex-A9
2
3 Thumb & 32-bit Mode
4
5 Using the IAR Tools
6
71. Building the ThreadX run-time Library
8
9Building the ThreadX library is easy. First, open the Azure RTOS workspace
10azure_rtos.eww. Next, make the TX project the "active project" in the
11IAR Embedded Workbench and select the "Make" button. You should observe
12assembly and compilation of a series of ThreadX source files. This
13results in the ThreadX run-time library file tx.a, which is needed by
14the application.
15
16
172. Demonstration System
18
19The ThreadX demonstration is designed to execute under the IAR
20Windows-based Cortex-A9 simulator.
21
22Building the demonstration is easy; simply make the sample_threadx.ewp project
23the "active project" in the IAR Embedded Workbench and select the
24"Make" button.
25
26You should observe the compilation of sample_threadx.c (which is the demonstration
27application) and linking with tx.a. The resulting file sample_threadx.out is a
28binary file that can be downloaded and executed on IAR's Cortex-A9 simulator.
29
30
313. System Initialization
32
33The entry point in ThreadX for the Cortex-A9 using IAR tools is at label
34?cstartup. This is defined within the IAR compiler's startup code. In
35addition, this is where all static and global preset C variable
36initialization processing takes place.
37
38The ThreadX tx_initialize_low_level.s file is responsible for setting up
39various system data structures, and a periodic timer interrupt source.
40By default, the vector area is defined at the top of cstartup.s, which is
41a slightly modified from the base IAR file.
42
43The _tx_initialize_low_level function inside of tx_initialize_low_level.s
44also determines the first available address for use by the application, which
45is supplied as the sole input parameter to your application definition function,
46tx_application_define. To accomplish this, a section is created in
47tx_initialize_low_level.s called FREE_MEM, which must be located after all
48other RAM sections in memory.
49
50
514. Register Usage and Stack Frames
52
53The IAR ARM compiler assumes that registers r0-r3 (a1-a4) and r12 (ip) are
54scratch registers for each function. All other registers used by a C function
55must be preserved by the function. ThreadX takes advantage of this in
56situations where a context switch happens as a result of making a ThreadX
57service call (which is itself a C function). In such cases, the saved
58context of a thread is only the non-scratch registers.
59
60The following defines the saved context stack frames for context switches
61that occur as a result of interrupt handling or from thread-level API calls.
62All suspended threads have one of these two types of stack frames. The top
63of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the
64associated thread control block TX_THREAD.
65
66
67
68 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
69
70 0x00 1 0
71 0x04 CPSR CPSR
72 0x08 r0 (a1) r4 (v1)
73 0x0C r1 (a2) r5 (v2)
74 0x10 r2 (a3) r6 (v3)
75 0x14 r3 (a4) r7 (v4)
76 0x18 r4 (v1) r8 (v5)
77 0x1C r5 (v2) r9 (v6)
78 0x20 r6 (v3) r10 (v7)
79 0x24 r7 (v4) r11 (fp)
80 0x28 r8 (v5) r14 (lr)
81 0x2C r9 (v6)
82 0x30 r10 (v7)
83 0x34 r11 (fp)
84 0x38 r12 (ip)
85 0x3C r14 (lr)
86 0x40 PC
87
88
895. Conditional Compilation Switches
90
91The following are conditional compilation options for building the ThreadX library
92and application:
93
94
95 TX_ENABLE_FIQ_SUPPORT This assembler/compiler define enables
96 FIQ interrupt handling support in the
97 ThreadX assembly files. If used,
98 it should be used on all assembly
99 files and the generic C source of
100 ThreadX should be compiled with
101 TX_ENABLE_FIQ_SUPPORT defined as well.
102
103 TX_ENABLE_IRQ_NESTING This assembler define enables IRQ
104 nested support. If IRQ nested
105 interrupt support is needed, this
106 define should be applied to
107 tx_initialize_low_level.s.
108
109 TX_ENABLE_FIQ_NESTING This assembler define enables FIQ
110 nested support. If FIQ nested
111 interrupt support is needed, this
112 define should be applied to
113 tx_initialize_low_level.s. In addition,
114 IRQ nesting should also be enabled.
115
116 TX_DISABLE_ERROR_CHECKING If defined before tx_api.h is included,
117 this define causes basic ThreadX error
118 checking to be disabled. Please see
119 Chapter 2 in the "ThreadX User Guide"
120 for more details.
121
122 TX_MAX_PRIORITIES Defines the priority levels for ThreadX.
123 Legal values range from 32 through
124 1024 (inclusive) and MUST be evenly divisible
125 by 32. Increasing the number of priority levels
126 supported increases the RAM usage by 128 bytes
127 for every group of 32 priorities. However, there
128 is only a negligible effect on performance. By
129 default, this value is set to 32 priority levels.
130
131 TX_MINIMUM_STACK Defines the minimum stack size (in bytes). It is
132 used for error checking when threads are created.
133 The default value is port-specific and is found
134 in tx_port.h.
135
136 TX_TIMER_THREAD_STACK_SIZE Defines the stack size (in bytes) of the internal
137 ThreadX timer thread. This thread processes all
138 thread sleep requests as well as all service call
139 timeouts. In addition, all application timer callback
140 routines are invoked from this context. The default
141 value is port-specific and is found in tx_port.h.
142
143 TX_TIMER_THREAD_PRIORITY Defines the priority of the internal ThreadX timer
144 thread. The default value is priority 0 - the highest
145 priority in ThreadX. The default value is defined
146 in tx_port.h.
147
148 TX_TIMER_PROCESS_IN_ISR Defined, this option eliminates the internal system
149 timer thread for ThreadX. This results in improved
150 performance on timer events and smaller RAM requirements
151 because the timer stack and control block are no
152 longer needed. However, using this option moves all
153 the timer expiration processing to the timer ISR level.
154 By default, this option is not defined.
155
156 TX_REACTIVATE_INLINE Defined, this option performs reactivation of ThreadX
157 timers in-line instead of using a function call. This
158 improves performance but slightly increases code size.
159 By default, this option is not defined.
160
161 TX_DISABLE_STACK_FILLING Defined, placing the 0xEF value in each byte of each
162 thread's stack is disabled. By default, this option is
163 not defined.
164
165 TX_ENABLE_STACK_CHECKING Defined, this option enables ThreadX run-time stack checking,
166 which includes analysis of how much stack has been used and
167 examination of data pattern "fences" before and after the
168 stack area. If a stack error is detected, the registered
169 application stack error handler is called. This option does
170 result in slightly increased overhead and code size. Please
171 review the tx_thread_stack_error_notify API for more information.
172 By default, this option is not defined.
173
174 TX_DISABLE_PREEMPTION_THRESHOLD Defined, this option disables the preemption-threshold feature
175 and slightly reduces code size and improves performance. Of course,
176 the preemption-threshold capabilities are no longer available.
177 By default, this option is not defined.
178
179 TX_DISABLE_REDUNDANT_CLEARING Defined, this option removes the logic for initializing ThreadX
180 global C data structures to zero. This should only be used if
181 the compiler's initialization code sets all un-initialized
182 C global data to zero. Using this option slightly reduces
183 code size and improves performance during initialization.
184 By default, this option is not defined.
185
186 TX_DISABLE_NOTIFY_CALLBACKS Defined, this option disables the notify callbacks for various
187 ThreadX objects. Using this option slightly reduces code size
188 and improves performance.
189
190 TX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
191 information on block pools. By default, this option is
192 not defined.
193
194 TX_BYTE_POOL_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
195 information on byte pools. By default, this option is
196 not defined.
197
198 TX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
199 information on event flags groups. By default, this option
200 is not defined.
201
202 TX_MUTEX_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
203 information on mutexes. By default, this option is
204 not defined.
205
206 TX_QUEUE_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
207 information on queues. By default, this option is
208 not defined.
209
210 TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
211 information on semaphores. By default, this option is
212 not defined.
213
214 TX_THREAD_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
215 information on threads. By default, this option is
216 not defined.
217
218 TX_TIMER_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
219 information on timers. By default, this option is
220 not defined.
221
222 TX_ENABLE_EVENT_TRACE Defined, this option enables the internal ThreadX trace
223 feature. The trace buffer is supplied at a later time
224 via an application call to tx_trace_enable.
225
226 TX_TRACE_TIME_SOURCE This defines the time-stamp source for event tracing.
227 This define is only pertinent if the ThreadX library is
228 built with TX_ENABLE_EVENT_TRACE defined.
229
230 TX_TRACE_TIME_MASK This defines the number of valid bits in the event trace
231 time-stamp source defined previously. If the time-stamp
232 source is 16-bits, this value should be 0xFFFF. Alternatively,
233 if the time-stamp source is 32-bits, this value should be
234 0xFFFFFFFF. This define is only pertinent if the ThreadX
235 library is built with TX_ENABLE_EVENT_TRACE defined.
236
237 TX_THUMB Defined, this option enables the BX LR calling return sequence
238 in assembly files, to ensure correct operation on systems that
239 use both ARM and Thumb mode. By default, this option is
240 not defined
241
242
243
244
245
2466. Improving Performance
247
248The distribution version of ThreadX is built without any compiler
249optimizations. This makes it easy to debug because you can trace or set
250breakpoints inside of ThreadX itself. Of course, this costs some
251performance. To make it run faster, you can change the ThreadX library
252project to enable various compiler optimizations.
253
254In addition, you can eliminate the ThreadX basic API error checking by
255compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
256defined.
257
258
2597. Interrupt Handling
260
261ThreadX provides complete and high-performance interrupt handling for Cortex-A9
262targets. There are a certain set of requirements that are defined in the
263following sub-sections:
264
265
2667.1 Vector Area
267
268The Cortex-A9 vectors start at address zero. The demonstration system startup
269cstartup.s file contains the vectors and is loaded at address zero.
270On actual hardware platforms, this area might have to be copied to address 0.
271
272
2737.2 IRQ ISRs
274
275ThreadX fully manages standard and vectored IRQ interrupts. ThreadX also supports nested
276IRQ interrupts. The following sub-sections define the IRQ capabilities.
277
278
2797.2.1 Standard IRQ ISRs
280
281The standard ARM IRQ mechanism has a single interrupt vector at address 0x18. This IRQ
282interrupt is managed by the __tx_irq_handler code in tx_initialize_low_level. The following
283is the default IRQ handler defined in tx_initialize_low_level.s:
284
285 PUBLIC __tx_irq_handler
286 PUBLIC __tx_irq_processing_return
287__tx_irq_handler
288;
289; /* Jump to context save to save system context. */
290 B _tx_thread_context_save
291__tx_irq_processing_return
292;
293; /* At this point execution is still in the IRQ mode. The CPSR, point of
294; interrupt, and all C scratch registers are available for use. Note
295; that IRQ interrupts are still disabled upon return from the context
296; save function. */
297;
298; /* Application ISR dispatch call goes here! */
299;
300; /* Jump to context restore to restore system context. */
301 B _tx_thread_context_restore
302
303
3047.2.2 Vectored IRQ ISRs
305
306The vectored ARM IRQ mechanism has multiple interrupt vectors at addresses specified
307by the particular implementation. The following is an example IRQ handler defined in
308tx_initialize_low_level.s:
309
310
311 RSEG .text:CODE:NOROOT(2)
312 PUBLIC __tx_example_vectored_irq_handler
313__tx_example_vectored_irq_handler
314;
315; /* Jump to context save to save system context. */
316 STMDB sp!, {r0-r3} ; Save some scratch registers
317 MRS r0, SPSR ; Pickup saved SPSR
318 SUB lr, lr, #4 ; Adjust point of interrupt
319 STMDB sp!, {r0, r10, r12, lr} ; Store other registers
320 BL _tx_thread_vectored_context_save
321;
322; /* At this point execution is still in the IRQ mode. The CPSR, point of
323; interrupt, and all C scratch registers are available for use. Note
324; that IRQ interrupts are still disabled upon return from the context
325; save function. */
326;
327; /* Application ISR dispatch call goes here! */
328;
329; /* Jump to context restore to restore system context. */
330 B _tx_thread_context_restore
331
332
3337.2.3 Nested IRQ Support
334
335By default, nested IRQ interrupt support is not enabled. To enable nested
336IRQ support, the entire library should be built with TX_ENABLE_IRQ_NESTING
337defined. With this defined, two new IRQ interrupt management services are
338available, namely _tx_thread_irq_nesting_start and _tx_thread_irq_nesting_end.
339These function should be called between the IRQ context save and restore
340calls.
341
342Execution between the calls to _tx_thread_irq_nesting_start and
343_tx_thread_irq_nesting_end is enabled for IRQ nesting. This is achieved
344by switching from IRQ mode to SYS mode and enabling IRQ interrupts.
345The SYS mode stack is used during the SYS mode operation, which was
346setup in tx_initialize_low_level.s. When nested IRQ interrupts are no
347longer required, calling the _tx_thread_irq_nesting_end service disables
348nesting by disabling IRQ interrupts and switching back to IRQ mode in
349preparation for the IRQ context restore service.
350
351The following is an example of enabling IRQ nested interrupts in a standard
352IRQ handler:
353
354 RSEG .text:CODE:NOROOT(2)
355 PUBLIC __tx_irq_handler
356 RSEG .text:CODE:NOROOT(2)
357 PUBLIC __tx_irq_processing_return
358__tx_irq_handler
359;
360; /* Jump to context save to save system context. */
361 B _tx_thread_context_save
362__tx_irq_processing_return
363;
364; /* At this point execution is still in the IRQ mode. The CPSR, point of
365; interrupt, and all C scratch registers are available for use. Note
366; that IRQ interrupts are still disabled upon return from the context
367; save function. */
368;
369; /* Interrupt nesting is allowed after calling _tx_thread_irq_nesting_start
370; from IRQ mode with interrupts disabled. This routine switches to the
371; system mode and returns with IRQ interrupts enabled.
372;
373; NOTE: It is very important to ensure all IRQ interrupts are cleared
374; prior to enabling nested IRQ interrupts. */
375;
376 BL _tx_thread_irq_nesting_start
377
378; /* Application ISR dispatch call goes here! */
379;
380; /* If interrupt nesting was started earlier, the end of interrupt nesting
381; service must be called before returning to _tx_thread_context_restore.
382; This routine returns in processing in IRQ mode with interrupts disabled. */
383;
384 BL _tx_thread_irq_nesting_end
385;
386; /* Jump to context restore to restore system context. */
387 B _tx_thread_context_restore
388
389
3907.3 FIQ Interrupts
391
392By default, Cortex-A9 FIQ interrupts are left alone by ThreadX. Of course, this
393means that the application is fully responsible for enabling the FIQ interrupt
394and saving/restoring any registers used in the FIQ ISR processing. To globally
395enable FIQ interrupts, the application should enable FIQ interrupts at the
396beginning of each thread or before any threads are created in tx_application_define.
397In addition, the application must ensure that no ThreadX service calls are made
398from default FIQ ISRs, which is located in tx_initialize_low_level.s.
399
400
4017.3.1 Managed FIQ Interrupts
402
403Full ThreadX management of FIQ interrupts is provided if the ThreadX sources
404are built with the TX_ENABLE_FIQ_SUPPORT defined. If the library is built
405this way, the FIQ interrupt handlers are very similar to the IRQ interrupt
406handlers defined previously. The following is default FIQ handler
407defined in tx_initialize_low_level.s:
408
409
410 RSEG .text:CODE:NOROOT(2)
411 PUBLIC __tx_fiq_handler
412 RSEG .text:CODE:NOROOT(2)
413 PUBLIC __tx_fiq_processing_return
414__tx_fiq_handler
415;
416; /* Jump to fiq context save to save system context. */
417 B _tx_thread_fiq_context_save
418__tx_fiq_processing_return:
419;
420; /* At this point execution is still in the FIQ mode. The CPSR, point of
421; interrupt, and all C scratch registers are available for use. */
422;
423; /* Application FIQ dispatch call goes here! */
424;
425; /* Jump to fiq context restore to restore system context. */
426 B _tx_thread_fiq_context_restore
427
428
429
4307.3.1.1 Nested FIQ Support
431
432By default, nested FIQ interrupt support is not enabled. To enable nested
433FIQ support, the entire library should be built with TX_ENABLE_FIQ_NESTING
434defined. With this defined, two new FIQ interrupt management services are
435available, namely _tx_thread_fiq_nesting_start and _tx_thread_fiq_nesting_end.
436These function should be called between the FIQ context save and restore
437calls.
438
439Execution between the calls to _tx_thread_fiq_nesting_start and
440_tx_thread_fiq_nesting_end is enabled for FIQ nesting. This is achieved
441by switching from FIQ mode to SYS mode and enabling FIQ interrupts.
442The SYS mode stack is used during the SYS mode operation, which was
443setup in tx_initialize_low_level.s. When nested FIQ interrupts are no
444longer required, calling the _tx_thread_fiq_nesting_end service disables
445nesting by disabling FIQ interrupts and switching back to FIQ mode in
446preparation for the FIQ context restore service.
447
448The following is an example of enabling FIQ nested interrupts in the
449typical FIQ handler:
450
451
452 RSEG .text:CODE:NOROOT(2)
453 PUBLIC __tx_fiq_handler
454 RSEG .text:CODE:NOROOT(2)
455 PUBLIC __tx_fiq_processing_return
456__tx_fiq_handler
457;
458; /* Jump to fiq context save to save system context. */
459 B _tx_thread_fiq_context_save
460__tx_fiq_processing_return:
461;
462; /* At this point execution is still in the FIQ mode. The CPSR, point of
463; interrupt, and all C scratch registers are available for use. */
464;
465; /* Enable nested FIQ interrupts. NOTE: Since this service returns
466; with FIQ interrupts enabled, all FIQ interrupt sources must be
467; cleared prior to calling this service. */
468 BL _tx_thread_fiq_nesting_start
469;
470; /* Application FIQ dispatch call goes here! */
471;
472; /* Disable nested FIQ interrupts. The mode is switched back to
473; FIQ mode and FIQ interrupts are disable upon return. */
474 BL _tx_thread_fiq_nesting_end
475;
476; /* Jump to fiq context restore to restore system context. */
477 B _tx_thread_fiq_context_restore
478
479
4808. ThreadX Timer Interrupt
481
482ThreadX requires a periodic interrupt source to manage all time-slicing,
483thread sleeps, timeouts, and application timers. Without such a timer
484interrupt source, these services are not functional. However, all other
485ThreadX services are operational without a periodic timer source.
486
487To add the timer interrupt processing, simply make a call to _tx_timer_interrupt
488in the IRQ processing.
489
490
4919. Thumb/Cortex-A9 Mixed Mode
492
493By default, ThreadX is setup for running in Cortex-A9 32-bit mode. This is
494also true for the demonstration system. It is possible to build any
495ThreadX file and/or the application in Thumb mode. The only exception
496to this is the file tx_thread_shell_entry.c. This file must always be
497built in 32-bit mode. In addition, if any Thumb code is used the entire
498ThreadX assembly source should be built with TX_THUMB defined.
499
500
50110. IAR Thread-safe Library Support
502
503Thread-safe support for the IAR tools is easily enabled by building the ThreadX library
504and the application with TX_ENABLE_IAR_LIBRARY_SUPPORT. Also, the linker control file
505should have the following line added (if not already in place):
506
507initialize by copy with packing = none { section __DLIB_PERTHREAD }; // Required in a multi-threaded application
508
509The project options "General Options -> Library Configuration" should also have the
510"Enable thread support in library" box selected.
511
512
51311. VFP Support
514
515By default, VFP support is disabled for each thread. If saving the context of the VFP registers
516is needed, the following API call must be made from the context of the application thread - before
517the VFP usage:
518
519void tx_thread_vfp_enable(void);
520
521After this API is called in the application, VFP registers will be saved/restored for this thread if it
522is preempted via an interrupt. All other suspension of the this thread will not require the VFP registers
523to be saved/restored.
524
525To disable VFP register context saving, simply call the following API:
526
527void tx_thread_vfp_disable(void);
528
529
530
53112. Revision History
532
533For generic code revision information, please refer to the readme_threadx_generic.txt
534file, which is included in your distribution. The following details the revision
535information associated with this specific port of ThreadX:
536
53704-02-2021 Release 6.1.6 changes:
538 tx_port.h Updated macro definition
539
54009-30-2020 Initial ThreadX version 6.1 for Cortex-A9 using IAR's ARM tools.
541
542
543Copyright(c) 1996-2020 Microsoft Corporation
544
545
546https://azure.com/rtos
547
548
