readme_threadx.txt
1 Microsoft's Azure RTOS ThreadX for Cortex-M7
2
3 Using the Green Hills Software Tools
4
51. Open the ThreadX Project Workspace
6
7In order to build the ThreadX library and the ThreadX demonstration first load
8the Azure RTOS Workspace azure_rtos_workspace.gpj, which is located inside the
9"example_build" directory.
10
11
122. Building the ThreadX run-time Library
13
14Building the ThreadX library is easy; simply select the MULTI project file
15tx.gpj and then select the build button. You should now observe the
16compilation and assembly of the ThreadX library. This project build produces
17the ThreadX library file tx.a.
18
19
203. Demonstration System
21
22The ThreadX demonstration is designed to execute under the MULTI environment
23on the Green Hills Cortex-M7 simulator. The instructions that follow describe
24how to get the ThreadX evaluation running under the MULTI Cortex-M7 simulation
25environment.
26
27Building the demonstration is easy; simply select the MULTI project file
28sample_threadx.gpj. At this point, select the "Project Build" button and observe
29the compilation, assembly, and linkage of the ThreadX demonstration application.
30
31After the demonstration is built, invoke the MULTI ARM simulator by selecting
32the simulator connection from within the sample_threadx.con connection file.
33Once connected to the simulator, select the "Debug" button. You should now
34observe the main function of sample_threadx.c.
35
36You are now ready to execute the ThreadX demonstration system. Select
37breakpoints and data watches to observe the execution of the sample_threadx.c
38application.
39
40
414. EventAnalyzer Demonstration
42
43To build a demonstration system that also logs events for the MULTI EventAnalyzer,
44perform the same steps as the regular demo, except build the ThreadX library with
45txe.gpj file and use the sample_threadx_el.gpj build file to build the demonstration.
46The resulting image will log all system events, which can then be displayed by the
47MULTI EventAnalyzer.
48
49
505. System Initialization
51
52The system entry point using the Green Hills tools is at the label _start.
53This is defined within the crt0.arm file supplied by Green Hills. In addition,
54this is where all static and global preset C variable initialization
55processing is called from.
56
57After the Green Hills startup function returns, ThreadX initialization is
58called. The main initialization function is _tx_initialize_low_level and
59is located in the file tx_initialize_low_level.arm. This function is responsible
60for setting up various system data structures, interrupt vectors, and the
61periodic timer interrupt source of ThreadX.
62
63In addition, _tx_initialize_low_level determines where the first available
64RAM memory address is located. This address is supplied to tx_application_define.
65
66By default, the first available RAM memory address is assumed to start at the
67beginning of the ThreadX section .free_mem. If changes are made to the
68sample_threadx.ld file, the .free_mem section should remain the last allocated
69section in the main RAM area. The starting address of this section is passed
70to tx_application_define.
71
72
736. Register Usage and Stack Frames
74
75The following defines the saved context stack frames for context switches
76that occur as a result of interrupt handling or from thread-level API calls.
77All suspended threads have the same stack frame in the Cortex-M7 version of
78ThreadX. The top of the suspended thread's stack is pointed to by
79tx_thread_stack_ptr in the associated thread control block TX_THREAD.
80
81
82Non-FPU Stack Frame:
83
84 Stack Offset Stack Contents
85
86 0x00 r4
87 0x04 r5
88 0x08 r6
89 0x0C r7
90 0x10 r8
91 0x14 r9
92 0x18 r10
93 0x1C r11
94 0x20 r0 (Hardware stack starts here!!)
95 0x24 r1
96 0x28 r2
97 0x2C r3
98 0x30 r12
99 0x34 lr
100 0x38 pc
101 0x3C xPSR
102
103FPU Stack Frame (only interrupted thread with FPU enabled):
104
105 Stack Offset Stack Contents
106
107 0x00 s0
108 0x04 s1
109 0x08 s2
110 0x0C s3
111 0x10 s4
112 0x14 s5
113 0x18 s6
114 0x1C s7
115 0x20 s8
116 0x24 s9
117 0x28 s10
118 0x2C s11
119 0x30 s12
120 0x34 s13
121 0x38 s14
122 0x3C s15
123 0x40 s16
124 0x44 s17
125 0x48 s18
126 0x4C s19
127 0x50 s20
128 0x54 s21
129 0x58 s22
130 0x5C s23
131 0x60 s24
132 0x64 s25
133 0x68 s26
134 0x6C s27
135 0x70 s28
136 0x74 s29
137 0x78 s30
138 0x7C s31
139 0x80 fpscr
140 0x84 r4
141 0x88 r5
142 0x8C r6
143 0x90 r7
144 0x94 r8
145 0x98 r9
146 0x9C r10 (sl)
147 0xA0 r11
148 0xA4 r0 (Hardware stack starts here!!)
149 0xA8 r1
150 0xAC r2
151 0xB0 r3
152 0xB4 r12
153 0xB8 lr
154 0xBC pc
155 0xC0 xPSR
156
157
1587. Improving Performance
159
160The distribution version of ThreadX is built without any compiler
161optimizations. This makes it easy to debug because you can trace or set
162breakpoints inside of ThreadX itself. Of course, this costs some
163performance. To make ThreadX run faster, you can change the tx.gpj project
164to disable debug information and enable the desired optimizations.
165
166In addition, you can eliminate the ThreadX basic API error checking by
167compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
168defined before tx_api.h is included.
169
170
1718. Interrupt Handling
172
173ThreadX provides complete and high-performance interrupt handling for Cortex-M7
174targets. There are a certain set of requirements that are defined in the
175following sub-sections:
176
177
1788.1 Vector Area
179
180The Cortex-M7 vectors start at the label __tx_vectors. The application may modify
181the vector area according to its needs.
182
183
1848.2 Managed Interrupts
185
186A ThreadX managed interrupt is defined below. By following these conventions, the
187application ISR is then allowed access to various ThreadX services from the ISR.
188Here is the standard template for managed ISRs in ThreadX:
189
190
191 .globl __tx_IntHandler
192__tx_IntHandler:
193 PUSH {lr}
194 BL _tx_thread_context_save
195
196 /* Do interrupt handler work here */
197
198 B _tx_thread_context_restore
199
200
2019. FPU Support
202
203By default, FPU support is disabled for each thread. If saving the context of the FPU registers
204is needed, the ThreadX library should be re-built with TX_ENABLE_FPU_SUPPORT defined. In addition,
205the following API call must be made from the context of the application thread - before
206the FPU usage:
207
208void tx_thread_fpu_enable(void);
209
210After this API is called in the application, FPU registers will be saved/restored for this thread if it
211is preempted via an interrupt. All other suspension of the this thread will not require the FPU registers
212to be saved/restored.
213
214To disable FPU register context saving, simply call the following API:
215
216void tx_thread_fpu_disable(void);
217
218
219
22010. Revision History
221
222For generic code revision information, please refer to the readme_threadx_generic.txt
223file, which is included in your distribution. The following details the revision
224information associated with this specific port of ThreadX:
225
22605/19/2020 Initial ThreadX version of Cortex-M7/Green Hills port.
227
228
229Copyright(c) 1996-2020 Microsoft Corporation
230
231
232https://azure.com/rtos
233
234
