1 /******************************************************************************* 2 Copyright (c) 2006-2015 Cadence Design Systems Inc. 3 4 Permission is hereby granted, free of charge, to any person obtaining 5 a copy of this software and associated documentation files (the 6 "Software"), to deal in the Software without restriction, including 7 without limitation the rights to use, copy, modify, merge, publish, 8 distribute, sublicense, and/or sell copies of the Software, and to 9 permit persons to whom the Software is furnished to do so, subject to 10 the following conditions: 11 12 The above copyright notice and this permission notice shall be included 13 in all copies or substantial portions of the Software. 14 15 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 16 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 17 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 18 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 19 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 20 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 21 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 22 -------------------------------------------------------------------------------- 23 24 XTENSA CONTEXT FRAMES AND MACROS FOR RTOS ASSEMBLER SOURCES 25 26 This header contains definitions and macros for use primarily by Xtensa 27 RTOS assembly coded source files. It includes and uses the Xtensa hardware 28 abstraction layer (HAL) to deal with config specifics. It may also be 29 included in C source files. 30 31 !! Supports only Xtensa Exception Architecture 2 (XEA2). XEA1 not supported. !! 32 33 NOTE: The Xtensa architecture requires stack pointer alignment to 16 bytes. 34 35 *******************************************************************************/ 36 37 #ifndef XTENSA_CONTEXT_H 38 #define XTENSA_CONTEXT_H 39 40 #ifdef __ASSEMBLER__ 41 #include <xtensa/coreasm.h> 42 #endif 43 44 #include <xtensa/config/tie.h> 45 #include <xtensa/corebits.h> 46 #include <xtensa/config/system.h> 47 #include <xtensa/xtruntime-frames.h> 48 49 50 /* Align a value up to nearest n-byte boundary, where n is a power of 2. */ 51 #define ALIGNUP(n, val) (((val) + (n)-1) & -(n)) 52 53 54 /* 55 ------------------------------------------------------------------------------- 56 Macros that help define structures for both C and assembler. 57 ------------------------------------------------------------------------------- 58 */ 59 60 #ifdef STRUCT_BEGIN 61 #undef STRUCT_BEGIN 62 #undef STRUCT_FIELD 63 #undef STRUCT_AFIELD 64 #undef STRUCT_END 65 #endif 66 67 #if defined(_ASMLANGUAGE) || defined(__ASSEMBLER__) 68 69 #define STRUCT_BEGIN .pushsection .text; .struct 0 70 #define STRUCT_FIELD(ctype,size,asname,name) asname: .space size 71 #define STRUCT_AFIELD(ctype,size,asname,name,n) asname: .space (size)*(n) 72 #define STRUCT_END(sname) sname##Size:; .popsection 73 74 #else 75 76 #define STRUCT_BEGIN typedef struct { 77 #define STRUCT_FIELD(ctype,size,asname,name) ctype name; 78 #define STRUCT_AFIELD(ctype,size,asname,name,n) ctype name[n]; 79 #define STRUCT_END(sname) } sname; 80 81 #endif //_ASMLANGUAGE || __ASSEMBLER__ 82 83 84 /* 85 ------------------------------------------------------------------------------- 86 INTERRUPT/EXCEPTION STACK FRAME FOR A THREAD OR NESTED INTERRUPT 87 88 A stack frame of this structure is allocated for any interrupt or exception. 89 It goes on the current stack. If the RTOS has a system stack for handling 90 interrupts, every thread stack must allow space for just one interrupt stack 91 frame, then nested interrupt stack frames go on the system stack. 92 93 The frame includes basic registers (explicit) and "extra" registers introduced 94 by user TIE or the use of the MAC16 option in the user's Xtensa config. 95 The frame size is minimized by omitting regs not applicable to user's config. 96 97 For Windowed ABI, this stack frame includes the interruptee's base save area, 98 another base save area to manage gcc nested functions, and a little temporary 99 space to help manage the spilling of the register windows. 100 ------------------------------------------------------------------------------- 101 */ 102 103 STRUCT_BEGIN 104 STRUCT_FIELD (long, 4, XT_STK_EXIT, exit) /* exit point for dispatch */ 105 STRUCT_FIELD (long, 4, XT_STK_PC, pc) /* return PC */ 106 STRUCT_FIELD (long, 4, XT_STK_PS, ps) /* return PS */ 107 STRUCT_FIELD (long, 4, XT_STK_A0, a0) 108 STRUCT_FIELD (long, 4, XT_STK_A1, a1) /* stack pointer before interrupt */ 109 STRUCT_FIELD (long, 4, XT_STK_A2, a2) 110 STRUCT_FIELD (long, 4, XT_STK_A3, a3) 111 STRUCT_FIELD (long, 4, XT_STK_A4, a4) 112 STRUCT_FIELD (long, 4, XT_STK_A5, a5) 113 STRUCT_FIELD (long, 4, XT_STK_A6, a6) 114 STRUCT_FIELD (long, 4, XT_STK_A7, a7) 115 STRUCT_FIELD (long, 4, XT_STK_A8, a8) 116 STRUCT_FIELD (long, 4, XT_STK_A9, a9) 117 STRUCT_FIELD (long, 4, XT_STK_A10, a10) 118 STRUCT_FIELD (long, 4, XT_STK_A11, a11) 119 STRUCT_FIELD (long, 4, XT_STK_A12, a12) 120 STRUCT_FIELD (long, 4, XT_STK_A13, a13) 121 STRUCT_FIELD (long, 4, XT_STK_A14, a14) 122 STRUCT_FIELD (long, 4, XT_STK_A15, a15) 123 STRUCT_FIELD (long, 4, XT_STK_SAR, sar) 124 STRUCT_FIELD (long, 4, XT_STK_EXCCAUSE, exccause) 125 STRUCT_FIELD (long, 4, XT_STK_EXCVADDR, excvaddr) 126 #if XCHAL_HAVE_LOOPS 127 STRUCT_FIELD (long, 4, XT_STK_LBEG, lbeg) 128 STRUCT_FIELD (long, 4, XT_STK_LEND, lend) 129 STRUCT_FIELD (long, 4, XT_STK_LCOUNT, lcount) 130 #endif 131 #ifndef __XTENSA_CALL0_ABI__ 132 /* Temporary space for saving stuff during window spill */ 133 STRUCT_FIELD (long, 4, XT_STK_TMP0, tmp0) 134 STRUCT_FIELD (long, 4, XT_STK_TMP1, tmp1) 135 STRUCT_FIELD (long, 4, XT_STK_TMP2, tmp2) 136 #endif 137 #ifdef XT_USE_SWPRI 138 /* Storage for virtual priority mask */ 139 STRUCT_FIELD (long, 4, XT_STK_VPRI, vpri) 140 #endif 141 #ifdef XT_USE_OVLY 142 /* Storage for overlay state */ 143 STRUCT_FIELD (long, 4, XT_STK_OVLY, ovly) 144 #endif 145 STRUCT_END(XtExcFrame) 146 147 #if defined(_ASMLANGUAGE) || defined(__ASSEMBLER__) 148 #define XT_STK_NEXT1 XtExcFrameSize 149 #else 150 #define XT_STK_NEXT1 sizeof(XtExcFrame) 151 #endif 152 153 /* Allocate extra storage if needed */ 154 #if XCHAL_EXTRA_SA_SIZE != 0 155 156 #if XCHAL_EXTRA_SA_ALIGN <= 16 157 #define XT_STK_EXTRA ALIGNUP(XCHAL_EXTRA_SA_ALIGN, XT_STK_NEXT1) 158 #else 159 /* If need more alignment than stack, add space for dynamic alignment */ 160 #define XT_STK_EXTRA (ALIGNUP(XCHAL_EXTRA_SA_ALIGN, XT_STK_NEXT1) + XCHAL_EXTRA_SA_ALIGN) 161 #endif 162 #define XT_STK_NEXT2 (XT_STK_EXTRA + XCHAL_EXTRA_SA_SIZE) 163 164 #else 165 166 #define XT_STK_NEXT2 XT_STK_NEXT1 167 168 #endif 169 170 /* 171 ------------------------------------------------------------------------------- 172 This is the frame size. Add space for 4 registers (interruptee's base save 173 area) and some space for gcc nested functions if any. 174 ------------------------------------------------------------------------------- 175 */ 176 #define XT_STK_FRMSZ (ALIGNUP(0x10, XT_STK_NEXT2) + 0x20) 177 178 179 /* 180 ------------------------------------------------------------------------------- 181 SOLICITED STACK FRAME FOR A THREAD 182 183 A stack frame of this structure is allocated whenever a thread enters the 184 RTOS kernel intentionally (and synchronously) to submit to thread scheduling. 185 It goes on the current thread's stack. 186 187 The solicited frame only includes registers that are required to be preserved 188 by the callee according to the compiler's ABI conventions, some space to save 189 the return address for returning to the caller, and the caller's PS register. 190 191 For Windowed ABI, this stack frame includes the caller's base save area. 192 193 Note on XT_SOL_EXIT field: 194 It is necessary to distinguish a solicited from an interrupt stack frame. 195 This field corresponds to XT_STK_EXIT in the interrupt stack frame and is 196 always at the same offset (0). It can be written with a code (usually 0) 197 to distinguish a solicted frame from an interrupt frame. An RTOS port may 198 opt to ignore this field if it has another way of distinguishing frames. 199 ------------------------------------------------------------------------------- 200 */ 201 202 STRUCT_BEGIN 203 #ifdef __XTENSA_CALL0_ABI__ 204 STRUCT_FIELD (long, 4, XT_SOL_EXIT, exit) 205 STRUCT_FIELD (long, 4, XT_SOL_PC, pc) 206 STRUCT_FIELD (long, 4, XT_SOL_PS, ps) 207 STRUCT_FIELD (long, 4, XT_SOL_NEXT, next) 208 STRUCT_FIELD (long, 4, XT_SOL_A12, a12) /* should be on 16-byte alignment */ 209 STRUCT_FIELD (long, 4, XT_SOL_A13, a13) 210 STRUCT_FIELD (long, 4, XT_SOL_A14, a14) 211 STRUCT_FIELD (long, 4, XT_SOL_A15, a15) 212 #else 213 STRUCT_FIELD (long, 4, XT_SOL_EXIT, exit) 214 STRUCT_FIELD (long, 4, XT_SOL_PC, pc) 215 STRUCT_FIELD (long, 4, XT_SOL_PS, ps) 216 STRUCT_FIELD (long, 4, XT_SOL_NEXT, next) 217 STRUCT_FIELD (long, 4, XT_SOL_A0, a0) /* should be on 16-byte alignment */ 218 STRUCT_FIELD (long, 4, XT_SOL_A1, a1) 219 STRUCT_FIELD (long, 4, XT_SOL_A2, a2) 220 STRUCT_FIELD (long, 4, XT_SOL_A3, a3) 221 #endif 222 STRUCT_END(XtSolFrame) 223 224 /* Size of solicited stack frame */ 225 #define XT_SOL_FRMSZ ALIGNUP(0x10, XtSolFrameSize) 226 227 228 /* 229 ------------------------------------------------------------------------------- 230 CO-PROCESSOR STATE SAVE AREA FOR A THREAD 231 232 The RTOS must provide an area per thread to save the state of co-processors 233 when that thread does not have control. Co-processors are context-switched 234 lazily (on demand) only when a new thread uses a co-processor instruction, 235 otherwise a thread retains ownership of the co-processor even when it loses 236 control of the processor. An Xtensa co-processor exception is triggered when 237 any co-processor instruction is executed by a thread that is not the owner, 238 and the context switch of that co-processor is then peformed by the handler. 239 Ownership represents which thread's state is currently in the co-processor. 240 241 Co-processors may not be used by interrupt or exception handlers. If an 242 co-processor instruction is executed by an interrupt or exception handler, 243 the co-processor exception handler will trigger a kernel panic and freeze. 244 This restriction is introduced to reduce the overhead of saving and restoring 245 co-processor state (which can be quite large) and in particular remove that 246 overhead from interrupt handlers. 247 248 The co-processor state save area may be in any convenient per-thread location 249 such as in the thread control block or above the thread stack area. It need 250 not be in the interrupt stack frame since interrupts don't use co-processors. 251 252 Along with the save area for each co-processor, two bitmasks with flags per 253 co-processor (laid out as in the CPENABLE reg) help manage context-switching 254 co-processors as efficiently as possible: 255 256 XT_CPENABLE 257 The contents of a non-running thread's CPENABLE register. 258 It represents the co-processors owned (and whose state is still needed) 259 by the thread. When a thread is preempted, its CPENABLE is saved here. 260 When a thread solicits a context-swtich, its CPENABLE is cleared - the 261 compiler has saved the (caller-saved) co-proc state if it needs to. 262 When a non-running thread loses ownership of a CP, its bit is cleared. 263 When a thread runs, it's XT_CPENABLE is loaded into the CPENABLE reg. 264 Avoids co-processor exceptions when no change of ownership is needed. 265 266 XT_CPSTORED 267 A bitmask with the same layout as CPENABLE, a bit per co-processor. 268 Indicates whether the state of each co-processor is saved in the state 269 save area. When a thread enters the kernel, only the state of co-procs 270 still enabled in CPENABLE is saved. When the co-processor exception 271 handler assigns ownership of a co-processor to a thread, it restores 272 the saved state only if this bit is set, and clears this bit. 273 274 XT_CP_CS_ST 275 A bitmask with the same layout as CPENABLE, a bit per co-processor. 276 Indicates whether callee-saved state is saved in the state save area. 277 Callee-saved state is saved by itself on a solicited context switch, 278 and restored when needed by the coprocessor exception handler. 279 Unsolicited switches will cause the entire coprocessor to be saved 280 when necessary. 281 282 XT_CP_ASA 283 Pointer to the aligned save area. Allows it to be aligned more than 284 the overall save area (which might only be stack-aligned or TCB-aligned). 285 Especially relevant for Xtensa cores configured with a very large data 286 path that requires alignment greater than 16 bytes (ABI stack alignment). 287 ------------------------------------------------------------------------------- 288 */ 289 290 #if XCHAL_CP_NUM > 0 291 292 /* Offsets of each coprocessor save area within the 'aligned save area': */ 293 #define XT_CP0_SA 0 294 #define XT_CP1_SA ALIGNUP(XCHAL_CP1_SA_ALIGN, XT_CP0_SA + XCHAL_CP0_SA_SIZE) 295 #define XT_CP2_SA ALIGNUP(XCHAL_CP2_SA_ALIGN, XT_CP1_SA + XCHAL_CP1_SA_SIZE) 296 #define XT_CP3_SA ALIGNUP(XCHAL_CP3_SA_ALIGN, XT_CP2_SA + XCHAL_CP2_SA_SIZE) 297 #define XT_CP4_SA ALIGNUP(XCHAL_CP4_SA_ALIGN, XT_CP3_SA + XCHAL_CP3_SA_SIZE) 298 #define XT_CP5_SA ALIGNUP(XCHAL_CP5_SA_ALIGN, XT_CP4_SA + XCHAL_CP4_SA_SIZE) 299 #define XT_CP6_SA ALIGNUP(XCHAL_CP6_SA_ALIGN, XT_CP5_SA + XCHAL_CP5_SA_SIZE) 300 #define XT_CP7_SA ALIGNUP(XCHAL_CP7_SA_ALIGN, XT_CP6_SA + XCHAL_CP6_SA_SIZE) 301 #define XT_CP_SA_SIZE ALIGNUP(16, XT_CP7_SA + XCHAL_CP7_SA_SIZE) 302 303 /* Offsets within the overall save area: */ 304 #define XT_CPENABLE 0 /* (2 bytes) coprocessors active for this thread */ 305 #define XT_CPSTORED 2 /* (2 bytes) coprocessors saved for this thread */ 306 #define XT_CP_CS_ST 4 /* (2 bytes) coprocessor callee-saved regs stored for this thread */ 307 #define XT_CP_ASA 8 /* (4 bytes) ptr to aligned save area */ 308 /* Overall size allows for dynamic alignment: */ 309 #define XT_CP_SIZE (12 + XT_CP_SA_SIZE + XCHAL_TOTAL_SA_ALIGN) 310 #else 311 #define XT_CP_SIZE 0 312 #endif 313 314 315 /* 316 Macro to get the current core ID. Only uses the reg given as an argument. 317 Reading PRID on the ESP32 gives us 0xCDCD on the PRO processor (0) 318 and 0xABAB on the APP CPU (1). We can distinguish between the two by checking 319 bit 13: it's 1 on the APP and 0 on the PRO processor. 320 */ 321 #ifdef __ASSEMBLER__ 322 .macro getcoreid reg 323 rsr.prid \reg 324 extui \reg,\reg,13,1 325 .endm 326 #endif 327 328 /* Note: These are different to xCoreID used in ESP-IDF FreeRTOS, most places use 329 0 and 1 which are determined by checking bit 13 (see previous comment) 330 */ 331 #define CORE_ID_REGVAL_PRO 0xCDCD 332 #define CORE_ID_REGVAL_APP 0xABAB 333 334 /* Included for compatibility, recommend using CORE_ID_REGVAL_PRO instead */ 335 #define CORE_ID_PRO CORE_ID_REGVAL_PRO 336 337 /* Included for compatibility, recommend using CORE_ID_REGVAL_APP instead */ 338 #define CORE_ID_APP CORE_ID_REGVAL_APP 339 340 /* 341 ------------------------------------------------------------------------------- 342 MACROS TO HANDLE ABI SPECIFICS OF FUNCTION ENTRY AND RETURN 343 344 Convenient where the frame size requirements are the same for both ABIs. 345 ENTRY(sz), RET(sz) are for framed functions (have locals or make calls). 346 ENTRY0, RET0 are for frameless functions (no locals, no calls). 347 348 where size = size of stack frame in bytes (must be >0 and aligned to 16). 349 For framed functions the frame is created and the return address saved at 350 base of frame (Call0 ABI) or as determined by hardware (Windowed ABI). 351 For frameless functions, there is no frame and return address remains in a0. 352 Note: Because CPP macros expand to a single line, macros requiring multi-line 353 expansions are implemented as assembler macros. 354 ------------------------------------------------------------------------------- 355 */ 356 357 #ifdef __ASSEMBLER__ 358 #ifdef __XTENSA_CALL0_ABI__ 359 /* Call0 */ 360 #define ENTRY(sz) entry1 sz 361 .macro entry1 size=0x10 362 addi sp, sp, -\size 363 s32i a0, sp, 0 364 .endm 365 #define ENTRY0 366 #define RET(sz) ret1 sz 367 .macro ret1 size=0x10 368 l32i a0, sp, 0 369 addi sp, sp, \size 370 ret 371 .endm 372 #define RET0 ret 373 #else 374 /* Windowed */ 375 #define ENTRY(sz) entry sp, sz 376 #define ENTRY0 entry sp, 0x10 377 #define RET(sz) retw 378 #define RET0 retw 379 #endif 380 #endif 381 382 383 384 385 386 #endif /* XTENSA_CONTEXT_H */ 387