1 Microsoft's Azure RTOS ThreadX for Cortex-A7
2
3 Thumb & 32-bit Mode
4
5 Using ARM Compiler 5 (AC5)
6
71. Building the ThreadX run-time Library
8
9First make sure you are in the "example_build" directory. Also, make sure that
10you have setup your path and other environment variables necessary for the AC5
11Compiler. At this point you may run the build_threadx.bat batch file. This will
12build the ThreadX 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
191.1 Building with Project Files
20
21The ThreadX library can also be built via project files. Simply open
22the tx.mcp file with project builder and select make. This will place
23the tx.a library file into the Debug sub-directory.
24
25
262. Demonstration System
27
28The ThreadX demonstration is designed to execute under the ARM
29Windows-based simulator.
30
31Building the demonstration is easy; simply execute the build_threadx_sample.bat
32batch file while inside the "example_build" directory.
33
34You should observe the compilation of sample_threadx.c (which is the demonstration
35application) and linking with tx.a. The resulting file sample_threadx.axf
36is a binary file that can be downloaded and executed on the ARM simulator.
37
382.0.1 Building with Project Files
39
40The ThreadX demonstration can also be built via project files. Simply open
41the sample_threadx.mcp file with project builder and select make. This will place
42the sample_threadx.axf output image into the Debug sub-directory.
43
44
453. System Initialization
46
47The entry point in ThreadX for the Cortex-A7 using AC5 tools is at label
48__main. This is defined within the AC5 compiler's startup code. In
49addition, this is where all static and global pre-set C variable
50initialization processing takes place.
51
52The ThreadX tx_initialize_low_level.s file is responsible for setting up
53various system data structures, the vector area, and a periodic timer interrupt
54source. By default, the vector area is defined to be located in the Init area,
55which is defined at the top of tx_initialize_low_level.s. This area is typically
56located at 0. In situations where this is impossible, the vectors at the beginning
57of the Init area should be copied to address 0.
58
59This is also where initialization of a periodic timer interrupt source
60should take place.
61
62In addition, _tx_initialize_low_level determines the first available
63address for use by the application, which is supplied as the sole input
64parameter to your application definition function, tx_application_define.
65
66
674. Assembler / Compiler Switches
68
69The following are compiler switches used in building the demonstration
70system:
71
72Compiler Switch Meaning
73
74 -g Specifies debug information
75 -c Specifies object code generation
76 --cpu Cortex-A7 Specifies Cortex-A7 instruction set
77 --apcs /interwork Specifies Thumb/32-bit compatibility
78
79Linker Switch Meaning
80
81 -d Specifies to retain debug information in output file
82 -o demo.axf Specifies demo output file name
83 --elf Specifies elf output file format
84 --ro Specifies that Read-Only memory starts at address 0
85 --first tx_initialize_low_level.o(Init)
86 Specifies that the first area loaded is Init
87 --remove Remove unused areas
88 --list Specifies map file name
89 --symbols Specifies symbols for map file
90 --map Creates a map file
91
92Application Defines
93
94 --PD "TX_ENABLE_FIQ_SUPPORT SETL {TRUE}" This assembler define enables FIQ
95 interrupt handling support in the
96 ThreadX assembly files. If used,
97 it should be used on all assembly
98 files and the generic C source of
99 ThreadX should be compiled with
100 TX_ENABLE_FIQ_SUPPORT defined as well.
101 --PD "TX_ENABLE_IRQ_NESTING SETL {TRUE}" This assembler define enables IRQ
102 nested support. If IRQ nested
103 interrupt support is needed, this
104 define should be applied to
105 tx_initialize_low_level.s.
106 --PD "TX_ENABLE_FIQ_NESTING SETL {TRUE}" This assembler define enables FIQ
107 nested support. If FIQ nested
108 interrupt support is needed, this
109 define should be applied to
110 tx_initialize_low_level.s. In addition,
111 IRQ nesting should also be enabled.
112 -DTX_ENABLE_FIQ_SUPPORT This compiler define enables FIQ
113 interrupt handling in the ThreadX
114 generic C source. This define
115 should also be used in conjunction
116 with the corresponding assembler
117 define.
118 -DTX_DISABLE_ERROR_CHECKING If defined before tx_api.h is included,
119 this define causes basic ThreadX error
120 checking to be disabled. Please see
121 Chapter 2 in the "ThreadX User Guide"
122 for more details.
123
124 -DTX_MAX_PRIORITIES Defines the priority levels for ThreadX.
125 Legal values range from 32 through
126 1024 (inclusive) and MUST be evenly divisible
127 by 32. Increasing the number of priority levels
128 supported increases the RAM usage by 128 bytes
129 for every group of 32 priorities. However, there
130 is only a negligible effect on performance. By
131 default, this value is set to 32 priority levels.
132
133 -DTX_MINIMUM_STACK Defines the minimum stack size (in bytes). It is
134 used for error checking when threads are created.
135 The default value is port-specific and is found
136 in tx_port.h.
137
138 -DTX_TIMER_THREAD_STACK_SIZE Defines the stack size (in bytes) of the internal
139 ThreadX timer thread. This thread processes all
140 thread sleep requests as well as all service call
141 timeouts. In addition, all application timer callback
142 routines are invoked from this context. The default
143 value is port-specific and is found in tx_port.h.
144
145 -DTX_TIMER_THREAD_PRIORITY Defines the priority of the internal ThreadX timer
146 thread. The default value is priority 0 - the highest
147 priority in ThreadX. The default value is defined
148 in tx_port.h.
149
150 -DTX_TIMER_PROCESS_IN_ISR Defined, this option eliminates the internal system
151 timer thread for ThreadX. This results in improved
152 performance on timer events and smaller RAM requirements
153 because the timer stack and control block are no
154 longer needed. However, using this option moves all
155 the timer expiration processing to the timer ISR level.
156 By default, this option is not defined.
157
158 -DTX_REACTIVATE_INLINE Defined, this option performs reactivation of ThreadX
159 timers in-line instead of using a function call. This
160 improves performance but slightly increases code size.
161 By default, this option is not defined.
162
163 -DTX_DISABLE_STACK_FILLING Defined, placing the 0xEF value in each byte of each
164 thread's stack is disabled. By default, this option is
165 not defined.
166
167 -DTX_ENABLE_STACK_CHECKING Defined, this option enables ThreadX run-time stack checking,
168 which includes analysis of how much stack has been used and
169 examination of data pattern "fences" before and after the
170 stack area. If a stack error is detected, the registered
171 application stack error handler is called. This option does
172 result in slightly increased overhead and code size. Please
173 review the tx_thread_stack_error_notify API for more information.
174 By default, this option is not defined.
175
176 -DTX_DISABLE_PREEMPTION_THRESHOLD Defined, this option disables the preemption-threshold feature
177 and slightly reduces code size and improves performance. Of course,
178 the preemption-threshold capabilities are no longer available.
179 By default, this option is not defined.
180
181 -DTX_DISABLE_REDUNDANT_CLEARING Defined, this option removes the logic for initializing ThreadX
182 global C data structures to zero. This should only be used if
183 the compiler's initialization code sets all un-initialized
184 C global data to zero. Using this option slightly reduces
185 code size and improves performance during initialization.
186 By default, this option is not defined.
187
188 -DTX_DISABLE_NOTIFY_CALLBACKS Defined, this option disables the notify callbacks for various
189 ThreadX objects. Using this option slightly reduces code size
190 and improves performance.
191
192 -DTX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
193 information on block pools. By default, this option is
194 not defined.
195
196 -DTX_BYTE_POOL_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
197 information on byte pools. By default, this option is
198 not defined.
199
200 -DTX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
201 information on event flags groups. By default, this option
202 is not defined.
203
204 -DTX_MUTEX_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
205 information on mutexes. By default, this option is
206 not defined.
207
208 -DTX_QUEUE_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
209 information on queues. By default, this option is
210 not defined.
211
212 -DTX_SEMAPHORE_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
213 information on semaphores. By default, this option is
214 not defined.
215
216 -DTX_THREAD_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
217 information on threads. By default, this option is
218 not defined.
219
220 -DTX_TIMER_ENABLE_PERFORMANCE_INFO Defined, this option enables the gathering of performance
221 information on timers. By default, this option is
222 not defined.
223
224 -DTX_ENABLE_EVENT_TRACE Defined, this option enables the internal ThreadX trace
225 feature. The trace buffer is supplied at a later time
226 via an application call to tx_trace_enable.
227
228 -DTX_TRACE_TIME_SOURCE This defines the time-stamp source for event tracing.
229 This define is only pertinent if the ThreadX library is
230 built with TX_ENABLE_EVENT_TRACE defined.
231
232 -DTX_TRACE_TIME_MASK This defines the number of valid bits in the event trace
233 time-stamp source defined previously. If the time-stamp
234 source is 16-bits, this value should be 0xFFFF. Alternatively,
235 if the time-stamp source is 32-bits, this value should be
236 0xFFFFFFFF. This define is only pertinent if the ThreadX
237 library is built with TX_ENABLE_EVENT_TRACE defined.
238
239
240
2415. Register Usage and Stack Frames
242
243The AC5 compiler assumes that registers r0-r3 (a1-a4) and r12 (ip) are scratch
244registers for each function. All other registers used by a C function must
245be preserved by the function. ThreadX takes advantage of this in situations
246where a context switch happens as a result of making a ThreadX service call
247(which is itself a C function). In such cases, the saved context of a thread
248is only the non-scratch registers.
249
250The following defines the saved context stack frames for context switches
251that occur as a result of interrupt handling or from thread-level API calls.
252All suspended threads have one of these two types of stack frames. The top
253of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the
254associated thread control block TX_THREAD.
255
256
257
258 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
259
260 0x00 1 0
261 0x04 CPSR CPSR
262 0x08 r0 (a1) r4 (v1)
263 0x0C r1 (a2) r5 (v2)
264 0x10 r2 (a3) r6 (v3)
265 0x14 r3 (a4) r7 (v4)
266 0x18 r4 (v1) r8 (v5)
267 0x1C r5 (v2) r9 (v6)
268 0x20 r6 (v3) r10 (v7)
269 0x24 r7 (v4) r11 (fp)
270 0x28 r8 (v5) r14 (lr)
271 0x2C r9 (v6)
272 0x30 r10 (v7)
273 0x34 r11 (fp)
274 0x38 r12 (ip)
275 0x3C r14 (lr)
276 0x40 PC
277
278
2796. Improving Performance
280
281The distribution version of ThreadX is built without any compiler
282optimizations. This makes it easy to debug because you can trace or set
283breakpoints inside of ThreadX itself. Of course, this costs some
284performance. To make it run faster, you can change the build_threadx.bat file to
285remove the -g option and enable all compiler optimizations.
286
287In addition, you can eliminate the ThreadX basic API error checking by
288compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
289defined.
290
291
2927. Interrupt Handling
293
294ThreadX provides complete and high-performance interrupt handling for Cortex-A7
295targets. There are a certain set of requirements that are defined in the
296following sub-sections:
297
298
2997.1 Vector Area
300
301The Cortex-A7 vectors start at address zero. The demonstration system startup
302Init area contains the vectors and is loaded at address zero. On actual
303hardware platforms, this area might have to be copied to address 0.
304
305
3067.2 IRQ ISRs
307
308ThreadX fully manages standard and vectored IRQ interrupts. ThreadX also supports nested
309IRQ interrupts. The following sub-sections define the IRQ capabilities.
310
311
3127.2.1 Standard IRQ ISRs
313
314The standard ARM IRQ mechanism has a single interrupt vector at address 0x18. This IRQ
315interrupt is managed by the __tx_irq_handler code in tx_initialize_low_level. The following
316is the default IRQ handler defined in tx_initialize_low_level.s:
317
318 EXPORT __tx_irq_handler
319 EXPORT __tx_irq_processing_return
320__tx_irq_handler
321;
322; /* Jump to context save to save system context. */
323 B _tx_thread_context_save ; Jump to the context save
324__tx_irq_processing_return
325;
326; /* At this point execution is still in the IRQ mode. The CPSR, point of
327; interrupt, and all C scratch registers are available for use. Note
328; that IRQ interrupts are still disabled upon return from the context
329; save function. */
330;
331; /* Application ISR call(s) go here! */
332;
333; /* Jump to context restore to restore system context. */
334 B _tx_thread_context_restore
335
336
3377.2.2 Vectored IRQ ISRs
338
339The vectored ARM IRQ mechanism has multiple interrupt vectors at addresses specified
340by the particular implementation. The following is an example IRQ handler defined in
341tx_initialize_low_level.s:
342
343 EXPORT __tx_irq_example_handler
344__tx_irq_example_handler
345;
346; /* Call context save to save system context. */
347
348 STMDB sp!, {r0-r3} ; Save some scratch registers
349 MRS r0, SPSR ; Pickup saved SPSR
350 SUB lr, lr, #4 ; Adjust point of interrupt
351 STMDB sp!, {r0, r10, r12, lr} ; Store other scratch registers
352 BL _tx_thread_vectored_context_save ; Call the vectored IRQ context save
353;
354; /* At this point execution is still in the IRQ mode. The CPSR, point of
355; interrupt, and all C scratch registers are available for use. Note
356; that IRQ interrupts are still disabled upon return from the context
357; save function. */
358;
359; /* Application ISR call goes here! */
360;
361; /* Jump to context restore to restore system context. */
362 B _tx_thread_context_restore
363
364
3657.2.3 Nested IRQ Support
366
367By default, nested IRQ interrupt support is not enabled. To enable nested
368IRQ support, the entire library should be built with TX_ENABLE_IRQ_NESTING
369defined. With this defined, two new IRQ interrupt management services are
370available, namely _tx_thread_irq_nesting_start and _tx_thread_irq_nesting_end.
371These function should be called between the IRQ context save and restore
372calls.
373
374Execution between the calls to _tx_thread_irq_nesting_start and
375_tx_thread_irq_nesting_end is enabled for IRQ nesting. This is achieved
376by switching from IRQ mode to SYS mode and enabling IRQ interrupts.
377The SYS mode stack is used during the SYS mode operation, which was
378setup in tx_initialize_low_level.s. When nested IRQ interrupts are no longer required,
379calling the _tx_thread_irq_nesting_end service disables nesting by disabling
380IRQ interrupts and switching back to IRQ mode in preparation for the IRQ
381context restore service.
382
383The following is an example of enabling IRQ nested interrupts in a standard
384IRQ handler:
385
386 EXPORT __tx_irq_handler
387 EXPORT __tx_irq_processing_return
388__tx_irq_handler
389;
390; /* Jump to context save to save system context. */
391 B _tx_thread_context_save
392__tx_irq_processing_return
393;
394; /* Enable nested IRQ interrupts. NOTE: Since this service returns
395; with IRQ interrupts enabled, all IRQ interrupt sources must be
396; cleared prior to calling this service. */
397 BL _tx_thread_irq_nesting_start
398;
399; /* Application ISR call(s) go here! */
400;
401; /* Disable nested IRQ interrupts. The mode is switched back to
402; IRQ mode and IRQ interrupts are disable upon return. */
403 BL _tx_thread_irq_nesting_end
404;
405; /* Jump to context restore to restore system context. */
406 B _tx_thread_context_restore
407
408
4097.3 FIQ Interrupts
410
411By default, Cortex-A7 FIQ interrupts are left alone by ThreadX. Of course, this
412means that the application is fully responsible for enabling the FIQ interrupt
413and saving/restoring any registers used in the FIQ ISR processing. To globally
414enable FIQ interrupts, the application should enable FIQ interrupts at the
415beginning of each thread or before any threads are created in tx_application_define.
416In addition, the application must ensure that no ThreadX service calls are made
417from default FIQ ISRs, which is located in tx_initialize_low_level.s.
418
419
4207.3.1 Managed FIQ Interrupts
421
422Full ThreadX management of FIQ interrupts is provided if the ThreadX sources
423are built with the TX_ENABLE_FIQ_SUPPORT defined. If the library is built
424this way, the FIQ interrupt handlers are very similar to the IRQ interrupt
425handlers defined previously. The following is default FIQ handler
426defined in tx_initialize_low_level.s:
427
428
429 EXPORT __tx_fiq_handler
430 EXPORT __tx_fiq_processing_return
431__tx_fiq_handler
432;
433; /* Jump to fiq context save to save system context. */
434 B _tx_thread_fiq_context_save
435__tx_fiq_processing_return:
436;
437; /* At this point execution is still in the FIQ mode. The CPSR, point of
438; interrupt, and all C scratch registers are available for use. */
439;
440; /* Application FIQ handlers can be called here! */
441;
442; /* Jump to fiq context restore to restore system context. */
443 B _tx_thread_fiq_context_restore
444
445
4467.3.1.1 Nested FIQ Support
447
448By default, nested FIQ interrupt support is not enabled. To enable nested
449FIQ support, the entire library should be built with TX_ENABLE_FIQ_NESTING
450defined. With this defined, two new FIQ interrupt management services are
451available, namely _tx_thread_fiq_nesting_start and _tx_thread_fiq_nesting_end.
452These function should be called between the FIQ context save and restore
453calls.
454
455Execution between the calls to _tx_thread_fiq_nesting_start and
456_tx_thread_fiq_nesting_end is enabled for FIQ nesting. This is achieved
457by switching from FIQ mode to SYS mode and enabling FIQ interrupts.
458The SYS mode stack is used during the SYS mode operation, which was
459setup in tx_initialize_low_level.s. When nested FIQ interrupts are no longer required,
460calling the _tx_thread_fiq_nesting_end service disables nesting by disabling
461FIQ interrupts and switching back to FIQ mode in preparation for the FIQ
462context restore service.
463
464The following is an example of enabling FIQ nested interrupts in the
465typical FIQ handler:
466
467
468 EXPORT __tx_fiq_handler
469 EXPORT __tx_fiq_processing_return
470__tx_fiq_handler
471;
472; /* Jump to fiq context save to save system context. */
473 B _tx_thread_fiq_context_save
474__tx_fiq_processing_return
475;
476; /* At this point execution is still in the FIQ mode. The CPSR, point of
477; interrupt, and all C scratch registers are available for use. */
478;
479; /* Enable nested FIQ interrupts. NOTE: Since this service returns
480; with FIQ interrupts enabled, all FIQ interrupt sources must be
481; cleared prior to calling this service. */
482 BL _tx_thread_fiq_nesting_start
483;
484; /* Application FIQ handlers can be called here! */
485;
486; /* Disable nested FIQ interrupts. The mode is switched back to
487; FIQ mode and FIQ interrupts are disable upon return. */
488 BL _tx_thread_fiq_nesting_end
489;
490; /* Jump to fiq context restore to restore system context. */
491 B _tx_thread_fiq_context_restore
492
493
4948. ThreadX Timer Interrupt
495
496ThreadX requires a periodic interrupt source to manage all time-slicing,
497thread sleeps, timeouts, and application timers. Without such a timer
498interrupt source, these services are not functional. However, all other
499ThreadX services are operational without a periodic timer source.
500
501To add the timer interrupt processing, simply make a call to
502_tx_timer_interrupt in the IRQ processing. An example of this can be
503found in the file tx_initialize_low_level.s in the Integrator sub-directories.
504
505
5069. Thumb/Cortex-A7 Mixed Mode
507
508By default, ThreadX is setup for running in Cortex-A7 32-bit mode. This is
509also true for the demonstration system. It is possible to build any
510ThreadX file and/or the application in Thumb mode. If any Thumb code
511is used the entire ThreadX source- both C and assembly - should be built
512with the "-apcs /interwork" option.
513
51410. VFP Support
515
516By default, VFP support is disabled for each thread. If saving the context of the VFP registers
517is needed, the following API call must be made from the context of the application thread - before
518the VFP usage:
519
520void tx_thread_vfp_enable(void);
521
522After this API is called in the application, VFP registers will be saved/restored for this thread if it
523is preempted via an interrupt. All other suspension of the this thread will not require the VFP registers
524to be saved/restored.
525
526To disable VFP register context saving, simply call the following API:
527
528void tx_thread_vfp_disable(void);
529
530
53111. 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 6.1 version for Cortex-A7 using AC5 tools.
541
542
543Copyright(c) 1996-2020 Microsoft Corporation
544
545
546https://azure.com/rtos
547
548
