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