readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX for ARC HS
2
3 Using the MetaWare Tools
4
51. Open the Azure RTOS Workspace
6
7In order to build the ThreadX library and the ThreadX demonstration first load
8the Azure RTOS Workspace, which is located inside the "example_build" directory.
9
10
112. Building the ThreadX run-time Library
12
13Building the ThreadX library is easy; simply select the ThreadX library project
14file "tx" and then select the build button. You should now observe the compilation
15and assembly of the ThreadX library. This project build produces the ThreadX
16library file tx.a.
17
18
193. Demonstration System
20
21The ThreadX demonstration is designed to execute under the MetaWare ARC HS
22simulation. The instructions that follow describe how to get the ThreadX
23demonstration running.
24
25Building the demonstration is easy; simply select the demonstration project file
26"sample_threadx." At this point, select the build button and observe the
27compilation, assembly, and linkage of the ThreadX demonstration application.
28
29After the demonstration is built, click on the "Debug" button and it will
30automatically launch a pre-configured connection to the ARC HS simulator.
31
32You are now ready to execute the ThreadX demonstration system. Select
33breakpoints and data watches to observe the execution of the sample_threadx.c
34application.
35
36
374. System Initialization
38
39The system entry point using the MetaWare tools is at the label _start.
40This is defined within the crt1.s file supplied by MetaWare. In addition,
41this is where all static and global preset C variable initialization
42processing is called from.
43
44After the MetaWare startup function completes, ThreadX initialization is
45called. The main initialization function is _tx_initialize_low_level and
46is located in the file tx_initialize_low_level.s. This function is
47responsible for setting up various system data structures, and interrupt
48vectors.
49
50By default free memory is assumed to start at the section .free_memory
51which is referenced in tx_initialize_low_level.s and located in the
52linker control file after all the linker defined RAM addresses. This is
53the address passed to the application definition function, tx_application_define.
54
55
565. Register Usage and Stack Frames
57
58The ARC compiler assumes that registers r0-r12 are scratch registers for
59each function. All other registers used by a C function must be preserved
60by the function. ThreadX takes advantage of this in situations where a
61context switch happens as a result of making a ThreadX service call (which
62is itself a C function). In such cases, the saved context of a thread is
63only the non-scratch registers.
64
65The following defines the saved context stack frames for context switches
66that occur as a result of interrupt handling or from thread-level API calls.
67All suspended threads have one of these two types of stack frames. The top
68of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the
69associated thread control block TX_THREAD.
70
71
72
73 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
74
75 0x00 1 0
76 0x04 LP_START blink
77 0x08 LP_END fp
78 0x0C LP_COUNT r26
79 0x10 blink r25
80 0x14 ilink r24
81 0x18 fp r23
82 0x1C r26 r22
83 0x20 r25 r21
84 0x24 r24 r20
85 0x28 r23 r19
86 0x2C r22 r18
87 0x30 r21 r17
88 0x34 r20 r16
89 0x38 r19 r15
90 0x3C r18 r14
91 0x40 r17 r13
92 0x44 r16 STATUS32
93 0x48 r15 r30
94 0x4C r14
95 0x50 r13
96 0x54 r12
97 0x58 r11
98 0x5C r10
99 0x60 r9
100 0x64 r8
101 0x68 r7
102 0x6C r6
103 0x70 r5
104 0x74 r4
105 0x78 r3
106 0x7C r2
107 0x80 r1
108 0x84 r0
109 0x88 r30
110 0x8C r58 (if TX_ENABLE_ACC defined)
111 0x90 r59 (if TX_ENABLE_ACC defined)
112 0x94 reserved
113 0x98 reserved
114 0x9C bta
115 0xA0 point of interrupt
116 0xA4 STATUS32
117
118
119
1206. Improving Performance
121
122The distribution version of ThreadX is built without any compiler
123optimizations. This makes it easy to debug because you can trace or set
124breakpoints inside of ThreadX itself. Of course, this costs some
125performance. To make it run faster, you can change the build_threadx.bat
126file to remove the -g option and enable all compiler optimizations.
127
128In addition, you can eliminate the ThreadX basic API error checking by
129compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
130defined.
131
132
1337. Interrupt Handling
134
135ThreadX provides complete and high-performance interrupt handling for the
136ARC HS processor, including support for software interrupts and fast
137hardware interrupts.
138
1397.1 Software Interrupt Handling
140
141The following template should be used for software interrupts
142managed by ThreadX:
143
144 .global _tx_interrupt_x
145_tx_interrupt_x:
146 sub sp, sp, 160 ; Allocate an interrupt stack frame
147 st blink, [sp, 16] ; Save blink (blink must be saved before _tx_thread_context_save)
148 bl _tx_thread_context_save ; Save interrupt context
149;
150; /* Application ISR processing goes here! Your ISR can be written in
151; assembly language or in C. If it is written in C, you must allocate
152; 16 bytes of stack space before it is called. This must also be
153; recovered once your C ISR return. An example of this is shown below.
154;
155; If the ISR is written in assembly language, only the compiler scratch
156; registers are available for use without saving/restoring (r0-r12).
157; If use of additional registers are required they must be saved and
158; restored. */
159;
160 bl.d your_ISR_written_in_C ; Call an ISR written in C
161 sub sp, sp, 16 ; Allocate stack space (delay slot)
162 add sp, sp, 16 ; Recover stack space
163
164;
165 b _tx_thread_context_restore ; Restore interrupt context
166
167
168The application handles interrupts directly, which necessitates all register
169preservation by the application's ISR. ISRs that do not use the ThreadX
170_tx_thread_context_save and _tx_thread_context_restore routines are not
171allowed access to the ThreadX API. In addition, custom application ISRs
172should be higher priority than all ThreadX-managed ISRs.
173
1747.2 Fast Interrupt Handling
175
176ThreadX supports the ARC HS fast interrupt processing. It is assumed that
177multiple register banks are available and the ARC HS processor automatically
178uses register bank 1 as the fast interrupt register bank.
179
180In order to use fast interrupts with register bank 1, the interrupt desired
181must have priority 0 and the application must call the following ThreadX API
182to setup register bank 1:
183
184void tx_initialize_fast_interrupt_setup(void *stack_ptr);
185
186The parameter "stack_ptr" is the first usable address for the fast interrupt
187stack. For example, assume the fast interrupt stack is to be located in the
188array "unsigned char fast_interrupt_stack[1024]" the call to this API would
189look like:
190
191 tx_initialize_fast_interrupt_setup(&fast_interrupt_stack[1020]);
192
193As for the fast interrupt ISR, the following template should be used for
194ARC HS fast interrupts managed by ThreadX:
195
196 .global _tx_fast_interrupt_x
197_tx_fast_interrupt_x:
198 bl _tx_thread_context_fast_save
199;
200; /* Fast ISR processing goes here. Interrupts must not be re-enabled
201; in the fast interrupt mode. Also note that multiple register banks
202; are available and the fast interrupt processing always maps to
203; register bank 1. */
204;
205 b _tx_thread_context_fast_restore
206
207
2088. ThreadX Timer Interrupt
209
210ThreadX requires a periodic interrupt source to manage all time-slicing,
211thread sleeps, timeouts, and application timers. Without such a timer
212interrupt source, these services are not functional but the remainder of
213ThreadX will still run.
214
215By default, the ThreadX timer interrupt is mapped to the ARC HS auxiliary
216timer 0, which generates low priority interrupts on interrupt vector 16.
217It is easy to change the timer interrupt source and priority by changing the
218setup code in tx_initialize_low_level.s.
219
220
2219. Thread Hardware Register Bank Context
222
223ThreadX supports the use of hardware register banks on the ARC HS. A hardware
224register bank may be associated with a specific application thread via the
225following API:
226
227void tx_thread_register_bank_assign(TX_THREAD *thread_ptr, register_bank);
228
229This API is assumed to be called from initialization (interrupts are locked out
230and execution is from register bank 0) and after the specified thread has been
231created. This API assumes the register bank number is correct, i.e., a valid
232register bank greater than 0 and one that hasn't been used for another thread.
233
234Note: if fast interrupts are used, register bank 1 must also not be used. In this
235case the valid register bank range is 2 through maximum register banks minus 1.
236
237
23810. Revision History
239
240For generic code revision information, please refer to the readme_threadx_generic.txt
241file, which is included in your distribution. The following details the revision
242information associated with this specific port of ThreadX:
243
24404-02-2021 Release 6.1.6 changes:
245 tx_port.h Updated macro definition
246
24709-30-2020 Initial ThreadX 6.1 for ARC HS using MetaWare tools.
248
249
250Copyright(c) 1996-2021 Microsoft Corporation
251
252
253https://azure.com/rtos
254
255
