From 865109cace7a4770507dc19bcda5c79a8d2dbddc Mon Sep 17 00:00:00 2001 From: MMS Date: Sat, 28 Jan 2023 10:16:22 -0500 Subject: [PATCH] 1.0.0 Initial commit 1.0.0 --- .gitignore | 52 +++++++++++ LICENSE | 21 +++++ README.md | 80 +++++++++++++++++ dbc_assert.h | 207 ++++++++++++++++++++++++++++++++++++++++++++ img/github-star.jpg | Bin 0 -> 25587 bytes 5 files changed, 360 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 README.md create mode 100644 dbc_assert.h create mode 100644 img/github-star.jpg diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c6127b3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,52 @@ +# Prerequisites +*.d + +# Object files +*.o +*.ko +*.obj +*.elf + +# Linker output +*.ilk +*.map +*.exp + +# Precompiled Headers +*.gch +*.pch + +# Libraries +*.lib +*.a +*.la +*.lo + +# Shared objects (inc. Windows DLLs) +*.dll +*.so +*.so.* +*.dylib + +# Executables +*.exe +*.out +*.app +*.i*86 +*.x86_64 +*.hex + +# Debug files +*.dSYM/ +*.su +*.idb +*.pdb + +# Kernel Module Compile Results +*.mod* +*.cmd +.tmp_versions/ +modules.order +Module.symvers +Mkfile.old +dkms.conf diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3a72bac --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 Quantum Leaps + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ca1eecc --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +## Brought to you by: +[![Quantum Leaps](https://www.state-machine.com/attachments/logo_ql_400.png)](https://www.state-machine.com) +
+ +[![GitHub release (latest by date)](https://img.shields.io/github/v/release/QuantumLeaps/DBC-for-embedded-C)](https://github.com/QuantumLeaps/DBC-for-embedded-C/releases/latest) +[![GitHub](https://img.shields.io/github/license/QuantumLeaps/DBC-for-embedded-C)](https://github.com/QuantumLeaps/DBC-for-embedded-C/blob/master/LICENSE) + +# Design By Contract (DBC) +Design By Contract (DBC), pioneered by Bertrand Meyer, views a software system +as a set of components whose collaboration is based on precisely defined +specifications of mutual obligations—the contracts.1 The central idea of this +method is to inherently embed the contracts in the code and validate them +automatically at run time. Doing so consistently has two major benefits: + +1. It automatically helps detect bugs (as opposed to "handling" them), and +2. It is one of the best ways to document code. + +# DBC for Embedded C and C++ +You can implement the most important aspects of DBC (the contracts) in C or +C++ with **assertions**. The Standard C Library macro `assert()` is rarely +applicable to embedded systems, however, because its default behavior (when +the integer expression passed to the macro evaluates to `false`) is to print +an error message and exit. Neither of these actions makes much sense for most +embedded systems, which rarely have a screen to print to and cannot really +exit either (at least not in the same sense that a desktop application can). +Therefore, in an embedded environment, you usually have to define your own +assertions that suit your tools and allow you to customize the error response. +However, you should think twice before you go about "enhancing" assertions +because a large part of their power derives from their relative *simplicity*. + +# This DBC implementation +The DBC implementation in this repository consists of just one header file +[dbc_assert.h](./dbc_assert.h), which has been specifically tailored +for embedded systems and has the following properties: + +- allows customizing the error response (by implementing the DBC +fault handler `DBC_fault_handler()`); + +- conserves memory by avoiding proliferation of multiple copies +of the filename string (macro `DBC_MODULE_NAME()`); + +- provides additional macros for checking and documenting preconditions +(`DBC_REQUIRE()`), postconditions (`DBC_ENSURE()`), and invariants +(`DBC_INVARIANT()`). + +> **NOTE**
+The names of the three last macros are a direct loan from Eiffel, +the programming language that natively supports DBC. + + +# Example of Use +``` +#include "dbc_assert.h" /* Design By Contract (DBC) assertions */ + +DBC_MODULE_NAME("sst") /* for DBC assertions in this module */ + +/*..........................................................................*/ +void SST_Task_post(SST_Task * const me, SST_Evt const * const e) { + /*! @pre the queue must be sized adequately and cannot overflow */ + DBC_REQUIRE(300, me->nUsed <= me->end); + ... +} +``` + +## More DBC Resources +To learn more about DBC for embedded systems, please check out the following +resources: + +[1] [Key Concept: Design by Contract](https://www.state-machine.com/dbc)
+[2] ["Design by Contract for Embedded C"](https://barrgroup.com/embedded-systems/how-to/design-by-contract-for-embedded-software)
+[3] ["A Nail for a Fuse"](https://www.state-machine.com/a-nail-for-a-fuse)
+[4] ["An Exception or a Bug"](https://www.state-machine.com/doc/Samek0308.pdf) + + +# How to Help this Project? +Please feel free to clone, fork, and make pull requests to improve DBC +for Embedded C. If you like this project, please give it a star (in the +upper-right corner of your browser window): + +

diff --git a/dbc_assert.h b/dbc_assert.h new file mode 100644 index 0000000..22da57f --- /dev/null +++ b/dbc_assert.h @@ -0,0 +1,207 @@ +/*============================================================================ +* Design By Contract (DBC) for embedded C and C++ +* GitHub: https://github.com/QuantumLeaps/DBC-for-embedded-C +* +* Q u a n t u m L e a P s +* ------------------------ +* Modern Embedded Software +* +* Copyright (C) 2005 Quantum Leaps, . +* +* SPDX-License-Identifier: MIT +* +* Permission is hereby granted, free of charge, to any person obtaining a +* copy of this software and associated documentation files (the "Software"), +* to deal in the Software without restriction, including without limitation +* the rights to use, copy, modify, merge, publish, distribute, sublicense, +* and/or sell copies of the Software, and to permit persons to whom the +* Software is furnished to do so, subject to the following conditions: +* +* The above copyright notice and this permission notice shall be included in +* all copies or substantial portions of the Software. +* +* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +* DEALINGS IN THE SOFTWARE. +============================================================================*/ +#ifndef DBC_ASSERT_H_ +#define DBC_ASSERT_H_ + +/*! @file +* @brief Memory-efficient Design by Contract (DBC) for embedded C and C++. +* +* @note +* The runtime checking of the DBC assertions can be disabled by defining +* the macro #DBC_DISABLE. However, it is generally **not** advisable to +* disable assertions, *especially* in the production code. Instead, the +* assertion fault handler DBC_fault_handler() should be very carefully +* designed and tested under all fault conditions. +*/ + +/* Active DbC macros -------------------------------------------------------*/ +#ifndef DBC_DISABLE + +/*! Define the user-specified module name for assertions in this file. +* +* @details +* Macro to be placed at the top of each C/C++ module to define the +* single instance of the module name string to be used in reporting +* assertions in this module. This macro takes the user-supplied parameter +* `name_`. +* +* @param[in] name_ string constant representing the module name +* +* @note +* This macro should **not** be terminated by a semicolon. +*/ +#define DBC_MODULE_NAME(name_) \ + static char const DBC_module_name_[] = name_; + +/*! General purpose assertion with user-specified ID number. +* +* @details +* Makes sure the `expr_` parameter is TRUE. Calls the DBC_fault_handler() +* callback if the `expr_` evaluates to FALSE. This assertion takes the +* user-supplied parameter `label_` to identify the location of this +* assertion within the module. This avoids the volatility of using line +* numbers, which change whenever a line of code is added or removed +* upstream from the assertion. +* +* @param[in] label_ numeric label of the assertion (unique within the module) +* @param[in] expr_ Boolean expression to check +* +* @note +* The `expr_` expression is **not** evaluated if assertions are +* disabled with the ::DBC_DISABLE switch. +*/ +#define DBC_ASSERT(label_, expr_) ((expr_) \ + ? ((void)0) : DBC_fault_handler(&DBC_module_name_[0], (label_))) + +/*! General purpose assertion with user-specified ID number that +* evaluates the `expr_` expression even when assertions are disabled. +* +* @details +* Like the DBC_ASSERT() macro, except it **always** evaluates the +* `expr_` expression even when DBC assertions are disabled with the +* #DBC_DISABLE macro. +* +* @param[in] label_ numeric label of the assertion (unique within the module) +* @param[in] expr_ Boolean expression to check +*/ +#define DBC_ALLEGE(label_, expr_) DBC_ASSERT(label_, expr_) + +/*! Assertion for a wrong path through the code +* +* @details +* Calls the DBC_fault_handler() callback if ever executed. This assertion +* takes the user-supplied parameter `id_` to identify the location of +* this assertion within the file. This avoids the volatility of using +* line numbers, which change whenever a line of code is added or removed +* upstream from the assertion. +* +* @param[in] label_ numeric label of the assertion (unique within the module) +*/ +#define DBC_ERROR(label_) DBC_fault_handler(&DBC_module_name_[0], (label_)) + +/*! Assertion for checking preconditions. +* +* @details +* Equivalent to DBC_ASSERT(), except the name provides a better +* documentation of the intention of this assertion. +* +* @param[in] label_ numeric label of the assertion (unique within the module) +* @param[in] expr_ Boolean expression to check +* +* @note +* The `expr_` expression is **not** evaluated if assertions are +* disabled with the ::DBC_DISABLE switch. +*/ +#define DBC_REQUIRE(label_, expr_) DBC_ASSERT((label_), (expr_)) + +/*! Assertion for checking postconditions. +* +* @details +* Equivalent to DBC_ASSERT(), except the name provides a better +* documentation of the intention of this assertion. +* +* @param[in] label_ numeric label of the assertion (unique within the module) +* @param[in] expr_ Boolean expression to check +* +* @note +* The `expr_` expression is **not** evaluated if assertions are +* disabled with the ::DBC_DISABLE switch. +*/ +#define DBC_ENSURE(label_, expr_) DBC_ASSERT((label_), (expr_)) + +/*! Assertion for checking invariants. +* +* @details +* Equivalent to DBC_ASSERT(), except the name provides a better +* documentation of the intention of this assertion. +* +* @param[in] label_ numeric label of the assertion (unique within the module) +* @param[in] expr_ Boolean expression to check +* +* @note +* The `expr_` expression is **not** evaluated if assertions are +* disabled with the ::DBC_DISABLE switch. +*/ +#define DBC_INVARIANT(label_, expr_) DBC_ASSERT((label_), (expr_)) + +#ifndef DBC_NORETURN +#define DBC_NORETURN +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/*! DBC assertion fault handler. +* +* @details +* This is an application-specific callback function needs to be defined in +* the application to perform the clean system shutdown and perhaps a reset. +* The DBC_fault_handler() function is the last line of defense after the +* system failure and its implementation should be very **carefully** +* designed and **tested** under various fault conditions, including but +* not limited to: stack overflow, stack corruption, or calling +* DBC_fault_handler() from ISRs. + +* @param[in] module name of the file/module in which the assertion failed +* (constant, zero-terminated C string) +* @param[in] label unique label of the assertion within the module. +* This could be a line number or a user-defined label. +* +* @returns +* This callback function should **not return** (see #NORETURN), +* as continuation after an assertion failure does not make sense. +* +* @note +* It is typically a **bad idea** to implement DBC_fault_handler() as an +* endless loop that ties up the CPU. During debugging, DBC_fault_handler() +* is an ideal place to put a breakpoint. +*/ +DBC_NORETURN void DBC_fault_handler(char const * module, int label); + +#ifdef __cplusplus +} +#endif + +/* Inactive DbC macros -----------------------------------------------------*/ +#else + +#define DBC_MODULE_NAME(dummy_) +#define DBC_ASSERT(label_, expr_) ((void)0) +#define DBC_ERROR(label_) ((void)0) +#define DBC_REQUIRE(label_, expr_) ((void)0) +#define DBC_ENSURE(label_, expr_) ((void)0) +#define DBC_INVARIANT(label_, expr_) ((void)0) +#define DBC_ALLEGE(label_, expr_) ((void)(expr_)) + +#endif /* Inactive DBC macros */ + +#endif /* DBC_ASSERT_ */ diff --git a/img/github-star.jpg b/img/github-star.jpg new file mode 100644 index 0000000000000000000000000000000000000000..c230ace57809986d0a8cce9bc5c310aff13a0949 GIT binary patch literal 25587 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