VirtualBox

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

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

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