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
