1 /*****************************************************************************
3 * Last Updated for Version: 4.0.02
4 * Date of the Last Update: Aug 11, 2008
6 * Q u a n t u m L e a P s
7 * ---------------------------
8 * innovating embedded systems
10 * Copyright (C) 2002-2008 Quantum Leaps, LLC. All rights reserved.
12 * This software may be distributed and modified under the terms of the GNU
13 * General Public License version 2 (GPL) as published by the Free Software
14 * Foundation and appearing in the file GPL.TXT included in the packaging of
15 * this file. Please note that GPL Section 2[b] requires that all works based
16 * on this software must also be made publicly available under the terms of
17 * the GPL ("Copyleft").
19 * Alternatively, this software may be distributed and modified under the
20 * terms of Quantum Leaps commercial licenses, which expressly supersede
21 * the GPL and are specifically designed for licensees interested in
22 * retaining the proprietary status of their code.
24 * Contact information:
25 * Quantum Leaps Web site: http://www.quantum-leaps.com
27 *****************************************************************************/
34 * \brief Customizable assertions.
36 * Defines customizable and memory-efficient assertions applicable to
37 * embedded systems. This header file can be used in C, C++, and mixed C/C++
40 * \note The preprocessor switch Q_NASSERT disables checking assertions.
41 * In particular macros \ref Q_ASSERT, \ref Q_REQUIRE, \ref Q_ENSURE,
42 * \ref Q_INVARIANT, and \ref Q_ERROR do NOT evaluate the test condition
43 * passed as the argument to these macros. One notable exception is the
44 * macro \ref Q_ALLEGE, that still evaluates the test condition, but does
45 * not report assertion failures when the switch Q_NASSERT is defined.
47 #ifdef Q_NASSERT /* Q_NASSERT defined--assertion checking disabled */
49 #define Q_DEFINE_THIS_FILE
50 #define Q_DEFINE_THIS_MODULE(name_)
51 #define Q_ASSERT(test_) ((void)0)
52 #define Q_ALLEGE(test_) ((void)(test_))
53 #define Q_ERROR() ((void)0)
55 #else /* Q_NASSERT not defined--assertion checking enabled */
61 /** callback invoked in case the condition passed to \ref Q_ASSERT,
62 * \ref Q_REQUIRE, \ref Q_ENSURE, \ref Q_ERROR, or \ref Q_ALLEGE
65 * \param file file name where the assertion failed
66 * \param line line number at which the assertion failed
68 /*lint -sem(Q_onAssert, r_no) Q_onAssert() never returns */
69 void Q_onAssert(char const Q_ROM * const Q_ROM_VAR file, int line);
75 /** Place this macro at the top of each C/C++ module to define the file
76 * name string using __FILE__ (NOTE: __FILE__ might contain lengthy path
77 * name). This file name will be used in reporting assertions in this file.
79 #define Q_DEFINE_THIS_FILE \
80 static char const Q_ROM Q_ROM_VAR l_this_file[] = __FILE__;
82 /** Place this macro at the top of each C/C++ module to define the module
83 * name as the argument \a name_. This file name will be used in reporting
84 * assertions in this file.
86 #define Q_DEFINE_THIS_MODULE(name_) \
87 static char const Q_ROM Q_ROM_VAR l_this_file[] = #name_;
89 /** General purpose assertion that makes sure the \a test_ argument is
90 * TRUE. Calls the Q_onAssert() callback if the \a test_ evaluates
92 * \note the \a test_ is NOT evaluated if assertions are
93 * disabled with the Q_NASSERT switch.
95 #define Q_ASSERT(test_) \
98 else (Q_onAssert(l_this_file, __LINE__))
100 /** General purpose assertion that ALWAYS evaluates the \a test_
101 * argument and calls the Q_onAssert() callback if the \a test_
102 * evaluates to FALSE.
103 * \note the \a test_ argument IS always evaluated even when assertions are
104 * disabled with the Q_NASSERT macro. When the Q_NASSERT macro is
105 * defined, the Q_onAssert() callback is NOT called, even if the
106 * \a test_ evaluates to FALSE.
108 #define Q_ALLEGE(test_) Q_ASSERT(test_)
110 /** Assertion that always calls the Q_onAssert() callback if
112 * \note can be disabled with the Q_NASSERT switch.
115 (Q_onAssert(l_this_file, __LINE__))
117 #endif /* Q_NASSERT */
119 /** Assertion that checks for a precondition. This macro is equivalent to
120 * \ref Q_ASSERT, except the name provides a better documentation of the
121 * intention of this assertion.
123 #define Q_REQUIRE(test_) Q_ASSERT(test_)
125 /** Assertion that checks for a postcondition. This macro is equivalent to
126 * \ref Q_ASSERT, except the name provides a better documentation of the
127 * intention of this assertion.
129 #define Q_ENSURE(test_) Q_ASSERT(test_)
131 /** Assertion that checks for an invariant. This macro is equivalent to
132 * \ref Q_ASSERT, except the name provides a better documentation of the
133 * intention of this assertion.
135 #define Q_INVARIANT(test_) Q_ASSERT(test_)
137 /** Compile-time assertion exploits the fact that in C/C++ a dimension of
138 * an array must be non-zero. The following declaration causes a compilation
139 * error if the compile-time expression (\a test_) is not TRUE. The assertion
140 * has no runtime side effects.
142 #define Q_ASSERT_COMPILE(test_) \
143 extern char Q_assert_compile[(test_)]
145 #endif /* qassert_h */