new file mode 100644
@@ -0,0 +1,91 @@
+/* Copyright (c) 2013, Linaro Limited
+ * All rights reserved
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/**
+@page exception_handling Exception handling in the ODP API
+@tableofcontents
+
+For the implimentation of the exception handling please see @ref odp_debug.h
+
+@section requirements Requirements
+- Minimal overhead in a finished running system.
+- Minimizing the propagation of an error from its point of origin
+- Identifying what is a programming error
+- Identifying a legitimate infield exception
+- We only specify what happens inside the ODP library, not in a calling application
+
+There are two kinds of exceptional behaviour,
+-# Run time exceptions, those that are unusual but foreseeable cases in a running system (out of memory)
+-# Programming exceptions, those introduced as bugs (null pointers, out of bounds).
+
+@section run_time Run time exceptions
+These are characterized by the following rules in order of importance
+-# These must gracefully leave the system in a known stable state.
+-# These checks must remain unconditionally in the code base.
+-# These should return the error state to the caller.
+-# They may emit an error message via \ref ODP_ERR which can be redefined or disabled.
+
+@subsection run_time_examples Examples
+- Being "too late" to cancel a timer that's already popped, or exceeding some implementation-defined limit
+- Backpressure due to resource limits (corner case that is error-prone)
+- Checks for any condition that could arise in the field, e.g. running out of buffers or failure to allocate memory
+@code
+
+if (unrecoverable_out_of_foos == 1)
+{
+ ODP_ERR("Completely unable to proceed, no foos available");
+ tidy_up_for_exit();
+ ...
+}
+
+@endcode
+@note ODP does not trap segfaults, it may not be checking for NULL pointers etc to improve the execution speed. The application should trap segfaults.
+
+@section programming_exceptions Programming exceptions
+There are two classes of programming error
+-# Compile time, these can be caught by compile time assertions in the preprocessor
+-# Run Time, these are run time assertions
+
+@section compile_time Compile time programming exceptions
+These have the following rules
+-# Zero overhead at run time, they never need to be turned off (undefined)
+-# Use @#error which will break the build, or @#warning which may not break the build unless -Werror is defined.
+-# Can be done for any static evaluation case.
+
+@subsection compile_time_examples Examples
+Checking size and alignment of a struct with offsetof
+
+@code
+typedef struct timer timer;
+struct timer
+{
+ uint8_t MODE;
+ uint32_t DATA;
+ uint32_t COUNT;
+};
+
+ODP_STATIC_ASSERT (ODP_OFFSETOF(timer, DATA) != 4, "DATA must be at offset 4 in timer");
+
+@section compile_run_time Run time programming exceptions
+There are two rules
+-# These must be capable of being turned off by defining -DODP_NO_DEBUG
+-# They must use ODP_ASSERT so that the output may be redirected on systems without stderr.
+-# ODP_ASSERT will call abort() as its final operation.
+
+@note ODP_ASSERT is defined to make it easier to redirect output from stderr. For example
+an in memory text buffer may be in use if stderr has no meaning on a bare metal implimentation
+
+@subsection compile_run_time_examples Examples
+Checks that the API function arguments are within the permitted value range (e.g. handle validation
+
+@code
+void odp_foo(char *pointer)
+{
+ ODP_ASSERT(pointer != NULL);
+ …
+}
+@endcode
+*/
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- exception_handling.dox | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 exception_handling.dox