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