Debug tools. More...

Defines
#define	os_bug(code) DOC_HIDDEN
	critical bug exception
#define	_debug_pin_set(port, pin_no) DOC_HIDDEN
#define	debug_pin_set(pin_name) _debug_pin_set( pin_name##_PORT, pin_name##_PIN )
	setting pin to 1
#define	_debug_pin_clr(port, pin_no) DOC_HIDDEN
	setting pin to 0
#define	debug_pin_clr(pin_name) _debug_pin_clr( pin_name##_PORT, pin_name##_PIN )
	setting pin to 0
#define	_debug_pin_inv(port, pin_no) DOC_HIDDEN
	setting pin to 0
#define	debug_pin_inv(pin_name) _debug_pin_inv( pin_name##_PORT, pin_name##_PIN )
	inverting state of the pin
Typedefs
typedef enum os_bug_type_e	os_bug_type_t
	bug exception type
Enumerations
enum	os_bug_type_e { OS_BUG_NONE = 0, OS_BUG_OVERFLOW = 1, OS_BUG_LOCK = 2, OS_BUG_THREAD_FUN_EXIT = 3, OS_BUG_MUTEX_BAD_RELEASE = 4, OS_BUG_MUTEX = 5, OS_BUG_SEMA = 6, OS_BUG_DBL_FREE = 7, OS_BUG_INVALID_PTR = 8, OS_BUG_PREEMPT_LOCK = 9, OS_BUG_EMPTY_RDY_LIST = 10, OS_BUG_SM_INVALID_STATE = 11, OS_BUG_DINT_INVALID = 12, OS_BUG_LAST }
	Codes for os_bug() critical exceptions. More...
Functions
void	_os_bug (void)
	internal function for os_bug exceptions catching
Variables
os_bug_type_t	os_bug_code
	Critical bug type.
uni_cpu_pc_reg_t	os_bug_at_pc
	Location of critical exception.

Detailed Description

Debug tools.

Author:: Piotr Romaniuk, (c) ELESOFTROM

Version:: 1.1 Nov 8, 2013

The module contains bug exceptions definition that are thrown when critical conditions occur in the code. "Critical" means that it cannot be recovered and should be considered as very serious. If the code is free of errors the bug exceptions should never appear. It is intended only for debug purpose or detection faults at runtime. Currently, os_bug() call redirects execution to _os_bug() function, where the CPU is locked in endless loop with disabled interrupts. In order to use this mechanism set a breakpoint in that location (i.e. _os_bug()). When it is reached read a contents of global variables: os_bug_code and os_bug_at_pc - you will be able to determine the reason and the location where the bug appeared. User can define his own bug codes (in bug_user.h). User can prepare his own version of _os_bug() function, and implement specific behaviour for runtime, e.g. logging, restart etc.

Note:: The bug mechanism will work even if the stack is corrupted.

This file contains also pin signalling support - very useful tool for real time testing of the firmware. Each GPIO pin is assigned to selected event in the code. When the event appears the bit is set or cleared. If the events are very close each other the bit may be inverted on event. After adding the testpoints with debug_pin_set() etc. you need to capture the signals on the pins by logic analyser. Recorded contents may be subject for timing analysis and conclusion what has happened. This method does not add a lot of extra load, so it preserve the firmware behaviour almost unchanged when the signalling is added. This is valuable advantage over traditional logging which requires more CPU load and may slow down execution. Pin signalling can be used in analysis very fast events and issues conected with hazzard. This can be recorded together with some signals in hardware so is very convenient to coherent software-hardware testing.

User can configure which port is used for that signalling and define his own symbolic names for pins (debug_user.h).

Note:: Debug port must be initialized by debug_pin_init().

Define Documentation

#define _debug_pin_clr	(	port,
		pin_no
	)	DOC_HIDDEN

setting pin to 0

Parameters:

[in]	port	name of the port
[in]	pin_no	number of the pin

#define _debug_pin_inv	(	port,
		pin_no
	)	DOC_HIDDEN

setting pin to 0

Parameters:

[in]	port	name of the port
[in]	pin_no	number of the pin

#define _debug_pin_set	(	port,
		pin_no
	)	DOC_HIDDEN

Signaling timing events on pins

#define debug_pin_clr ( pin_name ) _debug_pin_clr( pin_name##_PORT, pin_name##_PIN )

setting pin to 0

Parameters:

[in] pin_name name of the pin to be cleared. Pins should be defined in debug_user.h file. For each pin define SomeName_PIN and SomeName_PORT, then call use SomeName when you call this function.

#define debug_pin_inv ( pin_name ) _debug_pin_inv( pin_name##_PORT, pin_name##_PIN )

inverting state of the pin

Parameters:

[in] pin_name name of pin to be inverted. Pins should be defined in debug_user.h file. For each pin define SomeName_PIN and SomeName_PORT, then call use SomeName when you call this function.

Note:: It is not atomic for Cortex-M3

#define debug_pin_set ( pin_name ) _debug_pin_set( pin_name##_PORT, pin_name##_PIN )

setting pin to 1

Parameters:

[in] pin_name name of the pin to be set. Pins should be defined in debug_user.h file. For each pin define SomeName_PIN and SomeName_PORT, then call use SomeName when you call this function.

#define os_bug ( code ) DOC_HIDDEN

critical bug exception

Use this macro in source code, when critical unrecoverable condition is detected.
Set a breakpoint on _os_bug(), and add watches of two global variables:
os_bug_code
os_bug_at_pc
When debugger stops there, read code and address of the exception occurrence.

Parameters:

[in] code bug type

Returns:: never returns, it is locked in _os_bug(). Custom implementation of _os_bug() may be provided.

Enumeration Type Documentation

enum os_bug_type_e

Codes for os_bug() critical exceptions.

Enumerator:

OS_BUG_NONE	no bug code, this is used for initialization of global os_bug_code
OS_BUG_OVERFLOW	critical overflow in object has happened (e.g. in semaphore, mutex, etc.)
OS_BUG_LOCK	lock conditions detected
OS_BUG_THREAD_FUN_EXIT	main thread function exited
OS_BUG_MUTEX_BAD_RELEASE	trial of mutex release by non owner thread
OS_BUG_MUTEX	release of mutex that is unlocked
OS_BUG_SEMA	internal semaphore in os_sleep() has waiting thread during destroy
OS_BUG_DBL_FREE	double free of memory pool item
OS_BUG_INVALID_PTR	invalid pointer detected
OS_BUG_PREEMPT_LOCK	detected lock due to preemption disabled
OS_BUG_EMPTY_RDY_LIST	no threads on ready list
OS_BUG_SM_INVALID_STATE	Invalid state in state machine.
OS_BUG_DINT_INVALID	tcb.dint_counter has invalid (=negative) value

                   {
         OS_BUG_NONE = 0, 
         OS_BUG_OVERFLOW = 1,
         OS_BUG_LOCK = 2,  
         OS_BUG_THREAD_FUN_EXIT = 3,
         OS_BUG_MUTEX_BAD_RELEASE = 4,
         OS_BUG_MUTEX = 5,
         OS_BUG_SEMA = 6, 
         OS_BUG_DBL_FREE = 7,
         OS_BUG_INVALID_PTR = 8,
         OS_BUG_PREEMPT_LOCK = 9,
         OS_BUG_EMPTY_RDY_LIST = 10,
         OS_BUG_SM_INVALID_STATE = 11,
         OS_BUG_DINT_INVALID = 12, 
#include "bug_user.h" //intentionally included here, it provides user bug codes in this enum
         
         OS_BUG_LAST};

Function Documentation

void _os_bug ( void )

internal function for os_bug exceptions catching

Set a breakpoint in this function, control will be stopped on exception.
In os_bug_code and os_bug_at_pc you can determine where and why happened the critical bug.

Variable Documentation

uni_cpu_pc_reg_t os_bug_at_pc

Location of critical exception.

This is PC content of bug exception, location in a program can be determined using this address

os_bug_type_t os_bug_code

Critical bug type.

Global variable set on critical condition

core/arch/cortex-m3/gcc/include/debug.h File Reference

Defines

Typedefs

Enumerations

Functions

Variables

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation