-
Notifications
You must be signed in to change notification settings - Fork 748
/
Copy pathtraceformat.h
101 lines (92 loc) · 4.39 KB
/
traceformat.h
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
/*******************************************************************************
* Copyright IBM Corp. and others 2014
*
* This program and the accompanying materials are made available under
* the terms of the Eclipse Public License 2.0 which accompanies this
* distribution and is available at https://www.eclipse.org/legal/epl-2.0/
* or the Apache License, Version 2.0 which accompanies this distribution and
* is available at https://www.apache.org/licenses/LICENSE-2.0.
*
* This Source Code may also be made available under the following
* Secondary Licenses when the conditions for such availability set
* forth in the Eclipse Public License, v. 2.0 are satisfied: GNU
* General Public License, version 2 with the GNU Classpath
* Exception [1] and GNU General Public License, version 2 with the
* OpenJDK Assembly Exception [2].
*
* [1] https://www.gnu.org/software/classpath/license.html
* [2] https://openjdk.org/legal/assembly-exception.html
*
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0 OR GPL-2.0-only WITH OpenJDK-assembly-exception-1.0
*******************************************************************************/
#ifndef TRACEFORMAT_H_
#define TRACEFORMAT_H_
/**
* Trace formatting functions. Exposed as external symbols.
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* A callback to obtain a format string for a trace point with id tracepoint in
* component componentName.
*
* Typically the format string will be obtained from a trace format .dat file though
* this is not required. Care must be taken that the format file matches the original
* trace point data as it will contain format specifiers which will be filled in when
* the trace data for this trace point is formatted.
*
* If the string cannot be found a constant string with no inserts should be returned
* rather than null.
* (For example "UNKNOWN TRACEPOINT ID")
*
* @param[in] componentName the name of the component this trace point belongs to, for example j9mm
* @param[in] tracepoint the trace point number within the component, for example 123
*/
typedef char *(*FormatStringCallback)(const char *componentName, int32_t tracepoint);
struct UtTraceFileIterator;
typedef struct UtTraceFileIterator UtTraceFileIterator;
struct UtTracePointIterator;
typedef struct UtTracePointIterator UtTracePointIterator;
/**
* Obtain a UtTraceFileIterator for the file named in fileName.
*
* This iterator can then be used to obtain trace point iterators over each
* buffer in the file via calls to omr_trc_getTracePointIteratorForNextBuffer
*
* @param[in] portLib An initialized OMRPortLibrary structure.
* @param[in] fileName The name of the trace file to open.
* @param[in,out] iteratorPtr A pointer to a location where the initialized UtTraceFileIterator pointer can be stored.
* @param[in] getFormatString A callback the formatter can use to obtain a format string for a trace point id in a named module.
*
* @return OMR_ERROR_NONE on success
* @return OMR_ERROR_NOT_AVAILABLE if the specified file cannot be opened
* @return OMR_ERROR_ILLEGAL_ARGUMENT if the specified file does not contain valid trace data.
* @return OMR_ERROR_OUT_OF_NATIVE_MEMORY if memory for the iterator structure cannot be allocated.
* @return OMR_ERROR_NOT_AVAILABLE if the specified file cannot be opened.
*/
omr_error_t omr_trc_getTraceFileIterator(OMRPortLibrary *portLib, char *fileName, UtTraceFileIterator **iteratorPtr, FormatStringCallback getFormatString);
/**
* Format the next trace point available from iter into buffer.
* Returns a pointer to buffer on success or NULL if no more trace
* can be formatted from this buffer.
*
* @param[in] iter the UtTracePointIterator to obtain the next trace point from.
* @param[in,out] buffer the buffer to format the trace point into
* @param[in] buffLen the length of the buffer
* @return a pointer to buffer or NULL if there are no more trace points available
*/
char *omr_trc_formatNextTracePoint(UtTracePointIterator *iter, char *buffer, uint32_t buffLen);
/**
* Free a trace point iterator and any memory associated with it
* All UtTracePointIterators obtained from a file iterator should
* be free'd before the UtTraceFileIterator is free'd.
*
* @param[in] iter the UtTracePointIterator to free
* @return OMR_ERROR_NONE on success
*/
omr_error_t omr_trc_freeTracePointIterator(UtTracePointIterator *iter);
#ifdef __cplusplus
}
#endif
#endif /* TRACEFORMAT_H_ */