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