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