Assertions

Specifies the assertion macros. More...

Files
file	rkhassert.h
	Specifies the assertion macros.

Macros
#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...
#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.

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

Specifies the assertion macros.

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

RKH_ASSERT

#define RKH_ASSERT

(

exp

)

Value:

        if ((exp)) \
        { \
        } \
        else \
        { \
            rkh_assert(m_name, __LINE__); \
        }

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]

exp

expression 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 129 of file rkhassert.h.

RKH_ALLEGE

#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 151 of file rkhassert.h.

RKH_ERROR

#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 163 of file rkhassert.h.

RKH_REQUIRE

#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 180 of file rkhassert.h.

RKH_ENSURE

#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 191 of file rkhassert.h.

RKH_INVARIANT

#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 202 of file rkhassert.h.

RKH_MODULE_NAME

#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]

__fname

file name where the assertion failed

Definition at line 111 of file rkhfwk_module.h.

Function Documentation

rkh_assert()

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]	file	file name where the assertion failed
[in]	line	line 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_DIS_INTERRUPT();
    RKH_TR_FWK_ASSERT( (RKHROM char *)file, line );
    __debugbreak();
}