E:/fip/workspaces/fip/source/debug/fip_trace.h

Go to the documentation of this file.

/*
 * Copyright (c) 2010, FIP AUTHORS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   1) Redistributions of source code must retain the above copyright notice,
 *      this list of conditions and the following disclaimer.
 *
 *   2) Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *
 *   3) Neither the name of the FIP AUTHORS nor the names of its contributors
 *       may be used to endorse or promote products derived from this software
 *       without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */
#ifndef FIP_TRACE_H_
#define FIP_TRACE_H_
/**
 * @file
 *         Trace Functions
 *
 * @author
 *         Colin O'Flynn
 *
 */
/**
 * @addtogroup fip_trace
 * 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.
 *
 * @section extendingTriggers 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.
 *
 * @subsection step1 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:
@code
#define FIP_TRACE_TR_YYYY    N
#define FIP_TRACE_TR_YYYY_S  "Description string"
@endcode
 * Note when calling the macro with the TRACE() macros you will only pass the
 * YYYY part of the name, nothing else.
 *
 * @subsection step2 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
@code
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_YYYY);
@endcode
 *
 * @subsection step3 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.
@code
TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_YYYY),
@endcode
 *
 * @section examples Examples
 * Using trace a check on input parameters can be easily added & reported back.
 @code
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;
    }
    ....
}
@endcode
 *
 * Similarly the more advanced processing could be used to print IPv6 addresses with ease:
@code
extern unsigned char serverAddr[16];
//Report servers address in DEBUG level
TRACE_ADDVAR(DEBUG, IPV6ADDR, NETWORK, "Server's Address", serverAddr, 16);
@endcode
 *
 * Adding an TRACE_ADDRET() will add the address of the return function, which
 * you can resolve to a function with addr2line utility if available.
@code
//Add return information for INFO or lower only
TRACE_ADDRET(INFO);
 @endcode
 * @{
 */

/** @addtogroup fip_trace_levels Trace Levels
 * Trace levels define the severity of a trace statement.
 * Trace levels must go in order from least important = 0 to most important
 * for the comparisons to work. Do not add new trace levels without adjusting
 * the array of trace level names too!
 *
 * @par Setting the trace level
 * The default trace level is set in @ref TRACE_LEVEL_DEFAULT. However it can
 * be changed on a per-file basis by the following before including any FIP
 * headers, for example to use 'debug' level trace:
 @code
 #define TRACE_LEVEL TRACE_LEVEL_DEBUG
 #include "fip.h"
 @endcode
 * If you want to make TRACE_LEVEL, dynamic, just define it to what your
 * global variable is, for example:
@code
extern unsigned char globalTraceLevel;
#define TRACE_LEVEL globalTraceLevel
#include "fip.h"
@endcode
 */
/**@{*/

/** NONE: No statement printed ever, use to disable trace */
#define TRACE_LEVEL_NONE    4
/** ERROR: Error Level */
#define TRACE_LEVEL_ERROR   3
/** WARN: Warning level */
#define TRACE_LEVEL_WARN    2
/** INFO: Info level */
#define TRACE_LEVEL_INFO    1
/** DEBUG: Debug level */
#define TRACE_LEVEL_DEBUG   0

/** Default trace level */
#define TRACE_LEVEL_DEFAULT TRACE_LEVEL_INFO

#ifdef TRACE_USE_DYNAMIC
#if TRACE_USE_DYNAMIC
#undef TRACE_LEVEL
extern unsigned char fip_global_trace_level;
#define TRACE_LEVEL fip_global_trace_level
#endif
#endif

#ifdef MINIMIZE_STRING_WASTE
#define TRACE_LEVEL TRACE_LEVEL_NONE
#endif

#ifndef TRACE_LEVEL
#define TRACE_LEVEL TRACE_LEVEL_DEFAULT
#endif
/**@}*/

/* This file can define the strings if you set TRACE_DEFINE_STRINGS to 1 before
 * including it. */
#ifndef TRACE_DEFINE_STRINGS
#define TRACE_DEFINE_STRINGS 0
#endif

/* Not all platforms have/need __builtin_extract_return_address */
#ifndef __builtin_extract_return_address
#define __builtin_extract_return_address
#endif

/* Get the return pointer from the __builtin_return_address() function.
 * This doesn't work on AVR-GCC < 4.5 unfortunately so you need a pretty recent
 * build to use this (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=21078)*/
#define builtin_getRPtr() __builtin_extract_return_address(__builtin_return_address(0))

/* AVR stores strings in FLASH, otherwise strings just stored as CONST */
#if __AVR__
#define TRACE_DEFINE_CONSTSTRING(a) const char a##_P[] __attribute__((__progmem__)) = a##_S
#else
/* Special memcpy for getting string from FLASH if required */
#define memcpy_P memcpy
/* Special printf for getting string from FLASH if required */
#define printf_P printf
/* Force string to go into FLASH if required */
#define PROGMEM
/* Pointer to a constant string type, stored in FLASH */
#define PGM_P const char *
/* Define a constant string stored in FLASH */
#define TRACE_DEFINE_CONSTSTRING(a) const char a##_P[] = a##_S
#endif

/* Use this macro to initialise the array of trace strings.
 *
 * Uses C99 style array initialisation,
 * where you can specify the array element to be initialised. This prevents you
 * from requiring a very specific order of elements in case someone later changes
 * the number associated with a trace statement. */
#define TRACE_INIT_STRINGARRAY(a) [a] = a##_P

/*--------------- TRACE LEVELS -----------------*/
#define TRACE_LEVEL_DEBUG_S   "DEBUG"
#define TRACE_LEVEL_INFO_S    "INFO"
#define TRACE_LEVEL_WARN_S    "WARN"
#define TRACE_LEVEL_ERROR_S   "ERROR"
#define TRACE_LEVEL_NONE_S    ""

#if TRACE_DEFINE_STRINGS
TRACE_DEFINE_CONSTSTRING(TRACE_LEVEL_DEBUG);
TRACE_DEFINE_CONSTSTRING(TRACE_LEVEL_INFO);
TRACE_DEFINE_CONSTSTRING(TRACE_LEVEL_WARN);
TRACE_DEFINE_CONSTSTRING(TRACE_LEVEL_ERROR);
TRACE_DEFINE_CONSTSTRING(TRACE_LEVEL_NONE);

PGM_P trace_level_array[] PROGMEM = {
        TRACE_INIT_STRINGARRAY(TRACE_LEVEL_DEBUG),
        TRACE_INIT_STRINGARRAY(TRACE_LEVEL_INFO),
        TRACE_INIT_STRINGARRAY(TRACE_LEVEL_WARN),
        TRACE_INIT_STRINGARRAY(TRACE_LEVEL_ERROR),
        TRACE_INIT_STRINGARRAY(TRACE_LEVEL_NONE),
};
#else
extern PGM_P trace_level_array[] PROGMEM;
#endif

/*------------- TRACE TRIGGERS ------------------*/

#define FIP_TRACE_TR_NULL             0
#define FIP_TRACE_TR_NULL_S             ""

#define FIP_TRACE_TR_STARTINPUT       1
#define FIP_TRACE_TR_STARTINPUT_S       "Input processing begins"

#define FIP_TRACE_TR_STARTOUTPUT      2
#define FIP_TRACE_TR_STARTOUTPUT_S      "Output processing begins"

#define FIP_TRACE_TR_HDRINVALID       3
#define FIP_TRACE_TR_HDRINVALID_S       "Header Invalid"

#define FIP_TRACE_TR_TOOSHORT         4
#define FIP_TRACE_TR_TOOSHORT_S         "Packet too short"

#define FIP_TRACE_TR_WRONGADDR        5
#define FIP_TRACE_TR_WRONGADDR_S        "Packet not addressed to us"

#define FIP_TRACE_TR_SRCMULTI         6
#define FIP_TRACE_TR_SRCMULTI_S         "Source Address Multicast"

#define FIP_TRACE_TR_RXMULTI          7
#define FIP_TRACE_TR_RXMULTI_S          "Packet destined to us, multicast"

#define FIP_TRACE_TR_RXUNI            8
#define FIP_TRACE_TR_RXUNI_S            "Packet destined to us, unicast"

#define FIP_TRACE_TR_HDRUNKNOWN       9
#define FIP_TRACE_TR_HDRUNKNOWN_S       "Header type unknown"

#define FIP_TRACE_TR_CHECKSUM         10
#define FIP_TRACE_TR_CHECKSUM_S         "Checksum invalid"

#define FIP_TRACE_TR_MEMORY           11
#define FIP_TRACE_TR_MEMORY_S           "Out of memory"

#define FIP_TRACE_TR_TIMEOUT          12
#define FIP_TRACE_TR_TIMEOUT_S          "Timeout exceeded"

#define FIP_TRACE_TR_OUTOFORDER       13
#define FIP_TRACE_TR_OUTOFORDER_S       "Out of order packet delivery"

#define FIP_TRACE_TR_DAD_NS           14
#define FIP_TRACE_TR_DAD_NS_S           "DAD: NS Sent"

#define FIP_TRACE_TR_DAD_DONE         15
#define FIP_TRACE_TR_DAD_DONE_S         "DAD: Finished OK"

#define FIP_TRACE_TR_NA_SENT          16
#define FIP_TRACE_TR_NA_SENT_S          "Unsolicited NA Sent"

#define FIP_TRACE_TR_NA_UNKNOWN       17
#define FIP_TRACE_TR_NA_UNKNOWN_S       "NA Received but dropped as no reference in neighbour cache"

#define FIP_TRACE_TR_NA_NOLLAO        18
#define FIP_TRACE_TR_NA_NOLLAO_S        "NA Received but dropped as no LLAO present"

#define FIP_TRACE_TR_INVALIDPARAM     19
#define FIP_TRACE_TR_INVALIDPARAM_S     "Invalid Parameters"

#define FIP_TRACE_TR_ULSET            20
#define FIP_TRACE_TR_ULSET_S            "U/L Bit Set"

#define FIP_TRACE_TR_ULNOTSET         21
#define FIP_TRACE_TR_ULNOTSET_S         "U/L Bit Not Set"

#define FIP_TRACE_TR_IIDMATCH         22
#define FIP_TRACE_TR_IIDMATCH_S         "IID Matches"

#define FIP_TRACE_TR_ADDRDUPLICATE    24
#define FIP_TRACE_TR_ADDRDUPLICATE_S    "Duplicate Address"

#define FIP_TRACE_TR_ROUTINGHEADER    25
#define FIP_TRACE_TR_ROUTINGHEADER_S    "Routing Header"

#define FIP_TRACE_TR_ROUTEFAILED      26
#define FIP_TRACE_TR_ROUTEFAILED_S      "Route Failed"

#define FIP_TRACE_TR_NARECEIVED       27
#define FIP_TRACE_TR_NARECEIVED_S       "NA Received"

#define FIP_TRACE_TR_NOTAUTOCONF      28
#define FIP_TRACE_TR_NOTAUTOCONF_S      "Address not autoconf based"

#define FIP_TRACE_TR_TOOBIG           29
#define FIP_TRACE_TR_TOOBIG_S           "Packet too big"

#define FIP_TRACE_TR_TTLZERO          30
#define FIP_TRACE_TR_TTLZERO_S          "TTL of Zero"

#define FIP_TRACE_TR_UNKNOWNOPT       31
#define FIP_TRACE_TR_UNKNOWNOPT_S       "Unknown option type"

#define FIP_TRACE_TR_ECHOREQ          32
#define FIP_TRACE_TR_ECHOREQ_S          "ICMP Echo Request"

#define FIP_TRACE_TR_QUEUE            33
#define FIP_TRACE_TR_QUEUE_S            "Packet removed from Queue"

#define FIP_TRACE_TR_FRAG             34
#define FIP_TRACE_TR_FRAG_S             "Fragmentation"

/* Adding new trigger: STEP1: Add a #define pair above this line */

#if TRACE_DEFINE_STRINGS
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_NULL);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_STARTINPUT);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_STARTOUTPUT);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_HDRINVALID);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_TOOSHORT);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_WRONGADDR);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_SRCMULTI);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_RXMULTI);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_RXUNI);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_HDRUNKNOWN);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_CHECKSUM);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_MEMORY);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_TIMEOUT);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_OUTOFORDER);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_DAD_NS);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_DAD_DONE);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_NA_SENT);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_NA_UNKNOWN);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_NA_NOLLAO);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_INVALIDPARAM);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_ULSET);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_ULNOTSET);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_IIDMATCH);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_ADDRDUPLICATE);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_ROUTINGHEADER);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_ROUTEFAILED);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_NARECEIVED);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_NOTAUTOCONF);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_TOOBIG);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_TTLZERO);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_UNKNOWNOPT);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_ECHOREQ);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_QUEUE);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_TR_FRAG);
/* Adding new trigger: STEP2: Add a TRACE_DEFINE_CONSTSTRING() above this line */

PGM_P trace_trigger_array[] PROGMEM = {
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_NULL),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_STARTINPUT),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_STARTOUTPUT),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_HDRINVALID),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_TOOSHORT),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_WRONGADDR),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_SRCMULTI),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_RXMULTI),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_RXUNI),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_HDRUNKNOWN),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_CHECKSUM),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_MEMORY),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_TIMEOUT),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_OUTOFORDER),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_DAD_NS),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_DAD_DONE),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_NA_SENT),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_NA_UNKNOWN),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_NA_NOLLAO),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_INVALIDPARAM),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_ULSET),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_ULNOTSET),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_IIDMATCH),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_ADDRDUPLICATE),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_ROUTINGHEADER),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_ROUTEFAILED),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_NARECEIVED),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_NOTAUTOCONF),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_TOOBIG),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_TTLZERO),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_UNKNOWNOPT),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_ECHOREQ),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_QUEUE),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_TR_FRAG),
    /* Adding new trigger: STEP3: Add a TRACE_INIT_STRINGARRAY() above this line */
};

#else
extern PGM_P trace_trigger_array[] PROGMEM;
#endif

/*------------- TRACE ACTIONS ------------------*/

#define FIP_TRACE_ACT_NONE             0
#define FIP_TRACE_ACT_NONE_S             ""

#define FIP_TRACE_ACT_DROPPED          1
#define FIP_TRACE_ACT_DROPPED_S          "Dropped"

#define FIP_TRACE_ACT_EXCEPTION        2
#define FIP_TRACE_ACT_EXCEPTION_S        "Exception raised"

#define FIP_TRACE_ACT_SKIPDAD          3
#define FIP_TRACE_ACT_SKIPDAD_S          "Moving address to preferred"

#define FIP_TRACE_ACT_DISABLED         4
#define FIP_TRACE_ACT_DISABLED_S         "Disabled"

#define FIP_TRACE_ACT_FAILED           5
#define FIP_TRACE_ACT_FAILED_S           "Failed"

#define FIP_TRACE_ACT_SENDING          6
#define FIP_TRACE_ACT_SENDING_S          "Sending"

#define FIP_TRACE_ACT_DONE             7
#define FIP_TRACE_ACT_DONE_S             "Done"

/* Adding new action: STEP1: Add a #define pair above this line */

#if TRACE_DEFINE_STRINGS
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_ACT_NONE);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_ACT_DROPPED);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_ACT_EXCEPTION);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_ACT_SKIPDAD);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_ACT_DISABLED);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_ACT_FAILED);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_ACT_SENDING);
TRACE_DEFINE_CONSTSTRING(FIP_TRACE_ACT_DONE);
/* Adding new action: STEP2: Add a TRACE_DEFINE_CONSTSTRING() above this line */

PGM_P trace_action_array[] PROGMEM = {
    TRACE_INIT_STRINGARRAY(FIP_TRACE_ACT_NONE),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_ACT_DROPPED),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_ACT_EXCEPTION),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_ACT_SKIPDAD),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_ACT_DISABLED),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_ACT_FAILED),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_ACT_SENDING),
    TRACE_INIT_STRINGARRAY(FIP_TRACE_ACT_DONE),
    /* Adding new action: STEP3: Add a TRACE_INIT_STRINGARRAY() above this line */
};
#else
extern PGM_P trace_action_array[] PROGMEM;
#endif

typedef unsigned char fip_trace_lvl_t;
typedef unsigned char fip_trace_tr_t;
typedef unsigned char fip_trace_act_t;

/**
 * Add a TRACE statement.
 *
 * @param level Trace Level, one of DEBUG, INFO, WARN, ERROR
 * @param trigger Trigger for the TRACE, such as TIMEOUT, MEMORY, etc. The macro
 *                adds the FIP_TRACE_TR_ part, so just add the last section.
 * @param action Action performed such as NONE, DROPPED, etc. The macro
 *                adds the FIP_TRACE_ACT_ part, so just add the last section.
 */
#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 variable to the TRACE statement.
 *
 * @param level Trace level, one of DEBUG, INFO, WARN, ERROR
 * @param format The format specified such as UNSIGNED, SIGNED, HEX, etc
 * @param order The byte order, either MSBFIRST, LSBFIRST, HOST, or NETWORK
 * @param name Name the varialbe should be printed as
 * @param 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.
 * @param size Size in bytes, suggested to use the sizeof() macro to get this
 */
#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 hosts variable to the TRACE statement, small version that requires
 * less information by making a number of assumptions
 * @param level Trace level, one of DEBUG, INFO, WARN, ERROR
 * @param format The format specified such as UNSIGNED, SIGNED, HEX, etc
 * @param name Name of the variable, this will get printed, the pointer will be
 *             &name, and the size must be sizeof(name)
 */
#define TRACE_ADDVARH(level, format, name) TRACE_ADDVAR(level, format, HOST, #name, &name, sizeof(name))

/**
 * 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.
 *
 * @param level Trace level
 */
#define TRACE_ADDRET(level) TRACE_ADDVAR(level, POINTER, HOST, "Retaddr", builtin_getRPtr(), sizeof(void *));

/**
 * Add an IPv6 Address to the trace statement
 *
 * @param level Trace level
 * @param name Name of the address to print
 * @param addr Pointer to the address to print
 */
#define TRACE_ADDIP6ADDR(level, name, addr) TRACE_ADDVAR(level, IPV6ADDR, MSBFIRST, name, addr, 16)

/** No format, no data */
#define TRACE_FORMAT_NULL       0

/** Unsigned decimal */
#define TRACE_FORMAT_UNSIGNED   1

/** Signed decimal */
#define TRACE_FORMAT_SIGNED     2

/** Hex of form 0xYY, 0xYYYY, etc depending on length */
#define TRACE_FORMAT_HEX        3

/** IPv6 Address */
#define TRACE_FORMAT_IPV6ADDR   4

/** Address in form YY:YY:YY:YY */
#define TRACE_FORMAT_BYTEADDR   5

#define TRACE_FORMAT_POINTER    6


/** Flag: network order  */
#define TRACE_ORDER_MSBFIRST    0x80

/** Flag: host order */
#define TRACE_ORDER_LSBFIRST    0x00

/** Flag mask */
#define TRACE_ORDER_MASK        0x80

/** Format mast */
#define TRACE_FORMAT_MASK       0x7F

#define TRACE_ORDER_HOST    TRACE_ORDER_LSBFIRST
#define TRACE_ORDER_NETWORK TRACE_ORDER_MSBFIRST

/* Print a DEBUG/INFO/WARN/ERROR trace statement, you should use the TRACE()
 * macro instead of this directly. */
void fip_trace_print(fip_trace_lvl_t level,
                     const char * funcName,
                     fip_trace_tr_t trigger,
                     fip_trace_act_t action);


/* Print a variable, you should use the TRACE statements instead of this
 * directly */
void fip_trace_addvar(unsigned char format_code,
                      char * name,
                      unsigned char *ptr,
                      unsigned char size);

/** Run a test by printing a number of TRACE statements. Useful to check the
 * output is working OK. */
void fip_trace_test(void);

/**@}*/

#endif /* FIP_TRACE_H_ */

---