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