1 Microsoft's Azure RTOS ThreadX for Cortex-R4 2 3 Thumb & 32-bit Mode 4 5 Using ARM Compiler 6 & DS 6 71. Import the ThreadX Projects 8 9In order to build the ThreadX library and the ThreadX demonstration, first move 10the project folders into your DS workspace directory. The project folders are 11named 'tx' and 'sample_threadx' and are located in the installation directory. 12 13Now that the projects are in the workspace directory, import them into DS by 14doing the following for each project: 15 16 1. Click 'File -> Import -> Existing Projects into Workspace' 17 2. Set the root directory the project i.e. the 'tx' or 'sample_threadx' directory 18 3. Click 'Finish' 19 20Note: the projects were made using DS-5, so DS will prompt you to migrate the projects. 21This is expected, so please do so. 22 23 242. Building the ThreadX run-time Library 25 26Building the ThreadX library is easy; simply right-click the Eclipse project 27"tx" and then select the "Build Project" button. You should now observe the compilation 28and assembly of the ThreadX library. This project build produces the ThreadX 29library file tx.a. 30 31 323. Demonstration System 33 34The ThreadX demonstration is designed to execute under the DS-5 debugger on the 35VE_Cortex-R4 Bare Metal simulator. 36 37Building the demonstration is easy; simply right-click the Eclipse project 38"sample_threadx" and then select the "Build Project" button. You should now observe 39the compilation and assembly of the ThreadX demonstration. This project build produces 40the ThreadX library file sample_threadx.axf. Next, expand the demo ThreadX project folder 41in the Project Explorer window, right-click on the 'cortex-r4_tx.launch' file, click 42'Debug As', and then click 'cortex-r4_tx' from the submenu. This will cause the 43debugger to load the sample_threadx.axf ELF file and run to main. You are now ready 44to execute the ThreadX demonstration. 45 46 474. System Initialization 48 49The entry point in ThreadX for the Cortex-R4 using ARM tools is at label 50"Vectors". This is defined within startup.S in the sample_threadx project. In addition, 51this is where all static and global pre-set C variable initialization processing 52takes place. 53 54The ThreadX tx_initialize_low_level.s file is responsible for determining the 55first available RAM address for use by the application, which is supplied as the 56sole input parameter to your application definition function, tx_application_define. 57 58 595. Register Usage and Stack Frames 60 61The ARM compiler assumes that registers r0-r3 (a1-a4) and r12 (ip) are scratch 62registers for each function. All other registers used by a C function must 63be preserved by the function. ThreadX takes advantage of this in situations 64where a context switch happens as a result of making a ThreadX service call 65(which is itself a C function). In such cases, the saved context of a thread 66is only the non-scratch registers. 67 68The following defines the saved context stack frames for context switches 69that occur as a result of interrupt handling or from thread-level API calls. 70All suspended threads have one of these two types of stack frames. The top 71of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the 72associated thread control block TX_THREAD. 73 74 75 76 Offset Interrupted Stack Frame Non-Interrupt Stack Frame 77 78 0x00 1 0 79 0x04 CPSR CPSR 80 0x08 r0 (a1) r4 (v1) 81 0x0C r1 (a2) r5 (v2) 82 0x10 r2 (a3) r6 (v3) 83 0x14 r3 (a4) r7 (v4) 84 0x18 r4 (v1) r8 (v5) 85 0x1C r5 (v2) r9 (v6) 86 0x20 r6 (v3) r10 (v7) 87 0x24 r7 (v4) r11 (fp) 88 0x28 r8 (v5) r14 (lr) 89 0x2C r9 (v6) 90 0x30 r10 (v7) 91 0x34 r11 (fp) 92 0x38 r12 (ip) 93 0x3C r14 (lr) 94 0x40 PC 95 96 976. Improving Performance 98 99The distribution version of ThreadX is built without any compiler 100optimizations. This makes it easy to debug because you can trace or set 101breakpoints inside of ThreadX itself. Of course, this costs some 102performance. To make it run faster, you can change the build_threadx.bat file to 103remove the -g option and enable all compiler optimizations. 104 105In addition, you can eliminate the ThreadX basic API error checking by 106compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING 107defined. 108 109 1107. Interrupt Handling 111 112ThreadX provides complete and high-performance interrupt handling for Cortex-R4 113targets. There are a certain set of requirements that are defined in the 114following sub-sections: 115 116 1177.1 Vector Area 118 119The Cortex-R4 vectors start at address zero. The demonstration system startup.S 120file contains the vectors and is loaded at address zero. On actual hardware platforms, 121this area might have to be copied to address 0. 122 123 1247.2 IRQ ISRs 125 126ThreadX fully manages standard and vectored IRQ interrupts. ThreadX also supports nested 127IRQ interrupts. The following sub-sections define the IRQ capabilities. 128 129 1307.2.1 Standard IRQ ISRs 131 132The standard ARM IRQ mechanism has a single interrupt vector at address 0x18. This IRQ 133interrupt is managed by the __tx_irq_handler code in tx_initialize_low_level. The following 134is the default IRQ handler defined in tx_initialize_low_level.s: 135 136 .global __tx_irq_handler 137 .type __tx_irq_handler, %function 138__tx_irq_handler: 139 140 /* Jump to context save to save system context. */ 141 B _tx_thread_context_save 142 143 ... 144 145 /* At this point execution is still in the IRQ mode. The CPSR, point of 146 interrupt, and all C scratch registers are available for use. In 147 addition, IRQ interrupts may be re-enabled - with certain restrictions - 148 if nested IRQ interrupts are desired. Interrupts may be re-enabled over 149 small code sequences where lr is saved before enabling interrupts and 150 restored after interrupts are again disabled. */ 151 152 /* Application IRQ handlers can be called here! */ 153 154 ... 155 156 /* Jump to context restore to restore system context. */ 157 B _tx_thread_context_restore 158 1597.2.2 Vectored IRQ ISRs 160 161The vectored ARM ISR mechanism has multiple interrupt vectors at addresses specified 162by the particular implementation. The following is an example ISR handler defined in 163tx_initialize_low_level.s: 164 165 .global __tx_example_vectored_irq_handler 166 .type __tx_example_vectored_irq_handler, %function 167__tx_example_vectored_irq_handler: 168 169 170 /* Save initial context and call context save to prepare for 171 vectored ISR execution. */ 172 173 STMDB sp!, {r0-r3} // Save some scratch registers 174 MRS r0, SPSR // Pickup saved SPSR 175 SUB lr, lr, #4 // Adjust point of interrupt 176 STMDB sp!, {r0, r10, r12, lr} // Store other scratch registers 177 BL _tx_thread_vectored_context_save // Vectored context save 178 179 ... 180 181 /* At this point execution is still in the IRQ mode. The CPSR, point of 182 interrupt, and all C scratch registers are available for use. In 183 addition, IRQ interrupts may be re-enabled - with certain restrictions - 184 if nested IRQ interrupts are desired. Interrupts may be re-enabled over 185 small code sequences where lr is saved before enabling interrupts and 186 restored after interrupts are again disabled. */ 187 188 /* Application IRQ handlers can be called here! */ 189 190 ... 191 192 /* Jump to context restore to restore system context. */ 193 B _tx_thread_context_restore 194 195 1967.2.3 Nested IRQ Support 197 198By default, nested IRQ interrupt support is not enabled. To enable nested 199IRQ support, the entire library should be built with TX_ENABLE_IRQ_NESTING 200defined. With this defined, two new IRQ interrupt management services are 201available, namely _tx_thread_irq_nesting_start and _tx_thread_irq_nesting_end. 202These function should be called between the IRQ context save and restore 203calls. 204 205Execution between the calls to _tx_thread_irq_nesting_start and 206_tx_thread_irq_nesting_end is enabled for IRQ nesting. This is achieved 207by switching from IRQ mode to SYS mode and enabling IRQ interrupts. 208The SYS mode stack is used during the SYS mode operation, which was 209setup in tx_initialize_low_level.s. When nested IRQ interrupts are no longer required, 210calling the _tx_thread_irq_nesting_end service disables nesting by disabling 211IRQ interrupts and switching back to IRQ mode in preparation for the IRQ 212context restore service. 213 214The following is an example of enabling IRQ nested interrupts in a standard 215IRQ handler: 216 217 .global __tx_irq_handler 218 .type __tx_irq_handler, %function 219 .global __tx_irq_processing_return 220 .type __tx_irq_processing_return, %function 221__tx_irq_handler: 222 223 /* Jump to context save to save system context. */ 224 B _tx_thread_context_save 225__tx_irq_processing_return: 226 227 ... 228 229 /* Interrupt nesting is allowed after calling _tx_thread_irq_nesting_start 230 from IRQ mode with interrupts disabled. This routine switches to the 231 system mode and returns with IRQ interrupts enabled. */ 232 233 /* NOTE: It is very important to ensure all IRQ interrupts are cleared 234 prior to enabling nested IRQ interrupts. */ 235 BL _tx_thread_irq_nesting_start 236 237 /* Application IRQ handlers can be called here! */ 238 239 ... 240 241 /* If interrupt nesting was started earlier, the end of interrupt nesting 242 service must be called before returning to _tx_thread_context_restore. 243 This routine returns in processing in IRQ mode with interrupts disabled. */ 244 BL _tx_thread_irq_nesting_end 245 246 /* Jump to context restore to restore system context. */ 247 B _tx_thread_context_restore 248 249 2507.3 FIQ Interrupts 251 252By default, Cortex-R4 FIQ interrupts are left alone by ThreadX. Of course, this 253means that the application is fully responsible for enabling the FIQ interrupt 254and saving/restoring any registers used in the FIQ ISR processing. To globally 255enable FIQ interrupts, the application should enable FIQ interrupts at the 256beginning of each thread or before any threads are created in tx_application_define. 257In addition, the application must ensure that no ThreadX service calls are made 258from default FIQ ISRs, which is located in tx_initialize_low_level.s. 259 260 2617.3.1 Managed FIQ Interrupts 262 263Full ThreadX management of FIQ interrupts is provided if the ThreadX sources 264are built with the TX_ENABLE_FIQ_SUPPORT defined. If the library is built 265this way, the FIQ interrupt handlers are very similar to the IRQ interrupt 266handlers defined previously. The following is default FIQ handler 267defined in tx_initialize_low_level.s: 268 269 270 .global __tx_fiq_handler 271 .type __tx_fiq_handler, %function 272 .global __tx_fiq_processing_return 273 .type __tx_fiq_processing_return, %function 274__tx_fiq_handler: 275 276 /* Jump to fiq context save to save system context. */ 277 B _tx_thread_fiq_context_save 278__tx_fiq_processing_return: 279 280 /* At this point execution is still in the FIQ mode. The CPSR, point of 281 interrupt, and all C scratch registers are available for use. */ 282 283 /* Application FIQ handlers can be called here! */ 284 285 /* Jump to fiq context restore to restore system context. */ 286 B _tx_thread_fiq_context_restore 287 288 2897.3.1.1 Nested FIQ Support 290 291By default, nested FIQ interrupt support is not enabled. To enable nested 292FIQ support, the entire library should be built with TX_ENABLE_FIQ_NESTING 293defined. With this defined, two new FIQ interrupt management services are 294available, namely _tx_thread_fiq_nesting_start and _tx_thread_fiq_nesting_end. 295These function should be called between the FIQ context save and restore 296calls. 297 298Execution between the calls to _tx_thread_fiq_nesting_start and 299_tx_thread_fiq_nesting_end is enabled for FIQ nesting. This is achieved 300by switching from FIQ mode to SYS mode and enabling FIQ interrupts. 301The SYS mode stack is used during the SYS mode operation, which was 302setup in tx_initialize_low_level.s. When nested FIQ interrupts are no longer required, 303calling the _tx_thread_fiq_nesting_end service disables nesting by disabling 304FIQ interrupts and switching back to FIQ mode in preparation for the FIQ 305context restore service. 306 307The following is an example of enabling FIQ nested interrupts in the 308typical FIQ handler: 309 310 311 .global __tx_fiq_handler 312 .type __tx_fiq_handler, %function 313 .global __tx_fiq_processing_return 314 .type __tx_fiq_processing_return, %function 315__tx_fiq_handler: 316 317 /* Jump to fiq context save to save system context. */ 318 B _tx_thread_fiq_context_save 319__tx_fiq_processing_return: 320 321 /* At this point execution is still in the FIQ mode. The CPSR, point of 322 interrupt, and all C scratch registers are available for use. */ 323 324 /* Enable nested FIQ interrupts. NOTE: Since this service returns 325 with FIQ interrupts enabled, all FIQ interrupt sources must be 326 cleared prior to calling this service. */ 327 BL _tx_thread_fiq_nesting_start 328 329 /* Application FIQ handlers can be called here! */ 330 331 /* Disable nested FIQ interrupts. The mode is switched back to 332 FIQ mode and FIQ interrupts are disable upon return. */ 333 BL _tx_thread_fiq_nesting_end 334 335 /* Jump to fiq context restore to restore system context. */ 336 B _tx_thread_fiq_context_restore 337 338 3398. ThreadX Timer Interrupt 340 341ThreadX requires a periodic interrupt source to manage all time-slicing, 342thread sleeps, timeouts, and application timers. Without such a timer 343interrupt source, these services are not functional. However, all other 344ThreadX services are operational without a periodic timer source. 345 346To add the timer interrupt processing, simply make a call to 347_tx_timer_interrupt in the IRQ processing. An example of this can be 348found in the file tx_initialize_low_level.s in the Integrator sub-directories. 349 350 3519. Thumb/Cortex-R4 Mixed Mode 352 353By default, ThreadX is setup for running in Cortex-R4 32-bit mode. This is 354also true for the demonstration system. It is possible to build any 355ThreadX file and/or the application in Thumb mode. To build ThreadX 356assembly files in Thumb mode, define TX_THUMB_MODE. 357 358 35910. VFP Support 360 361By default, VFP support is disabled for each thread. If saving the context of the VFP registers 362is needed, the following API call must be made from the context of the application thread - before 363the VFP usage: 364 365void tx_thread_vfp_enable(void); 366 367After this API is called in the application, VFP registers will be saved/restored for this thread if it 368is preempted via an interrupt. All other suspension of the this thread will not require the VFP registers 369to be saved/restored. 370 371To disable VFP register context saving, simply call the following API: 372 373void tx_thread_vfp_disable(void); 374 375Note that if VFP registers are used in ISRs, the save/restore of VFP registers must be done by the ISR. 376In addition, the startup code is responsible for enabling VFP usage. 377 378 37911. Revision History 380 381For generic code revision information, please refer to the readme_threadx_generic.txt 382file, which is included in your distribution. The following details the revision 383information associated with this specific port of ThreadX: 384 38504-02-2021 Release 6.1.6 changes: 386 tx_port.h Updated macro definition 387 38809-30-2020 Initial ThreadX 6.1 version for Cortex-R4 using ARM tools. 389 390 391Copyright(c) 1996-2020 Microsoft Corporation 392 393 394https://azure.com/rtos 395 396
