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