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
|
/* IBM_PROLOG_BEGIN_TAG */
/* This is an automatically generated prolog. */
/* */
/* $Source: src/include/usr/trace/trace.H $ */
/* */
/* IBM CONFIDENTIAL */
/* */
/* COPYRIGHT International Business Machines Corp. 2011,2013 */
/* */
/* p1 */
/* */
/* Object Code Only (OCO) source materials */
/* Licensed Internal Code Source Materials */
/* IBM HostBoot Licensed Internal Code */
/* */
/* The source code 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. */
/* */
/* Origin: 30 */
/* */
/* IBM_PROLOG_END_TAG */
/**
* @file trace.H
*
* Internal trace definitions and functions. External users should
* not directly include or use this file. trace/interface.H is the external
* file.
*/
#ifndef __TRACE_TRACE_H
#define __TRACE_TRACE_H
#include <stdint.h>
#include <trace/interface.H>
const uint32_t TRACE_DEBUG_ON = 1; //< Set to this when debug trace on
const uint32_t TRACE_DEBUG_OFF = 0; //< Set to this when debug trace off
const uint32_t TRAC_COMP_SIZE = 16; //< Max component name size
const uint32_t TRAC_MAX_ARGS = 9; //< Max number of arguments in trace
typedef uint32_t trace_hash_val; //< Hash values are 32 bits.
extern "C" {
/**
* @brief dummy function to satisfy BEAM.
* C files are normally pre(pre)processed by the "tracepp" script,
* which translates this function call to a call to a unique hash function.
* When BEAM is run on the un-preprocessed files, it outputs lots
* of parser errors because it cannot find this function.
* This must be extern "C", otherwise BEAM cannot find it.
*/
trace_hash_val trace_adal_hash( ... ) ;
} // end extern "C"
namespace TRACE
{
class ComponentDesc; // Forward declaration.
/** @brief Buffer type that a component is directed to. */
enum BUFFER_TYPES
{
BUFFER_SLOW, //< Traces are part of an infinite non-blocking buffer.
BUFFER_FAST, //< Traces are part of a smaller blocking buffer.
BUFFER_COUNT //< Number of trace buffers supported.
};
/**
* @brief Initialize a trace buffer.
*
* Size is capped at 2KB. You can request larger, but
* the code in src/usr/trace/trace.C imposes
* a maximum size of 2KB. Sizes smaller than 2KB
* will save space.
*
* @param [out] o_td Trace descriptor to initialize
* @param [in] i_comp Component name for trace buffer
* @param [in] i_size Size to allocate for trace buffer
* @param [in] i_bufferType Type of buffer.
*
* @return void
*/
void initBuffer(ComponentDesc **o_td,
const char* i_comp,
size_t i_size,
uint8_t i_bufferType = BUFFER_FAST);
/**
* @brief Write component trace out to input buffer
*
* Note that to continue to support tracepp, we must keep the
* name of this function as is.
*
* @param [in,out] io_td Trace descriptor of buffer to write to.
* @param [in] i_hash Descriptive string hash value
* @param [in] i_fmt Formatting string
* @param [in] i_line Line number trace was done at
* @param [in] i_type Type of trace (TRACE_DEBUG, TRACE_FIELD)
*
* @return void
*/
void trace_adal_write_all(ComponentDesc *io_td,
const trace_hash_val i_hash,
const char * i_fmt,
const uint32_t i_line,
const uint32_t i_type, ...);
/**
* @brief Write binary data out to trace buffer
*
* Note that to continue to support tracepp, we must keep the
* name of this function as is.
*
* @param [in,out] io_td Trace descriptor of buffer to write to.
* @param [in] i_hash Descriptive string hash value
* @param [in] i_line Line number trace was done at
* @param [in] i_ptr Pointer to binary data
* @param [in] i_size Size of binary data
* @param [in] i_type Type of trace (TRACE_DEBUG, TRACE_FIELD)
*
* @return void
*/
void trace_adal_write_bin(ComponentDesc * io_td,
const trace_hash_val i_hash,
const uint32_t i_line,
const void *i_ptr,
const uint32_t i_size,
const uint32_t i_type);
/**
* @brief Retrieve the trace buffer named by i_pName
*
* Caller must allocate memory for the output buffer. Caller may
* first query the size of the buffer by calling with the desired
* buffer name and with o_data null and i_bufferSize
* zero. The value returned will be the full buffer size. Caller
* allocates the buffer and calls again.
*
* The buffer provided can be less than the full size of the desired
* buffer. In that case, this function will copy as many of the most
* recent traces into the output buffer as will fit. The buffer must
* be big enough to hold a trace buffer header (40 bytes).
*
* i_bufferSize may be larger that the desired trace buffer.
*
* @param [in] i_pName name of trace buffer
* @param [out] o_data pointer to output buffer
* @param [in] i_bufferSize size of output buffer in bytes
*
* @return Count of bytes copied, or if given null parameters,
* the size of the buffer. Returns zero for error, perhaps the
* component name/trace buffer name is not found, or perhaps
* the size of the provided buffer is unreasonable.
*/
size_t getBuffer( const char * i_pName,
void * o_data,
size_t i_bufferSize );
/**
* @brief flush Continuous trace buffers
*/
void flushBuffers();
};
typedef TRACE::ComponentDesc trace_desc_t;
#endif
|
