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