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