| Message ID | 1397644580-5709-2-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
On 04/16/2014 02:36 PM, Mike Holmes wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > exception_handling.dox | 119 +++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 119 insertions(+) > create mode 100644 exception_handling.dox > > diff --git a/exception_handling.dox b/exception_handling.dox > new file mode 100644 > index 0000000..2645caa > --- /dev/null > +++ b/exception_handling.dox How about to putting it to Documentation directory? > @@ -0,0 +1,119 @@ > +/* > +Copyright (c) 2014, Linaro Limited > +All rights reserved. > + > +Redistribution and use in source and binary forms, with or without > +modification, are permitted provided that the following conditions are met: > + > + * Redistributions of source code must retain the above copyright notice, this > + list of conditions and the following disclaimer. > + > + * 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. > + > + * Neither the name of Linaro Limited nor the names of its contributors may be > + used to endorse or promote products derived from this software without specific > + prior written permission. > + > +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 HOLDER 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. > +*/ will this comment be in generated documentation? If not then it's better to change it to spdx header. > + > +/** > +@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. Do we need to allocate some static buffer for error message and make ODP_ERR fill some message to that buffer? For example snort has error_buf[] to be passed from modules to core program to print readable error. Similar to perror(). > + > +@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_op_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;} does "}" at the end of line needed? > +struct timer > +{ > + uint8_t MODE; > + uint32_t DATA; > + uint32_t COUNT; > +}; > + > + > +#if (offsetof(timer, DATA) != 4)} same "}" here. > +#error DATA must be at offset 4 in timer > +#endif > +@endcode > + > +@section compile_run_time Run time programming exceptions > +There are two rules > +-# These must be capable of being turned off by defining -DNODP_DEBUG -DNOUDO_DEBUG should be changed to "without -DODP_DEBUG=1" include/odp_debug.h #define ODP_DBG(fmt, ...) \ do { if (ODP_DEBUG == 1) printf(fmt, ##__VA_ARGS__); } while (0) #define ODP_ERR(fmt, ...) \ fprintf(stderr, "%s:%d:%s(): " fmt, __FILE__, \ __LINE__, __func__, ##__VA_ARGS__) > +-# 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); assert() - abort the program if assertion is false, so: ODP_ASSERT(pointer); Best regards, Maxim. > + … > +} > +@endcode > +*/
On 16 April 2014 07:06, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > On 04/16/2014 02:36 PM, Mike Holmes wrote: > >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> exception_handling.dox | 119 ++++++++++++++++++++++++++++++ >> +++++++++++++++++++ >> 1 file changed, 119 insertions(+) >> create mode 100644 exception_handling.dox >> >> diff --git a/exception_handling.dox b/exception_handling.dox >> new file mode 100644 >> index 0000000..2645caa >> --- /dev/null >> +++ b/exception_handling.dox >> > > How about to putting it to Documentation directory? It is in its own repo, I don't think we want to mix the code with the architecture doc, however I already proved that if you do point the API doc at this source as well, it combines them seamlessly and add all the links, making a very powerful combined document, the nightly regression builds will do this. > > @@ -0,0 +1,119 @@ >> +/* >> +Copyright (c) 2014, Linaro Limited >> +All rights reserved. >> + >> +Redistribution and use in source and binary forms, with or without >> +modification, are permitted provided that the following conditions are >> met: >> + >> + * Redistributions of source code must retain the above copyright >> notice, this >> + list of conditions and the following disclaimer. >> + >> + * 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. >> + >> + * Neither the name of Linaro Limited nor the names of its >> contributors may be >> + used to endorse or promote products derived from this software >> without specific >> + prior written permission. >> + >> +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 HOLDER 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. >> +*/ >> > will this comment be in generated documentation? If not then it's better > to change it to spdx header. I can do that. > > + >> +/** >> +@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. >> > Do we need to allocate some static buffer for error message and make > ODP_ERR fill some message to that buffer? > For example snort has error_buf[] to be passed from modules to core program > to print readable error. Similar to perror(). That is an alternative implementation up to the application writer, should we just keep the example simple with printf ? This is just the Arch doc, so we and make as many implementations as we like. > > + >> +@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_op_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;} >> > does "}" at the end of line needed? > > +struct timer >> +{ >> + uint8_t MODE; >> + uint32_t DATA; >> + uint32_t COUNT; >> +}; >> + >> + >> +#if (offsetof(timer, DATA) != 4)} >> > same "}" here. > Yes looks like a typo, just shows you should compile even pseudo code > examples :), will fix > >> +#error DATA must be at offset 4 in timer >> +#endif >> +@endcode >> + >> +@section compile_run_time Run time programming exceptions >> +There are two rules >> +-# These must be capable of being turned off by defining -DNODP_DEBUG >> > -DNOUDO_DEBUG should be changed to "without -DODP_DEBUG=1" > Those semantics then don't match the usual -NDEBUG do they? > > include/odp_debug.h > #define ODP_DBG(fmt, ...) \ > do { if (ODP_DEBUG == 1) printf(fmt, ##__VA_ARGS__); } while (0) > #define ODP_ERR(fmt, ...) \ > fprintf(stderr, "%s:%d:%s(): " fmt, __FILE__, \ > __LINE__, __func__, ##__VA_ARGS__) > > > +-# 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); >> > assert() - abort the program if assertion is false, so: > ODP_ASSERT(pointer); > > Assertions are comments that do not become outdated. They document which theoretical states are intended, and which states should not occur. if you read "ODP_ASSERT(pointer);" in English it does not actually say what you are asserting to be true, however ODP_ASSERT(pointer != NULL); says I make the assertion that this pointer is not null Best regards, > Maxim. > >> + … >> +} >> +@endcode >> +*/ >> > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
On 04/16/2014 03:28 PM, Mike Holmes wrote: > > > > On 16 April 2014 07:06, Maxim Uvarov <maxim.uvarov@linaro.org > <mailto:maxim.uvarov@linaro.org>> wrote: > > On 04/16/2014 02:36 PM, Mike Holmes wrote: > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org > <mailto:mike.holmes@linaro.org>> > --- > exception_handling.dox | 119 > +++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 119 insertions(+) > create mode 100644 exception_handling.dox > > diff --git a/exception_handling.dox b/exception_handling.dox > new file mode 100644 > index 0000000..2645caa > --- /dev/null > +++ b/exception_handling.dox > > > How about to putting it to Documentation directory? > > > It is in its own repo, I don't think we want to mix the code with the > architecture doc, however I already proved that if you do point the > API doc at this source as well, it combines them seamlessly and add > all the links, making a very powerful combined document, the nightly > regression builds will do this. > > > @@ -0,0 +1,119 @@ > +/* > +Copyright (c) 2014, Linaro Limited > +All rights reserved. > + > +Redistribution and use in source and binary forms, with or > without > +modification, are permitted provided that the following > conditions are met: > + > + * Redistributions of source code must retain the above > copyright notice, this > + list of conditions and the following disclaimer. > + > + * 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. > + > + * Neither the name of Linaro Limited nor the names of its > contributors may be > + used to endorse or promote products derived from this > software without specific > + prior written permission. > + > +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 HOLDER 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. > +*/ > > will this comment be in generated documentation? If not then it's > better to change it to spdx header. > > > I can do that. > > > + > +/** > +@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. > > Do we need to allocate some static buffer for error message and > make ODP_ERR fill some message to that buffer? > > > For example snort has error_buf[] to be passed from modules to > core program to print readable error. Similar to perror(). > > That is an alternative implementation up to the application writer, > should we just keep the example simple with printf ? This is just the > Arch doc, so we and make as many implementations as we like. > > > + > +@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_op_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;} > > does "}" at the end of line needed? > > +struct timer > +{ > + uint8_t MODE; > + uint32_t DATA; > + uint32_t COUNT; > +}; > + > + > +#if (offsetof(timer, DATA) != 4)} > > same "}" here. > Yes looks like a typo, just shows you should compile even pseudo > code examples :), will fix > > +#error DATA must be at offset 4 in timer > +#endif > +@endcode > + > +@section compile_run_time Run time programming exceptions > +There are two rules > +-# These must be capable of being turned off by defining > -DNODP_DEBUG > > -DNOUDO_DEBUG should be changed to "without -DODP_DEBUG=1" > > Those semantics then don't match the usual -NDEBUG do they? > > > include/odp_debug.h > #define ODP_DBG(fmt, ...) \ > do { if (ODP_DEBUG == 1) printf(fmt, ##__VA_ARGS__); } > while (0) > #define ODP_ERR(fmt, ...) \ > fprintf(stderr, "%s:%d:%s(): " fmt, __FILE__, \ > __LINE__, __func__, ##__VA_ARGS__) > > > +-# 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); > > assert() - abort the program if assertion is false, so: > ODP_ASSERT(pointer); > > Assertions are comments that do not become outdated. They document > which theoretical states are intended, and which states should not occur. > if you read "ODP_ASSERT(pointer);" in English it does not actually say > what you are asserting to be true, however > ODP_ASSERT(pointer != NULL); says I make the assertion that this > pointer is not null Ok, I used to work with BUG_ON() and WARN(). btw, in networking kernel code was very useful function WARN_ONCE(), or rate limited warning / output. It might be reasonable to add this to architecture doc also. > > Best regards, > Maxim. > > + … > +} > +@endcode > +*/ > > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > http://lists.linaro.org/mailman/listinfo/lng-odp > > > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP
diff --git a/exception_handling.dox b/exception_handling.dox new file mode 100644 index 0000000..2645caa --- /dev/null +++ b/exception_handling.dox @@ -0,0 +1,119 @@ +/* +Copyright (c) 2014, Linaro Limited +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + + * 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. + + * Neither the name of Linaro Limited nor the names of its contributors may be + used to endorse or promote products derived from this software without specific + prior written permission. + +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 HOLDER 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. +*/ + +/** +@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_op_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; +}; + + +#if (offsetof(timer, DATA) != 4)} +#error DATA must be at offset 4 in timer +#endif +@endcode + +@section compile_run_time Run time programming exceptions +There are two rules +-# These must be capable of being turned off by defining -DNODP_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 | 119 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 exception_handling.dox