include/iprt/trace.h

   1 /** @file
   2  * IPRT - Tracing.
   3  */
   4
   5 /*
   6  * Copyright (C) 2011-2024 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
  46 RT_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
 101 RTDECL(int)         RTTraceBufCreate(PRTTRACEBUF hTraceBuf, uint32_t cEntries, uint32_t cbEntry, uint32_t fFlags);
 102 RTDECL(int)         RTTraceBufCarve(PRTTRACEBUF hTraceBuf, uint32_t cEntries, uint32_t cbEntry, uint32_t fFlags,
 103                                     void *pvBlock, size_t *pcbBlock);
 104 RTDECL(uint32_t)    RTTraceBufRetain(RTTRACEBUF hTraceBuf);
 105 RTDECL(uint32_t)    RTTraceBufRelease(RTTRACEBUF hTraceBuf);
 106 RTDECL(int)         RTTraceBufDumpToLog(RTTRACEBUF hTraceBuf);
 107 RTDECL(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  */
 123 typedef 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. */
 126 typedef 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  */
 144 RTDECL(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  */
 154 RTDECL(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  */
 164 RTDECL(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  */
 176 RTDECL(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  */
 187 RTDECL(bool)        RTTraceBufEnable(RTTRACEBUF hTraceBuf);
 188
 189
 190 RTDECL(int)         RTTraceBufAddMsg(      RTTRACEBUF hTraceBuf, const char *pszMsg);
 191 RTDECL(int)         RTTraceBufAddMsgF(     RTTRACEBUF hTraceBuf, const char *pszMsgFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3);
 192 RTDECL(int)         RTTraceBufAddMsgV(     RTTRACEBUF hTraceBuf, const char *pszMsgFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
 193 RTDECL(int)         RTTraceBufAddMsgEx(    RTTRACEBUF hTraceBuf, const char *pszMsg, size_t cbMaxMsg);
 194
 195 RTDECL(int)         RTTraceBufAddPos(      RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL);
 196 RTDECL(int)         RTTraceBufAddPosMsg(   RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsg);
 197 RTDECL(int)         RTTraceBufAddPosMsgEx( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsg, size_t cbMaxMsg);
 198 RTDECL(int)         RTTraceBufAddPosMsgF(  RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsgFmt, ...) RT_IPRT_FORMAT_ATTR(5, 6);
 199 RTDECL(int)         RTTraceBufAddPosMsgV(  RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsgFmt, va_list va) RT_IPRT_FORMAT_ATTR(5, 0);
 200
 201
 202 RTDECL(int)         RTTraceSetDefaultBuf(RTTRACEBUF hTraceBuf);
 203 RTDECL(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
 225 RT_C_DECLS_END
 226
 227 #endif /* !IPRT_INCLUDED_trace_h */
 228