[PATCH v3 1/5] cpukit: Add exception extensions

[Kinsey Moore]

This adds the set of functions necessary to allow more generic handling
of machine exceptions. This initial patch offers the ability to
manipulate a CPU_Exception_frame and resume execution using that
exception information with or without thread dispatch. These functions
are gated behind the RTEMS_EXCEPTION_EXTENSIONS configuration option.
---
 .../cpu/no_cpu/include/rtems/score/cpu.h      | 78 +++++++++++++++++++
 spec/build/cpukit/cpuopts.yml                 |  2 +
 spec/build/cpukit/optexceptionextensions.yml  | 18 +++++
 3 files changed, 98 insertions(+)
 create mode 100644 spec/build/cpukit/optexceptionextensions.yml

diff --git a/cpukit/score/cpu/no_cpu/include/rtems/score/cpu.h b/cpukit/score/cpu/no_cpu/include/rtems/score/cpu.h
index e224a5e56e..f9afbe7243 100644
--- a/cpukit/score/cpu/no_cpu/include/rtems/score/cpu.h
+++ b/cpukit/score/cpu/no_cpu/include/rtems/score/cpu.h
@@ -1142,6 +1142,84 @@ typedef struct {
  */
 void _CPU_Exception_frame_print( const CPU_Exception_frame *frame );
 
+#ifdef RTEMS_EXCEPTION_EXTENSIONS
+  /**
+   * @brief Resumes normal execution using the provided exception frame.
+   *
+   * This routine helps to avoid dead code in the exception handler epilogue and
+   * does not return. This routine may assume that the provided pointer is valid
+   * for resetting the exception stack.
+   *
+   * @param exception_frame The CPU_Exception_frame describing the machine
+   * exception.
+   */
+  RTEMS_NO_RETURN void _CPU_Exception_resume( CPU_Exception_frame *ef );
+
+  /**
+   * @brief Performs thread dispatch and resumes normal execution.
+   *
+   * This routine helps to avoid dead code in the exception handler epilogue and
+   * does not return. This routine may assume that the provided pointer is valid
+   * for resetting the exception stack. This function is expected to decrement
+   * the ISR nest level and thread dispatch disable level in the Per_CPU_Control
+   * structure.
+   *
+   * @param exception_frame The CPU_Exception_frame describing the machine
+   * exception.
+   */
+  RTEMS_NO_RETURN void _CPU_Exception_dispatch_and_resume( CPU_Exception_frame *ef );
+
+  /**
+   * @brief Disables thread dispatch.
+   *
+   * This must be called before calling _CPU_Exception_dispatch_and_resume
+   * since that function is expected to reduce the levels incremented below.
+   *
+   * @param exception_frame The CPU_Exception_frame describing the machine
+   * exception.
+   */
+  void _CPU_Exception_disable_thread_dispatch( void );
+
+  /**
+   * @brief Retrieves the generic exception class of the machine exception.
+   *
+   * @param exception_frame The CPU_Exception_frame describing the machine
+   * exception.
+   * @return The signal associated with the CPU_Exception_frame.
+   */
+  int _CPU_Exception_frame_get_signal( CPU_Exception_frame *ef );
+
+  /**
+   * @brief Sets the execution address of the exception frame.
+   *
+   * @param exception_frame The CPU_Exception_frame describing the machine
+   * exception.
+   */
+  void _CPU_Exception_frame_set_resume( CPU_Exception_frame *ef, void *address );
+
+  /**
+   * @brief Sets the execution address of the exception frame to the next
+   * instruction.
+   *
+   * @param exception_frame The CPU_Exception_frame describing the machine
+   * exception.
+   */
+  void _CPU_Exception_frame_set_resume_next_instruction( CPU_Exception_frame *ef );
+
+  /**
+   * @brief Copies data to the new exception frame from the old exception frame.
+   *
+   * @param old_ef The existing CPU_Exception_frame describing the machine
+   * exception.
+   * @param new_ef The new CPU_Exception_frame describing the machine
+   * exception.
+   */
+  void _CPU_Exception_frame_copy(
+    CPU_Exception_frame *new_ef,
+    CPU_Exception_frame *old_ef
+  );
+#endif
+
 /**
  * @defgroup RTEMSScoreCPUExampleCPUEndian CPUEndian
  * 
diff --git a/spec/build/cpukit/cpuopts.yml b/spec/build/cpukit/cpuopts.yml
index 908c65d3b9..301d49ccea 100644
--- a/spec/build/cpukit/cpuopts.yml
+++ b/spec/build/cpukit/cpuopts.yml
@@ -39,6 +39,8 @@ links:
   uid: optdebug
 - role: build-dependency
   uid: optdrvmgr
+- role: build-dependency
+  uid: optexceptionextensions
 - role: build-dependency
   uid: optmpci
 - role: build-dependency
diff --git a/spec/build/cpukit/optexceptionextensions.yml b/spec/build/cpukit/optexceptionextensions.yml
new file mode 100644
index 0000000000..1bc6d8686f
--- /dev/null
+++ b/spec/build/cpukit/optexceptionextensions.yml
@@ -0,0 +1,18 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+actions:
+- get-boolean: null
+- env-enable: null
+- define-condition: null
+build-type: option
+copyrights:
+- Copyright (C) 2021 On-Line Applications Research (OAR)
+default: true
+default-by-family: []
+default-by-variant: []
+description: |
+  Enable the RTEMS Exception Extensions for manipulating and acting on exception
+  frames.
+enabled-by:
+links: []
+name: RTEMS_EXCEPTION_EXTENSIONS
+type: build
-- 
2.30.2