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