1 Microsoft's Azure RTOS ThreadX for ThreadX SMP for MIPS32 interAptiv/VPE 2 3 Using the Green Hills Software Tools 4 51. Installation 6 7ThreadX for the MIPS32 interAptiv is delivered on a single CD-ROM compatible disk. 8The entire distribution can be found in the sub-directory: 9 10\threadx 11 12To install ThreadX to your hard-disk, either run the supplied installer 13program Setup.exe or copy the distribution from the CD manually. 14 15To copy the ThreadX distribution manually, make a threadx directory on your 16hard-disk (we recommend C:\threadx\mips32_interaptiv\green) and copy all the contents 17of the threadx sub-directory on the distribution disk. The following 18is an example MS-DOS copy command from the distribution directory 19(assuming source is d: and c: is your hard-drive): 20 21 22d:\threadx> xcopy /S *.* c:\threadx\mips32_interaptiv\green 23 24 252. Open the ThreadX Project Workspace 26 27In order to build the ThreadX library and the ThreadX demonstration first 28load the ThreadX project workspace threadx_project_workspace.gpj, which is 29located inside your ThreadX directory: 30 31C:\threadx\mips32_interaptiv\green\threadx_project_workspace.gpj 32 33 343. Building the ThreadX run-time Library 35 36Building the ThreadX library is easy; simply select the MULTI project file 37tx.gpj and then select the build button. You should now observe the 38compilation and assembly of the ThreadX library. This project build produces 39the ThreadX library file tx.a. 40 41 424. Demonstration System 43 44The ThreadX demonstration is designed to execute under the MULTI environment 45on the MIPS interAptiv MALTA board. By default, the demonstration is setup for a 463 core (6 VPE) interAptiv configuration. The instructions that follow describe 47how to get the ThreadX evaluation running under the MIPS interAptiv MALTA board. 48 49Building the demonstration is easy; simply select the MULTI project file 50demo_threadx.gpj. At this point, select the "Project Build" button and observe 51the compilation, assembly, and linkage of the ThreadX demonstration application. 52 53After the demonstration is built, follow these steps to download and execute the 54ThreadX SMP interAptiv demonstration: 55 56A. Select the "demo_threadx_ram_interAptiv_3c2v4t.ghsmc" multi-core configuration 57 file and then the debug button (or [F5] key). You should observe a debugger 58 window with 6 unconnected demo_threadx.elf executables. 59 60B. Select the first of the 6 unconnected demo_threadx.elf images and click the 61 "prepare target" button (or right-click -> prepare target). You should now 62 get a "Connection Chooser" dialog box. 63 64C. Connect to the "GHS_Probe_interAptive_3c2v4t" target. You should observe the 65 "prepare target" dialog. 66 67D. In the "prepare target" dialog, select "download". You should now see a 68 connection to 12 threads, as follows: 69 70 Id 0 -> c0v0t0 boot_mips.elf @ _start ) (code and data are loaded on Id 0) 71 Id 1 -> c0v1t1 boot_mips.elf @ 0xdeadbeef (scripted indication of uninitialized vpe1) 72 Id 2 -> c0v1t2 (not used) 73 Id 3 -> c0v1t3 (not used) 74 Id 4 -> c1v0t0 boot_mips.elf @ _start (scripted init triggered by load on Id 0) 75 Id 5 -> c1v1t1 boot_mips.elf @ 0xdeadbeef (scripted indication of uninitialized vpe1) 76 Id 6 -> c1v1t2 (not used) 77 Id 7 -> c1v1t3 (not used) 78 Id 8 -> c2v0t0 boot_mips.elf @ _start (scripted init triggered by load on Id 0) 79 Id 9 -> c2v1t1 boot_mips.elf @ 0xdeadbeef (scripted indication of uninitialized vpe1) 80 Id 10 -> c2v1t2 (not used) 81 Id 11 -> c2v1t3 (not used) 82 83E. To start execution, select and run Id 0, Id 4, and Id 8. All the cores are now 84 running and you should observe messages being displayed on the MALTA board. 85 86 875. EventAnalyzer Demonstration 88 89To build a demonstration system that also logs events for the MULTI EventAnalyzer, 90perform the same steps as the regular demo, except build the ThreadX library with 91txe.gpj file and use the demo_threadx_el.gpj build file to build the demonstration. 92The resulting image will log all system events, which can then be displayed by the 93MULTI EventAnalyzer. 94 95 966. System Initialization 97 98The system entry point using the Green Hills tools is at the label _start. 99This is defined within the start.mip file supplied by MIPS. In addition, 100this is where all static and global preset C variable initialization 101processing is called from. 102 103Once the startup function finishes, main is called, which is also where ThreadX 104initialization takes place. The main initialization function for ThreadX is 105_tx_initialize_low_level and is located in the file tx_initialize_low_level.mip. 106This function is responsible for setting up various system data structures, 107interrupt vectors, and the periodic timer interrupt source of ThreadX. 108 109In addition, _tx_initialize_low_level determines where the first available 110RAM memory address is located. This address is supplied to tx_application_define. 111 112By default, the first available RAM memory address is assumed to start at the 113beginning of the ThreadX section .free_mem. If changes are made to the 114demo_threadx.ld file, the .free_mem section should remain the last allocated 115section in the main RAM area. The starting address of this section is passed 116to tx_application_define. 117 118 1197. User defines 120 121Please reference the ThreadX_SMP_User_Guide.pdf for details on build options. 122 123 1248. Register Usage and Stack Frames 125 126The Green Hills MIPS compiler assumes that registers t0-t9 ($8-$15, $24, $25) 127are scratch registers for each function. All other registers used by a 128C function must be preserved by the function. ThreadX takes advantage 129of this in situations where a context switch happens as a result of making a 130ThreadX service call (which is itself a C function). In such cases, the 131saved context of a thread is only the non-scratch registers. 132 133The following defines the saved context stack frames for context switches 134that occur as a result of interrupt handling or from thread-level API calls. 135All suspended threads have one of these two types of stack frames. The top 136of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the 137associated thread control block TX_THREAD. 138 139 140 141 Offset Interrupted Stack Frame Non-Interrupt Stack Frame 142 143 0x000 1 0 144 0x004 s8 ($30) s8 ($30) 145 0x008 s7 ($23) s7 ($23) 146 0x00C s6 ($22) s6 ($22) 147 0x010 s5 ($21) s5 ($21) 148 0x014 s4 ($20) s4 ($20) 149 0x018 s3 ($19) s3 ($19) 150 0x01C s2 ($18) s2 ($18) 151 0x020 s1 ($17) s1 ($17) 152 0x024 s0 ($16) s0 ($16) 153 0x028 hi hi 154 0x02C lo lo 155 0x030 t9 ($25) ra ($31) 156 0x034 t8 ($24) SR 157 0x038 t7 ($15) f31 <------------+ 158 0x03C t6 ($14) | 159 0x040 t5 ($13) f30 | 160 0x044 t4 ($12) | 161 0x048 t3 ($11) f29 | 162 0x04C t2 ($10) | 163 0x050 t1 ($9) f28 | 164 0x054 t0 ($8) | 165 0x058 a3 ($7) f27 | 166 0x05C a2 ($6) | 167 0x060 a1 ($5) f26 | 168 0x064 a0 ($4) 169 0x068 v1 ($3) f25 TX_ENABLE_64BIT_FPU_SUPPORT 170 0x06C v0 ($2) 171 0x070 at ($1) f24 | 172 0x074 ra ($31) | 173 0x078 SR f23 | 174 0x07C EPC | 175 0x080 f31 <-----------+ f22 | 176 0x088 f30 | f21 | 177 0x090 f29 | f20 | 178 0x098 f28 | fcr31 <------------+ 179 0x09C | not used 180 0x0A0 f27 | 181 0x0A4 | 182 0x0A8 f26 | 183 0x0AC | 184 0x0B0 f25 | 185 0x0B4 | 186 0x0B8 f24 | 187 0x0BC | 188 0x0C0 f23 | 189 0x0C8 f22 | 190 0x0D0 f21 | 191 0x0D8 f20 | 192 0x0E0 f19 | 193 0x0E8 f18 | 194 0x0F0 f17 195 0x0F8 f16 TX_ENABLE_64BIT_FPU_SUPPORT 196 0x100 f15 197 0x108 f14 | 198 0x110 f13 | 199 0x118 f12 | 200 0x120 f11 | 201 0x128 f10 | 202 0x130 f9 | 203 0x138 f8 | 204 0x140 f7 | 205 0x148 f6 | 206 0x150 f5 | 207 0x158 f4 | 208 0x160 f3 | 209 0x168 f2 | 210 0x170 f1 | 211 0x178 f0 | 212 0x180 fcr31 <-----------+ 213 0x184 not used 214 215 2169. Improving Performance 217 218The distribution version of ThreadX is built without any compiler 219optimizations. This makes it easy to debug because you can trace or set 220breakpoints inside of ThreadX itself. Of course, this costs some 221performance. To make ThreadX run faster, you can change the tx.gpj project 222to disable debug information and enable the desired optimizations. 223 224In addition, you can eliminate the ThreadX basic API error checking by 225compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING 226defined before tx_api.h is included. 227 228 22910. Interrupt Handling 230 231ThreadX provides complete and high-performance interrupt handling for MIPS32 interAptiv 232targets. The general exception handler is at address: 0x80000180 (0xA0000180 non- 233cached). The ThreadX general exception handler is defined in the file 234tx_initialize_low_level.mip at the label _tx_exception_handler. A small piece of 235code to jump to this exception handler is copied to the general exception handler 236address during initialization. 237 23810.1 Application ISRs 239 240Multiple exceptions may be processed with a single execution of the exception 241handler. This is because the Cause register could indicate more than a single 242exception. Processing for each exception is also located in the general 243exception handler that starts at the label: _tx_exception_handler. Application 244ISRs can be added into this handler. 245 246 24711. Theory of Operation - SMP 248 249ThreadX for the MIPS interAptiv brings Symmetric Multi-Processing (SMP) technology to 250the MIPS interAptiv. ThreadX application threads (of varying priority) that are "READY" 251to run are dynamically allocated to VPEs during scheduling, thus taking full 252advantage of all available MIPS interAptiv VPEs. This results in true SMP processing, 253including automatic load balancing of application thread execution across all 254available MIPS interAptiv VPEs. 255 256Initialization is done exclusively in VPE 0, which is the default running VPE 257after reset. The additional VPEs on the interAptiv are initialized by VPE 0 and simply 258wait until VPE 0 completes the initialization before they start running. 259 260During thread execution, multithreading in the MIPS interAptiv is fully enabled. This 261means that application threads may be preempted by higher priority threads, may 262suspend themselves, or may exit the system upon completion of their work. Protection 263between VPEs is accomplished via a conditional load-store structure (see the variable 264_tx_thread_smp_protection and the typedef TX_THREAD_SMP_PROTECT found in tx_thread.h). 265 266All VPEs are eligible to handle interrupts under the direction of the application. The 267ThreadX timer interrupt is by default assigned to VPE 0 for processing. Please see 268the code in tx_timer_interrupt.mip for the implementation. 269 270ThreadX for the MIPS interAptiv also optionally supports the MIPS interAptiv FPU. 271 272The number of VPEs is defined by the compile time constant TX_THREAD_SMP_MAX_CORES. 273By default, this is set to 2 in tx_port.h. It may be changed to support any number 274of cores either in tx_port.h or on the command line via a -D symbol definition. 275 276 27712. Current Limitations 278 2791. Hardware priority assignment for each TC is not setup. 2802. DSP registers are not saved/restored. 281 282 28313. Debug Information 284 285ThreadX SMP for MIPS32 interAptiv has a built-in debug facility to capture SMP scheduling 286information. This is enabled by building the system with TX_THREAD_SMP_DEBUG_ENABLE 287defined. This results in the creation of circular log containing debug information. 288The log is defined in the variable _tx_thread_smp_debug_info_array. 289 290 29114. Revision History 292 293For generic code revision information, please refer to the readme_threadx_generic.txt 294file, which is included in your distribution. The following details the revision 295information associated with this specific port of ThreadX: 296 297 29803-08-2023 Initial ThreadX version 6.2.1 of MIPS32_interAptiv VPE/Green Hills port. 299 300 301Copyright(c) 1996-2020 Microsoft Corporation 302 303https://azure.com/rtos 304
