readme_threadx.txt
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
