704 lines
26 KiB
C
704 lines
26 KiB
C
/** @file
|
|
* IPRT - Binary trace log API.
|
|
*/
|
|
|
|
/*
|
|
* Copyright (C) 2018-2023 Oracle and/or its affiliates.
|
|
*
|
|
* This file is part of VirtualBox base platform packages, as
|
|
* available from https://www.virtualbox.org.
|
|
*
|
|
* This program is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License
|
|
* as published by the Free Software Foundation, in version 3 of the
|
|
* License.
|
|
*
|
|
* This program is distributed in the hope that it will be useful, but
|
|
* WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, see <https://www.gnu.org/licenses>.
|
|
*
|
|
* The contents of this file may alternatively be used under the terms
|
|
* of the Common Development and Distribution License Version 1.0
|
|
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
|
* in the VirtualBox distribution, in which case the provisions of the
|
|
* CDDL are applicable instead of those of the GPL.
|
|
*
|
|
* You may elect to license modified versions of this file under the
|
|
* terms and conditions of either the GPL or the CDDL or both.
|
|
*
|
|
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
|
*/
|
|
|
|
#ifndef IPRT_INCLUDED_tracelog_h
|
|
#define IPRT_INCLUDED_tracelog_h
|
|
#ifndef RT_WITHOUT_PRAGMA_ONCE
|
|
# pragma once
|
|
#endif
|
|
|
|
#include <iprt/sg.h>
|
|
#include <iprt/types.h>
|
|
|
|
RT_C_DECLS_BEGIN
|
|
|
|
|
|
/** @defgroup grp_tracelog RTTraceLog - Binary trace log API
|
|
* @ingroup grp_rt
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Trace log item type.
|
|
*/
|
|
typedef enum RTTRACELOGTYPE
|
|
{
|
|
/** Invalid first value. */
|
|
RTTRACELOGTYPE_INVALID = 0,
|
|
/** Boolean item type. */
|
|
RTTRACELOGTYPE_BOOL,
|
|
/** Unsigned 8bit integer type. */
|
|
RTTRACELOGTYPE_UINT8,
|
|
/** Signed 8bit integer type. */
|
|
RTTRACELOGTYPE_INT8,
|
|
/** Unsigned 16bit integer type. */
|
|
RTTRACELOGTYPE_UINT16,
|
|
/** Signed 16bit integer type. */
|
|
RTTRACELOGTYPE_INT16,
|
|
/** Unsigned 32bit integer type. */
|
|
RTTRACELOGTYPE_UINT32,
|
|
/** Signed 32bit integer type. */
|
|
RTTRACELOGTYPE_INT32,
|
|
/** Unsigned 64bit integer type. */
|
|
RTTRACELOGTYPE_UINT64,
|
|
/** Signed 64bit integer type. */
|
|
RTTRACELOGTYPE_INT64,
|
|
/** 32bit floating point type. */
|
|
RTTRACELOGTYPE_FLOAT32,
|
|
/** 64bit floating point type. */
|
|
RTTRACELOGTYPE_FLOAT64,
|
|
/** Raw binary data type. */
|
|
RTTRACELOGTYPE_RAWDATA,
|
|
/** Pointer data type. */
|
|
RTTRACELOGTYPE_POINTER,
|
|
/** size_t data type. */
|
|
RTTRACELOGTYPE_SIZE,
|
|
/** 32-bit hack. */
|
|
RTTRACELOGTYPE_32BIT_HACK = 0x7fffffff
|
|
} RTTRACELOGTYPE;
|
|
/** Pointer to a trace log item type. */
|
|
typedef RTTRACELOGTYPE *PRTTRACELOGTYPE;
|
|
/** Pointer to a const trace log item type. */
|
|
typedef const RTTRACELOGTYPE *PCRTTRACELOGTYPE;
|
|
|
|
|
|
/**
|
|
* Trace log event severity.
|
|
*/
|
|
typedef enum RTTRACELOGEVTSEVERITY
|
|
{
|
|
/** Invalid severity. */
|
|
RTTRACELOGEVTSEVERITY_INVALID = 0,
|
|
/** Informational event. */
|
|
RTTRACELOGEVTSEVERITY_INFO,
|
|
/** Warning event. */
|
|
RTTRACELOGEVTSEVERITY_WARNING,
|
|
/** Error event. */
|
|
RTTRACELOGEVTSEVERITY_ERROR,
|
|
/** Fatal event. */
|
|
RTTRACELOGEVTSEVERITY_FATAL,
|
|
/** Debug event. */
|
|
RTTRACELOGEVTSEVERITY_DEBUG,
|
|
/** 32bit hack.*/
|
|
RTTRACELOGEVTSEVERITY_32BIT_HACK = 0x7fffffff
|
|
} RTTRACELOGEVTSEVERITY;
|
|
/** Pointer to a event severity class. */
|
|
typedef RTTRACELOGEVTSEVERITY *PRTTRACELOGEVTSEVERITY;
|
|
/** Pointer to a const event severiy class. */
|
|
typedef RTTRACELOGEVTSEVERITY *PCRTTRACELOGEVTSEVERITY;
|
|
|
|
|
|
/**
|
|
* Trace log reader event.
|
|
*/
|
|
typedef enum RTTRACELOGRDRPOLLEVT
|
|
{
|
|
/** Invalid event. */
|
|
RTTRACELOGRDRPOLLEVT_INVALID = 0,
|
|
/** The header was received and valid. */
|
|
RTTRACELOGRDRPOLLEVT_HDR_RECVD,
|
|
/** Event data was fetched. */
|
|
RTTRACELOGRDRPOLLEVT_TRACE_EVENT_RECVD,
|
|
/** 32bit hack. */
|
|
RTTRACELOGRDRPOLLEVT_32BIT_HACK = 0x7fffffff
|
|
} RTTRACELOGRDRPOLLEVT;
|
|
/** Pointer to a trace log reader event. */
|
|
typedef RTTRACELOGRDRPOLLEVT *PRTTRACELOGRDRPOLLEVT;
|
|
|
|
|
|
/**
|
|
* Trace log event item descriptor.
|
|
*/
|
|
typedef struct RTTRACELOGEVTITEMDESC
|
|
{
|
|
/** Event item name. */
|
|
const char *pszName;
|
|
/** Event item description. */
|
|
const char *pszDesc;
|
|
/** Event item type. */
|
|
RTTRACELOGTYPE enmType;
|
|
/** The size of the raw data if static for the item,
|
|
* 0 otherwise (and given when the event is logged).
|
|
* Only valid for the RTTRACELOGTYPE_RAWDATA type,
|
|
* ignored otherwise. */
|
|
size_t cbRawData;
|
|
} RTTRACELOGEVTITEMDESC;
|
|
/** Pointer to an trace log event item descriptor. */
|
|
typedef RTTRACELOGEVTITEMDESC *PRTTRACELOGEVTITEMDESC;
|
|
/** Pointer to a const trace log event item descriptor. */
|
|
typedef const RTTRACELOGEVTITEMDESC *PCRTTRACELOGEVTITEMDESC;
|
|
/** Pointer to a trace log event item descriptor pointer. */
|
|
typedef PRTTRACELOGEVTITEMDESC *PPRTTRACELOGEVTITEMDESC;
|
|
/** Pointer to a const trace log event item descriptor pointer. */
|
|
typedef PCRTTRACELOGEVTITEMDESC *PPCRTTRACELOGEVTITEMDESC;
|
|
|
|
|
|
/**
|
|
* Trace log event descriptor.
|
|
*/
|
|
typedef struct RTTRACELOGEVTDESC
|
|
{
|
|
/** Event identifier. */
|
|
const char *pszId;
|
|
/** Event description. */
|
|
const char *pszDesc;
|
|
/** Severity class of the event. */
|
|
RTTRACELOGEVTSEVERITY enmSeverity;
|
|
/** Number of items recorded for an event. */
|
|
uint32_t cEvtItems;
|
|
/** Pointer to array of event item descriptors. */
|
|
PCRTTRACELOGEVTITEMDESC paEvtItemDesc;
|
|
} RTTRACELOGEVTDESC;
|
|
/** Pointer to a trace log event descriptor. */
|
|
typedef RTTRACELOGEVTDESC *PRTTRACELOGEVTDESC;
|
|
/** Pointer to a const trace log event descriptor. */
|
|
typedef const RTTRACELOGEVTDESC *PCRTTRACELOGEVTDESC;
|
|
|
|
|
|
/**
|
|
* Trace log event item value.
|
|
*/
|
|
typedef struct RTTRACELOGEVTVAL
|
|
{
|
|
/** Pointer to the corresponding event item descriptor. */
|
|
PCRTTRACELOGEVTITEMDESC pItemDesc;
|
|
/** Value union. */
|
|
union
|
|
{
|
|
bool f;
|
|
uint8_t u8;
|
|
int8_t i8;
|
|
uint16_t u16;
|
|
int16_t i16;
|
|
uint32_t u32;
|
|
int32_t i32;
|
|
uint64_t u64;
|
|
int64_t i64;
|
|
uint64_t sz;
|
|
uint64_t uPtr;
|
|
float f32;
|
|
double f64;
|
|
struct
|
|
{
|
|
size_t cb;
|
|
const uint8_t *pb;
|
|
} RawData;
|
|
} u;
|
|
} RTTRACELOGEVTVAL;
|
|
/** Pointer to trace log event item value. */
|
|
typedef RTTRACELOGEVTVAL *PRTTRACELOGEVTVAL;
|
|
/** Pointer to a const trace log event item value. */
|
|
typedef const RTTRACELOGEVTVAL *PCRTTRACELOGEVTVAL;
|
|
|
|
|
|
/**
|
|
* Item mapping descriptor.
|
|
*/
|
|
typedef struct RTTRACELOGRDRMAPITEM
|
|
{
|
|
/** The item name. */
|
|
const char *pszName;
|
|
/** The value type to map the item to. */
|
|
RTTRACELOGTYPE enmType;
|
|
} RTTRACELOGRDRMAPITEM;
|
|
/** Pointer to a mapping item descriptor. */
|
|
typedef RTTRACELOGRDRMAPITEM *PRTTRACELOGRDRMAPITEM;
|
|
/** Pointer to a const mapping item descriptor. */
|
|
typedef const RTTRACELOGRDRMAPITEM *PCRTTRACELOGRDRMAPITEM;
|
|
|
|
|
|
/**
|
|
* Event item to value mapping descriptor for RTTraceLogRdrEvtMapToStruct().
|
|
*/
|
|
typedef struct RTTRACELOGRDRMAPDESC
|
|
{
|
|
/** The event ID this mapping describes. */
|
|
const char *pszEvtId;
|
|
/** Number of event items to extract. */
|
|
uint32_t cEvtItems;
|
|
/** Pointer to the event items to extract (in the given order). */
|
|
PCRTTRACELOGRDRMAPITEM paMapItems;
|
|
} RTTRACELOGRDRMAPDESC;
|
|
/** Pointer to a event mapping descriptor. */
|
|
typedef RTTRACELOGRDRMAPDESC *PRTTRACELOGRDRMAPDESC;
|
|
/** Pointer to a const event mapping descriptor. */
|
|
typedef const RTTRACELOGRDRMAPDESC *PCRTTRACELOGRDRMAPDESC;
|
|
|
|
|
|
/**
|
|
* Header for an event mapped to a binary.
|
|
*/
|
|
typedef struct RTTRACELOGRDREVTHDR
|
|
{
|
|
/** The mapping descriptor this event was mapped to. */
|
|
PCRTTRACELOGRDRMAPDESC pEvtMapDesc;
|
|
/** The event descriptor as extracted from the event log. */
|
|
PCRTTRACELOGEVTDESC pEvtDesc;
|
|
/** Sequence number of the descriptor. */
|
|
uint64_t idSeqNo;
|
|
/** The timestamp of the event. */
|
|
uint64_t tsEvt;
|
|
/** Pointer to the event data items. */
|
|
PCRTTRACELOGEVTVAL paEvtItems;
|
|
} RTTRACELOGRDREVTHDR;
|
|
/** Pointer to an event header. */
|
|
typedef RTTRACELOGRDREVTHDR *PRTTRACELOGRDREVTHDR;
|
|
/** Pointer to a const event header. */
|
|
typedef const RTTRACELOGRDREVTHDR *PCRTTRACELOGRDREVTHDR;
|
|
|
|
|
|
/** Event group ID. */
|
|
typedef uint64_t RTTRACELOGEVTGRPID;
|
|
/** Pointer to the event group ID. */
|
|
typedef RTTRACELOGEVTGRPID *PRTTRACELOGEVTGRPID;
|
|
/** Trace log event handle. */
|
|
typedef uint64_t RTRACELOGEVT;
|
|
/** Pointer to a trace log event handle. */
|
|
typedef RTRACELOGEVT *PRTRACELOGEVT;
|
|
/** Trace log writer handle. */
|
|
typedef struct RTTRACELOGWRINT *RTTRACELOGWR;
|
|
/** Pointer to a trace log writer handle. */
|
|
typedef RTTRACELOGWR *PRTTRACELOGWR;
|
|
/** NIL trace log writer handle value. */
|
|
#define NIL_RTTRACELOGWR ((RTTRACELOGWR)0)
|
|
/** Trace log reader handle. */
|
|
typedef struct RTTRACELOGRDRINT *RTTRACELOGRDR;
|
|
/** Pointer to a trace log reader handle. */
|
|
typedef RTTRACELOGRDR *PRTTRACELOGRDR;
|
|
/** NIL trace log reader handle value. */
|
|
#define NIL_RTTRACELOGRDR ((RTTRACELOGRDR)0)
|
|
/** Trace log reader iterator handle. */
|
|
typedef struct RTTRACELOGRDRITINT *RTTRACELOGRDRIT;
|
|
/** Pointer to a trace log reader iterator handle. */
|
|
typedef RTTRACELOGRDRIT *PRTTRACELOGRDRIT;
|
|
/** NIL trace log reader iterator handle. */
|
|
#define NIL_RTTRACELOGRDRIT ((RTTRACELOGRDRIT)0)
|
|
/** Trace log reader event handle. */
|
|
typedef struct RTTRACELOGRDREVTINT *RTTRACELOGRDREVT;
|
|
/** Pointer to a trace log reader event handle. */
|
|
typedef RTTRACELOGRDREVT *PRTTRACELOGRDREVT;
|
|
/** NIL trace log reader event handle. */
|
|
#define NIL_RTTRACELOGRDREVT ((RTTRACELOGRDREVT)0)
|
|
|
|
/** A new grouped event is started. */
|
|
#define RTTRACELOG_WR_ADD_EVT_F_GRP_START RT_BIT_32(0)
|
|
/** A grouped event is finished. */
|
|
#define RTTRACELOG_WR_ADD_EVT_F_GRP_FINISH RT_BIT_32(1)
|
|
|
|
/**
|
|
* Callback to stream out data from the trace log writer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param pvUser Opaque user data passed on trace log writer creation.
|
|
* @param pvBuf Pointer to the buffer to stream out.
|
|
* @param cbBuf Number of bytes to stream.
|
|
* @param pcbWritten Where to store the number of bytes written on success, optional.
|
|
*/
|
|
typedef DECLCALLBACKTYPE(int, FNRTTRACELOGWRSTREAM,(void *pvUser, const void *pvBuf, size_t cbBuf, size_t *pcbWritten));
|
|
/** Pointer to a writer stream callback. */
|
|
typedef FNRTTRACELOGWRSTREAM *PFNRTTRACELOGWRSTREAM;
|
|
|
|
|
|
/**
|
|
* Callback to stream int data to the trace log reader.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_EOF if the stream reached the end.
|
|
* @retval VERR_INTERRUPTED if waiting for something to arrive was interrupted.
|
|
* @retval VERR_TIMEOUT if the timeout was reached.
|
|
* @param pvUser Opaque user data passed on trace log reader creation.
|
|
* @param pvBuf Where to store the read data.
|
|
* @param cbBuf Number of bytes the buffer can hold.
|
|
* @param pcbRead Where to store the number of bytes read on success.
|
|
* @param cMsTimeout How long to wait for something to arrive
|
|
*/
|
|
typedef DECLCALLBACKTYPE(int, FNRTTRACELOGRDRSTREAM,(void *pvUser, void *pvBuf, size_t cbBuf, size_t *pcbRead,
|
|
RTMSINTERVAL cMsTimeout));
|
|
/** Pointer to a writer stream callback. */
|
|
typedef FNRTTRACELOGRDRSTREAM *PFNRTTRACELOGRDRSTREAM;
|
|
|
|
|
|
/**
|
|
* Callback to close the stream.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param pvUser Opaque user data passed on trace log writer creation.
|
|
*/
|
|
typedef DECLCALLBACKTYPE(int, FNRTTRACELOGSTREAMCLOSE,(void *pvUser));
|
|
/** Pointer to a stream close callback. */
|
|
typedef FNRTTRACELOGSTREAMCLOSE *PFNRTTRACELOGSTREAMCLOSE;
|
|
|
|
|
|
/**
|
|
* Creates a new trace log writer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phTraceLogWr Where to store the handle to the trace log writer on success.
|
|
* @param pszDesc Optional description to store in the header.
|
|
* @param pfnStreamOut The callback to use for streaming the trace log data.
|
|
* @param pfnStreamClose The callback to use for closing the stream.
|
|
* @param pvUser Opaque user data to pass to the streaming callback.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrCreate(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
|
|
PFNRTTRACELOGWRSTREAM pfnStreamOut,
|
|
PFNRTTRACELOGSTREAMCLOSE pfnStreamClose, void *pvUser);
|
|
|
|
|
|
/**
|
|
* Creates a new trace log writer streaming data to the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phTraceLogWr Where to store the handle to the trace log writer on success.
|
|
* @param pszDesc Optional description to store in the header.
|
|
* @param pszFilename The filename to stream the data to.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrCreateFile(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
|
|
const char *pszFilename);
|
|
|
|
|
|
/**
|
|
* Creates a new TCP server style trace log writer waiting for the other end to connect to it.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phTraceLogWr Where to store the handle to the trace log writer on success.
|
|
* @param pszDesc Optional description to store in the header.
|
|
* @param pszListen The address to listen on, NULL to listen on all interfaces.
|
|
* @param uPort The port to listen on.
|
|
*
|
|
* @note The writer will block here until a client has connected.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrCreateTcpServer(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
|
|
const char *pszListen, unsigned uPort);
|
|
|
|
|
|
/**
|
|
* Creates a new TCP client style trace log writer connecting to the other end.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phTraceLogWr Where to store the handle to the trace log writer on success.
|
|
* @param pszDesc Optional description to store in the header.
|
|
* @param pszAddress The address to connect to.
|
|
* @param uPort The port to connect to.
|
|
*
|
|
* @note An error is returned if no connection can be established.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrCreateTcpClient(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
|
|
const char *pszAddress, unsigned uPort);
|
|
|
|
|
|
/**
|
|
* Destroys the given trace log writer instance.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hTraceLogWr The trace log writer instance handle.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrDestroy(RTTRACELOGWR hTraceLogWr);
|
|
|
|
|
|
/**
|
|
* Adds a given event structure descriptor to the given trace log writer instance
|
|
* (for prepopulation).
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hTraceLogWr The trace log writer instance handle.
|
|
* @param pEvtDesc The event structure descriptor to add.
|
|
*
|
|
* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
|
|
* so don't free after this method finishes.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrAddEvtDesc(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc);
|
|
|
|
|
|
/**
|
|
* Adds a new event to the trace log.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hTraceLogWr The trace log writer instance handle.
|
|
* @param pEvtDesc The event descriptor to use for formatting.
|
|
* @param fFlags Flags to use for this event.y
|
|
* @param uGrpId A unique group ID for grouped events.
|
|
* @param uParentGrpId A parent group ID this event originated from.
|
|
* @param pvEvtData Pointer to the raw event data.
|
|
* @param pacbRawData Pointer to the array of size indicators for non static raw data in the event data stream.
|
|
*
|
|
* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
|
|
* so don't free after this method finishes.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrEvtAdd(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
|
|
RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId,
|
|
const void *pvEvtData, size_t *pacbRawData);
|
|
|
|
|
|
/**
|
|
* Adds a new event to the trace log.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hTraceLogWr The trace log writer instance handle.
|
|
* @param pEvtDesc The event descriptor used for formatting the data.
|
|
* @param fFlags Flags to use for this event.
|
|
* @param uGrpId A unique group ID for grouped events.
|
|
* @param uParentGrpId A parent group ID this event originated from.
|
|
* @param pSgBufEvtData S/G buffer holding the raw event data.
|
|
* @param pacbRawData Pointer to the array of size indicators for non static raw data in the event data stream.
|
|
*
|
|
* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
|
|
* so don't free after this method finishes.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrEvtAddSg(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
|
|
RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId,
|
|
PRTSGBUF *pSgBufEvtData, size_t *pacbRawData);
|
|
|
|
|
|
/**
|
|
* Adds a new event to the trace log - list variant.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hTraceLogWr The trace log writer instance handle.
|
|
* @param pEvtDesc The event descriptor used for formatting the data.
|
|
* @param fFlags Flags to use for this event.
|
|
* @param uGrpId A unique group ID for grouped events.
|
|
* @param uParentGrpId A parent group ID this event originated from.
|
|
* @param va The event data as single items as described by the descriptor.
|
|
*
|
|
* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
|
|
* so don't free after this method finishes.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrEvtAddLV(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
|
|
RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId, va_list va);
|
|
|
|
|
|
/**
|
|
* Adds a new event to the trace log - list variant.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hTraceLogWr The trace log writer instance handle.
|
|
* @param pEvtDesc The event descriptor used for formatting the data.
|
|
* @param fFlags Flags to use for this event.
|
|
* @param uGrpId A unique group ID for grouped events.
|
|
* @param uParentGrpId A parent group ID this event originated from.
|
|
* @param ... The event data as single items as described by the descriptor.
|
|
*
|
|
* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
|
|
* so don't free after this method finishes.
|
|
*/
|
|
RTDECL(int) RTTraceLogWrEvtAddL(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
|
|
RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId, ...);
|
|
|
|
|
|
/**
|
|
* Creates a new trace log reader instance.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phTraceLogRdr Where to store the handle to the trace log reader instance on success.
|
|
* @param pfnStreamIn Callback to stream the data into the reader.
|
|
* @param pfnStreamClose The callback to use for closing the stream.
|
|
* @param pvUser Opaque user data passed to the stream callback.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrCreate(PRTTRACELOGRDR phTraceLogRdr, PFNRTTRACELOGRDRSTREAM pfnStreamIn,
|
|
PFNRTTRACELOGSTREAMCLOSE pfnStreamClose, void *pvUser);
|
|
|
|
|
|
/**
|
|
* Creates a new trace log reader for the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phTraceLogRdr Where to store the handle to the trace log reader instance on success.
|
|
* @param pszFilename The file to read the trace log data from.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrCreateFromFile(PRTTRACELOGRDR phTraceLogRdr, const char *pszFilename);
|
|
|
|
|
|
/**
|
|
* Destroys the given trace log reader instance.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hTraceLogRdr The trace log reader instance handle.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrDestroy(RTTRACELOGRDR hTraceLogRdr);
|
|
|
|
|
|
/**
|
|
* Polls for an event on the trace log reader instance.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_TIMEOUT if the timeout was reached.
|
|
* @retval VERR_INTERRUPTED if the poll was interrupted.
|
|
* @param hTraceLogRdr The trace log reader instance handle.
|
|
* @param penmEvt Where to store the event identifier.
|
|
* @param cMsTimeout How long to poll for an event.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrEvtPoll(RTTRACELOGRDR hTraceLogRdr, RTTRACELOGRDRPOLLEVT *penmEvt, RTMSINTERVAL cMsTimeout);
|
|
|
|
/**
|
|
* Queries the last received event from the trace log read instance.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_NOT_FOUND if no event was received so far.
|
|
* @param hTraceLogRdr The trace log reader instance handle.
|
|
* @param phRdrEvt Where to store the event handle on success.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrQueryLastEvt(RTTRACELOGRDR hTraceLogRdr, PRTTRACELOGRDREVT phRdrEvt);
|
|
|
|
/**
|
|
* Queries a new iterator for walking received events.
|
|
*
|
|
* @returns IPRT status code
|
|
* @param hTraceLogRdr The trace log reader instance handle.
|
|
* @param phIt Where to store the handle to iterator on success.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrQueryIterator(RTTRACELOGRDR hTraceLogRdr, PRTTRACELOGRDRIT phIt);
|
|
|
|
|
|
/**
|
|
* Extracts the given number of events from the given trace log reader instance returning
|
|
* and array of events with the values filled in from the mapping descriptor.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hTraceLogRdr The trace log reader instance handle.
|
|
* @param fFlags Flags controlling the behavior, MBZ.
|
|
* @param cEvts Number of events to extract, UINT32_MAX to map all immediately available events.
|
|
* @param paMapDesc Pointer to an array of mapping descriptors describing how to map events.
|
|
* @param ppaEvtHdr Where to return the pointer to the allocated array of event headers on success.
|
|
* @param pcEvts Where to store the returned number of events on success.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrEvtMapToStruct(RTTRACELOGRDR hTraceLogRdr, uint32_t fFlags, uint32_t cEvts,
|
|
PCRTTRACELOGRDRMAPDESC paMapDesc, PCRTTRACELOGRDREVTHDR *ppaEvtHdr,
|
|
uint32_t *pcEvts);
|
|
|
|
|
|
/**
|
|
* Frees all resources of the given array of event headers as allocated by RTTraceLogRdrEvtMapToStruct().
|
|
*
|
|
* @param paEvtHdr Pointer to the array of events as returned by RTTraceLogRdrEvtMapToStruct().
|
|
* @param cEvts Number of events as returned by RTTraceLogRdrEvtMapToStruct().
|
|
*/
|
|
RTDECL(void) RTTraceLogRdrEvtMapFree(PCRTTRACELOGRDREVTHDR paEvtHdr, uint32_t cEvts);
|
|
|
|
|
|
/**
|
|
* Frees a previously created iterator.
|
|
*
|
|
* @param hIt The iterator handle to free.
|
|
*/
|
|
RTDECL(void) RTTraceLogRdrIteratorFree(RTTRACELOGRDRIT hIt);
|
|
|
|
|
|
/**
|
|
* Advances to the next event.
|
|
*
|
|
* @returns IPRT status code
|
|
* @retval VERR_TRACELOG_READER_ITERATOR_END if the iterator reached the end.
|
|
* @param hIt The iterator handle.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrIteratorNext(RTTRACELOGRDRIT hIt);
|
|
|
|
|
|
/**
|
|
* Queries the event at the current iterator position.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hIt The iterator handle.
|
|
* @param phRdrEvt Where to store the event handle on success.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrIteratorQueryEvent(RTTRACELOGRDRIT hIt, PRTTRACELOGRDREVT phRdrEvt);
|
|
|
|
|
|
/**
|
|
* Returns the sequence number of the given event.
|
|
*
|
|
* @returns Sequence number of the given event.
|
|
* @param hRdrEvt The reader event handle.
|
|
*/
|
|
RTDECL(uint64_t) RTTraceLogRdrEvtGetSeqNo(RTTRACELOGRDREVT hRdrEvt);
|
|
|
|
|
|
/**
|
|
* Gets the timestamp of the given event.
|
|
*
|
|
* @returns Timestamp of the given event.
|
|
* @param hRdrEvt The reader event handle.
|
|
*/
|
|
RTDECL(uint64_t) RTTraceLogRdrEvtGetTs(RTTRACELOGRDREVT hRdrEvt);
|
|
|
|
|
|
/**
|
|
* Returns whether the given event is part of an event group.
|
|
*
|
|
* @returns Flag whether the event is part of a group.
|
|
* @param hRdrEvt The reader event handle.
|
|
*/
|
|
RTDECL(bool) RTTraceLogRdrEvtIsGrouped(RTTRACELOGRDREVT hRdrEvt);
|
|
|
|
|
|
/**
|
|
* Returns the event descriptor associated with the given event.
|
|
*
|
|
* @returns The trace log event descriptor associated with this event.
|
|
* @param hRdrEvt The reader event handle.
|
|
*/
|
|
RTDECL(PCRTTRACELOGEVTDESC) RTTraceLogRdrEvtGetDesc(RTTRACELOGRDREVT hRdrEvt);
|
|
|
|
|
|
/**
|
|
* Queries an event item by its name returning the value in the supplied buffer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_NOT_FOUND if the item name was not found for the given event.
|
|
* @param hRdrEvt The reader event handle.
|
|
* @param pszName The item name to query.
|
|
* @param pVal The item value buffer to initialise.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrEvtQueryVal(RTTRACELOGRDREVT hRdrEvt, const char *pszName, PRTTRACELOGEVTVAL pVal);
|
|
|
|
|
|
/**
|
|
* Fills the given value array using the values from the given event.
|
|
*
|
|
* @returns IPRT status code
|
|
* @param hRdrEvt The reader event handle.
|
|
* @param idxItemStart The index of the item to start filling the value in.
|
|
* @param paVals Array of values to fill.
|
|
* @param cVals Number of values the array is able to hold.
|
|
* @param pcVals Where to store the number of values filled on success.
|
|
*/
|
|
RTDECL(int) RTTraceLogRdrEvtFillVals(RTTRACELOGRDREVT hRdrEvt, unsigned idxItemStart, PRTTRACELOGEVTVAL paVals,
|
|
unsigned cVals, unsigned *pcVals);
|
|
|
|
RT_C_DECLS_END
|
|
|
|
/** @} */
|
|
|
|
#endif /* !IPRT_INCLUDED_tracelog_h */
|
|
|