readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX Modules for Cortex-A35
2
3 Using the ARM GNU Compiler & DS
4
51. Import the ThreadX Modules Projects
6
7In order to build the ThreadX library and the ThreadX demonstration, first import
8the 'tx', 'txm', 'sample_threadx', 'sample_threadx_module' and
9'sample_thread_module_manager' projects (located in the "example_build" directory)
10into your DS workspace.
11
12
132. Building the ThreadX run-time Library
14
15Building the ThreadX library is easy; simply select the Eclipse project file
16"tx" and then select the build button. You should now observe the compilation
17and assembly of the ThreadX library. This project build produces the ThreadX
18library file tx.a. To bild the ThreadX Module library select the project "txm"
19and select the build button to produce the file txm.a.
20
21
223. Demonstration System
23
24The ThreadX demonstration is designed to execute under the DS debugger on the
25Base_A35x1 Bare Metal simulator.
26
27Building the basic ThreadX demonstration is easy; simply select the sample_threadx project, and
28select the build button. Next, in the sample_threadx project, right-click on the
29sample_threadx.launch file and select 'Debug As -> sample_threadx'. The debugger is
30setup for the Cortex-A35 FVP, so selecting "Debug" will launch the FVP, load
31the sample_threadx.axf ELF file and run to the entry point. You are now ready to execute
32the ThreadX demonstration.
33
34The ThreadX Modules demonstration is composed of a module and a module manager.
35First build the ThreadX sample module project sample_thread_module by selecting it and
36clicking the build button. Next built the ThreadX Module Manager sample by selecting
37sample_threadx_module_manager and clicking the build button.
38
39To run the ThreadX Module Manager demo in the sample_threadx_module_manager project,
40right-click on the sample_threadx_module_manager.launch file and select 'Debug As -> sample_threadx'.
41The debugger is setup for the Cortex-A35 FVP, so selecting "Debug" will launch the FVP, load
42the sample_threadx.axf ELF file and run to the entry point. You are now ready to execute
43the ThreadX demonstration.
44
45
464. System Initialization
47
48The entry point in ThreadX for the Cortex-A35 using GCC tools is at label
49"start64". This is defined within the GCC compiler's startup code. In addition,
50this is where all static and global pre-set C variable initialization processing
51takes place.
52
53The ThreadX tx_initialize_low_level.s file is responsible for determining the
54first available RAM address for use by the application, which is supplied as the
55sole input parameter to your application definition function, tx_application_define.
56
57
585. Register Usage and Stack Frames
59
60The 64-bit GCC compiler assumes that registers x0-x18 are scratch registers
61for each function. All other registers used by a C function must be preserved
62by the function. ThreadX takes advantage of this in situations where a context
63switch happens as a result of making a ThreadX service call (which is itself a
64C function). In such cases, the saved context of a thread is only the
65non-scratch registers.
66
67The following defines the saved context stack frames for context switches
68that occur as a result of interrupt handling or from thread-level API calls.
69All suspended threads have one of these two types of stack frames. The top
70of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the
71associated thread control block TX_THREAD.
72
73
74FP not enabled and TX_THREAD.tx_thread_fp_enable == 0:
75
76 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
77
78 0x000 SPSR DAIF
79 0x008 ELR 0
80 0x010 x28 x27
81 0x018 reserved x28
82 0x020 x26 x25
83 0x028 x27 x26
84 0x030 x24 x23
85 0x038 x25 x24
86 0x040 x22 x21
87 0x048 x23 x22
88 0x050 x20 x19
89 0x058 x21 x20
90 0x060 x18 x29
91 0x068 x19 x30
92 0x070 x16
93 0x078 x17
94 0x080 x14
95 0x088 x15
96 0x090 x12
97 0x098 x13
98 0x0A0 x10
99 0x0A8 x11
100 0x0B0 x8
101 0x0B8 x9
102 0x0C0 x6
103 0x0C8 x7
104 0x0D0 x4
105 0x0D8 x5
106 0x0E0 x2
107 0x0E8 x3
108 0x0F0 x0
109 0x0F8 x1
110 0x100 x29
111 0x108 x30
112
113
114FP enabled and TX_THREAD.tx_thread_fp_enable == 1:
115
116 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
117
118 0x000 SPSR DAIF
119 0x008 ELR 0
120 0x010 FPSR FPSR
121 0x018 FPCR FPCR
122 0x020 q30 q14
123 0x030 q31 q15
124 0x040 q28 q12
125 0x050 q29 q13
126 0x060 q26 q10
127 0x070 q27 q11
128 0x080 q24 q8
129 0x090 q25 q9
130 0x0A0 q22 x27
131 0x0A8 x28
132 0x0B0 q23 x25
133 0x0B8 x26
134 0x0C0 q20 x23
135 0x0C8 x24
136 0x0D0 q21 x21
137 0x0D8 x22
138 0x0E0 q18 x19
139 0x0E8 x20
140 0x0F0 q19 x29
141 0x0F8 x30
142 0x100 q16
143 0x110 q17
144 0x120 q14
145 0x130 q15
146 0x140 q12
147 0x150 q13
148 0x160 q10
149 0x170 q11
150 0x180 q8
151 0x190 q9
152 0x1A0 q6
153 0x1B0 q7
154 0x1C0 q4
155 0x1D0 q5
156 0x1E0 q2
157 0x1F0 q3
158 0x200 q0
159 0x210 q1
160 0x220 x28
161 0x228 reserved
162 0x230 x26
163 0x238 x27
164 0x240 x24
165 0x248 x25
166 0x250 x22
167 0x258 x23
168 0x260 x20
169 0x268 x21
170 0x270 x18
171 0x278 x19
172 0x280 x16
173 0x288 x17
174 0x290 x14
175 0x298 x15
176 0x2A0 x12
177 0x2A8 x13
178 0x2B0 x10
179 0x2B8 x11
180 0x2C0 x8
181 0x2C8 x9
182 0x2D0 x6
183 0x2D8 x7
184 0x2E0 x4
185 0x2E8 x5
186 0x2F0 x2
187 0x2F8 x3
188 0x300 x0
189 0x308 x1
190 0x310 x29
191 0x318 x30
192
193
194
1956. Improving Performance
196
197The distribution version of ThreadX is built without any compiler optimizations.
198This makes it easy to debug because you can trace or set breakpoints inside of
199ThreadX itself. Of course, this costs some performance. To make it run faster,
200you can change the project settings to the desired compiler optimization level.
201
202In addition, you can eliminate the ThreadX basic API error checking by
203compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
204defined.
205
206
2077. Interrupt Handling
208
209ThreadX provides complete and high-performance interrupt handling for Cortex-A35
210targets. Interrupts handlers for the 64-bit mode of the Cortex-A35 have the following
211format:
212
213 .global irq_handler
214irq_handler:
215 MSR SPSel, 0
216 STP x29, x30, [sp, #-16]!
217 BL _tx_thread_context_save
218
219 /* Your ISR call goes here! */
220 BL application_isr_handler
221
222 B _tx_thread_context_restore
223
224By default, ThreadX assumes EL3 level of execution. Running and taking exceptions in EL1
225and EL2 can be done by simply building the ThreadX library with either EL1 or EL2 defined.
226
227
2288. ThreadX Timer Interrupt
229
230ThreadX requires a periodic interrupt source to manage all time-slicing, thread sleeps,
231timeouts, and application timers. Without such a timer interrupt source, these services
232are not functional. However, all other ThreadX services are operational without a
233periodic timer source.
234
235
2369. ARM FP Support
237
238By default, FP support is disabled for each thread. If saving the context of the FP registers
239is needed, the following API call must be made from the context of the application thread - before
240the FP usage:
241
242void tx_thread_fp_enable(void);
243
244After this API is called in the application, FP registers will be saved/restored for this thread if it
245is preempted via an interrupt. All other suspension of the this thread will not require the FP registers
246to be saved/restored.
247
248To disable FP register context saving, simply call the following API:
249
250void tx_thread_fp_disable(void);
251
252
25310. Revision History
254
255For generic code revision information, please refer to the readme_threadx_generic.txt
256file, which is included in your distribution. The following details the revision
257information associated with this specific port of ThreadX:
258
25912-31-2020 Initial ThreadX 6.1.3 version for Cortex-A35 using GCC tools.
260
261
262Copyright(c) 1996-2020 Microsoft Corporation
263
264
265https://azure.com/rtos
266
267
