1                       Microsoft's Azure RTOS ThreadX for ARMv7-M
2                            (Cortex-M3, Cortex-M4, Cortex-M7)
3                              Using ARM Compiler 6 (AC6)
4
5
61.  Building the ThreadX run-time Library
7
8In order to build the ThreadX library and the ThreadX demonstration, first import
9the 'tx' and 'sample_threadx' projects (located in the "example_build" directory)
10into your DS workspace.
11
12Building the ThreadX library is easy; simply right-click the Eclipse project
13"tx" and then select the "Build Project" button. You should now observe the compilation
14and assembly of the ThreadX library. This project build produces the ThreadX
15library file tx.a.
16
17
182.  Demonstration System
19
20The ThreadX demonstration is designed to execute under the DS debugger on the
21MPS2_Cortex_Mx Bare Metal simulator.
22
23Building the demonstration is easy; simply right-click the Eclipse project
24"sample_threadx" and then select the "Build Project" button. You should now observe
25the compilation and assembly of the ThreadX demonstration. This project build produces
26the ThreadX library file sample_threadx.axf. Next, expand the demo ThreadX project folder
27in the Project Explorer window, right-click on the 'cortex-mx_tx.launch' file, click
28'Debug As', and then click 'cortex-mx_tx' from the submenu. This will cause the
29debugger to load the sample_threadx.axf ELF file and run to main. You are now ready
30to execute the ThreadX demonstration.
31
32
333.  System Initialization
34
35The entry point in ThreadX for the Cortex-M using AC6 tools uses the standard GNU
36Cortex-M reset sequence. From the reset vector the C runtime will be initialized.
37
38The ThreadX tx_initialize_low_level.S file is responsible for setting up
39various system data structures, the vector area, and a periodic timer interrupt
40source.
41
42In addition, _tx_initialize_low_level determines the first available
43address for use by the application, which is supplied as the sole input
44parameter to your application definition function, tx_application_define.
45
46
474.  Register Usage and Stack Frames
48
49The following defines the saved context stack frames for context switches
50that occur as a result of interrupt handling or from thread-level API calls.
51All suspended threads have the same stack frame in the Cortex-M version of
52ThreadX. The top of the suspended thread's stack is pointed to by
53tx_thread_stack_ptr in the associated thread control block TX_THREAD.
54
55Non-FPU Stack Frame:
56
57    Stack Offset    Stack Contents
58
59    0x00            lr          Interrupted lr (lr at time of PENDSV)
60    0x04            r4          Software stacked GP registers
61    0x08            r5
62    0x0C            r6
63    0x10            r7
64    0x14            r8
65    0x18            r9
66    0x1C            r10
67    0x20            r11
68    0x24            r0          Hardware stacked registers
69    0x28            r1
70    0x2C            r2
71    0x30            r3
72    0x34            r12
73    0x38            lr
74    0x3C            pc
75    0x40            xPSR
76
77FPU Stack Frame (only interrupted thread with FPU enabled):
78
79    Stack Offset    Stack Contents
80
81    0x00            lr          Interrupted lr (lr at time of PENDSV)
82    0x04            s16         Software stacked FPU registers
83    0x08            s17
84    0x0C            s18
85    0x10            s19
86    0x14            s20
87    0x18            s21
88    0x1C            s22
89    0x20            s23
90    0x24            s24
91    0x28            s25
92    0x2C            s26
93    0x30            s27
94    0x34            s28
95    0x38            s29
96    0x3C            s30
97    0x40            s31
98    0x44            r4          Software stacked registers
99    0x48            r5
100    0x4C            r6
101    0x50            r7
102    0x54            r8
103    0x58            r9
104    0x5C            r10
105    0x60            r11
106    0x64            r0          Hardware stacked registers
107    0x68            r1
108    0x6C            r2
109    0x70            r3
110    0x74            r12
111    0x78            lr
112    0x7C            pc
113    0x80            xPSR
114    0x84            s0          Hardware stacked FPU registers
115    0x88            s1
116    0x8C            s2
117    0x90            s3
118    0x94            s4
119    0x98            s5
120    0x9C            s6
121    0xA0            s7
122    0xA4            s8
123    0xA8            s9
124    0xAC            s10
125    0xB0            s11
126    0xB4            s12
127    0xB8            s13
128    0xBC            s14
129    0xC0            s15
130    0xC4            fpscr
131
132
1335.  Improving Performance
134
135The distribution version of ThreadX is built without any compiler
136optimizations. This makes it easy to debug because you can trace or set
137breakpoints inside of ThreadX itself. Of course, this costs some
138performance. To make it run faster, you can change the ThreadX library
139project to enable various compiler optimizations.
140
141In addition, you can eliminate the ThreadX basic API error checking by
142compiling your application code with the symbol TX_DISABLE_ERROR_CHECKING
143defined.
144
145
1466.  Interrupt Handling
147
148ThreadX provides complete and high-performance interrupt handling for Cortex-M
149targets. There are a certain set of requirements that are defined in the
150following sub-sections:
151
152
1536.1  Vector Area
154
155The Cortex-M vectors start at the label __tx_vectors or similar. The application may modify
156the vector area according to its needs. There is code in tx_initialize_low_level() that will
157configure the vector base register.
158
159
1606.2 Managed Interrupts
161
162A ThreadX managed interrupt is defined below. By following these conventions, the
163application ISR is then allowed access to various ThreadX services from the ISR.
164Here is the standard template for managed ISRs in ThreadX:
165
166
167        .global  __tx_IntHandler
168        .thumb_func
169__tx_IntHandler:
170; VOID InterruptHandler (VOID)
171; {
172        PUSH    {r0, lr}
173
174;    /* Do interrupt handler work here */
175;    /* BL <your interrupt routine in C> */
176
177        POP     {r0, lr}
178        BX      lr
179; }
180
181
182Note: the Cortex-M requires exception handlers to be thumb labels, this implies bit 0 set.
183To accomplish this, the declaration of the label has to be preceded by the assembler directive
184.thumb_func to instruct the linker to create thumb labels. The label __tx_IntHandler needs to
185be inserted in the correct location in the interrupt vector table. This table is typically
186located in either your runtime startup file or in the tx_initialize_low_level.S file.
187
188
1897. FPU Support
190
191ThreadX for Cortex-M supports automatic ("lazy") VFP support, which means that applications threads
192can simply use the VFP and ThreadX automatically maintains the VFP registers as part of the thread
193context - no additional setup by the application.
194
195
1968.  Revision History
197
198For generic code revision information, please refer to the readme_threadx_generic.txt
199file, which is included in your distribution. The following details the revision
200information associated with this specific port of ThreadX:
201
20206-02-2021  Initial ThreadX version 6.1.7 for Cortex-M using AC6 tools.
203
204
205Copyright(c) 1996-2021 Microsoft Corporation
206
207
208https://azure.com/rtos
209
210