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

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