1 // Copyright 2020 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 #include "pw_preprocessor/compiler.h" 17 #include "pw_preprocessor/util.h" 18 19 PW_EXTERN_C_START 20 21 // Forward declaration of pw_cpu_exception_State. Definition provided by cpu 22 // exception entry backend. 23 struct pw_cpu_exception_State; 24 25 // By default, the exception entry function will terminate by handing execution 26 // over to pw_cpu_exception_DefaultHandler(). This can be used to override the 27 // current handler. This allows runtime insertion of an exception handler which 28 // may also be helpful for loading a bootloader exception handler by default 29 // that an application overrides. 30 void pw_cpu_exception_SetHandler(void (*handler)(pw_cpu_exception_State*)); 31 32 // Set the exception handler to point to pw_cpu_exception_DefaultHandler(). 33 void pw_cpu_exception_RestoreDefaultHandler(void); 34 35 // Application-defined recoverable CPU exception handler. 36 // 37 // Applications must define this function; it is not defined by the exception 38 // entry backend. After CPU state is captured by the cpu exception entry 39 // backend, this function is called. Applications can then choose to either 40 // gracefully handle the exception and return, or decide the exception cannot be 41 // handled and abort normal execution (e.g. reset). 42 // 43 // Examples of what applications could do in the handler: gracefully recover 44 // (e.g. enabling a floating point unit after triggering an exception executing 45 // a floating point instruction), reset the device, or wait for a debugger to 46 // attach. 47 // 48 // See the cpu_exception module documentation for more details. 49 PW_USED void pw_cpu_exception_DefaultHandler(pw_cpu_exception_State* state); 50 51 // This is the underlying function the CPU exception entry backend should call. 52 // This calls the currently set handler. 53 void pw_cpu_exception_HandleException(void* cpu_state); 54 55 PW_EXTERN_C_END 56