summaryrefslogtreecommitdiffstats
path: root/src/include/tracinterface.H
blob: a6d8853143f8f89f6ca3ea4029c01f109d3ed4ea (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
/******************************************************************************
 * 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 TRACINTERFACE_H
#define TRACINTERFACE_H

/*!@file tracinterface.H
 * @brief Contains macros for trace interface
 *
 * This header file provides a common interface for the Trace
 * mechanism.  Trace is a way for developers to debug their code.  They
 * can use the trace Macro's to write to standar out, to wraparound files and
 * to a wraparound buffer which will be stored in shared memory.
 *
 * There are two types of trace, debug and field, that you can use when tracing.
 * Debug traces will be compiled out of the code when the system is released to the field.
 * Field traces will be remain in the code permenantly.
 *
 * TRACxSYSn calls will always go to syslog
 *
 * There are three different environments trace will operate in.
 *
 * Unit Test / Simulation: All component traces (debug and field) are sent to standard out by default.
 * The developer has the option to do define an evironmental variable:
 * 'export FIPS_TRACE_PATH="<path>"' where path is the location to write the files (ex. "./").
 *
 * Lab: All component traces will, by default, follow the same implementation as the
 * Unit Test / Simulation env.  However, drivers flashed onto the system (built by the
 * build team) will use the memory wrapping implementation.  Code built in a local
 * sandbox will continue to use the file wrapping implementation.  This will give
 * the developer the speed of the memory wrapping trace (for code they don't really
 * care about) and ease of debug with the file wrapping code (for their own code).
 *
 * Field: Only component traces of type field will be sent to the shared memory wraparound
 * buffer.  Debug traces will be compiled out of the code.
 *
 * In Unit Test / Simulation, The file will have the name "trac" + 'component name'.
 * For example the error logger component would be <path>/tracERRL
*/
/* Change Log *****************************************************************/
/*                                                                            */
/* ch#  Feat/def# Userid    Date      Description                             */
/* --- ---------- --------  --------  ----------------------------------------*/
/* 00   N/A       andrewg   08/27/01  Created                                            */
/* 01   N/A       andrewg   10/03/01  Removed duplicate copyright and other housekeeping */
/* 02   N/A       andrewg   10/17/01  Added deallocateBuffer flag to TRAC_FREE_BUFFER    */
/* 03   N/A       andrewg   10/19/01  Added 'using namespace std;', vector.h -> vector   */
/*                                     included iostream.h, printf bug.                  */
/* 04   354052    andrewg   11/09/01  Took out file writing portion, only go to printf   */
/* ag05 354388    andrewg   11/14/01  Changed binary macro name and added typedef        */
/* ag06 354696    andrewg   11/19/01  Removed ag05 change flags, causing errors          */
/* n/a  355095    andrewg   11/28/01  Put common.h include first                         */
/* ag07 354971    andrewg   11/28/01  Added file wrapping code                           */
/* ag08 359225    andrewg   02/11/01  Added memory wrapping code, removed USE_PRINTF defined flag */
/* ag09 360869    andrewg   03/04/02  Added persistant writing macro                     */
/* ag10 361649    andrewg   03/08/02  Added the constants                                */
/* n/a  363697    andrewg   03/28/02  Modified to use new file object                    */
/* n/a  376324    andrewg   07/24/02  Fixed bad define of TRACDCOMP9                     */
/* ag11 382759    andrewg   09/09/02  Support compile flag to remove debug trace         */
/* n/a  385314    andrewg   09/27/02  Remove use of STL                                  */
/* n/a  388981    andrewg   11/12/02  Add new static variable constructor                */
/* n/a  HBIBASE   iawilllia 10/05/10  Removed a lot of stuff for HBI trace base.         */
/* End Change Log *************************************************************/

//--------------------------------------------------------------------//
//  Constants                                                         //
//--------------------------------------------------------------------//
#define ENTER_MRK ">>"  // -- ag10
#define EXIT_MRK  "<<"  // -- ag10
#define ERR_MRK	  "E>"  // -- ag10
#define INFO_MRK  "I>"  // -- ag10
#define ARG_MRK	  "A>"  // -- ag10

#ifndef NFP_CLIENT  // dc99
#include <stdint.h>
#include <trace_adal.h>
#else
typedef int tracDesc_t;
typedef int trace_desc_t;
#endif

#if( defined(NFP_LIBRARY) || defined(NFP_CLIENT) )  // dc99

#define TRACSCOMP(des,printf_string,args...) do {} while(0)
#define TRACDCOMP(des,printf_string,args...) do {} while(0)
#define TRACDBIN(des,descString,address,length) do {} while(0)

#define TRACFCOMP(des,printf_string,args...) \
	printf(printf_string "\n", ##args)
#define TRACFBIN(des,descString,address,length) \
        printf("%s pointer:%p size:%d\n",descString,address,length)

#define TRAC_INIT_BUFFER(des,comp_name, bufferSize) \
        *(des) = 1

#define TRAC_INIT(des,comp_name, bufferSize)

#define TRAC_FREE_BUFFER(des,deallocateBuff) do {} while(0)

#else

// 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

//------------------------------------------------------------------------------
// INCLUDES
//------------------------------------------------------------------------------

#include <trace_adal.h>

/* 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

#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.
 @note If you are passing parameters then make sure 'printf_string' has the
 @note necessary parameter formatting i.e. 'p1' = "hello" make sure
 @note 'printf_string' has "%s" somewhere in it to corretcly format p1.
 @return void The user will not be impacted by the failure of this function
 @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
*/

/* a macro w/o the param number suffix. number is calculated from printf string */
#define TRACDCOMP(des,printf_string,args...) \
        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.  The debug
 binary trace will be compiled out in the field environment so only use for early
 bringup debug. When this is being written to a file, it will be displayed in
 hexidecimal.
 @return void The user will not be impacted by the failure of this function
 @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.
*/
#define TRACDBIN(des,descString,address,len) \
        do{ trace_entry_head_t __e; \
            __e.tag    = TRACE_DEBUGBIN; \
            __e.line   = __LINE__; \
            __e.length = (len); \
            __e.hash   = trace_adal_hash(descString, 0); \
            trace_adal_write2((des), TRACE_DEBUG, sizeof(trace_entry_head_t), &__e, \
                             (uint32_t) (__e.length), (uint32_t *) (address)); \
        } while(0)

#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.
 @note If you are passing parameters then make sure 'printf_string' has the
 @note necessary parameter formatting
 @note i.e. 'p1' = "hello" make sure 'printf_string' has "%s" somewhere in
 @note it to corretcly format p1.
 @return void The user will not be impacted by the failure of this function
 @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
*/

/* a macro w/o the param number suffix. number is calculated from printf string */
#define TRACFCOMP(des,printf_string,args...) \
        trace_adal_write_all((des),__ALL_HASH(printf_string,-1),__LINE__,TRACE_FIELD, ##args)

/**
 @fn void TRACSCOMP0(des, printf_string)
 @brief Defines all Strace Component Traces

 The user can pass 0 to 9 parameters to the macro.  These traces will be treated
 as debug traces but will never be compiled out of the code so that they can always be
 dynamically turned on/off.

 @note If you are passing parameters then make sure 'printf_string' has the
 @note necessary parameter formatting i.e. 'p1' = "hello" make sure
 @note 'printf_string' has '%s' somewhere in it to corretcly format p1.
 @return void The user will not be impacted by the failure of this function
 @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

 tracepp replaces trace_adal_hash() with hash value and reduced format string
*/

/* a macro w/o the param number suffix. number is calculated from printf string */
#define TRACSCOMP(des,printf_string,args...) \
        trace_adal_write_all((des),__ALL_HASH(printf_string,-1),__LINE__,TRACE_DEBUG, ##args)

/**
 @fn void TRACFBIN(des,descString,address,length)
 @brief Defines field binary trace

 The binary trace should be used to write out a section of memory.  The field
 binary trace will always be logged so use for important information.
 When this is being written to a file, it will be displayed in hexidecimal.
 @return void The user will not be impacted by the failure of this function
 @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.
*/
#define TRACFBIN(des,descString,address,len) \
        do{ trace_entry_head_t __e; \
            __e.tag    = TRACE_FIELDBIN; \
            __e.line   = __LINE__; \
            __e.length = (len); \
            __e.hash   = trace_adal_hash(descString, 0); \
            trace_adal_write2((des), TRACE_FIELD, sizeof(trace_entry_head_t), &__e, \
                             (uint32_t) (__e.length), (uint32_t *) (address)); \
        } while(0)

			
/**
 @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 file for the calling component and returns a trace
 descriptor which is used by the trace calls to find the correct file to write to.
 @return void The user will not be impacted by the failure of this function. If des is a positive value, success.
 @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.
*/
#define TRAC_INIT_BUFFER(des,comp_name, bufferSize) \
        trace_adal_init_buffer((des), (comp_name), (bufferSize))


class TracInit
{
  public:

    /*------------------------------------------------------------------------*/
    /* Constructor                                                            */
    /*------------------------------------------------------------------------*/

    TracInit(tracDesc_t *o_td, const char *i_comp,const size_t i_size)
    {
        // printf("TracInit constructor called for %s, size %u\n",i_comp,i_size);
        TRAC_INIT_BUFFER(o_td,i_comp,i_size);
    }

    ~TracInit()
    {
        // printf("in the TracInit destructor\n");
    }

};

/*******************************************************************************
  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) 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__)

#endif  //! -- NFP Library
#endif //! -- !defined TRACINTERFACE_H
OpenPOWER on IntegriCloud