begriffs open source - freertos/blob - portable/ThirdParty/GCC/Xtensa_ESP32/include/xtensa_rtos.h

   1 /*\r
   2  * FreeRTOS Kernel V10.4.4\r
   3  * Copyright (C) 2003-2015 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 *\r
  32 *       RTOS-SPECIFIC INFORMATION FOR XTENSA RTOS ASSEMBLER SOURCES\r
  33 *                           (FreeRTOS Port)\r
  34 *\r
  35 *  This header is the primary glue between generic Xtensa RTOS support\r
  36 *  sources and a specific RTOS port for Xtensa.  It contains definitions\r
  37 *  and macros for use primarily by Xtensa assembly coded source files.\r
  38 *\r
  39 *  Macros in this header map callouts from generic Xtensa files to specific\r
  40 *  RTOS functions. It may also be included in C source files.\r
  41 *\r
  42 *  Xtensa RTOS ports support all RTOS-compatible configurations of the Xtensa\r
  43 *  architecture, using the Xtensa hardware abstraction layer (HAL) to deal\r
  44 *  with configuration specifics.\r
  45 *\r
  46 *  Should be included by all Xtensa generic and RTOS port-specific sources.\r
  47 *\r
  48 *******************************************************************************/\r
  49 \r
  50 #ifndef XTENSA_RTOS_H\r
  51 #define XTENSA_RTOS_H\r
  52 \r
  53 #ifdef __ASSEMBLER__\r
  54     #include    <xtensa/coreasm.h>\r
  55 #else\r
  56     #include    <xtensa/config/core.h>\r
  57 #endif\r
  58 \r
  59 #include    <xtensa/corebits.h>\r
  60 #include    <xtensa/config/system.h>\r
  61 \r
  62 /*\r
  63  * Include any RTOS specific definitions that are needed by this header.\r
  64  */\r
  65 #include    "FreeRTOSConfig.h"\r
  66 \r
  67 /*\r
  68  * Convert FreeRTOSConfig definitions to XTENSA definitions.\r
  69  * However these can still be overridden from the command line.\r
  70  */\r
  71 \r
  72 #ifndef XT_SIMULATOR\r
  73     #if configXT_SIMULATOR\r
  74         #define XT_SIMULATOR    1       /* Simulator mode */\r
  75     #endif\r
  76 #endif\r
  77 \r
  78 #ifndef XT_BOARD\r
  79     #if configXT_BOARD\r
  80         #define XT_BOARD    1           /* Board mode */\r
  81     #endif\r
  82 #endif\r
  83 \r
  84 #ifndef XT_TIMER_INDEX\r
  85     #if defined configXT_TIMER_INDEX\r
  86         #define XT_TIMER_INDEX    configXT_TIMER_INDEX     /* Index of hardware timer to be used */\r
  87     #endif\r
  88 #endif\r
  89 \r
  90 #ifndef XT_INTEXC_HOOKS\r
  91     #if configXT_INTEXC_HOOKS\r
  92         #define XT_INTEXC_HOOKS    1    /* Enables exception hooks */\r
  93     #endif\r
  94 #endif\r
  95 \r
  96 #if !defined( XT_SIMULATOR ) && !defined( XT_BOARD )\r
  97     #error Either XT_SIMULATOR or XT_BOARD must be defined.\r
  98 #endif\r
  99 \r
 100 \r
 101 /*\r
 102  * Name of RTOS (for messages).\r
 103  */\r
 104 #define XT_RTOS_NAME    FreeRTOS\r
 105 \r
 106 /*\r
 107  * Check some Xtensa configuration requirements and report error if not met.\r
 108  * Error messages can be customize to the RTOS port.\r
 109  */\r
 110 \r
 111 #if !XCHAL_HAVE_XEA2\r
 112     #error "FreeRTOS/Xtensa requires XEA2 (exception architecture 2)."\r
 113 #endif\r
 114 \r
 115 \r
 116 /*******************************************************************************\r
 117 *\r
 118 *  RTOS CALLOUT MACROS MAPPED TO RTOS PORT-SPECIFIC FUNCTIONS.\r
 119 *\r
 120 *  Define callout macros used in generic Xtensa code to interact with the RTOS.\r
 121 *  The macros are simply the function names for use in calls from assembler code.\r
 122 *  Some of these functions may call back to generic functions in xtensa_context.h .\r
 123 *\r
 124 *******************************************************************************/\r
 125 \r
 126 /*\r
 127  * Inform RTOS of entry into an interrupt handler that will affect it.\r
 128  * Allows RTOS to manage switch to any system stack and count nesting level.\r
 129  * Called after minimal context has been saved, with interrupts disabled.\r
 130  * RTOS port can call0 _xt_context_save to save the rest of the context.\r
 131  * May only be called from assembly code by the 'call0' instruction.\r
 132  */\r
 133 /* void XT_RTOS_INT_ENTER(void) */\r
 134 #define XT_RTOS_INT_ENTER    _frxt_int_enter\r
 135 \r
 136 /*\r
 137  * Inform RTOS of completion of an interrupt handler, and give control to\r
 138  * RTOS to perform thread/task scheduling, switch back from any system stack\r
 139  * and restore the context, and return to the exit dispatcher saved in the\r
 140  * stack frame at XT_STK_EXIT. RTOS port can call0 _xt_context_restore\r
 141  * to save the context saved in XT_RTOS_INT_ENTER via _xt_context_save,\r
 142  * leaving only a minimal part of the context to be restored by the exit\r
 143  * dispatcher. This function does not return to the place it was called from.\r
 144  * May only be called from assembly code by the 'call0' instruction.\r
 145  */\r
 146 /* void XT_RTOS_INT_EXIT(void) */\r
 147 #define XT_RTOS_INT_EXIT    _frxt_int_exit\r
 148 \r
 149 /*\r
 150  * Inform RTOS of the occurrence of a tick timer interrupt.\r
 151  * If RTOS has no tick timer, leave XT_RTOS_TIMER_INT undefined.\r
 152  * May be coded in or called from C or assembly, per ABI conventions.\r
 153  * RTOS may optionally define XT_TICK_PER_SEC in its own way (eg. macro).\r
 154  */\r
 155 /* void XT_RTOS_TIMER_INT(void) */\r
 156 #define XT_RTOS_TIMER_INT    _frxt_timer_int\r
 157 #define XT_TICK_PER_SEC      configTICK_RATE_HZ\r
 158 \r
 159 /*\r
 160  * Return in a15 the base address of the co-processor state save area for the\r
 161  * thread that triggered a co-processor exception, or 0 if no thread was running.\r
 162  * The state save area is structured as defined in xtensa_context.h and has size\r
 163  * XT_CP_SIZE. Co-processor instructions should only be used in thread code, never\r
 164  * in interrupt handlers or the RTOS kernel. May only be called from assembly code\r
 165  * and by the 'call0' instruction. A result of 0 indicates an unrecoverable error.\r
 166  * The implementation may use only a2-4, a15 (all other regs must be preserved).\r
 167  */\r
 168 /* void* XT_RTOS_CP_STATE(void) */\r
 169 #define XT_RTOS_CP_STATE    _frxt_task_coproc_state\r
 170 \r
 171 \r
 172 /*******************************************************************************\r
 173 *\r
 174 *  HOOKS TO DYNAMICALLY INSTALL INTERRUPT AND EXCEPTION HANDLERS PER LEVEL.\r
 175 *\r
 176 *  This Xtensa RTOS port provides hooks for dynamically installing exception\r
 177 *  and interrupt handlers to facilitate automated testing where each test\r
 178 *  case can install its own handler for user exceptions and each interrupt\r
 179 *  priority (level). This consists of an array of function pointers indexed\r
 180 *  by interrupt priority, with index 0 being the user exception handler hook.\r
 181 *  Each entry in the array is initially 0, and may be replaced by a function\r
 182 *  pointer of type XT_INTEXC_HOOK. A handler may be uninstalled by installing 0.\r
 183 *\r
 184 *  The handler for low and medium priority obeys ABI conventions so may be coded\r
 185 *  in C. For the exception handler, the cause is the contents of the EXCCAUSE\r
 186 *  reg, and the result is -1 if handled, else the cause (still needs handling).\r
 187 *  For interrupt handlers, the cause is a mask of pending enabled interrupts at\r
 188 *  that level, and the result is the same mask with the bits for the handled\r
 189 *  interrupts cleared (those not cleared still need handling). This allows a test\r
 190 *  case to either pre-handle or override the default handling for the exception\r
 191 *  or interrupt level (see xtensa_vectors.S).\r
 192 *\r
 193 *  High priority handlers (including NMI) must be coded in assembly, are always\r
 194 *  called by 'call0' regardless of ABI, must preserve all registers except a0,\r
 195 *  and must not use or modify the interrupted stack. The hook argument 'cause'\r
 196 *  is not passed and the result is ignored, so as not to burden the caller with\r
 197 *  saving and restoring a2 (it assumes only one interrupt per level - see the\r
 198 *  discussion in high priority interrupts in xtensa_vectors.S). The handler\r
 199 *  therefore should be coded to prototype 'void h(void)' even though it plugs\r
 200 *  into an array of handlers of prototype 'unsigned h(unsigned)'.\r
 201 *\r
 202 *  To enable interrupt/exception hooks, compile the RTOS with '-DXT_INTEXC_HOOKS'.\r
 203 *\r
 204 *******************************************************************************/\r
 205 \r
 206 #define XT_INTEXC_HOOK_NUM    ( 1 + XCHAL_NUM_INTLEVELS + XCHAL_HAVE_NMI )\r
 207 \r
 208 #ifndef __ASSEMBLER__\r
 209     typedef unsigned (* XT_INTEXC_HOOK)( unsigned cause );\r
 210     extern volatile XT_INTEXC_HOOK _xt_intexc_hooks[ XT_INTEXC_HOOK_NUM ];\r
 211 #endif\r
 212 \r
 213 \r
 214 /*******************************************************************************\r
 215 *\r
 216 *  CONVENIENCE INCLUSIONS.\r
 217 *\r
 218 *  Ensures RTOS specific files need only include this one Xtensa-generic header.\r
 219 *  These headers are included last so they can use the RTOS definitions above.\r
 220 *\r
 221 *******************************************************************************/\r
 222 \r
 223 #include    "xtensa_context.h"\r
 224 \r
 225 #ifdef XT_RTOS_TIMER_INT\r
 226     #include    "xtensa_timer.h"\r
 227 #endif\r
 228 \r
 229 \r
 230 /*******************************************************************************\r
 231 *\r
 232 *  Xtensa Port Version.\r
 233 *\r
 234 *******************************************************************************/\r
 235 \r
 236 #define XTENSA_PORT_VERSION           1.4 .2\r
 237 #define XTENSA_PORT_VERSION_STRING    "1.4.2"\r
 238 \r
 239 #endif /* XTENSA_RTOS_H */\r