begriffs open source - freertos/blob - portable/ThirdParty/XCC/Xtensa/xtensa_context.h

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