diff options
Diffstat (limited to 'src/include/usr/trace/interface.H')
| -rw-r--r-- | src/include/usr/trace/interface.H | 350 |
1 files changed, 350 insertions, 0 deletions
diff --git a/src/include/usr/trace/interface.H b/src/include/usr/trace/interface.H new file mode 100644 index 000000000..6d62efca0 --- /dev/null +++ b/src/include/usr/trace/interface.H @@ -0,0 +1,350 @@ +/****************************************************************************** + * IBM Confidential + * + * Licensed Internal Code Source Materials + * + * IBM Flexible Support Processor Licensed Internal Code + * + * (c) Copyright IBM Corp. 2004, 2010 + * + * The source code is for this program is not published or otherwise divested + * of its trade secrets, irrespective of what has been deposited with the + * U.S. Copyright Office. + *****************************************************************************/ + +#ifndef __TRACE_INTERFACE_H +#define __TRACE_INTERFACE_H + +/*!@file interface.H + * @brief Contains macros for trace interface + * + * Note that this file was for the most parted ported in from the fsp-trace + * implementation. + * + * This header file provides a common interface for the Trace + * mechanism. + * + * There are two types of trace, debug and field, that you can use when tracing. + * Debug traces are not enabled by default, they must be enabled by the user. + * Field traces will always be enabled. +*/ + +/******************************************************************************/ +// Includes +/******************************************************************************/ +#include <stdint.h> + +/******************************************************************************/ +// Globals/Constants +/******************************************************************************/ +#define ENTER_MRK ">>" +#define EXIT_MRK "<<" +#define ERR_MRK "E>" +#define INFO_MRK "I>" +#define ARG_MRK "A>" + +#define TRAC_COMP_SIZE 16 // Max component name size +#define TRAC_MAX_ARGS 9 // Max number of arguments in trace + + +#define TRACE_DEBUG 1 //Indicates trace is debug +#define TRACE_FIELD 0 //Indicates trace is field + +// check compatibility of header file/macros and preprocessor tracepp +// if tracepp was used +#define TRAC_MACROVER 1 +#ifdef TRAC_TRACEPP +#if !defined(TRAC_PPVER) +#warning fsptrace preprocessor version unknown, might be incompatible with header file +#elif TRAC_PPVER < TRAC_MACROVER +#error fsptrace header file version and preprocessor version dont fit +#endif +#endif + + +/* for any trace_adal_write_all call we need the printf_string in addition to + * the hash value. if tracepp is used it will add a (shortened) printf string, + * otherwise the macros has to add it + */ +#ifdef TRAC_TRACEPP +#define __ALL_HASH(printf_string,num) trace_adal_hash(printf_string,num) +#else +#define __ALL_HASH(printf_string,num) trace_adal_hash(printf_string,num),printf_string +#endif + +/******************************************************************************/ +// Macros +/******************************************************************************/ + +#ifdef TRAC_DEBUG_OUT /* compile out everyones debug traces */ + +#define TRACDCOMP(des,printf_string,args...) do {} while(0) +#define TRACDBIN(des,descString,address,length) do {} while(0) + +#else /* direct them to real function calls */ + +/** + * @fn void TRACDCOMP0(des, printf_string) + * @brief Defines all Debug Component Traces + * + * The user can pass 0 to 9 parameters to the macro. In the field environment, + * these trace calls will be compiled out of the code. Use these for early bringup + * needs. These trace calls are written to a memory buffer. + * + * @param des This is assigned by TRAC_INIT_BUFFER + * @param printf_string String describing the trace entry and providing the + * formatting flags for any parameters passed. + * @param p1,p2... Optional parameters + * + * @return void +*/ + +/* a macro w/o the param number suffix. number is calculated from printf string */ +#define TRACDCOMP(des,printf_string,args...) \ + TRACE::trace_adal_write_all((des),__ALL_HASH(printf_string,-1),__LINE__,TRACE_DEBUG, ##args) + +/** + * @fn void TRACDBIN(des,descString,address,length) + * @brief Defines debug binary trace + * + * The binary trace should be used to write out a section of memory. + * + * @param des This is assigned by TRAC_INIT_BUFFER + * @param descString A string that will be put in front of the binary dump, + * developer assigns anything they want. + * @param address Address of beginning of data to dump. + * @param length length of the binary data. + * + * @return void + +*/ +#define TRACDBIN(des,printf_string,address,len) \ + TRACE::trace_adal_write_bin(des,__ALL_HASH(printf_string,0), \ + __LINE__, \ + address, \ + len, \ + TRACE_DEBUG) +#endif /* TRAC_DEBUG_OUT */ + +/** + * @fn void TRACFCOMP0(des, printf_string) + * @brief Defines all Field Component Traces + * + * The user can pass 0 to 9 parameters to the macro. These trace calls will + * always be written to the trace memory buffer. + * + * @param des This is assigned by TRAC_INIT_BUFFER + * @param printf_string String describing the trace entry and providing the + * formatting flags for any parameters passed. + * @param p1,p2... Optional parameters + * + * @return void +*/ + +/* a macro w/o the param number suffix. number is calculated from printf string */ +#define TRACFCOMP(des,printf_string,args...) \ + TRACE::trace_adal_write_all((des),__ALL_HASH(printf_string,-1),__LINE__,TRACE_FIELD, ##args) + + +/** + * @fn void TRACFBIN(des,descString,address,len) + * @brief Defines field binary trace + * + * The binary trace should be used to write out a section of memory. + * + * @param des This is assigned by TRAC_INIT_BUFFER + * @param descString A string that will be put in front of the binary dump, + * developer assigns anything they want. + * @param address Address of beginning of data to dump. + * @param length lenght of the binary data. + * + * @return void +*/ +#define TRACFBIN(des,printf_string,address,len) \ + TRACE::trace_adal_write_bin(des,__ALL_HASH(printf_string,0), \ + __LINE__, \ + address, \ + len, \ + TRACE_FIELD) + +/** + * @fn void TRAC_INIT_BUFFER(des,comp_name, bufferSize) + * @brief Initializes trace buffer for component + * + * This function must be called before any other trace calls. It + * initializes a buffer for the calling component and returns a trace + * descriptor which is used by the trace calls to find the correct + * buffer to write to. + * + * @param des This is assigned by this function. + * @param comp_name This is the four character name of the component requesting + * the trace buffer. + * @param bufferSize Requested length of the buffer, if 0 is entered the user will + * get default buffer size. + * @return void +*/ +#define TRAC_INIT_BUFFER(des,comp_name, bufferSize) \ + TRACE::trace_adal_init_buffer((des), (comp_name), (bufferSize)) + +/******************************************************************************* + TRAC_INIT: Class for creating trace descriptor object. + + About the macros. + TRAC_INIT -- Called by users, adds __LINE__ for uniqueness. + TRAC_INIT_LINE -- Translates __LINE__ into the line number. Using + macro expansion in this statement would result in + tracInit static g_trac_"__LINE__" + TRAC_INIT_UNIQ -- With line number translated, use the '##' operator to + append number in variable name. +*******************************************************************************/ + +#define TRAC_INIT_UNIQ(des, name, sz, ln) TRACE::TracInit static g_trac_##ln(des, name, sz) +#define TRAC_INIT_LINE(des, name, sz, ln) TRAC_INIT_UNIQ(des, name, sz, ln) +#define TRAC_INIT(des, name, sz) TRAC_INIT_LINE(des, name, sz, __LINE__) + + +/******************************************************************************/ +// Internals - Not to be called or used directly by host boot code +/******************************************************************************/ + + +typedef uint32_t trace_hash_val; // Hash values are 32 bytes + +/* + * @brief Structure is put at beginning of all trace buffers + */ +typedef struct trace_buf_head { + unsigned char ver; /*!< version of this struct (1) */ + unsigned char hdr_len; /*!< size of this struct in bytes */ + unsigned char time_flg; /*!< meaning of timestamp entry field */ + unsigned char endian_flg; /*!< flag for big ('B') or little ('L') endian*/ + char comp[TRAC_COMP_SIZE]; /*!< the buffer name as specified in init call*/ + uint32_t size; /*!< size of buffer, including this struct */ + uint32_t times_wrap; /*!< how often the buffer wrapped */ + uint32_t next_free; /*!< offset of the byte behind the latest entry*/ + uint32_t te_count; /*!< Updated each time a trace is done */ + uint32_t extracted; /*!< Not currently used */ +}trace_buf_head_t; + +/*! + * @brief Timestamp and thread id for each trace entry. + */ +typedef struct trace_entry_stamp { + //uint32_t tbh; /*!< timestamp upper part */ + //uint32_t tbl; /*!< timestamp lower part */ + uint32_t tb[2]; + //uint64_t tb; + uint32_t tid; /*!< process/thread id */ +}trace_entry_stamp_t; + +/* + * @brief Structure is used by adal app. layer to fill in trace info. + */ +typedef struct trace_entry_head { + uint16_t length; /*!< size of trace entry */ + uint16_t tag; /*!< type of entry: xTRACE xDUMP, (un)packed */ + uint32_t hash; /*!< a value for the (format) string */ + uint32_t line; /*!< source file line number of trace call */ +}trace_entry_head_t; + +/* + * @brief Parameter traces can be all contained in one write. + */ +typedef struct trace_entire_entry { + trace_entry_stamp_t stamp; + trace_entry_head_t head; + uint64_t args[TRAC_MAX_ARGS + 1]; +} trace_entire_entry_t; + + +/* + * @brief Binary first writes header and time stamp. + */ +typedef struct trace_bin_entry { + trace_entry_stamp_t stamp; + trace_entry_head_t head; +} trace_bin_entry_t; + +/** + * @brief New version name of this typedef + */ +typedef trace_buf_head_t trace_desc_t; + +namespace TRACE +{ + +/** + * @brief Initialize a trace buffer + * + * @param o_td[out] Trace descriptor to initialize + * @param i_comp[in] Component name for trace buffer + * @param i_size[in] Size to allocate for trace buffer + * + * @return void + */ +void trace_adal_init_buffer(trace_desc_t **o_td, + const char* i_comp, + const size_t i_size ); + +/** + * @brief Write component trace out to input buffer + * + * @param io_td[inout] Trace descriptor of buffer to write to. + * @param i_hash[in] Descriptive string hash value + * @param i_fmt [in] Formatting string + * @param i_line[in] Line number trace was done at + * @param i_type[in] Type of trace (TRACE_DEBUG, TRACE_FIELD) + * + * @return void + */ +void trace_adal_write_all(trace_desc_t *io_td, + const trace_hash_val i_hash, + const char * i_fmt, + const uint32_t i_line, + const int32_t i_type, ...); + +/** + * @brief Write binary data out to trace buffer + * + * @param io_td[inout] Trace descriptor of buffer to write to. + * @param i_hash[in] Descriptive string hash value + * @param i_line[in] Line number trace was done at + * @param i_ptr[in] Pointer to binary data + * @param i_size[in] Size of binary data + * @param i_type[in] Type of trace (TRACE_DEBUG, TRACE_FIELD) + * + * @return void + */ +void trace_adal_write_bin(trace_desc_t * io_td, + const trace_hash_val i_hash, + const uint32_t i_line, + const void *i_ptr, + const uint32_t i_size, + const int32_t type); + + +/******************************************************************************/ +// Allow users to init trace buffer outside of a function +/******************************************************************************/ +class TracInit +{ + public: + + /*------------------------------------------------------------------------*/ + /* Constructor */ + /*------------------------------------------------------------------------*/ + + TracInit(trace_desc_t **o_td, const char *i_comp,const size_t i_size) + { + TRAC_INIT_BUFFER(o_td,i_comp,i_size); + } + + ~TracInit() + { + } + +}; + +}; // Namespace + +#endif //! -- !defined __TRACE_INTERFACE_H |
