readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX SMP for ARC HS
2
3 Using the MetaWare Tools
4
51. Open the ThreadX SMP Workspace
6
7In order to build the ThreadX SMP library and the ThreadX SMP demonstration
8first load the Azure RTOS Workspace, which is located inside the "example_build"
9directory.
10
11
122. Building the ThreadX SMP run-time Library
13
14Building the ThreadX SMP library is easy; simply select the ThreadX library project
15file "tx" and then select the build button. You should now observe the compilation
16and assembly of the ThreadX SMP library. This project build produces the ThreadX SMP
17library file tx.a.
18
19
203. Demonstration System
21
22The ThreadX demonstration is designed to execute under the MetaWare ARC HS SMP
23simulation. The instructions that follow describe how to get the ThreadX SMP
24demonstration running.
25
26Building the demonstration is easy; simply select the demonstration project file
27"sample_threadx." At this point, select the build button and observe the
28compilation, assembly, and linkage of the ThreadX SMP demonstration application.
29
30After the demonstration is built, execute the "run_threadx_smp_demo.bat" batch file
31to invoke and load the ThreadX SMP demonstration.
32
33You are now ready to execute the ThreadX demonstration system. Select
34breakpoints and data watches to observe the execution of the sample_threadx.c
35SMP application.
36
37
384. System Initialization
39
40The system entry point using the MetaWare tools is at the label _start.
41This is defined within the crt1.s file supplied by MetaWare. In addition,
42this is where all static and global preset C variable initialization
43processing is called from.
44
45After the MetaWare startup function completes, ThreadX initialization is
46called. The main initialization function is _tx_initialize_low_level and
47is located in the file tx_initialize_low_level.s. This function is
48responsible for setting up various system data structures, and interrupt
49vectors.
50
51By default free memory is assumed to start at the section .free_memory
52which is referenced in tx_initialize_low_level.s and located in the
53linker control file after all the linker defined RAM addresses. This is
54the address passed to the application definition function, tx_application_define.
55
56
575. Register Usage and Stack Frames
58
59The ARC compiler assumes that registers r0-r12 are scratch registers for
60each function. All other registers used by a C function must be preserved
61by the function. ThreadX takes advantage of this in situations where a
62context switch happens as a result of making a ThreadX service call (which
63is itself a C function). In such cases, the saved context of a thread is
64only the non-scratch registers.
65
66The following defines the saved context stack frames for context switches
67that occur as a result of interrupt handling or from thread-level API calls.
68All suspended threads have one of these two types of stack frames. The top
69of the suspended thread's stack is pointed to by tx_thread_stack_ptr in the
70associated thread control block TX_THREAD.
71
72
73
74 Offset Interrupted Stack Frame Non-Interrupt Stack Frame
75
76 0x00 1 0
77 0x04 LP_START blink
78 0x08 LP_END fp
79 0x0C LP_COUNT r26
80 0x10 blink r25
81 0x14 ilink r24
82 0x18 fp r23
83 0x1C r26 r22
84 0x20 r25 r21
85 0x24 r24 r20
86 0x28 r23 r19
87 0x2C r22 r18
88 0x30 r21 r17
89 0x34 r20 r16
90 0x38 r19 r15
91 0x3C r18 r14
92 0x40 r17 r13
93 0x44 r16 STATUS32
94 0x48 r15 r30
95 0x4C r14
96 0x50 r13
97 0x54 r12
98 0x58 r11
99 0x5C r10
100 0x60 r9
101 0x64 r8
102 0x68 r7
103 0x6C r6
104 0x70 r5
105 0x74 r4
106 0x78 r3
107 0x7C r2
108 0x80 r1
109 0x84 r0
110 0x88 r30
111 0x8C r58 - ACCL (optional)
112 0x90 r59 - ACCH (optional)
113 0x94 reserved
114 0x98 reserved
115 0x9C bta
116 0xA0 point of interrupt
117 0xA4 STATUS32
118
119
120
1216. Improving Performance
122
123The distribution version of ThreadX is built without any compiler
124optimizations. This makes it easy to debug because you can trace or set
125breakpoints inside of ThreadX itself. Of course, this costs some
126performance. To make it run faster, you can change the build_threadx.bat
127file to remove the -g option and enable all compiler optimizations.
128
129In addition, you can eliminate the ThreadX basic API error checking by
130compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
131defined.
132
133
1347. Interrupt Handling
135
136ThreadX provides complete and high-performance interrupt handling for the
137ARC HS processor, including support for software interrupts and fast
138hardware interrupts.
139
1407.1 Software Interrupt Handling
141
142The following template should be used for software interrupts
143managed by ThreadX:
144
145 .global _tx_interrupt_x
146_tx_interrupt_x:
147 sub sp, sp, 160 ; Allocate an interrupt stack frame
148 st blink, [sp, 16] ; Save blink (blink must be saved before _tx_thread_context_save)
149 bl _tx_thread_context_save ; Save interrupt context
150;
151; /* Application ISR processing goes here! Your ISR can be written in
152; assembly language or in C. If it is written in C, you must allocate
153; 16 bytes of stack space before it is called. This must also be
154; recovered once your C ISR return. An example of this is shown below.
155;
156; If the ISR is written in assembly language, only the compiler scratch
157; registers are available for use without saving/restoring (r0-r12).
158; If use of additional registers are required they must be saved and
159; restored. */
160;
161 bl.d your_ISR_written_in_C ; Call an ISR written in C
162 sub sp, sp, 16 ; Allocate stack space (delay slot)
163 add sp, sp, 16 ; Recover stack space
164
165;
166 b _tx_thread_context_restore ; Restore interrupt context
167
168
169The application handles interrupts directly, which necessitates all register
170preservation by the application's ISR. ISRs that do not use the ThreadX
171_tx_thread_context_save and _tx_thread_context_restore routines are not
172allowed access to the ThreadX API. In addition, custom application ISRs
173should be higher priority than all ThreadX-managed ISRs.
174
175
1768. ThreadX Timer Interrupt
177
178ThreadX SMP requires a periodic interrupt source to manage all time-slicing,
179thread sleeps, timeouts, and application timers. Without such a timer
180interrupt source, these services are not functional but the remainder of
181ThreadX will still run.
182
183By default, the ThreadX timer interrupt is mapped to the ARC HS auxiliary
184timer 0, which generates low priority interrupts on interrupt vector 16.
185It is easy to change the timer interrupt source and priority by changing the
186setup code in tx_initialize_low_level.s. In addition, the ThreadX SMP timer
187is mapped to core 0. To change to another core, please edit arc.c and
188_tx_timer_interrupt.s. Only one core should be used as the ThreadX SMP
189periodic timer interrupt source.
190
191
1929. Revision History
193
194For generic code revision information, please refer to the readme_threadx_generic.txt
195file, which is included in your distribution. The following details the revision
196information associated with this specific port of ThreadX:
197
19804-02-2021 Release 6.1.6 changes:
199 tx_port.h Updated macro definition
200
20109-30-2020 Initial ThreadX 6.1 for ARC HS using MetaWare tools.
202
203
204Copyright(c) 1996-2020 Microsoft Corporation
205
206
207https://azure.com/rtos
208
209
