pw_cpu_exception: Split facade

The pw_cpu_exception facade is comprised of three parts: the part
implemented by the architecture, and the part implemented by the
application, and some supporting libraries that make it easier to dump
CPU state. Since these are provided independently, the facade has been
split into three facades:

 1. entry
 2. handler
 3. support

Change-Id: I48c92f42b208f79596740f1bec59ed3d29e277a8
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/11646
Commit-Queue: Armando Montanez <amontanez@google.com>
Reviewed-by: Wyatt Hepler <hepler@google.com>

Author: armandomontanez

BUILD.gn

@@ -185,7 +185,7 @@ if (current_toolchain != default_toolchain) {
     import("$dir_pw_cpu_exception/backend.gni")
 
     # TODO(pwbug/17): Re-think when Pigweed config system is added.
-    if (pw_cpu_exception_BACKEND == dir_pw_cpu_exception_armv7m) {
+    if (pw_cpu_exception_ENTRY_BACKEND == dir_pw_cpu_exception_armv7m) {
       group_deps += [ "$dir_pw_cpu_exception_armv7m:tests" ]
     }
 

pw_cpu_exception/BUILD

@@ -19,6 +19,10 @@ licenses(["notice"])  # Apache License 2.0
 filegroup(
     name = "pw_cpu_exception",
     srcs = [
-        "public/pw_cpu_exception/cpu_exception.h",
+        "basic_handler.cc",
+        "public/pw_cpu_exception/entry.h",
+        "public/pw_cpu_exception/handler.h",
+        "public/pw_cpu_exception/support.h",
+        "start_exception_handler.cc",
     ],
 )

pw_cpu_exception/BUILD.gn

@@ -22,15 +22,73 @@ config("default_config") {
   include_dirs = [ "public" ]
 }
 
-pw_facade("pw_cpu_exception") {
-  backend = pw_cpu_exception_BACKEND
+group("pw_cpu_exception") {
+  public_deps = [
+    ":entry",
+    ":handler",
+  ]
+}
+
+# This module has three facades, each of whose backends are set with a
+# different GN variable.
+#
+# - entry: This is the library that handles early exception entry and prepares
+#   any CPU state that must be available to the exception handler via the
+#   pw_CpuState object. The backend for this facade will be architecture-
+#   specific.
+#   Set this facade's backend via `pw_cpu_exception_ENTRY_BACKEND`
+#
+# - handler: This facade is backed by an application-specific handler that
+#   determines what to do when an exception is encountered. This may be
+#   capturing a crash report before resetting the device, or in some cases
+#   handling the exception to allow execution to continue.
+#   Set this facade's backend via `pw_cpu_exception_HANDLER_BACKEND`
+#
+# - support: This facade provides architecture-independent functions that may be
+#   helpful for dumping CPU state in various forms. This allows an application
+#   to create an application-specific handler that is portable across multiple
+#   architectures.
+#   Set this facade's backend via `pw_cpu_exception_SUPPORT_BACKEND`
+
+pw_facade("entry") {
+  backend = pw_cpu_exception_ENTRY_BACKEND
+  facade_name = "entry_facade"
+  public_configs = [ ":default_config" ]
+  public_deps = [ "$dir_pw_preprocessor" ]
+  deps = [ ":handler_facade" ]
+  public = [ "public/pw_cpu_exception/entry.h" ]
+}
+
+pw_facade("handler") {
+  backend = pw_cpu_exception_HANDLER_BACKEND
+  facade_name = "handler_facade"
   public_configs = [ ":default_config" ]
   public_deps = [
     "$dir_pw_preprocessor",
     "$dir_pw_span",
-    "$dir_pw_string",
   ]
-  public = [ "public/pw_cpu_exception/cpu_exception.h" ]
+  sources = [ "start_exception_handler.cc" ]
+  public = [ "public/pw_cpu_exception/handler.h" ]
+}
+
+# This library is technically optional. It is recommended to use `support` when
+# doing basic dumps of CPU state. As an alternative, projects may choose to
+# directly depend on the entry backend if they require direct access to
+# pw_CpuExceptionState members.
+pw_facade("support") {
+  backend = pw_cpu_exception_SUPPORT_BACKEND
+  facade_name = "support_facade"
+  public_configs = [ ":default_config" ]
+  public_deps = [ "$dir_pw_span" ]
+  public = [ "public/pw_cpu_exception/support.h" ]
+}
+
+pw_source_set("basic_handler") {
+  deps = [
+    ":handler_facade",
+    dir_pw_log,
+  ]
+  sources = [ "basic_handler.cc" ]
 }
 
 pw_doc_group("docs") {

pw_cpu_exception/backend.gni

@@ -14,5 +14,7 @@
 
 declare_args() {
   # Backend for the pw_cpu_exception module.
-  pw_cpu_exception_BACKEND = ""
+  pw_cpu_exception_ENTRY_BACKEND = ""
+  pw_cpu_exception_HANDLER_BACKEND = ""
+  pw_cpu_exception_SUPPORT_BACKEND = ""
 }

pw_cpu_exception/basic_handler.cc

@@ -0,0 +1,27 @@
+// Copyright 2020 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.
+#include <cstdlib>
+
+#include "pw_cpu_exception/handler.h"
+#include "pw_log/log.h"
+
+namespace pw::cpu_exception {
+
+extern "C" void pw_CpuExceptionDefaultHandler(pw_CpuExceptionState*) {
+  PW_LOG_CRITICAL("Unhandled CPU exception encountered!");
+  // TODO(pwbug/95): Replace with pw_abort when that module exists.
+  std::abort();
+}
+
+}  // namespace pw::cpu_exception

pw_cpu_exception/docs.rst

@@ -22,8 +22,8 @@ called immediately upon a CPU exception. For specifics on how this may be done,
 see the backend documentation for your architecture.
 
 Applications must also provide an implementation for
-``pw::cpu_exception::HandleCpuException()``. The behavior of this functions
-is entirely up to the application/project, but some examples are provided below:
+``pw_CpuExceptionDefaultHandler()``. The behavior of this functions is entirely
+up to the application/project, but some examples are provided below:
 
   * Enter an infinite loop so the device can be debugged by JTAG.
   * Reset the device.
@@ -35,42 +35,53 @@ is entirely up to the application/project, but some examples are provided below:
 Module Usage
 ============
 Basic usage of this module entails applications supplying a definition for
-``pw::cpu_exception::HandleCpuException()``. ``HandleCpuException()`` should
-contain any logic to determine if a exception can be recovered from, as well
-as necessary actions to properly recover. If the device cannot recover from the
+``pw_CpuExceptionDefaultHandler()``. ``pw_CpuExceptionDefaultHandler()`` should
+contain any logic to determine if a exception can be recovered from, as well as
+necessary actions to properly recover. If the device cannot recover from the
 exception, the function should **not** return.
 
+``pw_CpuExceptionDefaultHandler()`` is called indirectly, and may be overridden
+at runtime via ``pw_CpuExceptionSetHandler()``. The handler can also be reset to
+point to ``pw_CpuExceptionDefaultHandler()`` by calling
+``pw_CpuExceptionRestoreDefaultHandler()``.
+
 When writing an exception handler, prefer to use the functions provided by this
-interface rather than relying on the backend implementation of ``CpuState``.
-This allows better code portability as it helps prevent an application fault
-handler from being tied to a single backend.
+interface rather than relying on the backend implementation of
+``pw_CpuExceptionState``. This allows better code portability as it helps
+prevent an application fault handler from being tied to a single backend.
 
 For example; when logging or dumping CPU state, prefer ``ToString()`` or
-``RawFaultingCpuState()`` over directly accessing members of a ``CpuState``
-object.
+``RawFaultingCpuState()`` over directly accessing members of a
+``pw_CpuExceptionState`` object.
 
 Some exception handling behavior may require architecture-specific CPU state to
 attempt to correct a fault. In this situation, the application's exception
 handler will be tied to the backend implementation of the CPU exception module.
 
-Dependencies
-============
-  * ``pw_span``
-  * ``pw_preprocessor``
-
 Backend Expectations
 ====================
 CPU exception backends do not provide an exception handler, but instead provide
 mechanisms to capture CPU state for use by an application's exception handler,
 and allow recovery from CPU exceptions when possible.
 
-  * A backend should provide a definition for the ``CpuState`` struct that
-    provides suitable means to access and modify any captured CPU state.
+  * A backend should provide a definition for the ``pw_CpuExceptionState``
+    struct that provides suitable means to access and modify any captured CPU
+    state.
   * If an application's exception handler modifies the captured CPU state, the
     state should be treated as though it were the original state of the CPU when
     the exception occurred. The backend may need to manually restore some of the
     modified state to ensure this on exception handler return.
   * A backend should implement the ``pw_CpuExceptionEntry()`` function that will
-    call ``HandleCpuException()`` after performing any necessary actions prior
-    to handing control to the application's exception handler (e.g. capturing
-    necessary CPU state).
+    call ``pw_HandleCpuException()`` after performing any necessary
+    actions prior to handing control to the application's exception handler
+    (e.g. capturing necessary CPU state).
+
+Compatibility
+=============
+Most of the pw_cpu_exception module is C-compatible. The exception to this is
+the "support" facade and library, which requires C++.
+
+Dependencies
+============
+  * ``pw_span``
+  * ``pw_preprocessor``

pw_cpu_exception/public/pw_cpu_exception/cpu_exception.h

@@ -0,0 +1,43 @@
+// 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. By default, this module invokes the following user-defined function
+// after early exception handling completes:
+//
+//   pw_CpuExceptionDefaultHandler(pw_CpuExceptionState* 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
+//            pw_CpuExceptionDefaultHandler() in some part of your application.
+
+#include "pw_preprocessor/compiler.h"
+#include "pw_preprocessor/util.h"
+
+// Low-level raw exception entry handler.
+//
+// Captures faulting CPU state into a platform-specific pw_CpuExceptionState
+// object, then calls the user-provided 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.
+PW_EXTERN_C PW_NO_PROLOGUE void pw_CpuExceptionEntry(void);

pw_cpu_exception/public/pw_cpu_exception/entry.h

@@ -0,0 +1,55 @@
+// Copyright 2020 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
+
+#include "pw_preprocessor/compiler.h"
+#include "pw_preprocessor/util.h"
+
+PW_EXTERN_C_START
+
+// Forward declaration of pw_CpuExceptionState. Definition provided by cpu
+// exception entry backend.
+struct pw_CpuExceptionState;
+
+// By default, the exception entry function will terminate by handing execution
+// over to pw_CpuExceptionDefaultHandler(). This can be used to override the
+// current handler. This allows runtime insertion of an exception handler which
+// may also be helpful for loading a bootloader exception handler by default
+// that an application overrides.
+void pw_CpuExceptionSetHandler(void (*handler)(pw_CpuExceptionState*));
+
+// Set the exception handler to point to pw_CpuExceptionDefaultHandler().
+void pw_CpuExceptionRestoreDefaultHandler(void);
+
+// Application-defined recoverable CPU exception handler.
+//
+// Applications must define this function; it is not defined by the exception
+// entry backend. After CPU state is captured by the cpu exception entry
+// backend, this function is called. Applications can then choose to either
+// gracefully handle the exception 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 pw_CpuExceptionDefaultHandler(pw_CpuExceptionState* state);
+
+// This is the underlying function the CPU exception entry backend should call.
+// This calls the currently set handler.
+void pw_HandleCpuException(void* cpu_state);
+
+PW_EXTERN_C_END