third_party/pigweed/repo/pw_cpu_exception/public/pw_cpu_exception/handler.h

   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