1 Microsoft's Azure RTOS ThreadX for Cortex-A7 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-A7 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-A7 simulator. 29 30 313. System Initialization 32 33The entry point in ThreadX for the Cortex-A7 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-A7 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-A7 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-A7 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-A7 Mixed Mode 492 493By default, ThreadX is setup for running in Cortex-A7 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-A7 using IAR's ARM tools. 541 542 543Copyright(c) 1996-2020 Microsoft Corporation 544 545 546https://azure.com/rtos 547 548
