Trace
[Debug]

Trace statements are separated into modules. More...

Collaboration diagram for Trace:


Modules
	Trace Levels
	Trace levels define the severity of a trace statement.
Defines
#define	TRACE(level, trigger, action) /lint -E{506} -E{774}/if(TRACE_LEVEL_##level >= TRACE_LEVEL) fip_trace_print(TRACE_LEVEL_##level, __func__, FIP_TRACE_TR_##trigger, FIP_TRACE_ACT_##action)
	Add a TRACE statement.
#define	TRACE_ADDVAR(level, format, order, name, ptr, size) /lint -E{506} -E{774}/if(TRACE_LEVEL_##level >= TRACE_LEVEL) fip_trace_addvar(TRACE_ORDER_##order \| TRACE_FORMAT_##format, name, (unsigned char *)ptr, size);
	Add a variable to the TRACE statement.
#define	TRACE_ADDVARH(level, format, name) TRACE_ADDVAR(level, format, HOST, #name, &name, sizeof(name))
	Add a hosts variable to the TRACE statement, small version that requires less information by making a number of assumptions.
#define	TRACE_ADDRET(level) TRACE_ADDVAR(level, POINTER, HOST, "Retaddr", builtin_getRPtr(), sizeof(void *));
	Add a statement with the return address of the function, can be used to figure out where the current function was called for.
#define	TRACE_ADDIP6ADDR(level, name, addr) TRACE_ADDVAR(level, IPV6ADDR, MSBFIRST, name, addr, 16)
	Add an IPv6 Address to the trace statement.
#define	TRACE_FORMAT_NULL 0
	No format, no data.
#define	TRACE_FORMAT_UNSIGNED 1
	Unsigned decimal.
#define	TRACE_FORMAT_SIGNED 2
	Signed decimal.
#define	TRACE_FORMAT_HEX 3
	Hex of form 0xYY, 0xYYYY, etc depending on length.
#define	TRACE_FORMAT_IPV6ADDR 4
	IPv6 Address.
#define	TRACE_FORMAT_BYTEADDR 5
	Address in form YY:YY:YY:YY.
#define	TRACE_ORDER_MSBFIRST 0x80
	Flag: network order.
#define	TRACE_ORDER_LSBFIRST 0x00
	Flag: host order.
#define	TRACE_ORDER_MASK 0x80
	Flag mask.
#define	TRACE_FORMAT_MASK 0x7F
	Format mast.
Functions
void	fip_trace_test (void)
	Run a test by printing a number of TRACE statements.

Detailed Description

Trace statements are separated into modules.

When a trace report is built it will become "[TRACE_LEVEL]: [FUNCTION]: [TRIGGER]: [ACTION]". Thus statements & actions are not module-specific, but built in one large list of all statements.

Everything is built into both a decimal value, and a string associated with that decimal value. This allows storing/transmitting of just the decimal value without needing to send the entire string.

Extending triggers & actions

To extend the list of permissible triggers & actions, you will need to look into this header file for several spots marked 'step 1', 'step 2', and 'step 3'. They are done in an 'odd' manner to avoid possible problems with strings being added in the wrong order, and to support storing the strings in FLASH for small devices.

Step 1: Add Number & String

Step 1 is to add a new trigger 'number', and also the associated string. The number is just the next available, so for example you would add in the appropriate section:

#define FIP_TRACE_TR_YYYY    N
#define FIP_TRACE_TR_YYYY_S  "Description string"

Note when calling the macro with the TRACE() macros you will only pass the YYYY part of the name, nothing else.

Step 2: Add String Instance

The string will now need to be defined to possibly allocate storage for the string. Do so by adding the call to

TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_YYYY);

Step 3: Add String to Array

Add the string to the array, by adding to the trace_trigger_array or action_trigger_array depending if you have a trigger or action.

TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_YYYY),

Examples

Using trace a check on input parameters can be easily added & reported back.

void doSomething(unsigned char channel)
{
    //Channel must be < 24
    if(channel > 23)
    {
        //User has entered an invalid parameter, print message & param
        TRACE(WARN, INVALIDPARAM, NONE);
        TRACE_ADDVAR(WARN, HEX, channel);
        return;
    }
    ....
}

Similarly the more advanced processing could be used to print IPv6 addresses with ease:

extern unsigned char serverAddr[16];
//Report servers address in DEBUG level
TRACE_ADDVAR(DEBUG, IPV6ADDR, NETWORK, "Server's Address", serverAddr, 16);

Adding an TRACE_ADDRET() will add the address of the return function, which you can resolve to a function with addr2line utility if available.

//Add return information for INFO or lower only
TRACE_ADDRET(INFO);

Define Documentation

#define TRACE	(	level,
		trigger,
		action	)	/lint -E{506} -E{774}/if(TRACE_LEVEL_##level >= TRACE_LEVEL) fip_trace_print(TRACE_LEVEL_##level, __func__, FIP_TRACE_TR_##trigger, FIP_TRACE_ACT_##action)

Add a TRACE statement.

Parameters:

	level	Trace Level, one of DEBUG, INFO, WARN, ERROR
	trigger	Trigger for the TRACE, such as TIMEOUT, MEMORY, etc. The macro adds the FIP_TRACE_TR_ part, so just add the last section.
	action	Action performed such as NONE, DROPPED, etc. The macro adds the FIP_TRACE_ACT_ part, so just add the last section.

Referenced by fip_icmp6_process(), fip_ip_process(), fip_ip_send(), fip_nd6_6lowpan_processNA(), fip_nd6_periodicUnicast(), fip_nd6_process(), fip_nd6_processNA(), fip_packet_activeNew(), fip_packet_activeQueuePacket(), fip_packet_activeResponsePacket(), fip_route6_getNextHop(), fip_route6_process(), fip_sixlowpan_process(), fip_sixlowpanhc_compress(), and fip_task().

#define TRACE_ADDIP6ADDR	(	level,
		name,
		addr	)	TRACE_ADDVAR(level, IPV6ADDR, MSBFIRST, name, addr, 16)

Add an IPv6 Address to the trace statement.

Parameters:

	level	Trace level
	name	Name of the address to print
	addr	Pointer to the address to print

Referenced by fip_nd6_periodicUnicast().

#define TRACE_ADDRET ( level ) TRACE_ADDVAR(level, POINTER, HOST, "Retaddr", builtin_getRPtr(), sizeof(void *));

Add a statement with the return address of the function, can be used to figure out where the current function was called for.

Useful for functions which can be called from many places.

Parameters:

level

Trace level

Referenced by fip_packet_activeNew(), fip_packet_activeQueuePacket(), fip_packet_activeResponsePacket(), and fip_trace_test().

#define TRACE_ADDVAR	(	level,
		format,
		order,
		name,
		ptr,
		size	)	/lint -E{506} -E{774}/if(TRACE_LEVEL_##level >= TRACE_LEVEL) fip_trace_addvar(TRACE_ORDER_##order \| TRACE_FORMAT_##format, name, (unsigned char *)ptr, size);

Add a variable to the TRACE statement.

Parameters:

	level	Trace level, one of DEBUG, INFO, WARN, ERROR
	format	The format specified such as UNSIGNED, SIGNED, HEX, etc
	order	The byte order, either MSBFIRST, LSBFIRST, HOST, or NETWORK
	name	Name the varialbe should be printed as
	ptr	A pointer to the data to print. The only exception is for the POINTER format specifier, where you just pass the pointer and NOT a pointer to the pointer.
	size	Size in bytes, suggested to use the sizeof() macro to get this

Referenced by fip_nd6_6lowpan_processNA(), fip_nd6_process(), and fip_trace_test().

#define TRACE_ADDVARH	(	level,
		format,
		name	)	TRACE_ADDVAR(level, format, HOST, #name, &name, sizeof(name))

Add a hosts variable to the TRACE statement, small version that requires less information by making a number of assumptions.

Parameters:

	level	Trace level, one of DEBUG, INFO, WARN, ERROR
	format	The format specified such as UNSIGNED, SIGNED, HEX, etc
	name	Name of the variable, this will get printed, the pointer will be &name, and the size must be sizeof(name)

Referenced by fip_ip_process(), fip_packet_activeNew(), fip_packet_activeResponsePacket(), fip_sixlowpanhc_compress(), and fip_trace_test().