readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX for ARC EM
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 ARCv2 EM
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 ARCv2 EM 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
136ARCv2 EM processor. The following template should be used for interrupts
137managed by ThreadX:
138
139 .global _tx_interrupt_x
140_tx_interrupt_x:
141 sub sp, sp, 160 ; Allocate an interrupt stack frame
142 st blink, [sp, 16] ; Save blink (blink must be saved before _tx_thread_context_save)
143 bl _tx_thread_context_save ; Save interrupt context
144;
145; /* Application ISR processing goes here! Your ISR can be written in
146; assembly language or in C. If it is written in C, you must allocate
147; 16 bytes of stack space before it is called. This must also be
148; recovered once your C ISR return. An example of this is shown below.
149;
150; If the ISR is written in assembly language, only the compiler scratch
151; registers are available for use without saving/restoring (r0-r12).
152; If use of additional registers are required they must be saved and
153; restored. */
154;
155 bl.d your_ISR_written_in_C ; Call an ISR written in C
156 sub sp, sp, 16 ; Allocate stack space (delay slot)
157 add sp, sp, 16 ; Recover stack space
158
159;
160 b _tx_thread_context_restore ; Restore interrupt context
161
162
163The application handles interrupts directly, which necessitates all register
164preservation by the application's ISR. ISRs that do not use the ThreadX
165_tx_thread_context_save and _tx_thread_context_restore routines are not
166allowed access to the ThreadX API. In addition, custom application ISRs
167should be higher priority than all ThreadX-managed ISRs.
168
169
1708. ThreadX Timer Interrupt
171
172ThreadX requires a periodic interrupt source to manage all time-slicing,
173thread sleeps, timeouts, and application timers. Without such a timer
174interrupt source, these services are not functional but the remainder of
175ThreadX will still run.
176
177By default, the ThreadX timer interrupt is mapped to the ARCv2 EM auxiliary
178timer 0, which generates low priority interrupts on interrupt vector 16.
179It is easy to change the timer interrupt source and priority by changing the
180setup code in tx_initialize_low_level.s.
181
182
1839. Hardware Stack Checking
184
185ThreadX optionally supports the ARCv2 EM hardware stack checking feature. When enabled,
186the KSTACK_TOP and KSTACK_BASE registers are loaded with the stack top/bottom before
187each thread's execution. In addition, the SC bit of STATUS32 is set to enable the stack
188checking feature. During initialization, idle, or interrupt processing, the hardware
189stack checking on the system stack is performed, when enabled.
190
191To enable ThreadX support for hardware stack checking, simply build the ThreadX library
192and application assembly code with TX_ENABLE_HW_STACK_CHECKING defined. This will enable
193the stack checking logic in ThreadX.
194
195For the system stack checking to function properly, there are two sections that must
196be located around the .stack section, which defines the system stack location and size.
197The new sections are .stack_top and .stack_base. The .stack_top section should be placed
198immediately BEFORE the .stack section and .stack_base should be placed immediately AFTER
199the .stack section. Please see the sample_threadx.cmd linker control file for an example.
200
201When/if a stack exception occurs, the hardware will fetch the _tx_ev_protection_viol
202exception defined in tx_initialize_low_level.s. Processing for this exception is
203application specific.
204
205
20610. Revision History
207
208For generic code revision information, please refer to the readme_threadx_generic.txt
209file, which is included in your distribution. The following details the revision
210information associated with this specific port of ThreadX:
211
21204-02-2021 Release 6.1.6 changes:
213 tx_port.h Updated macro definition
214 tx_initialize_low_level.s Modified comments
215 tx_thread_context_restore.s r25/r30 are caller saved
216 tx_thread_context_save.s r25/r30 are caller saved
217 tx_thread_interrupt_control.s Modified comments
218 tx_thread_schedule.s fixed interrupt priority overwritting bug,
219 and fixed hardware stack checker disable and reenable logic
220 tx_thread_stack_build.s Modified comments
221 tx_thread_system_return.s Modified comments
222 tx_timer_interrupt.s remove unneeded load of _tx_thread_preempt_disable
223
22409-30-2020 Initial ThreadX 6.1 for ARCv2 EM using MetaWare tools.
225
226
227Copyright(c) 1996-2021 Microsoft Corporation
228
229
230https://azure.com/rtos
231
232
