Debug
[Kernel]

Collaboration diagram for Debug:

---

Description

Debug APIs and services:

• Trace buffer.
• Parameters check.
• Kernel assertions.

Data Structures
struct	CtxSwcEvent
	Trace buffer record. More...
struct	TraceBuffer
	Trace buffer header. More...
Defines
#define	STACK_FILL_VALUE   0x55
	Trace buffer entries.
#define	THREAD_FILL_VALUE   0xFF
	Fill value for thread area in debug mode.
#define	chDbgCheck(c, func)
	Function parameter check.
#define	chDbgAssert(c, m, r)
	Condition assertion.
Functions
void	trace_init (void)
	Trace circular buffer subsystem initialization.
void	chDbgTrace (Thread *otp)
	Inserts in the circular debug trace buffer a context switch record.
void	chDbgPanic (char *msg)
	Prints a panic message on the console and then halts the system.
Variables
TraceBuffer	trace_buffer
	Public trace buffer.
char *	panic_msg
	Pointer to the panic message.

---

Define Documentation

#define STACK_FILL_VALUE   0x55

Trace buffer entries.

Fill value for thread stack area in debug mode.

Definition at line 49 of file chdebug.h.

Referenced by chThdInit().

#define THREAD_FILL_VALUE   0xFF

Fill value for thread area in debug mode.

Note:

The chosen default value is 0xFF in order to make evident which thread fields were not initialized when inspecting the memory with a debugger. A uninitialized field is not an error in itself but it better to know it.

Definition at line 60 of file chdebug.h.

Referenced by chThdInit().

#define chDbgCheck	(	c,
		func		)

Value:

{                                           \
  if (!(c))                                                             \
    chDbgPanic(__QUOTE_THIS(func)"(), line "__QUOTE_THIS(__LINE__));    \
}

Function parameter 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
[in]	func	the undecorated function name

Definition at line 102 of file chdebug.h.

Referenced by adcStart(), adcStartConversion(), adcStop(), adcStopConversion(), canReceive(), canSleep(), canStart(), canStop(), canTransmit(), canWakeup(), chCondBroadcastI(), chCondInit(), chCondSignal(), chCondSignalI(), chCondWaitS(), chCondWaitTimeoutS(), chEvtBroadcastI(), chEvtDispatch(), chEvtRegisterMask(), chEvtSignal(), chEvtSignalI(), chEvtUnregister(), chHeapFree(), chHeapInit(), chIQReadTimeout(), chMBFetchS(), chMBInit(), chMBPostAheadS(), chMBPostS(), chMBReset(), chMsgSend(), chMtxInit(), chMtxLockS(), chMtxTryLockS(), chOQWriteTimeout(), chPoolAllocI(), chPoolFreeI(), chPoolInit(), chSemInit(), chSemResetI(), chSemSignal(), chSemSignalI(), chSemSignalWait(), chSemWaitS(), chSemWaitTimeoutS(), chThdCreateFromMemoryPool(), chThdInit(), chThdSetPriority(), chThdSleep(), chThdWait(), chVTResetI(), chVTSetI(), mmcConnect(), mmcDisconnect(), mmcSequentialRead(), mmcSequentialWrite(), mmcStart(), mmcStartSequentialRead(), mmcStartSequentialWrite(), mmcStop(), mmcStopSequentialRead(), mmcStopSequentialWrite(), palReadBus(), palSetBusMode(), palWriteBus(), pwmDisableChannel(), pwmEnableChannel(), pwmStart(), pwmStop(), sdAddFlagsI(), sdGetAndClearFlags(), sdIncomingDataI(), sdRequestDataI(), sdStart(), sdStop(), spiAcquireBus(), spiExchange(), spiIgnore(), spiReceive(), spiReleaseBus(), spiSelect(), spiSend(), spiStart(), spiStop(), and spiUnselect().

#define chDbgAssert	(	c,
		m,
		r		)

Value:

{                                          \
  if (!(c))                                                             \
    chDbgPanic(m);                                                      \
}

Condition assertion.

If the condition check fails then the kernel panics with the specified 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 convention for the message is the following:
<function_name>(), #<assert_number>

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]	m	the text message
[in]	r	a remark string

Definition at line 128 of file chdebug.h.

Referenced by adcStart(), adcStartConversion(), adcStop(), adcStopConversion(), adcWaitConversion(), canReceive(), canSleep(), canStart(), canStop(), canTransmit(), canWakeup(), chCondWaitS(), chCondWaitTimeoutS(), chEvtDispatch(), chHeapFree(), chMsgRelease(), chMtxLockS(), chMtxUnlock(), chMtxUnlockS(), chRegNextThread(), chThdAddRef(), chThdRelease(), chThdResume(), chThdWait(), chVTResetI(), mmcConnect(), mmcDisconnect(), mmcStart(), mmcStop(), pwmDisableChannel(), pwmEnableChannel(), pwmStart(), pwmStop(), sdStart(), sdStop(), spiExchange(), spiIgnore(), spiReceive(), spiSelect(), spiSend(), spiStart(), spiStop(), and spiUnselect().

---

Function Documentation

void trace_init

(

void

)

Trace circular buffer subsystem initialization.

Definition at line 51 of file chdebug.c.

References TraceBuffer::tb_buffer, TraceBuffer::tb_ptr, and TraceBuffer::tb_size.

Referenced by chSysInit().

void chDbgTrace

(

Thread *

otp

)

Inserts in the circular debug trace buffer a context switch record.

Parameters:

[in]

otp

the thread being switched out

Definition at line 62 of file chdebug.c.

References chTimeNow, CtxSwcEvent::cse_state, CtxSwcEvent::cse_tid, CtxSwcEvent::cse_time, CtxSwcEvent::cse_wtobjp, currp, Thread::p_state, Thread::p_u, TraceBuffer::tb_buffer, TraceBuffer::tb_ptr, and Thread::wtobjp.

Referenced by chSchDoRescheduleI(), chSchGoSleepS(), and chSchWakeupS().

void chDbgPanic

(

char *

msg

)

Prints a panic message on the console and then halts the system.

Parameters:

[in]

msg

the pointer to the panic message string

Definition at line 87 of file chdebug.c.

References chSysHalt, and panic_msg.

---

Variable Documentation

TraceBuffer trace_buffer

Public trace buffer.

Definition at line 46 of file chdebug.c.

char* panic_msg

Pointer to the panic message.

This pointer is meant to be accessed through the debugger, it is written once and then the system is halted. This variable can be set to NULL if the halt is caused by a stack overflow.

Definition at line 80 of file chdebug.c.

Referenced by chDbgPanic().