20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * IPRT - Tracing.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * Copyright (C) 2011 Oracle Corporation
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * available from http://www.virtualbox.org. This file is free software;
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * you can redistribute it and/or modify it under the terms of the GNU
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * General Public License (GPL) as published by the Free Software
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * The contents of this file may alternatively be used under the terms
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * of the Common Development and Distribution License Version 1.0
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * VirtualBox OSE distribution, in which case the provisions of the
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * CDDL are applicable instead of those of the GPL.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * You may elect to license modified versions of this file under the
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * terms and conditions of either the GPL or the CDDL or both.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync/** @defgroup grp_rt_trace RTTrace - Tracing
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * @ingroup grp_rt
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * The tracing facility is somewhat similar to a stripped down logger that
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * outputs to a circular buffer. Part of the idea here is that it can the
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * overhead is much smaller and that it can be done without involving any
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * locking or other thing that could throw off timing.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync/** @def RTTRACE_DISABLED
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * Use this compile time define to disable all tracing macros. This trumps
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * RTTRACE_ENABLED.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync/** @def RTTRACE_ENABLED
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * Use this compile time define to enable tracing when not in debug mode
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * Determine whether tracing is enabled and forcefully normalize the indicators.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync#if (defined(DEBUG) || defined(RTTRACE_ENABLED)) && !defined(RTTRACE_DISABLED)
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync/** @name RTTRACEBUF_FLAGS_XXX - RTTraceBufCarve and RTTraceBufCreate flags.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync/** Free the memory block on release using RTMemFree(). */
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync/** Whether the trace buffer is disabled or enabled. */
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync#define RTTRACEBUF_FLAGS_DISABLED RT_BIT_32(RTTRACEBUF_FLAGS_DISABLED_BIT)
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync/** The bit number corresponding to the RTTRACEBUF_FLAGS_DISABLED mask. */
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync/** Mask of the valid flags. */
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufCreate(PRTTRACEBUF hTraceBuf, uint32_t cEntries, uint32_t cbEntry, uint32_t fFlags);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufCarve(PRTTRACEBUF hTraceBuf, uint32_t cEntries, uint32_t cbEntry, uint32_t fFlags,
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(uint32_t) RTTraceBufRetain(RTTRACEBUF hTraceBuf);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(uint32_t) RTTraceBufRelease(RTTRACEBUF hTraceBuf);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufDumpToLog(RTTRACEBUF hTraceBuf);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufDumpToAssert(RTTRACEBUF hTraceBuf);
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * Trace buffer callback for processing one entry.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * Used by RTTraceBufEnumEntries.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @returns IPRT status code. Any status code but VINF_SUCCESS will abort the
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * enumeration and be returned by RTTraceBufEnumEntries.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param hTraceBuf The trace buffer handle.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param iEntry The entry number.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param NanoTS The timestamp of the entry.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param idCpu The ID of the CPU which added the entry.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param pszMsg The message text.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param pvUser The user argument.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsynctypedef DECLCALLBACK(int) FNRTTRACEBUFCALLBACK(RTTRACEBUF hTraceBuf, uint32_t iEntry, uint64_t NanoTS,
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync/** Pointer to trace buffer enumeration callback function. */
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsynctypedef FNRTTRACEBUFCALLBACK *PFNRTTRACEBUFCALLBACK;
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * Enumerates the used trace buffer entries, calling @a pfnCallback for each.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @returns IPRT status code. Should the callback (@a pfnCallback) return
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * anything other than VINF_SUCCESS, then the enumeration will be
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * aborted and the status code will be returned by this function.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @retval VINF_SUCCESS
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @retval VERR_INVALID_HANDLE
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @retval VERR_INVALID_PARAMETER
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @retval VERR_INVALID_POINTER
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param hTraceBuf The trace buffer handle. Special handles are
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * accepted.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param pfnCallback The callback to call for each entry.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param pvUser The user argument for the callback.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsyncRTDECL(int) RTTraceBufEnumEntries(RTTRACEBUF hTraceBuf, PFNRTTRACEBUFCALLBACK pfnCallback, void *pvUser);
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * Gets the entry size used by the specified trace buffer.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @returns The size on success, 0 if the handle is invalid.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param hTraceBuf The trace buffer handle. Special handles are
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * accepted.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsyncRTDECL(uint32_t) RTTraceBufGetEntrySize(RTTRACEBUF hTraceBuf);
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * Gets the number of entries in the specified trace buffer.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @returns The entry count on success, 0 if the handle is invalid.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param hTraceBuf The trace buffer handle. Special handles are
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * accepted.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsyncRTDECL(uint32_t) RTTraceBufGetEntryCount(RTTRACEBUF hTraceBuf);
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * Disables tracing.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @returns @c true if tracing was enabled prior to this call, @c false if
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * disabled already.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param hTraceBuf The trace buffer handle. Special handles are
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * accepted.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsyncRTDECL(bool) RTTraceBufDisable(RTTRACEBUF hTraceBuf);
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * Enables tracing.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @returns @c true if tracing was enabled prior to this call, @c false if
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * disabled already.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * @param hTraceBuf The trace buffer handle. Special handles are
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsync * accepted.
5c47137ffdbcb823e83b3cfc93bf8ccd3318bec3vboxsyncRTDECL(bool) RTTraceBufEnable(RTTRACEBUF hTraceBuf);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddMsg( RTTRACEBUF hTraceBuf, const char *pszMsg);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddMsgF( RTTRACEBUF hTraceBuf, const char *pszMsgFmt, ...);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddMsgV( RTTRACEBUF hTraceBuf, const char *pszMsgFmt, va_list va);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddMsgEx( RTTRACEBUF hTraceBuf, const char *pszMsg, size_t cbMaxMsg);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddPos( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddPosMsg( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsg);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddPosMsgEx( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsg, size_t cbMaxMsg);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddPosMsgF( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsgFmt, ...);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceBufAddPosMsgV( RTTRACEBUF hTraceBuf, RT_SRC_POS_DECL, const char *pszMsgFmt, va_list va);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsyncRTDECL(int) RTTraceSetDefaultBuf(RTTRACEBUF hTraceBuf);
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync/** @def RTTRACE_BUF
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * The trace buffer used by the macros.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync * Record the current source position.
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync# define RTTRACE_POS() do { RTTraceBufAddPos(RTTRACE_BUF, RT_SRC_POS); } while (0)