[PATCH v2 2/6] cpukit: Add Exception Manager

Kinsey Moore kinsey.moore at oarcorp.com
Thu Sep 23 00:16:50 UTC 2021


This adds the framework necessary to allow more generic handling of
machine exceptions. This initial patch offers the ability to get the
class of exception from the CPU_Exception_frame provided. Future
extensions of the Exception Manager could include the ability to get
the address of the exception if applicable or to resume execution at
the next instruction or an arbitrary location.
---
 cpukit/include/rtems/exception.h          | 166 ++++++++++++++++++++++
 spec/build/cpukit/cpuopts.yml             |   2 +
 spec/build/cpukit/librtemscpu.yml         |   1 +
 spec/build/cpukit/optexceptionmanager.yml |  17 +++
 4 files changed, 186 insertions(+)
 create mode 100644 cpukit/include/rtems/exception.h
 create mode 100644 spec/build/cpukit/optexceptionmanager.yml

diff --git a/cpukit/include/rtems/exception.h b/cpukit/include/rtems/exception.h
new file mode 100644
index 0000000000..89edfd02b4
--- /dev/null
+++ b/cpukit/include/rtems/exception.h
@@ -0,0 +1,166 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @brief This header file defines the Exception Manager API.
+ */
+
+/*
+ * Copyright (C) 2021 On-Line Applications Research Corporation (OAR)
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef _RTEMS_EXCEPTION_H
+#define _RTEMS_EXCEPTION_H
+
+#include <rtems/fatal.h>
+#include <rtems/score/percpu.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup RTEMSAPIClassicException Exception Manager
+ *
+ * @ingroup RTEMSAPIClassic
+ *
+ * @brief The Exception Manager processes all machine exceptions and passes
+ *   any unhandled exceptions to the Fatal Error Manager.
+ */
+
+/**
+ *  The following lists the generic exception classes supported by the Exception
+ *  Management API.
+ */
+typedef enum {
+  EXCEPTION_UNKNOWN,
+  EXCEPTION_FPU,
+  EXCEPTION_TAGGED_OVERFLOW,
+  EXCEPTION_DIV_ZERO,
+  EXCEPTION_DATA_ABORT_READ,
+  EXCEPTION_DATA_ABORT_WRITE,
+  EXCEPTION_DATA_ABORT_UNSPECIFIED,
+  EXCEPTION_INSTRUCTION_ABORT,
+  EXCEPTION_MMU_UNSPECIFIED,
+  EXCEPTION_ACCESS_ALIGNMENT,
+  EXCEPTION_SUPERVISOR,
+  EXCEPTION_TRAPPED_INSTRUCTION,
+  EXCEPTION_PC_ALIGNMENT,
+  EXCEPTION_SP_ALIGNMENT,
+  EXCEPTION_BREAKPOINT,
+  EXCEPTION_BREAK_INSTRUCTION,
+  EXCEPTION_STEP,
+  EXCEPTION_WATCHPOINT,
+  EXCEPTION_MAX
+} Exception_Class;
+
+/**
+ * @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 Exception_Manager_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 Exception_Manager_dispatch_and_resume( CPU_Exception_frame *ef );
+
+/**
+ * @brief Disables thread dispatch.
+ *
+ * This must be called before calling Exception_Manager_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.
+ */
+static inline void Exception_Manager_disable_thread_dispatch( void )
+{
+  Per_CPU_Control *cpu_self = _Per_CPU_Get();
+
+  /* Increment interrupt nest and thread dispatch disable level */
+  ++cpu_self->thread_dispatch_disable_level;
+  ++cpu_self->isr_nest_level;
+}
+
+/**
+ * @brief Retrieves the generic exception class of the machine exception.
+ *
+ * @param exception_frame The CPU_Exception_frame describing the machine
+ * exception.
+ * @return The class of exception represented by the CPU_Exception_frame.
+ */
+Exception_Class Exception_Manager_Get_class( 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 Exception_Manager_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 Exception_Manager_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 Exception_Manager_Copy_CPU_Exception_frame(
+  CPU_Exception_frame *new_ef,
+  CPU_Exception_frame *old_ef
+);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _RTEMS_EXCEPTION_H */
diff --git a/spec/build/cpukit/cpuopts.yml b/spec/build/cpukit/cpuopts.yml
index 0a07f6d5e9..5568ed1316 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: optexceptionmanager
 - role: build-dependency
   uid: optmpci
 - role: build-dependency
diff --git a/spec/build/cpukit/librtemscpu.yml b/spec/build/cpukit/librtemscpu.yml
index c0f8f6d670..6f8d223f1e 100644
--- a/spec/build/cpukit/librtemscpu.yml
+++ b/spec/build/cpukit/librtemscpu.yml
@@ -99,6 +99,7 @@ install:
   - cpukit/include/rtems/dumpbuf.h
   - cpukit/include/rtems/endian.h
   - cpukit/include/rtems/error.h
+  - cpukit/include/rtems/exception.h
   - cpukit/include/rtems/extension.h
   - cpukit/include/rtems/extensiondata.h
   - cpukit/include/rtems/extensionimpl.h
diff --git a/spec/build/cpukit/optexceptionmanager.yml b/spec/build/cpukit/optexceptionmanager.yml
new file mode 100644
index 0000000000..2188e16cf1
--- /dev/null
+++ b/spec/build/cpukit/optexceptionmanager.yml
@@ -0,0 +1,17 @@
+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 Exception Manager
+enabled-by:
+links: []
+name: RTEMS_EXCEPTION_MANAGER
+type: build
-- 
2.30.2



More information about the devel mailing list