VirtualBox

source: vbox/trunk/include/iprt/trace.h@ 75155

Last change on this file since 75155 was 69105, checked in by vboxsync, 7 years ago

include/iprt/: (C) year

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.7 KB
Line 
1/** @file
2 * IPRT - Tracing.
3 */
4
5/*
6 * Copyright (C) 2011-2017 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_trace_h
27#define ___iprt_trace_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#include <iprt/stdarg.h>
32
33RT_C_DECLS_BEGIN
34
35/** @defgroup grp_rt_trace RTTrace - Tracing
36 * @ingroup grp_rt
37 *
38 * The tracing facility is somewhat similar to a stripped down logger that
39 * outputs to a circular buffer. Part of the idea here is that it can the
40 * overhead is much smaller and that it can be done without involving any
41 * locking or other thing that could throw off timing.
42 *
43 * @{
44 */
45
46
47#ifdef DOXYGEN_RUNNING
48# define RTTRACE_DISABLED
49# define RTTRACE_ENABLED
50#endif
51
52/** @def RTTRACE_DISABLED
53 * Use this compile time define to disable all tracing macros. This trumps
54 * RTTRACE_ENABLED.
55 */
56
57/** @def RTTRACE_ENABLED
58 * Use this compile time define to enable tracing when not in debug mode
59 */
60
61/*
62 * Determine whether tracing is enabled and forcefully normalize the indicators.
63 */
64#if (defined(DEBUG) || defined(RTTRACE_ENABLED)) && !defined(RTTRACE_DISABLED)
65# undef RTTRACE_DISABLED
66# undef RTTRACE_ENABLED
67# define RTTRACE_ENABLED
68#else
69# undef RTTRACE_DISABLED
70# undef RTTRACE_ENABLED
71# define RTTRACE_DISABLED
72#endif
73
74
75/** @name RTTRACEBUF_FLAGS_XXX - RTTraceBufCarve and RTTraceBufCreate flags.
76 * @{ */
77/** Free the memory block on release using RTMemFree(). */
78#define RTTRACEBUF_FLAGS_FREE_ME RT_BIT_32(0)
79/** Whether the trace buffer is disabled or enabled. */
80#define RTTRACEBUF_FLAGS_DISABLED RT_BIT_32(RTTRACEBUF_FLAGS_DISABLED_BIT)
81/** The bit number corresponding to the RTTRACEBUF_FLAGS_DISABLED mask. */
82#define RTTRACEBUF_FLAGS_DISABLED_BIT 1
83/** Mask of the valid flags. */
84#define RTTRACEBUF_FLAGS_MASK UINT32_C(0x00000003)
85/** @} */
86
87
88RTDECL(int) RTTraceBufCreate(PRTTRACEBUF hTraceBuf, uint32_t cEntries, uint32_t cbEntry, uint32_t fFlags);
89RTDECL(int) RTTraceBufCarve(PRTTRACEBUF hTraceBuf, uint32_t cEntries, uint32_t cbEntry, uint32_t fFlags,
90 void *pvBlock, size_t *pcbBlock);
91RTDECL(uint32_t) RTTraceBufRetain(RTTRACEBUF hTraceBuf);
92RTDECL(uint32_t) RTTraceBufRelease(RTTRACEBUF hTraceBuf);
93RTDECL(int) RTTraceBufDumpToLog(RTTRACEBUF hTraceBuf);
94RTDECL(int) RTTraceBufDumpToAssert(RTTRACEBUF hTraceBuf);
95
96/**
97 * Trace buffer callback for processing one entry.
98 *
99 * Used by RTTraceBufEnumEntries.
100 *
101 * @returns IPRT status code. Any status code but VINF_SUCCESS will abort the
102 * enumeration and be returned by RTTraceBufEnumEntries.
103 * @param hTraceBuf The trace buffer handle.
104 * @param iEntry The entry number.
105 * @param NanoTS The timestamp of the entry.
106 * @param idCpu The ID of the CPU which added the entry.
107 * @param pszMsg The message text.
108 * @param pvUser The user argument.
109 */
110typedef DECLCALLBACK(int) FNRTTRACEBUFCALLBACK(RTTRACEBUF hTraceBuf, uint32_t iEntry, uint64_t NanoTS,
111 RTCPUID idCpu, const char *pszMsg, void *pvUser);
112/** Pointer to trace buffer enumeration callback function. */
113typedef FNRTTRACEBUFCALLBACK *PFNRTTRACEBUFCALLBACK;
114
115/**
116 * Enumerates the used trace buffer entries, calling @a pfnCallback for each.
117 *
118 * @returns IPRT status code. Should the callback (@a pfnCallback) return
119 * anything other than VINF_SUCCESS, then the enumeration will be
120 * aborted and the status code will be returned by this function.
121 * @retval VINF_SUCCESS
122 * @retval VERR_INVALID_HANDLE
123 * @retval VERR_INVALID_PARAMETER
124 * @retval VERR_INVALID_POINTER
125 *
126 * @param hTraceBuf The trace buffer handle. Special handles are
127 * accepted.
128 * @param pfnCallback The callback to call for each entry.
129 * @param pvUser The user argument for the callback.
130 */
131RTDECL(int) RTTraceBufEnumEntries(RTTRACEBUF hTraceBuf, PFNRTTRACEBUFCALLBACK pfnCallback, void *pvUser);
132
133/**
134 * Gets the entry size used by the specified trace buffer.
135 *
136 * @returns The size on success, 0 if the handle is invalid.
137 *
138 * @param hTraceBuf The trace buffer handle. Special handles are
139 * accepted.
140 */
141RTDECL(uint32_t) RTTraceBufGetEntrySize(RTTRACEBUF hTraceBuf);
142
143/**
144 * Gets the number of entries in the specified trace buffer.
145 *
146 * @returns The entry count on success, 0 if the handle is invalid.
147 *
148 * @param hTraceBuf The trace buffer handle. Special handles are
149 * accepted.
150 */
151RTDECL(uint32_t) RTTraceBufGetEntryCount(RTTRACEBUF hTraceBuf);
152
153
154/**
155 * Disables tracing.
156 *
157 * @returns @c true if tracing was enabled prior to this call, @c false if
158 * disabled already.
159 *
160 * @param hTraceBuf The trace buffer handle. Special handles are
161 * accepted.
162 */
163RTDECL(bool) RTTraceBufDisable(RTTRACEBUF hTraceBuf);
164
165/**
166 * Enables tracing.
167 *
168 * @returns @c true if tracing was enabled prior to this call, @c false if
169 * disabled already.
170 *
171 * @param hTraceBuf The trace buffer handle. Special handles are
172 * accepted.
173 */
174RTDECL(bool) RTTraceBufEnable(RTTRACEBUF hTraceBuf);
175
176
177RTDECL(int) RTTraceBufAddMsg( RTTRACEBUF hTraceBuf, const char *pszMsg);
178RTDECL(int) RTTraceBufAddMsgF( RTTRACEBUF hTraceBuf, const char *pszMsgFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3);
179RTDECL(int) RTTraceBufAddMsgV( RTTRACEBUF hTraceBuf, const char *pszMsgFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
180RTDECL(int) RTTraceBufAddMsgEx( RTTRACEBUF hTraceBuf, const char *pszMsg, size_t cbMaxMsg);
181
182RTDECL(int) RTTraceBufAddPos( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL);
183RTDECL(int) RTTraceBufAddPosMsg( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsg);
184RTDECL(int) RTTraceBufAddPosMsgEx( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsg, size_t cbMaxMsg);
185RTDECL(int) RTTraceBufAddPosMsgF( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsgFmt, ...) RT_IPRT_FORMAT_ATTR(5, 6);
186RTDECL(int) RTTraceBufAddPosMsgV( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsgFmt, va_list va) RT_IPRT_FORMAT_ATTR(5, 0);
187
188
189RTDECL(int) RTTraceSetDefaultBuf(RTTRACEBUF hTraceBuf);
190RTDECL(RTTRACEBUF) RTTraceGetDefaultBuf(void);
191
192
193/** @def RTTRACE_BUF
194 * The trace buffer used by the macros.
195 */
196#ifndef RTTRACE_BUF
197# define RTTRACE_BUF NULL
198#endif
199
200/**
201 * Record the current source position.
202 */
203#ifdef RTTRACE_ENABLED
204# define RTTRACE_POS() do { RTTraceBufAddPos(RTTRACE_BUF, RT_SRC_POS); } while (0)
205#else
206# define RTTRACE_POS() do { } while (0)
207#endif
208
209
210/** @} */
211
212RT_C_DECLS_END
213
214#endif
215
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette