readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX for ThreadX SMP for MIPS32 interAptiv/VPE
2
3 Using the GNU 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\gnu) 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\gnu
23
24
252. Building the ThreadX run-time Library
26
27First make sure you are in the ThreadX directory you have created on your
28hard-drive. Also, make sure that you have setup your path and other
29environment variables necessary for the GNU development environment.
30
31At this point you may run the build_threadx.bat batch file. This will
32build the ThreadX run-time environment in the ThreadX directory.
33
34C:\threadx\mips32_interaptiv\gnu> build_threadx
35
36You should observe assembly and compilation of a series of ThreadX source
37files. At the end of the batch file, they are all combined into the
38run-time library file: tx.a. This file must be linked with your
39application in order to use ThreadX.
40
41
423. Demonstration System
43
44Building the demonstration is easy; simply execute the build_threadx_demo.bat
45batch file while inside your ThreadX directory on your hard-disk.
46
47C:\threadx\mips32_interaptiv\gnu> build_threadx_demo
48
49You should observe the compilation of demo_threadx.c (which is the demonstration
50application) and linking with tx.a. The resulting file demo_threadx.out is an ELF
51binary file that can be downloaded and executed under simulation or on the MIPS
52MALTA evaluation board.
53
54
554. System Initialization
56
57The system entry point using the GNU tools is at the label _start.
58This is defined within the start.S file supplied by MIPS. In addition,
59this is where all static and global preset C variable initialization
60processing is called from.
61
62Once the startup function finishes, main is called, which is also where ThreadX
63initialization takes place. The main initialization function for ThreadX is
64_tx_initialize_low_level and is located in the file tx_initialize_low_level.S.
65This function is responsible for setting up various system data structures,
66interrupt vectors, and the periodic timer interrupt source of ThreadX.
67
68In addition, _tx_initialize_low_level determines where the first available
69RAM memory address is located. This address is supplied to tx_application_define.
70
71By default, the first available RAM memory address is assumed to start at the
72beginning of the ThreadX symbol _free_memory. If changes are made to the
73demo_threadx.ld file, the _free_memory symbol should remain the last allocated
74section in the main RAM area. The starting address of this section is passed
75to tx_application_define.
76
77
785. User defines
79
80Please reference the ThreadX_SMP_User_Guide.pdf for details on build options.
81
82
836. Register Usage and Stack Frames
84
85The GNU MIPS compiler assumes that registers t0-t9 ($8-$15, $24, $25)
86are scratch registers for each function. All other registers used by a
87C function must be preserved by the function. ThreadX takes advantage
88of this in situations where a context switch happens as a result of making a
89ThreadX service call (which is itself a C function). In such cases, the
90saved context of a thread is only the non-scratch registers.
91
92The following defines the saved context stack frames for context switches
93that occur as a result of interrupt handling or from thread-level API calls.
94All suspended threads have one of these two types of stack frames. The top
95of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the
96associated thread control block TX_THREAD.
97
98
99
100 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
101
102 0x000 1 0
103 0x004 s8 ($30) s8 ($30)
104 0x008 s7 ($23) s7 ($23)
105 0x00C s6 ($22) s6 ($22)
106 0x010 s5 ($21) s5 ($21)
107 0x014 s4 ($20) s4 ($20)
108 0x018 s3 ($19) s3 ($19)
109 0x01C s2 ($18) s2 ($18)
110 0x020 s1 ($17) s1 ($17)
111 0x024 s0 ($16) s0 ($16)
112 0x028 hi hi
113 0x02C lo lo
114 0x030 t9 ($25) ra ($31)
115 0x034 t8 ($24) SR
116 0x038 t7 ($15) f31 <------------+
117 0x03C t6 ($14) |
118 0x040 t5 ($13) f30 |
119 0x044 t4 ($12) |
120 0x048 t3 ($11) f29 |
121 0x04C t2 ($10) |
122 0x050 t1 ($9) f28 |
123 0x054 t0 ($8) |
124 0x058 a3 ($7) f27 |
125 0x05C a2 ($6) |
126 0x060 a1 ($5) f26 |
127 0x064 a0 ($4)
128 0x068 v1 ($3) f25 TX_ENABLE_64BIT_FPU_SUPPORT
129 0x06C v0 ($2)
130 0x070 at ($1) f24 |
131 0x074 ra ($31) |
132 0x078 SR f23 |
133 0x07C EPC |
134 0x080 f31 <-----------+ f22 |
135 0x088 f30 | f21 |
136 0x090 f29 | f20 |
137 0x098 f28 | fcr31 <------------+
138 0x09C | not used
139 0x0A0 f27 |
140 0x0A4 |
141 0x0A8 f26 |
142 0x0AC |
143 0x0B0 f25 |
144 0x0B4 |
145 0x0B8 f24 |
146 0x0BC |
147 0x0C0 f23 |
148 0x0C8 f22 |
149 0x0D0 f21 |
150 0x0D8 f20 |
151 0x0E0 f19 |
152 0x0E8 f18 |
153 0x0F0 f17
154 0x0F8 f16 TX_ENABLE_64BIT_FPU_SUPPORT
155 0x100 f15
156 0x108 f14 |
157 0x110 f13 |
158 0x118 f12 |
159 0x120 f11 |
160 0x128 f10 |
161 0x130 f9 |
162 0x138 f8 |
163 0x140 f7 |
164 0x148 f6 |
165 0x150 f5 |
166 0x158 f4 |
167 0x160 f3 |
168 0x168 f2 |
169 0x170 f1 |
170 0x178 f0 |
171 0x180 fcr31 <-----------+
172 0x184 not used
173
174
1757. Improving Performance
176
177The distribution version of ThreadX is built without any compiler
178optimizations. This makes it easy to debug because you can trace or set
179breakpoints inside of ThreadX itself. Of course, this costs some
180performance. To make ThreadX run faster, you can change the tx.gpj project
181to disable debug information and enable the desired optimizations.
182
183In addition, you can eliminate the ThreadX basic API error checking by
184compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
185defined before tx_api.h is included.
186
187
1888. Interrupt Handling
189
190ThreadX provides complete and high-performance interrupt handling for MIPS32 interAptiv
191targets. The general exception handler is at address: 0x80000180 (0xA0000180 non-
192cached). The ThreadX general exception handler is defined in the file
193tx_initialize_low_level.S at the label _tx_exception_handler. A small piece of
194code to jump to this exception handler is copied to the general exception handler
195address during initialization.
196
1978.1 Application ISRs
198
199Multiple exceptions may be processed with a single execution of the exception
200handler. This is because the Cause register could indicate more than a single
201exception. Processing for each exception is also located in the general
202exception handler that starts at the label: _tx_exception_handler. Application
203ISRs can be added into this handler.
204
205
2069. Theory of Operation - SMP
207
208ThreadX for the MIPS interAptiv brings Symmetric Multi-Processing (SMP) technology to
209the MIPS interAptiv. ThreadX application threads (of varying priority) that are "READY"
210to run are dynamically allocated to VPEs during scheduling, thus taking full
211advantage of all available MIPS interAptiv VPEs. This results in true SMP processing,
212including automatic load balancing of application thread execution across all
213available MIPS interAptiv VPEs.
214
215Initialization is done exclusively in VPE 0, which is the default running VPE
216after reset. The additional VPEs on the interAptiv are initialized by VPE 0 and simply
217wait until VPE 0 completes the initialization before they start running.
218
219During thread execution, multithreading in the MIPS interAptiv is fully enabled. This
220means that application threads may be preempted by higher priority threads, may
221suspend themselves, or may exit the system upon completion of their work. Protection
222between VPEs is accomplished via a conditional load-store structure (see the variable
223_tx_thread_smp_protection and the typedef TX_THREAD_SMP_PROTECT found in tx_thread.h).
224
225All VPEs are eligible to handle interrupts under the direction of the application. The
226ThreadX timer interrupt is by default assigned to VPE 0 for processing. Please see
227the code in tx_timer_interrupt.S for the implementation.
228
229ThreadX for the MIPS interAptiv also optionally supports the MIPS interAptiv FPU.
230
231The number of VPEs is defined by the compile time constant TX_THREAD_SMP_MAX_CORES.
232By default, this is set to 2 in tx_port.h. It may be changed to support any number
233of cores either in tx_port.h or on the command line via a -D symbol definition.
234
235
23610. Current Limitations
237
2381. Hardware priority assignment for each TC is not setup.
2392. DSP registers are not saved/restored.
240
241
24211. Debug Information
243
244ThreadX SMP for MIPS32 interAptiv has a built-in debug facility to capture SMP scheduling
245information. This is enabled by building the system with TX_THREAD_SMP_DEBUG_ENABLE
246defined. This results in the creation of circular log containing debug information.
247The log is defined in the variable _tx_thread_smp_debug_info_array.
248
249
25012. Revision History
251
252For generic code revision information, please refer to the readme_threadx_generic.txt
253file, which is included in your distribution. The following details the revision
254information associated with this specific port of ThreadX:
255
256
25703-08-2023 Initial ThreadX version 6.2.1 of MIPS32_interAptiv VPE/GNU port.
258
259
260Copyright(c) 1996-2020 Microsoft Corporation
261
262https://azure.com/rtos
263
