1 Microsoft's Azure RTOS ThreadX for Cortex-R5
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-R5 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-R5 simulator.
29
30
313. System Initialization
32
33The entry point in ThreadX for the Cortex-R5 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 TX_ENABLE_IRQ_NESTING This assembler define enables IRQ
95 nested support. If IRQ nested
96 interrupt support is needed, this
97 define should be applied to
98 tx_initialize_low_level.s.
99
100 TX_DISABLE_ERROR_CHECKING If defined before tx_api.h is included,
101 this define causes basic ThreadX error
102 checking to be disabled. Please see
103 Chapter 2 in the "ThreadX User Guide"
104 for more details.
105
106 TX_MAX_PRIORITIES Defines the priority levels for ThreadX.
107 Legal values range from 32 through
108 1024 (inclusive) and MUST be evenly divisible
109 by 32. Increasing the number of priority levels
110 supported increases the RAM usage by 128 bytes
111 for every group of 32 priorities. However, there
112 is only a negligible effect on performance. By
113 default, this value is set to 32 priority levels.
114
115 TX_MINIMUM_STACK Defines the minimum stack size (in bytes). It is
116 used for error checking when threads are created.
117 The default value is port-specific and is found
118 in tx_port.h.
119
120 TX_TIMER_THREAD_STACK_SIZE Defines the stack size (in bytes) of the internal
121 ThreadX timer thread. This thread processes all
122 thread sleep requests as well as all service call
123 timeouts. In addition, all application timer callback
124 routines are invoked from this context. The default
125 value is port-specific and is found in tx_port.h.
126
127 TX_TIMER_THREAD_PRIORITY Defines the priority of the internal ThreadX timer
128 thread. The default value is priority 0 - the highest
129 priority in ThreadX. The default value is defined
130 in tx_port.h.
131
132 TX_TIMER_PROCESS_IN_ISR Defined, this option eliminates the internal system
133 timer thread for ThreadX. This results in improved
134 performance on timer events and smaller RAM requirements
135 because the timer stack and control block are no
136 longer needed. However, using this option moves all
137 the timer expiration processing to the timer ISR level.
138 By default, this option is not defined.
139
140 TX_REACTIVATE_INLINE Defined, this option performs reactivation of ThreadX
141 timers in-line instead of using a function call. This
142 improves performance but slightly increases code size.
143 By default, this option is not defined.
144
145 TX_DISABLE_STACK_FILLING Defined, placing the 0xEF value in each byte of each
146 thread's stack is disabled. By default, this option is
147 not defined.
148
149 TX_ENABLE_STACK_CHECKING Defined, this option enables ThreadX run-time stack checking,
150 which includes analysis of how much stack has been used and
151 examination of data pattern "fences" before and after the
152 stack area. If a stack error is detected, the registered
153 application stack error handler is called. This option does
154 result in slightly increased overhead and code size. Please
155 review the tx_thread_stack_error_notify API for more information.
156 By default, this option is not defined.
157
158 TX_DISABLE_PREEMPTION_THRESHOLD Defined, this option disables the preemption-threshold feature
159 and slightly reduces code size and improves performance. Of course,
160 the preemption-threshold capabilities are no longer available.
161 By default, this option is not defined.
162
163 TX_DISABLE_REDUNDANT_CLEARING Defined, this option removes the logic for initializing ThreadX
164 global C data structures to zero. This should only be used if
165 the compiler's initialization code sets all un-initialized
166 C global data to zero. Using this option slightly reduces
167 code size and improves performance during initialization.
168 By default, this option is not defined.
169
170 TX_DISABLE_NOTIFY_CALLBACKS Defined, this option disables the notify callbacks for various
171 ThreadX objects. Using this option slightly reduces code size
172 and improves performance.
173
174 TX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
175 information on block pools. By default, this option is
176 not defined.
177
178 TX_BYTE_POOL_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
179 information on byte pools. By default, this option is
180 not defined.
181
182 TX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
183 information on event flags groups. By default, this option
184 is not defined.
185
186 TX_MUTEX_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
187 information on mutexes. By default, this option is
188 not defined.
189
190 TX_QUEUE_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
191 information on queues. By default, this option is
192 not defined.
193
194 TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
195 information on semaphores. By default, this option is
196 not defined.
197
198 TX_THREAD_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
199 information on threads. By default, this option is
200 not defined.
201
202 TX_TIMER_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
203 information on timers. By default, this option is
204 not defined.
205
206 TX_ENABLE_EVENT_TRACE Defined, this option enables the internal ThreadX trace
207 feature. The trace buffer is supplied at a later time
208 via an application call to tx_trace_enable.
209
210 TX_TRACE_TIME_SOURCE This defines the time-stamp source for event tracing.
211 This define is only pertinent if the ThreadX library is
212 built with TX_ENABLE_EVENT_TRACE defined.
213
214 TX_TRACE_TIME_MASK This defines the number of valid bits in the event trace
215 time-stamp source defined previously. If the time-stamp
216 source is 16-bits, this value should be 0xFFFF. Alternatively,
217 if the time-stamp source is 32-bits, this value should be
218 0xFFFFFFFF. This define is only pertinent if the ThreadX
219 library is built with TX_ENABLE_EVENT_TRACE defined.
220
221
222
2236. Improving Performance
224
225The distribution version of ThreadX is built without any compiler
226optimizations. This makes it easy to debug because you can trace or set
227breakpoints inside of ThreadX itself. Of course, this costs some
228performance. To make it run faster, you can change the ThreadX library
229project to enable various compiler optimizations.
230
231In addition, you can eliminate the ThreadX basic API error checking by
232compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
233defined.
234
235
2367. Interrupt Handling
237
238ThreadX provides complete and high-performance interrupt handling for Cortex-R5
239targets. There are a certain set of requirements that are defined in the
240following sub-sections:
241
242
2437.1 Vector Area
244
245The Cortex-R5 vectors start at address zero. The demonstration system startup
246cstartup.s file contains the vectors and is loaded at address zero.
247On actual hardware platforms, this area might have to be copied to address 0.
248
249
2507.2 IRQ ISRs
251
252ThreadX fully manages standard and vectored IRQ interrupts. ThreadX also supports nested
253IRQ interrupts. The following sub-sections define the IRQ capabilities.
254
255
2567.2.1 Standard IRQ ISRs
257
258The standard ARM IRQ mechanism has a single interrupt vector at address 0x18. This IRQ
259interrupt is managed by the __tx_irq_handler code in tx_initialize_low_level. The following
260is the default IRQ handler defined in tx_initialize_low_level.s:
261
262 PUBLIC __tx_irq_handler
263 PUBLIC __tx_irq_processing_return
264__tx_irq_handler
265;
266; /* Jump to context save to save system context. */
267 B _tx_thread_context_save
268__tx_irq_processing_return
269;
270; /* At this point execution is still in the IRQ mode. The CPSR, point of
271; interrupt, and all C scratch registers are available for use. Note
272; that IRQ interrupts are still disabled upon return from the context
273; save function. */
274;
275; /* Application ISR dispatch call goes here! */
276;
277; /* Jump to context restore to restore system context. */
278 B _tx_thread_context_restore
279
280
2817.2.2 Vectored IRQ ISRs
282
283The vectored ARM IRQ mechanism has multiple interrupt vectors at addresses specified
284by the particular implementation. The following is an example IRQ handler defined in
285tx_initialize_low_level.s:
286
287
288 RSEG .text:CODE:NOROOT(2)
289 PUBLIC __tx_example_vectored_irq_handler
290__tx_example_vectored_irq_handler
291;
292; /* Jump to context save to save system context. */
293 STMDB sp!, {r0-r3} ; Save some scratch registers
294 MRS r0, SPSR ; Pickup saved SPSR
295 SUB lr, lr, #4 ; Adjust point of interrupt
296 STMDB sp!, {r0, r10, r12, lr} ; Store other registers
297 BL _tx_thread_vectored_context_save
298;
299; /* At this point execution is still in the IRQ mode. The CPSR, point of
300; interrupt, and all C scratch registers are available for use. Note
301; that IRQ interrupts are still disabled upon return from the context
302; save function. */
303;
304; /* Application ISR dispatch call goes here! */
305;
306; /* Jump to context restore to restore system context. */
307 B _tx_thread_context_restore
308
309
3107.2.3 Nested IRQ Support
311
312By default, nested IRQ interrupt support is not enabled. To enable nested
313IRQ support, the entire library should be built with TX_ENABLE_IRQ_NESTING
314defined. With this defined, two new IRQ interrupt management services are
315available, namely _tx_thread_irq_nesting_start and _tx_thread_irq_nesting_end.
316These function should be called between the IRQ context save and restore
317calls.
318
319Execution between the calls to _tx_thread_irq_nesting_start and
320_tx_thread_irq_nesting_end is enabled for IRQ nesting. This is achieved
321by switching from IRQ mode to SYS mode and enabling IRQ interrupts.
322The SYS mode stack is used during the SYS mode operation, which was
323setup in tx_initialize_low_level.s. When nested IRQ interrupts are no
324longer required, calling the _tx_thread_irq_nesting_end service disables
325nesting by disabling IRQ interrupts and switching back to IRQ mode in
326preparation for the IRQ context restore service.
327
328The following is an example of enabling IRQ nested interrupts in a standard
329IRQ handler:
330
331 RSEG .text:CODE:NOROOT(2)
332 PUBLIC __tx_irq_handler
333 RSEG .text:CODE:NOROOT(2)
334 PUBLIC __tx_irq_processing_return
335__tx_irq_handler
336;
337; /* Jump to context save to save system context. */
338 B _tx_thread_context_save
339__tx_irq_processing_return
340;
341; /* At this point execution is still in the IRQ mode. The CPSR, point of
342; interrupt, and all C scratch registers are available for use. Note
343; that IRQ interrupts are still disabled upon return from the context
344; save function. */
345;
346; /* Interrupt nesting is allowed after calling _tx_thread_irq_nesting_start
347; from IRQ mode with interrupts disabled. This routine switches to the
348; system mode and returns with IRQ interrupts enabled.
349;
350; NOTE: It is very important to ensure all IRQ interrupts are cleared
351; prior to enabling nested IRQ interrupts. */
352;
353 BL _tx_thread_irq_nesting_start
354
355; /* Application ISR dispatch call goes here! */
356;
357; /* If interrupt nesting was started earlier, the end of interrupt nesting
358; service must be called before returning to _tx_thread_context_restore.
359; This routine returns in processing in IRQ mode with interrupts disabled. */
360;
361 BL _tx_thread_irq_nesting_end
362;
363; /* Jump to context restore to restore system context. */
364 B _tx_thread_context_restore
365
366
3677.3 FIQ Interrupts
368
369By default, Cortex-R5 FIQ interrupts are left alone by ThreadX. Of course, this
370means that the application is fully responsible for enabling the FIQ interrupt
371and saving/restoring any registers used in the FIQ ISR processing. To globally
372enable FIQ interrupts, the application should enable FIQ interrupts at the
373beginning of a thread or before any threads are created in tx_application_define.
374In addition, the application must ensure that no ThreadX service calls are made
375from default FIQ ISRs, which is located in tx_initialize_low_level.s.
376
377
3787.3.1 Managed FIQ Interrupts
379
380ThreadX management of FIQ interrupts is not provided because FIQ interrupts
381cannot be disabled. The hardware does not support nested FIQ interrupts.
382
383
3848. ThreadX Timer Interrupt
385
386ThreadX requires a periodic interrupt source to manage all time-slicing,
387thread sleeps, timeouts, and application timers. Without such a timer
388interrupt source, these services are not functional. However, all other
389ThreadX services are operational without a periodic timer source.
390
391To add the timer interrupt processing, simply make a call to _tx_timer_interrupt
392in the IRQ processing.
393
394
3959. Thumb/Cortex-R5 Mixed Mode
396
397By default, ThreadX is setup for running in Cortex-R5 32-bit mode. This is
398also true for the demonstration system. It is possible to build any
399ThreadX file and/or the application in Thumb mode. The only exception
400to this is the file tx_thread_shell_entry.c. This file must always be
401built in 32-bit mode.
402
403
40410. IAR Thread-safe Library Support
405
406Thread-safe support for the IAR tools is easily enabled by building the ThreadX library
407and the application with TX_ENABLE_IAR_LIBRARY_SUPPORT. Also, the linker control file
408should have the following line added (if not already in place):
409
410initialize by copy with packing = none { section __DLIB_PERTHREAD }; // Required in a multi-threaded application
411
412
41311. Revision History
414
415For generic code revision information, please refer to the readme_threadx_generic.txt
416file, which is included in your distribution. The following details the revision
417information associated with this specific port of ThreadX:
418
41904-02-2021 Release 6.1.6 changes:
420 tx_port.h Updated macro definition
421
42209-30-2020 Initial ThreadX version for Cortex-R5 using IAR's ARM tools.
423
424
425Copyright(c) 1996-2020 Microsoft Corporation
426
427
428https://azure.com/rtos
429
430
