1 Microsoft's Azure RTOS ThreadX for Cortex-R5 2 3 Using ARM Compiler 6 & DS 4 51. Import the ThreadX Projects 6 7In order to build the ThreadX library and the ThreadX demonstration, first import 8the 'tx' and 'sample_threadx' projects (located in the "example_build" directory) 9into your DS workspace. 10 11 122. Building the ThreadX run-time Library 13 14Building the ThreadX library is easy; simply right-click the Eclipse project 15"tx" and then select the "Build Project" button. You should now observe the compilation 16and assembly of the ThreadX library. This project build produces the ThreadX 17library file tx.a. 18 19 203. Demonstration System 21 22The ThreadX demonstration is designed to execute under the DS debugger on the 23VE_Cortex-R5 Bare Metal simulator. 24 25Building the demonstration is easy; simply right-click the Eclipse project 26"sample_threadx" and then select the "Build Project" button. You should now observe 27the compilation and assembly of the ThreadX demonstration. This project build produces 28the ThreadX library file sample_threadx.axf. Next, expand the demo ThreadX project folder 29in the Project Explorer window, right-click on the 'cortex-r5_tx.launch' file, click 30'Debug As', and then click 'cortex-r5_tx' from the submenu. This will cause the 31debugger to load the sample_threadx.axf ELF file and run to main. You are now ready 32to execute the ThreadX demonstration. 33 34 354. System Initialization 36 37The entry point in ThreadX for the Cortex-R5 using ARM tools is at label 38"Vectors". This is defined within startup.S in the sample_threadx project. In addition, 39this is where all static and global pre-set C variable initialization processing 40takes place. 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 505. Register Usage and Stack Frames 51 52The AC6 compiler assumes that registers r0-r3 (a1-a4) and r12 (ip) are scratch 53registers for each function. All other registers used by a C function must 54be preserved by the function. ThreadX takes advantage of this in situations 55where a context switch happens as a result of making a ThreadX service call 56(which is itself a C function). In such cases, the saved context of a thread 57is only the non-scratch registers. 58 59The following defines the saved context stack frames for context switches 60that occur as a result of interrupt handling or from thread-level API calls. 61All suspended threads have one of these two types of stack frames. The top 62of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the 63associated thread control block TX_THREAD. 64 65 66 67 Offset Interrupted Stack Frame Non-Interrupt Stack Frame 68 69 0x00 1 0 70 0x04 CPSR CPSR 71 0x08 r0 (a1) r4 (v1) 72 0x0C r1 (a2) r5 (v2) 73 0x10 r2 (a3) r6 (v3) 74 0x14 r3 (a4) r7 (v4) 75 0x18 r4 (v1) r8 (v5) 76 0x1C r5 (v2) r9 (v6) 77 0x20 r6 (v3) r10 (v7) 78 0x24 r7 (v4) r11 (fp) 79 0x28 r8 (v5) r14 (lr) 80 0x2C r9 (v6) 81 0x30 r10 (v7) 82 0x34 r11 (fp) 83 0x38 r12 (ip) 84 0x3C r14 (lr) 85 0x40 PC 86 87 886. Improving Performance 89 90The distribution version of ThreadX is built without any compiler 91optimizations. This makes it easy to debug because you can trace or set 92 93In addition, you can eliminate the ThreadX basic API error checking by 94compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING 95defined. 96 97 987. Interrupt Handling 99 100ThreadX provides complete and high-performance interrupt handling for Cortex-R5 101targets. There are a certain set of requirements that are defined in the 102following sub-sections: 103 104 1057.1 Vector Area 106 107The Cortex-R5 vectors start at address zero. The demonstration system startup 108reset.S file contains the vectors and is loaded at address zero. On actual 109hardware platforms, this area might have to be copied to address 0. 110 111 1127.2 IRQ ISRs 113 114ThreadX fully manages standard and vectored IRQ interrupts. ThreadX also supports 115nested IRQ interrupts. The following sub-sections define the IRQ capabilities. 116 117 1187.2.1 Standard IRQ ISRs 119 120The standard ARM IRQ mechanism has a single interrupt vector at address 0x18. This IRQ 121interrupt is managed by the __tx_irq_handler code in tx_initialize_low_level. The following 122is the default IRQ handler defined in tx_initialize_low_level.S: 123 124 .global __tx_irq_handler 125 .global __tx_irq_processing_return 126__tx_irq_handler: 127@ 128@ /* Jump to context save to save system context. */ 129 B _tx_thread_context_save @ Jump to the context save 130__tx_irq_processing_return: 131@ 132@ /* At this point execution is still in the IRQ mode. The CPSR, point of 133@ interrupt, and all C scratch registers are available for use. Note 134@ that IRQ interrupts are still disabled upon return from the context 135@ save function. */ 136@ 137@ /* Application ISR call(s) go here! */ 138@ 139@ /* Jump to context restore to restore system context. */ 140 B _tx_thread_context_restore 141 142 1437.2.2 Vectored IRQ ISRs 144 145The vectored ARM IRQ mechanism has multiple interrupt vectors at addresses specified 146by the particular implementation. The following is an example IRQ handler defined in 147tx_initialize_low_level.S: 148 149 .global __tx_irq_example_handler 150__tx_irq_example_handler: 151@ 152@ /* Call context save to save system context. */ 153 154 STMDB sp!, {r0-r3} @ Save some scratch registers 155 MRS r0, SPSR @ Pickup saved SPSR 156 SUB lr, lr, #4 @ Adjust point of interrupt 157 STMDB sp!, {r0, r10, r12, lr} @ Store other scratch registers 158 BL _tx_thread_vectored_context_save @ Call the vectored IRQ context save 159@ 160@ /* At this point execution is still in the IRQ mode. The CPSR, point of 161@ interrupt, and all C scratch registers are available for use. Note 162@ that IRQ interrupts are still disabled upon return from the context 163@ save function. */ 164@ 165@ /* Application ISR call goes here! */ 166@ 167@ /* Jump to context restore to restore system context. */ 168 B _tx_thread_context_restore 169 170 1717.2.3 Nested IRQ Support 172 173By default, nested IRQ interrupt support is not enabled. To enable nested 174IRQ support, the entire library should be built with TX_ENABLE_IRQ_NESTING 175defined. With this defined, two new IRQ interrupt management services are 176available, namely _tx_thread_irq_nesting_start and _tx_thread_irq_nesting_end. 177These function should be called between the IRQ context save and restore 178calls. 179 180Execution between the calls to _tx_thread_irq_nesting_start and 181_tx_thread_irq_nesting_end is enabled for IRQ nesting. This is achieved 182by switching from IRQ mode to SYS mode and enabling IRQ interrupts. 183The SYS mode stack is used during the SYS mode operation, which was 184setup in tx_initialize_low_level.S. When nested IRQ interrupts are no 185longer required, calling the _tx_thread_irq_nesting_end service disables 186nesting by disabling IRQ interrupts and switching back to IRQ mode in 187preparation for the IRQ context restore service. 188 189The following is an example of enabling IRQ nested interrupts in a standard 190IRQ handler: 191 192 .global __tx_irq_handler 193 .global __tx_irq_processing_return 194__tx_irq_handler: 195@ 196@ /* Jump to context save to save system context. */ 197 B _tx_thread_context_save 198__tx_irq_processing_return: 199@ 200@ /* Enable nested IRQ interrupts. NOTE: Since this service returns 201@ with IRQ interrupts enabled, all IRQ interrupt sources must be 202@ cleared prior to calling this service. */ 203 BL _tx_thread_irq_nesting_start 204@ 205@ /* Application ISR call(s) go here! */ 206@ 207@ /* Disable nested IRQ interrupts. The mode is switched back to 208@ IRQ mode and IRQ interrupts are disable upon return. */ 209 BL _tx_thread_irq_nesting_end 210@ 211@ /* Jump to context restore to restore system context. */ 212 B _tx_thread_context_restore 213 214 2157.3 FIQ Interrupts 216 217By default, FIQ interrupts are left alone by ThreadX. Of course, this 218means that the application is fully responsible for enabling the FIQ interrupt 219and saving/restoring any registers used in the FIQ ISR processing. To globally 220enable FIQ interrupts, the application should enable FIQ interrupts at the 221beginning of each thread or before any threads are created in tx_application_define. 222In addition, the application must ensure that no ThreadX service calls are made 223from default FIQ ISRs, which is located in tx_initialize_low_level.S. 224 225 2267.3.1 Managed FIQ Interrupts 227 228Full ThreadX management of FIQ interrupts is provided if the ThreadX sources 229are built with the TX_ENABLE_FIQ_SUPPORT defined. If the library is built 230this way, the FIQ interrupt handlers are very similar to the IRQ interrupt 231handlers defined previously. The following is default FIQ handler 232defined in tx_initialize_low_level.S: 233 234 235 .global __tx_fiq_handler 236 .global __tx_fiq_processing_return 237__tx_fiq_handler: 238@ 239@ /* Jump to fiq context save to save system context. */ 240 B _tx_thread_fiq_context_save 241__tx_fiq_processing_return: 242@ 243@ /* At this point execution is still in the FIQ mode. The CPSR, point of 244@ interrupt, and all C scratch registers are available for use. */ 245@ 246@ /* Application FIQ handlers can be called here! */ 247@ 248@ /* Jump to fiq context restore to restore system context. */ 249 B _tx_thread_fiq_context_restore 250 251 2527.3.1.1 Nested FIQ Support 253 254By default, nested FIQ interrupt support is not enabled. To enable nested 255FIQ support, the entire library should be built with TX_ENABLE_FIQ_NESTING 256defined. With this defined, two new FIQ interrupt management services are 257available, namely _tx_thread_fiq_nesting_start and _tx_thread_fiq_nesting_end. 258These function should be called between the FIQ context save and restore 259calls. 260 261Execution between the calls to _tx_thread_fiq_nesting_start and 262_tx_thread_fiq_nesting_end is enabled for FIQ nesting. This is achieved 263by switching from FIQ mode to SYS mode and enabling FIQ interrupts. 264The SYS mode stack is used during the SYS mode operation, which was 265setup in tx_initialize_low_level.S. When nested FIQ interrupts are no longer required, 266calling the _tx_thread_fiq_nesting_end service disables nesting by disabling 267FIQ interrupts and switching back to FIQ mode in preparation for the FIQ 268context restore service. 269 270The following is an example of enabling FIQ nested interrupts in the 271typical FIQ handler: 272 273 274 .global __tx_fiq_handler 275 .global __tx_fiq_processing_return 276__tx_fiq_handler: 277@ 278@ /* Jump to fiq context save to save system context. */ 279 B _tx_thread_fiq_context_save 280__tx_fiq_processing_return: 281@ 282@ /* At this point execution is still in the FIQ mode. The CPSR, point of 283@ interrupt, and all C scratch registers are available for use. */ 284@ 285@ /* Enable nested FIQ interrupts. NOTE: Since this service returns 286@ with FIQ interrupts enabled, all FIQ interrupt sources must be 287@ cleared prior to calling this service. */ 288 BL _tx_thread_fiq_nesting_start 289@ 290@ /* Application FIQ handlers can be called here! */ 291@ 292@ /* Disable nested FIQ interrupts. The mode is switched back to 293@ FIQ mode and FIQ interrupts are disable upon return. */ 294 BL _tx_thread_fiq_nesting_end 295@ 296@ /* Jump to fiq context restore to restore system context. */ 297 B _tx_thread_fiq_context_restore 298 299 3008. ThreadX Timer Interrupt 301 302ThreadX requires a periodic interrupt source to manage all time-slicing, 303thread sleeps, timeouts, and application timers. Without such a timer 304interrupt source, these services are not functional but the remainder of 305ThreadX will still run. 306 307To add the timer interrupt processing, simply make a call to 308_tx_timer_interrupt in the IRQ processing. An example of this can be 309found in the file tx_initialize_low_level.S for the demonstration system. 310 311 3129. Revision History 313 314For generic code revision information, please refer to the readme_threadx_generic.txt 315file, which is included in your distribution. The following details the revision 316information associated with this specific port of ThreadX: 317 31804-02-2021 Release 6.1.6 changes: 319 tx_port.h Updated macro definition 320 32109-30-2020 Initial ThreadX 6.1 version for Cortex-R5 using AC6 tools. 322 323 324Copyright(c) 1996-2020 Microsoft Corporation 325 326 327https://azure.com/rtos 328 329
