Checks and Assertions

Collaboration diagram for Checks and Assertions:

Detailed Description

Debug APIs and services:

• Runtime system state and call protocol check. The following panic messages can be generated:
  • SV#1, misplaced chSysDisable().
    • Called from an ISR.
    • Called from a critical zone.
  • SV#2, misplaced chSysSuspend()
    • Called from an ISR.
    • Called from a critical zone.
  • SV#3, misplaced chSysEnable().
    • Called from an ISR.
    • Called from a critical zone.
  • SV#4, misplaced chSysLock().
    • Called from an ISR.
    • Called from a critical zone.
  • SV#5, misplaced chSysUnlock().
    • Called from an ISR.
    • Not called from a critical zone.
  • SV#6, misplaced chSysLockFromISR().
    • Not called from an ISR.
    • Called from a critical zone.
  • SV#7, misplaced chSysUnlockFromISR().
    • Not called from an ISR.
    • Not called from a critical zone.
  • SV#8, misplaced CH_IRQ_PROLOGUE().
    • Not called at ISR begin.
    • Called from a critical zone.
  • SV#9, misplaced CH_IRQ_EPILOGUE().
    • CH_IRQ_PROLOGUE() missing.
    • Not called at ISR end.
    • Called from a critical zone.
  • SV#10, misplaced I-class function.
    • I-class function not called from within a critical zone.
  • SV#11, misplaced S-class function.
    • S-class function not called from within a critical zone.
    • Called from an ISR.
• Parameters check.
• Kernel assertions.

Note

Stack checks are not implemented in this module but in the port layer in an architecture-dependent way.

Debug related settings
#define	CH_DBG_STACK_FILL_VALUE   0x55
	Fill value for thread stack area in debug mode. More...

Macro Functions
#define	chDbgCheck(c)
	Function parameters check. More...
#define	chDbgAssert(c, r)
	Condition assertion. More...

Typedefs
typedef struct ch_system_debug	system_debug_t
	System debug data structure. More...

Data Structures
struct	ch_system_debug
	System debug data structure. More...

Functions
void	__dbg_check_disable (void)
	Guard code for chSysDisable(). More...
void	__dbg_check_suspend (void)
	Guard code for chSysSuspend(). More...
void	__dbg_check_enable (void)
	Guard code for chSysEnable(). More...
void	__dbg_check_lock (void)
	Guard code for chSysLock(). More...
void	__dbg_check_unlock (void)
	Guard code for chSysUnlock(). More...
void	__dbg_check_lock_from_isr (void)
	Guard code for chSysLockFromIsr(). More...
void	__dbg_check_unlock_from_isr (void)
	Guard code for chSysUnlockFromIsr(). More...
void	__dbg_check_enter_isr (void)
	Guard code for CH_IRQ_PROLOGUE(). More...
void	__dbg_check_leave_isr (void)
	Guard code for CH_IRQ_EPILOGUE(). More...
void	chDbgCheckClassI (void)
	I-class functions context check. More...
void	chDbgCheckClassS (void)
	S-class functions context check. More...
static void	__dbg_object_init (system_debug_t *sdp)
	Debug support initialization. More...

Macro Definition Documentation

CH_DBG_STACK_FILL_VALUE

#define CH_DBG_STACK_FILL_VALUE   0x55

Fill value for thread stack area in debug mode.

Definition at line 47 of file chdebug.h.

chDbgCheck

#define chDbgCheck

(

c

)

Value:

  do {                                                  \
  /*lint -save -e506 -e774 [2.1, 14.3] Can be a constant by design.*/       \
  if (CH_DBG_ENABLE_CHECKS != FALSE) {                                      \
    if (unlikely(!(c))) {                                                   \
  /*lint -restore*/                                                         \
      chSysHalt(__func__);                                                  \
    }                                                                       \
  }                                                                         \
} while (false)

Function parameters check.

If the condition check fails then the kernel panics and halts.

Note

The condition is tested only if the CH_DBG_ENABLE_CHECKS switch is specified in chconf.h else the macro does nothing.

Parameters

[in]

c

the condition to be verified to be true

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 118 of file chdebug.h.

chDbgAssert

#define chDbgAssert	(		c,
			r
	)

Value:

  do {                                              \
  /*lint -save -e506 -e774 [2.1, 14.3] Can be a constant by design.*/       \
  if (CH_DBG_ENABLE_ASSERTS != FALSE) {                                     \
    if (unlikely(!(c))) {                                                   \
  /*lint -restore*/                                                         \
      chSysHalt(__func__);                                                  \
    }                                                                       \
  }                                                                         \
} while (false)

Condition assertion.

If the condition check fails then the kernel panics with a message and halts.

Note

The condition is tested only if the CH_DBG_ENABLE_ASSERTS switch is specified in chconf.h else the macro does nothing.

The remark string is not currently used except for putting a comment in the code about the assertion.

Parameters

[in]	c	the condition to be verified to be true
[in]	r	a remark string

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 144 of file chdebug.h.

Typedef Documentation

system_debug_t

typedef struct ch_system_debug system_debug_t

System debug data structure.

Function Documentation

__dbg_check_disable()

void __dbg_check_disable

(

void

)

Guard code for chSysDisable().

Function Class:

Not an API, this function is for internal use only.

Definition at line 112 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chSysDisable().

Here is the call graph for this function:

__dbg_check_suspend()

void __dbg_check_suspend

(

void

)

Guard code for chSysSuspend().

Function Class:

Not an API, this function is for internal use only.

Definition at line 126 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chSysSuspend().

Here is the call graph for this function:

__dbg_check_enable()

void __dbg_check_enable

(

void

)

Guard code for chSysEnable().

Function Class:

Not an API, this function is for internal use only.

Definition at line 140 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chSysEnable().

Here is the call graph for this function:

__dbg_check_lock()

void __dbg_check_lock

(

void

)

Guard code for chSysLock().

Function Class:

Not an API, this function is for internal use only.

Definition at line 154 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chSysLock().

Here is the call graph for this function:

__dbg_check_unlock()

void __dbg_check_unlock

(

void

)

Guard code for chSysUnlock().

Function Class:

Not an API, this function is for internal use only.

Definition at line 169 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chSysUnlock().

Here is the call graph for this function:

__dbg_check_lock_from_isr()

void __dbg_check_lock_from_isr

(

void

)

Guard code for chSysLockFromIsr().

Function Class:

Not an API, this function is for internal use only.

Definition at line 184 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chSysLockFromISR().

Here is the call graph for this function:

__dbg_check_unlock_from_isr()

void __dbg_check_unlock_from_isr

(

void

)

Guard code for chSysUnlockFromIsr().

Function Class:

Not an API, this function is for internal use only.

Definition at line 199 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chSysUnlockFromISR().

Here is the call graph for this function:

__dbg_check_enter_isr()

void __dbg_check_enter_isr

(

void

)

Guard code for CH_IRQ_PROLOGUE().

Function Class:

Not an API, this function is for internal use only.

Definition at line 214 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Here is the call graph for this function:

__dbg_check_leave_isr()

void __dbg_check_leave_isr

(

void

)

Guard code for CH_IRQ_EPILOGUE().

Function Class:

Not an API, this function is for internal use only.

Definition at line 231 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Here is the call graph for this function:

chDbgCheckClassI()

void chDbgCheckClassI

(

void

)

I-class functions context check.

Verifies that the system is in an appropriate state for invoking an I-class API function. A panic is generated if the state is not compatible.

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 251 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chBSemGetStateI(), chBSemResetI(), chBSemSignalI(), chCondBroadcastI(), chCondSignalI(), chCoreAllocFromBaseI(), chCoreAllocFromTopI(), chEvtBroadcastFlagsI(), chEvtGetAndClearEventsI(), chEvtGetAndClearFlagsI(), chEvtRegisterMaskWithFlagsI(), chEvtSignalI(), chMBFetchI(), chMBGetFreeCountI(), chMBGetUsedCountI(), chMBPeekI(), chMBPostAheadI(), chMBPostI(), chMBResetI(), chMsgIsPendingI(), chMtxGetOwnerI(), chPoolAllocI(), chPoolFreeI(), chSchReadyI(), chSemAddCounterI(), chSemFastSignalI(), chSemFastWaitI(), chSemGetCounterI(), chSemResetWithMessageI(), chSemSignalI(), chSysIntegrityCheckI(), chSysTimerHandlerI(), chThdCreateSuspendedI(), chThdQueueIsEmptyI(), chTraceResumeI(), chTraceSuspendI(), chTraceWriteI(), chVTDoResetI(), chVTDoSetContinuousI(), chVTDoSetI(), chVTDoTickI(), chVTGetRemainingIntervalI(), chVTGetTimersStateI(), chVTGetTimeStampI(), chVTIsArmedI(), chVTResetTimeStamp(), and chVTResetTimeStampI().

Here is the call graph for this function:

chDbgCheckClassS()

void chDbgCheckClassS

(

void

)

S-class functions context check.

Verifies that the system is in an appropriate state for invoking an S-class API function. A panic is generated if the state is not compatible.

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 268 of file chdebug.c.

References chSysHalt(), currcore, ch_os_instance::dbg, ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and unlikely.

Referenced by chBSemWaitS(), chBSemWaitTimeoutS(), chCondWaitS(), chCondWaitTimeoutS(), chMBFetchTimeoutS(), chMBPostAheadTimeoutS(), chMBPostTimeoutS(), chMsgReleaseS(), chMsgWaitS(), chMsgWaitTimeoutS(), chMtxLockS(), chMtxQueueNotEmptyS(), chMtxTryLockS(), chMtxUnlockS(), chSchDoYieldS(), chSchGoSleepS(), chSchGoSleepTimeoutS(), chSchRescheduleS(), chSchWakeupS(), chSemWaitS(), and chSemWaitTimeoutS().

Here is the call graph for this function:

__dbg_object_init()

static void __dbg_object_init ( system_debug_t *  sdp )

inlinestatic

Debug support initialization.

Note

Internal use only.

Parameters

[out]

sdp

pointer to the system_debug_t structure

Function Class:

Not an API, this function is for internal use only.

Definition at line 192 of file chdebug.h.

References ch_system_debug::isr_cnt, ch_system_debug::lock_cnt, and ch_system_debug::panic_msg.

Referenced by chInstanceObjectInit().