RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages

The assertions (RKH_ASSERT() macro) are used to check expressions that ought to be true as long as the program is running correctly. It is a convenient way to insert sanity checks. More...

Files

file  rkhassert.h
 The assertions (RKH_ASSERT() macro) are used to check expressions that ought to be true as long as the program is running correctly. It is a convenient way to insert sanity checks.
 

Macros

#define RKH_MODULE_NAME(__fname)   static RKHROM char *const m_name = # __fname;
 This macro appears at the top of each C/C++ source file defining a name for that file. More...
 
#define RKH_THIS_MODULE   static RKHROM char *const m_name = __FILE__;
 This macro appears at the top of each C/C++ source file defining a name for that file, by means of FILE compiler directive.
 
#define RKH_ASSERT(exp)
 The RKH_ASSERT() macro is used to check expressions that ought to be true as long as the program is running correctly. More...
 
#define RKH_ALLEGE(exp)   RKH_ASSERT(exp)
 General purpose assertion that ALWAYS evaluates the exp argument and calls the RKH_ASSERT() macro if the exp evaluates to FALSE. More...
 
#define RKH_ERROR()   rkh_assert(m_name, __LINE__)
 Assertion that always calls the rkh_assert() callback if ever executed. More...
 
#define RKH_REQUIRE(exp)   RKH_ASSERT(exp)
 This macro checks the precondition. More...
 
#define RKH_ENSURE(exp)   RKH_ASSERT(exp)
 This macro checks the postcondition. More...
 
#define RKH_INVARIANT(exp)   RKH_ASSERT(exp)
 This macro is used to check a loop invariant. More...
 

Functions

void rkh_assert (const char *const file, int line)
 Callback invoked in case the condition passed to RKH_ASSERT(), RKH_REQUIRE(), RKH_ENSURE(), RKH_ERROR(), or RKH_ALLEGE() evaluates to FALSE. More...
 

Detailed Description

The assertions (RKH_ASSERT() macro) are used to check expressions that ought to be true as long as the program is running correctly. It is a convenient way to insert sanity checks.

A number of philosophies can be employed when deciding where to use an RKH_ASSERT() macro. Broadly speaking, the assertions only serve the purposes of catching bugs and helping documentation. Helping to document the code means that the statements inside the assertion tell the reader something he might not already know.

Macro Definition Documentation

#define RKH_MODULE_NAME (   __fname)    static RKHROM char *const m_name = # __fname;

This macro appears at the top of each C/C++ source file defining a name for that file.

Parameters
[in]__fnamefile name where the assertion failed

Definition at line 91 of file rkhassert.h.

#define RKH_ASSERT (   exp)
Value:
if ((exp)) \
{ \
} \
else \
{ \
rkh_assert(m_name, __LINE__); \
}
void rkh_assert(const char *const file, int line)
Callback invoked in case the condition passed to RKH_ASSERT(), RKH_REQUIRE(), RKH_ENSURE(), RKH_ERROR(), or RKH_ALLEGE() evaluates to FALSE.

The RKH_ASSERT() macro is used to check expressions that ought to be true as long as the program is running correctly.

The assertions (RKH_ASSERT() macro) are used to check expressions that ought to be true as long as the program is running correctly. It is a convenient way to insert sanity checks. A number of philosophies can be employed when deciding where to use an RKH_ASSERT() macro. Broadly speaking, the assertions only serve the purposes of catching bugs and helping documentation. Helping to document the code means that the statements inside the assertion tell the reader something he might not already know.

Parameters
[in]expexpression to be checked.
Note
The preprocessor switch RKH_CFG_FWK_ASSERT_EN disables checking assertions. In particular macros RKH_ASSERT(), RKH_REQUIRE(), RKH_ENSURE(), RKH_INVARIANT(), and RKH_ERROR() do NOT evaluate the test condition passed as the argument to these macros. One notable exception is the macro RKH_ALLEGE(), that still evaluates the test condition, but does not report assertion failures when the switch RKH_CFG_FWK_ASSERT_EN is defined.
See also
RKH_ALLEGE(), RKH_REQUIRE(), RKH_ENSURE(), RKH_ERROR() and RKH_INVARIANT() macros.
Usage
...
some_function( const char *p, int size )
{
RKH_ASSERT( p != ( const char* )0 &&
size > 0 &&
size < MAX_SIZE );
...
}

Definition at line 147 of file rkhassert.h.

#define RKH_ALLEGE (   exp)    RKH_ASSERT(exp)

General purpose assertion that ALWAYS evaluates the exp argument and calls the RKH_ASSERT() macro if the exp evaluates to FALSE.

Note
The exp argument IS always evaluated even when assertions are disabled with the RKH_CFG_FWK_ASSERT_EN. When the RKH_CFG_ASSERT_EN is set to one (1), the RKH_ASSERT() macro is NOT called, even if the exp evaluates to FALSE.

Definition at line 169 of file rkhassert.h.

#define RKH_ERROR ( )    rkh_assert(m_name, __LINE__)

Assertion that always calls the rkh_assert() callback if ever executed.

Note
Can be disabled with the RKH_CFG_FWK_ASSERT_EN switch.

Definition at line 181 of file rkhassert.h.

#define RKH_REQUIRE (   exp)    RKH_ASSERT(exp)

This macro checks the precondition.

This macro is equivalent to RKH_ASSERT() macro, except the name provides a better documentation of the intention of this assertion.

Definition at line 200 of file rkhassert.h.

#define RKH_ENSURE (   exp)    RKH_ASSERT(exp)

This macro checks the postcondition.

This macro is equivalent to RKH_ASSERT() macro, except the name provides a better documentation of the intention of this assertion.

Definition at line 211 of file rkhassert.h.

#define RKH_INVARIANT (   exp)    RKH_ASSERT(exp)

This macro is used to check a loop invariant.

This macro is equivalent to RKH_ASSERT() macro, except the name provides a better documentation of the intention of this assertion.

Definition at line 222 of file rkhassert.h.

Function Documentation

void rkh_assert ( const char *const  file,
int  line 
)

Callback invoked in case the condition passed to RKH_ASSERT(), RKH_REQUIRE(), RKH_ENSURE(), RKH_ERROR(), or RKH_ALLEGE() evaluates to FALSE.

If the expression evaluates to FALSE (0), the function rkh_assert() will be invoked, typically halting the program in some way and storing or reporting the error code. Once the rkh_assert() callback has stored or reported the error, it must decide on the system's next action. One option is:

  1. disable general interrupt
  2. stores or send detected error (could be use a trace facility)
  3. trigger a software reset

The policy chooses will be largely determined by the nature of product. If the system is running with a source level debugger, place a breakpoint within. Another option is to trigger a software reset and attempt to run the system again.

Also a unique identifier that can be reported from the field, easing the investigation of the problem. Therefore, the error code could be composed of the software version number, file number (.c file), line number of assertion, and other information. A number is easier to fill in on a report form and easier to store in NVRAM.

Parameters
[in]filefile name where the assertion failed
[in]lineline number at which the assertion failed
Note
The rkh_assert() callback will only get called if RKH_CFG_FWK_ASSERT_EN is set to 1 within rkhcfg.h file. When this is set the application must provide the callback function.
Usage
The following listing shows a illustrative example for Visual Studio C++ 2008 IDE:
void
rkh_assert( RKHROM char * const file, int line )
{
printf( "RKH_ASSERT: [%d] line from %s file\n", line, file );
RKH_TR_FWK_ASSERT( (RKHROM char *)file, line );
__debugbreak();
}