| // Copyright 2019 The Pigweed Authors |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| // use this file except in compliance with the License. You may obtain a copy of |
| // the License at |
| // |
| // https://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| // License for the specific language governing permissions and limitations under |
| // the License. |
| #pragma once |
| |
| // Platform-independent mechanism to catch hardware CPU faults in user code. |
| // This module encapsulates low level CPU exception handling assembly for the |
| // platform. After early exception handling completes, this module invokes |
| // the following user-defined function: |
| // |
| // pw::cpu_exception::HandleCpuException(CpuState* state) |
| // |
| // If platform-dependent access to the CPU registers is needed, then |
| // applications can include the respective backend module directly; for example |
| // cpu_exception_armv7m. |
| // |
| // IMPORTANT: To use this module, you MUST implement HandleCpuException() in |
| // some part of your application. |
| |
| #include <cstdint> |
| #include <span> |
| |
| #include "pw_preprocessor/compiler.h" |
| #include "pw_string/string_builder.h" |
| |
| namespace pw::cpu_exception { |
| |
| // Forward declaration of CpuState. Definition provided by backend. |
| struct CpuState; |
| |
| // Gets raw CPU state as a single contiguous block of data. The particular |
| // contents will depend on the specific backend and platform. |
| std::span<const uint8_t> RawFaultingCpuState(const CpuState& cpu_state); |
| |
| // Writes CPU state as a formatted string to a string builder. |
| // NEVER depend on the format of this output. This is exclusively FYI human |
| // readable output. |
| void ToString(const CpuState& cpu_state, StringBuilder* builder); |
| |
| // Application-defined recoverable CPU exception handler. |
| // |
| // Applications must define this function; it is not defined by the exception |
| // handler backend. After CPU state is captured by the cpu exception backend, |
| // this function is called. Applications can then choose to either gracefully |
| // handle the issue and return, or decide the exception cannot be handled and |
| // abort normal execution (e.g. reset). |
| // |
| // Examples of what applications could do in the handler: gracefully recover |
| // (e.g. enabling a floating point unit after triggering an exception executing |
| // a floating point instruction), reset the device, or wait for a debugger to |
| // attach. |
| // |
| // See the cpu_exception module documentation for more details. |
| PW_USED void HandleCpuException(CpuState* state); |
| |
| // Low-level raw exception entry handler. |
| // |
| // Captures faulting CPU state into a platform-specific CpuState object, then |
| // calls the user-supplied HandleCpuException() fault handler. |
| // |
| // This function should be called immediately after a fault; typically by being |
| // in the interrupt vector table entries for the hard fault exceptions. |
| // |
| // Note: applications should almost never invoke this directly; if you do, make |
| // sure you know what you are doing. |
| extern "C" PW_NO_PROLOGUE void pw_CpuExceptionEntry(void); |
| |
| } // namespace pw::cpu_exception |
