pw_cpu_exception_cortex_m: Move armv7m->cortex_m

Moves the armv7m implementation of pw_cpu_exception to
pw_cpu_exception_cortex_m since much of the logic can be shared between
ARMv8-M and ARMv7-M. Symbol names are also updated to reflect current
naming style for extern "C" symbols. Old names will be removed in
pwrev/31060.

Warning, symbol renames are breaking!
pw_CpuExceptionEntry -> pw_cpu_exception_Entry
pw_CpuExceptionDefaultHandler -> pw_cpu_exception_DefaultHandler

Change-Id: I7ab99ac7637c436ba959d7546043090c66fe4215
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/30922
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Reviewed-by: Ewout van Bekkum <ewout@google.com>
Pigweed-Auto-Submit: Armando Montanez <amontanez@google.com>

Author: armandomontanez

BUILD.gn

@@ -263,7 +263,7 @@ if (current_toolchain != default_toolchain) {
       "$dir_pw_checksum:tests",
       "$dir_pw_chrono:tests",
       "$dir_pw_containers:tests",
-      "$dir_pw_cpu_exception_armv7m:tests",
+      "$dir_pw_cpu_exception_cortex_m:tests",
       "$dir_pw_fuzzer:tests",
       "$dir_pw_hdlc:tests",
       "$dir_pw_hex_dump:tests",

CMakeLists.txt

@@ -36,7 +36,7 @@ add_subdirectory(pw_chrono EXCLUDE_FROM_ALL)
 add_subdirectory(pw_chrono_stl EXCLUDE_FROM_ALL)
 add_subdirectory(pw_containers EXCLUDE_FROM_ALL)
 add_subdirectory(pw_cpu_exception EXCLUDE_FROM_ALL)
-add_subdirectory(pw_cpu_exception_armv7m EXCLUDE_FROM_ALL)
+add_subdirectory(pw_cpu_exception_cortex_m EXCLUDE_FROM_ALL)
 add_subdirectory(pw_hdlc EXCLUDE_FROM_ALL)
 add_subdirectory(pw_kvs EXCLUDE_FROM_ALL)
 add_subdirectory(pw_log EXCLUDE_FROM_ALL)

README.md

@@ -122,7 +122,7 @@ on-device.
 See the "Module Guides" in the documentation for the complete list and
 documentation for each, but is a selection of some others:
 
- - `pw_cpu_exception_armv7m`: Robust low level hardware fault handler for ARM
+ - `pw_cpu_exception_cortex_m`: Robust low level hardware fault handler for ARM
    Cortex-M; the handler even has unit tests written in assembly to verify
    nested-hardware-fault handling!
 

docs/BUILD.gn

@@ -65,7 +65,7 @@ group("module_docs") {
     "$dir_pw_cli:docs",
     "$dir_pw_containers:docs",
     "$dir_pw_cpu_exception:docs",
-    "$dir_pw_cpu_exception_armv7m:docs",
+    "$dir_pw_cpu_exception_cortex_m:docs",
     "$dir_pw_docgen:docs",
     "$dir_pw_doctor:docs",
     "$dir_pw_env_setup:docs",

pw_cpu_exception/BUILD.gn

@@ -69,7 +69,7 @@ pw_facade("handler") {
 # 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_cpu_exception_State members.
 pw_facade("support") {
   backend = pw_cpu_exception_SUPPORT_BACKEND
   public_configs = [ ":default_config" ]

pw_cpu_exception/basic_handler.cc

@@ -18,7 +18,7 @@
 
 namespace pw::cpu_exception {
 
-extern "C" void pw_CpuExceptionDefaultHandler(pw_CpuExceptionState*) {
+extern "C" void pw_cpu_exception_DefaultHandler(pw_cpu_exception_State*) {
   PW_LOG_CRITICAL("Unhandled CPU exception encountered!");
   // TODO(pwbug/95): Replace with pw_abort when that module exists.
   std::abort();

pw_cpu_exception/docs.rst

@@ -12,13 +12,13 @@ otherwise be clobbered by an application's exception handler.
 
 Setup
 =====
-An application using this module **must** connect ``pw_CpuExceptionEntry()`` to
-the platform's CPU exception handler interrupt so ``pw_CpuExceptionEntry()`` is
+An application using this module **must** connect ``pw_cpu_exception_Entry()`` to
+the platform's CPU exception handler interrupt so ``pw_cpu_exception_Entry()`` is
 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_CpuExceptionDefaultHandler()``. The behavior of this functions is entirely
+``pw_cpu_exception_DefaultHandler()``. 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.
@@ -31,24 +31,24 @@ 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_CpuExceptionDefaultHandler()``. ``pw_CpuExceptionDefaultHandler()`` should
+``pw_cpu_exception_DefaultHandler()``. ``pw_cpu_exception_DefaultHandler()`` 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()``.
+``pw_cpu_exception_DefaultHandler()`` is called indirectly, and may be overridden
+at runtime via ``pw_cpu_exception_SetHandler()``. The handler can also be reset to
+point to ``pw_cpu_exception_DefaultHandler()`` by calling
+``pw_cpu_exception_RestoreDefaultHandler()``.
 
 When writing an exception handler, prefer to use the functions provided by this
 interface rather than relying on the backend implementation of
-``pw_CpuExceptionState``. This allows better code portability as it helps
+``pw_cpu_exception_State``. 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
-``pw_CpuExceptionState`` object.
+``pw_cpu_exception_State`` object.
 
 Some exception handling behavior may require architecture-specific CPU state to
 attempt to correct a fault. In this situation, the application's exception
@@ -60,15 +60,15 @@ 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 ``pw_CpuExceptionState``
+  * A backend should provide a definition for the ``pw_cpu_exception_State``
     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 ``pw_HandleCpuException()`` after performing any necessary
+  * A backend should implement the ``pw_cpu_exception_Entry()`` function that will
+    call ``pw_cpu_exception_HandleException()`` after performing any necessary
     actions prior to handing control to the application's exception handler
     (e.g. capturing necessary CPU state).
 

pw_cpu_exception/public/pw_cpu_exception/entry.h

@@ -18,26 +18,30 @@
 // platform. By default, this module invokes the following user-defined function
 // after early exception handling completes:
 //
-//   pw_CpuExceptionDefaultHandler(pw_CpuExceptionState* state)
+//   pw_cpu_exception_DefaultHandler(pw_cpu_exception_State* 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.
+//            pw_cpu_exception_DefaultHandler() 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
+// Captures faulting CPU state into a platform-specific pw_cpu_exception_State
 // 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_cpu_exception_Entry(void);
+
+// TODO(pwbug/311) Deprecated naming.
 PW_EXTERN_C PW_NO_PROLOGUE void pw_CpuExceptionEntry(void);

pw_cpu_exception/public/pw_cpu_exception/handler.h

@@ -18,19 +18,19 @@
 
 PW_EXTERN_C_START
 
-// Forward declaration of pw_CpuExceptionState. Definition provided by cpu
+// Forward declaration of pw_cpu_exception_State. Definition provided by cpu
 // exception entry backend.
-struct pw_CpuExceptionState;
+struct pw_cpu_exception_State;
 
 // By default, the exception entry function will terminate by handing execution
-// over to pw_CpuExceptionDefaultHandler(). This can be used to override the
+// over to pw_cpu_exception_DefaultHandler(). 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*));
+void pw_cpu_exception_SetHandler(void (*handler)(pw_cpu_exception_State*));
 
-// Set the exception handler to point to pw_CpuExceptionDefaultHandler().
-void pw_CpuExceptionRestoreDefaultHandler(void);
+// Set the exception handler to point to pw_cpu_exception_DefaultHandler().
+void pw_cpu_exception_RestoreDefaultHandler(void);
 
 // Application-defined recoverable CPU exception handler.
 //
@@ -46,10 +46,19 @@ void pw_CpuExceptionRestoreDefaultHandler(void);
 // attach.
 //
 // See the cpu_exception module documentation for more details.
-PW_USED void pw_CpuExceptionDefaultHandler(pw_CpuExceptionState* state);
+PW_USED void pw_cpu_exception_DefaultHandler(pw_cpu_exception_State* 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);
+void pw_cpu_exception_HandleException(void* cpu_state);
+
+// TODO(pwbug/311) Deprecated naming.
+typedef pw_cpu_exception_State pw_CpuExceptionState;
+#define pw_CpuExceptionSetHandler(...) pw_cpu_exception_SetHandler(__VA_ARGS__)
+#define pw_CpuExceptionRestoreDefaultHandler(...) \
+  pw_cpu_exception_RestoreDefaultHandler(__VA_ARGS__)
+#define pw_CpuExceptionDefaultHandler(...) \
+  pw_cpu_exception_DefaultHandler(__VA_ARGS__)
+#define pw_HandleCpuException(...) pw_cpu_exception_HandleException(__VA_ARGS__)
 
 PW_EXTERN_C_END

pw_cpu_exception/public/pw_cpu_exception/support.h

@@ -13,32 +13,36 @@
 // the License.
 
 // This facade provides an API for capturing the contents of a
-// pw_CpuExceptionState struct in a platform-agnostic way. While this facade
+// pw_cpu_exception_State struct in a platform-agnostic way. While this facade
 // does not provide a means to directly access individual members of a
-// pw_CpuExceptionState object, it does allow dumping CPU state without needing
-// to know any specifics about the underlying architecture.
+// pw_cpu_exception_State object, it does allow dumping CPU state without
+// needing to know any specifics about the underlying architecture.
 #pragma once
 
 #include <cstdint>
 #include <span>
 
-// Forward declaration of pw_CpuExceptionState. Definition provided by backend.
-struct pw_CpuExceptionState;
+// Forward declaration of pw_cpu_exception_State. Definition provided by
+// backend.
+struct pw_cpu_exception_State;
+
+// TODO(pwbug/311) Deprecated naming.
+typedef pw_cpu_exception_State pw_CpuExceptionState;
 
 namespace pw::cpu_exception {
 
 // 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 pw_CpuExceptionState& cpu_state);
+    const pw_cpu_exception_State& 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 pw_CpuExceptionState& cpu_state,
+void ToString(const pw_cpu_exception_State& cpu_state,
               const std::span<char>& dest);
 
 // Logs captured CPU state using pw_log at PW_LOG_LEVEL_INFO.
-void LogCpuState(const pw_CpuExceptionState& cpu_state);
+void LogCpuState(const pw_cpu_exception_State& cpu_state);
 
 }  // namespace pw::cpu_exception

pw_cpu_exception/start_exception_handler.cc

@@ -16,21 +16,21 @@
 
 namespace pw::cpu_exception {
 
-static void (*exception_handler)(pw_CpuExceptionState*) =
-    &pw_CpuExceptionDefaultHandler;
+static void (*exception_handler)(pw_cpu_exception_State*) =
+    &pw_cpu_exception_DefaultHandler;
 
-extern "C" void pw_CpuExceptionSetHandler(
-    void (*handler)(pw_CpuExceptionState*)) {
+extern "C" void pw_cpu_exception_SetHandler(
+    void (*handler)(pw_cpu_exception_State*)) {
   exception_handler = handler;
 }
 
-// Revert the exception handler to point to pw_CpuExceptionDefaultHandler().
-extern "C" void pw_CpuExceptionRestoreDefaultHandler() {
-  exception_handler = &pw_CpuExceptionDefaultHandler;
+// Revert the exception handler to point to pw_cpu_exception_DefaultHandler().
+extern "C" void pw_cpu_exception_RestoreDefaultHandler() {
+  exception_handler = &pw_cpu_exception_DefaultHandler;
 }
 
-extern "C" void pw_HandleCpuException(void* cpu_state) {
-  exception_handler(reinterpret_cast<pw_CpuExceptionState*>(cpu_state));
+extern "C" void pw_cpu_exception_HandleException(void* cpu_state) {
+  exception_handler(reinterpret_cast<pw_cpu_exception_State*>(cpu_state));
 }
 
 }  // namespace pw::cpu_exception

pw_cpu_exception_armv7m/BUILD

@@ -19,16 +19,8 @@ licenses(["notice"])  # Apache License 2.0
 filegroup(
     name = "pw_cpu_exception_armv7m",
     srcs = [
-        "entry.cc",
-        "cpu_state.cc",
-        "proto_dump.cc",
         "public/pw_cpu_exception_armv7m/cpu_state.h",
         "public/pw_cpu_exception_armv7m/proto_dump.h",
         "pw_cpu_exception_armv7m_private/cortex_m_constants.h",
     ],
 )
-
-filegroup(
-    name = "pw_cpu_exception_armv7m_test",
-    srcs = ["exception_entry_test.cc"],
-)

pw_cpu_exception_armv7m/BUILD.gn

@@ -15,10 +15,6 @@
 import("//build_overrides/pigweed.gni")
 
 import("$dir_pw_build/target_types.gni")
-import("$dir_pw_cpu_exception/backend.gni")
-import("$dir_pw_docgen/docs.gni")
-import("$dir_pw_protobuf_compiler/proto.gni")
-import("$dir_pw_unit_test/test.gni")
 
 config("default_config") {
   include_dirs = [ "public" ]
@@ -27,60 +23,20 @@ config("default_config") {
 
 pw_source_set("support") {
   public_configs = [ ":default_config" ]
-  public_deps = [
-    "$dir_pw_cpu_exception:support.facade",
-    dir_pw_preprocessor,
-    dir_pw_string,
-  ]
-  deps = [ dir_pw_log ]
+  public_deps = [ "$dir_pw_cpu_exception_cortex_m:support_armv7m" ]
   public = [ "public/pw_cpu_exception_armv7m/cpu_state.h" ]
-  sources = [
-    "cpu_state.cc",
-    "pw_cpu_exception_armv7m_private/cortex_m_constants.h",
-  ]
 }
 
 pw_source_set("proto_dump") {
-  public_deps = [
-    ":support",
-    dir_pw_protobuf,
-    dir_pw_status,
-    dir_pw_stream,
-  ]
+  public_configs = [ ":default_config" ]
+  public_deps = [ "$dir_pw_cpu_exception_cortex_m:proto_dump_armv7m" ]
   public = [ "public/pw_cpu_exception_armv7m/proto_dump.h" ]
-  deps = [ ":cpu_state_protos.pwpb" ]
-  sources = [ "proto_dump.cc" ]
-}
-
-pw_proto_library("cpu_state_protos") {
-  sources = [ "pw_cpu_exception_armv7m_protos/cpu_state.proto" ]
 }
 
 pw_source_set("pw_cpu_exception_armv7m") {
-  public_configs = [ ":default_config" ]
   public_deps = [
     ":proto_dump",
     ":support",
-    "$dir_pw_cpu_exception:entry.facade",
-    "$dir_pw_cpu_exception:handler",
-    "$dir_pw_preprocessor",
-  ]
-  sources = [
-    "entry.cc",
-    "pw_cpu_exception_armv7m_private/cortex_m_constants.h",
+    "$dir_pw_cpu_exception_cortex_m:cpu_exception_armv7m",
   ]
 }
-
-pw_test_group("tests") {
-  enable_if = pw_cpu_exception_ENTRY_BACKEND == dir_pw_cpu_exception_armv7m
-  tests = [ ":cpu_exception_entry_test" ]
-}
-
-pw_test("cpu_exception_entry_test") {
-  deps = [ ":pw_cpu_exception_armv7m" ]
-  sources = [ "exception_entry_test.cc" ]
-}
-
-pw_doc_group("docs") {
-  sources = [ "docs.rst" ]
-}

pw_cpu_exception_armv7m/CMakeLists.txt

@@ -1,4 +1,4 @@
-# Copyright 2020 The Pigweed Authors
+# Copyright 2021 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
@@ -15,6 +15,6 @@
 include($ENV{PW_ROOT}/pw_build/pigweed.cmake)
 
 pw_auto_add_simple_module(pw_cpu_exception_armv7m
-  IMPLEMENTS_FACADE
-    pw_cpu_exception
+  PUBLIC_DEPS
+    pw_cpu_exception_cortex_m
 )