diff options
Diffstat (limited to 'include/VBox/vmm/dbgfflowtrace.h')
| -rw-r--r-- | include/VBox/vmm/dbgfflowtrace.h | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/include/VBox/vmm/dbgfflowtrace.h b/include/VBox/vmm/dbgfflowtrace.h new file mode 100644 index 00000000..4906fe7e --- /dev/null +++ b/include/VBox/vmm/dbgfflowtrace.h @@ -0,0 +1,400 @@ +/** @file + * DBGF - Debugger Facility, Guest execution flow tracing. + */ + +/* + * Copyright (C) 2020-2022 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 VBOX_INCLUDED_vmm_dbgfflowtrace_h +#define VBOX_INCLUDED_vmm_dbgfflowtrace_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <VBox/types.h> +#include <VBox/vmm/dbgf.h> + +RT_C_DECLS_BEGIN +/** @defgroup grp_dbgf_flowtrace Guest Execution Flow Tracing + * @ingroup grp_dbgf + * + * @{ + */ + +/** A DBGF flow trace module handle. */ +typedef struct DBGFFLOWTRACEMODINT *DBGFFLOWTRACEMOD; +/** Pointer to a DBGF flow trace module handle. */ +typedef DBGFFLOWTRACEMOD *PDBGFFLOWTRACEMOD; +/** A DBGF flow trace probe handle. */ +typedef struct DBGFFLOWTRACEPROBEINT *DBGFFLOWTRACEPROBE; +/** Pointer to a DBGF flow trace state probe handle. */ +typedef DBGFFLOWTRACEPROBE *PDBGFFLOWTRACEPROBE; +/** A DBGF flow trace report handle. */ +typedef struct DBGFFLOWTRACEREPORTINT *DBGFFLOWTRACEREPORT; +/** Pointer to a DBGF flow trace report handle. */ +typedef DBGFFLOWTRACEREPORT *PDBGFFLOWTRACEREPORT; +/** A DBGF flow trace record handle. */ +typedef struct DBGFFLOWTRACERECORDINT *DBGFFLOWTRACERECORD; +/** Pointer to a DBGF flow trace record handle. */ +typedef DBGFFLOWTRACERECORD *PDBGFFLOWTRACERECORD; + + +/** Pointer to a flow trace probe entry. */ +typedef struct DBGFFLOWTRACEPROBEENTRY *PDBGFFLOWTRACEPROBEENTRY; +/** Pointer to a const flow trace probe entry. */ +typedef const struct DBGFFLOWTRACEPROBEENTRY *PCDBGFFLOWTRACEPROBEENTRY; + +/** @name Flags controlling the type of the addition of a single probe. + * @{ */ +/** Default options. */ +#define DBGF_FLOW_TRACE_PROBE_ADD_F_DEFAULT DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC +/** Collects the data specified by the data probe before the instruction is executed. */ +#define DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC RT_BIT_32(0) +/** Collects the data specified by the data probe after the instruction was executed. */ +#define DBGF_FLOW_TRACE_PROBE_ADD_F_AFTER_EXEC RT_BIT_32(1) +/** Mask of all valid flags. */ +#define DBGF_FLOW_TRACE_PROBE_ADD_F_VALID_MASK ( DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC \ + | DBGF_FLOW_TRACE_PROBE_ADD_F_AFTER_EXEC) +/** @} */ + + +/** + * Probe entry type. + */ +typedef enum DBGFFLOWTRACEPROBEENTRYTYPE +{ + /** Invalid type. */ + DBGFFLOWTRACEPROBEENTRYTYPE_INVALID = 0, + /** Register. */ + DBGFFLOWTRACEPROBEENTRYTYPE_REG, + /** Constant memory buffer pointer. */ + DBGFFLOWTRACEPROBEENTRYTYPE_CONST_MEM, + /** Indirect memory buffer pointer, obtained from the base and index register + * and a constant scale. */ + DBGFFLOWTRACEPROBEENTRYTYPE_INDIRECT_MEM, + /** Callback. */ + DBGFFLOWTRACEPROBEENTRYTYPE_CALLBACK, + /** Halt in the debugger when the entry is collected. */ + DBGFFLOWTRACEPROBEENTRYTYPE_DEBUGGER, + /** 32bit hack. */ + DBGFFLOWTRACEPROBEENTRYTYPE_32BIT_HACK = 0x7fffffff +} DBGFFLOWTRACEPROBEENTRYTYPE; + + +/** + * Register descriptor for a probe entry. + */ +typedef struct DBGFFLOWTRACEPROBEENTRYREG +{ + /** The register name - see DBGFR3RegNm*. */ + const char *pszName; + /** The size of the value in bytes. */ + DBGFREGVALTYPE enmType; +} DBGFFLOWTRACEPROBEENTRYREG; +/** Pointer to data probe register entry. */ +typedef DBGFFLOWTRACEPROBEENTRYREG *PDBGFFLOWTRACEPROBEENTRYREG; +/** Pointer to a const probe register entry. */ +typedef const DBGFFLOWTRACEPROBEENTRYREG *PCDBGFFLOWTRACEPROBEENTRYREG; + + +/** + * Flow trace probe callback. + * + * @returns VBox status code, any error aborts continuing fetching the data for the + * probe containing this callback. + * @param pUVM The usermode VM handle. + * @param idCpu The ID of the vCPU the probe as fired. + * @param hFlowTraceMod The handle to the flow trace module the probe was fired for. + * @param pAddrProbe The guest address the probe was fired at. + * @param hFlowTraceProbe The flow trace probe handle.this callback is in. + * @param pProbeEntry The probe entry this callback is part of. + * @param pvUser The opaque user data for the callback. + */ +typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEPROBECALLBACK, (PUVM pUVM, VMCPUID idCpu, DBGFFLOWTRACEMOD hFlowTraceMod, + PCDBGFADDRESS pAddrProbe, DBGFFLOWTRACEPROBE hFlowTraceProbe, + PCDBGFFLOWTRACEPROBEENTRY pProbeEntry, + void *pvUser)); +/** Pointer to a flow trace probe callback. */ +typedef FNDBGFFLOWTRACEPROBECALLBACK *PFNDBGFFLOWTRACEPROBECALLBACK; + + +/** + * Trace flow probe entry. + */ +typedef struct DBGFFLOWTRACEPROBEENTRY +{ + /** Entry type. */ + DBGFFLOWTRACEPROBEENTRYTYPE enmType; + /** Description for this entry, optional. */ + const char *pszDesc; + /** The data based on the entry type. */ + union + { + /** Register. */ + DBGFFLOWTRACEPROBEENTRYREG Reg; + /** Constant memory pointer. */ + struct + { + /** The address of the memory buffer. */ + DBGFADDRESS AddrMem; + /** Number of bytes to log. */ + size_t cbMem; + } ConstMem; + /** Indirect memory */ + struct + { + /** The base register. */ + DBGFFLOWTRACEPROBEENTRYREG RegBase; + /** The index register. */ + DBGFFLOWTRACEPROBEENTRYREG RegIndex; + /** The scale to apply to the index. */ + uint8_t uScale; + /** A constant offset which is applied at the end. */ + RTGCINTPTR iOffset; + /** Number of bytes to log. */ + size_t cbMem; + } IndirectMem; + /** Callback. */ + struct + { + /** The callback to call. */ + PFNDBGFFLOWTRACEPROBECALLBACK pfnCallback; + /** The opaque user data to provide. */ + void *pvUser; + } Callback; + } Type; +} DBGFFLOWTRACEPROBEENTRY; + + +/** + * Flow trace probe value. + */ +typedef struct DBGFFLOWTRACEPROBEVAL +{ + /** Pointer to the flow trace probe entry this value is for. */ + PCDBGFFLOWTRACEPROBEENTRY pProbeEntry; + /** Data based on the type in the entry. */ + union + { + /** Register value. */ + DBGFREGENTRYNM Reg; + /** Memory value (constant pointer or indirect). */ + struct + { + /** The guest address logged. */ + DBGFADDRESS Addr; + /** Pointer to the data logged. */ + const void *pvBuf; + /** Number of bytes logged. */ + size_t cbBuf; + } Mem; + } Type; +} DBGFFLOWTRACEPROBEVAL; +/** Pointer to a flow trace probe value. */ +typedef DBGFFLOWTRACEPROBEVAL *PDBGFFLOWTRACEPROBEVAL; +/** Pointer to a const flow trace probe value. */ +typedef const DBGFFLOWTRACEPROBEVAL *PCDBGFFLOWTRACEPROBEVAL; + +/** + * Flow trace report filter operation. + */ +typedef enum DBGFFLOWTRACEREPORTFILTEROP +{ + /** Invalid filter operation. */ + DBGFFLOWTRACEREPORTFILTEROP_INVALID = 0, + /** All filters must match with the record. */ + DBGFFLOWTRACEREPORTFILTEROP_AND, + /** Only one filter must match with the record. */ + DBGFFLOWTRACEREPORTFILTEROP_OR, + /** 32bit hack. */ + DBGFFLOWTRACEREPORTFILTEROP_32BIT_HACK = 0x7fffffff +} DBGFFLOWTRACEREPORTFILTEROP; + + +/** + * Flow trace report filter type. + */ +typedef enum DBGFFLOWTRACEREPORTFILTERTYPE +{ + /** Invalid filter type. */ + DBGFFLOWTRACEREPORTFILTERTYPE_INVALID = 0, + /** Filter by sequence number. */ + DBGFFLOWTRACEREPORTFILTERTYPE_SEQ_NUM, + /** Filter by timestamp. */ + DBGFFLOWTRACEREPORTFILTERTYPE_TIMESTAMP, + /** Filter by probe address. */ + DBGFFLOWTRACEREPORTFILTERTYPE_ADDR, + /** Filter by CPU ID. */ + DBGFFLOWTRACEREPORTFILTERTYPE_VMCPU_ID, + /** Filter by specific probe data. */ + DBGFFLOWTRACEREPORTFILTERTYPE_PROBE_DATA, + /** 32bit hack. */ + DBGFFLOWTRACEREPORTFILTERTYPE_32BIT_HACK = 0x7fffffff +} DBGFFLOWTRACEREPORTFILTERTYPE; + + +/** + * Flow trace report filter. + */ +typedef struct DBGFFLOWTRACEREPORTFILTER +{ + /** Filter type. */ + DBGFFLOWTRACEREPORTFILTERTYPE enmType; + /** Filter data, type dependent. */ + struct + { + /** Sequence number filtering. */ + struct + { + /** Sequence number filtering, start value. */ + uint64_t u64SeqNoFirst; + /** Sequence number filtering, last value. */ + uint64_t u64SeqNoLast; + } SeqNo; + /** Timestamp filtering. */ + struct + { + /** Start value. */ + uint64_t u64TsFirst; + /** Last value. */ + uint64_t u64TsLast; + } Timestamp; + /** Probe address filtering. */ + struct + { + /** Start address. */ + DBGFADDRESS AddrStart; + /** Last address. */ + DBGFADDRESS AddrLast; + } Addr; + /** vCPU id filtering. */ + struct + { + /** Start CPU id. */ + VMCPUID idCpuStart; + /** Last CPU id. */ + VMCPUID idCpuLast; + } VCpuId; + /** Probe data filtering. */ + struct + { + /** Pointer to the probe value array. */ + PCDBGFFLOWTRACEPROBEVAL paVal; + /** Number of entries in the array for filtering. */ + uint32_t cVals; + /** Flag whether to look into the common values or the probe specific ones. */ + bool fValCmn; + } ProbeData; + } Type; +} DBGFFLOWTRACEREPORTFILTER; +/** Pointer to a flow trace report filter. */ +typedef DBGFFLOWTRACEREPORTFILTER *PDBGFFLOWTRACEREPORTFILTER; + + +/** @name Flags controlling filtering records. + * @{ */ +/** Add records which don't match the filter. */ +#define DBGF_FLOW_TRACE_REPORT_FILTER_F_REVERSE RT_BIT_32(0) +/** Mask of all valid flags. */ +#define DBGF_FLOW_TRACE_REPORT_FILTER_F_VALID (DBGF_FLOW_TRACE_REPORT_FILTER_F_REVERSE) +/** @} */ + + +/** + * Flow trace report enumeration callback. + * + * @returns VBox status code, any non VINF_SUCCESS code aborts the enumeration and is returned + * by DBGFR3FlowTraceReportEnumRecords(). + * @param hFlowTraceReport The flow trace report handle being enumerated. + * @param hFlowTraceRecord The flow trace record handle. + * @param pvUser Opaque user data given in DBGFR3FlowTraceReportEnumRecords(). + */ +typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEREPORTENUMCLBK,(DBGFFLOWTRACEREPORT hFlowTraceReport, + DBGFFLOWTRACERECORD hFlowTraceRecord, + void *pvUser)); +/** Pointer to a record enumeration callback. */ +typedef FNDBGFFLOWTRACEREPORTENUMCLBK *PFNDBGFFLOWTRACEREPORTENUMCLBK; + + +VMMR3DECL(int) DBGFR3FlowTraceModCreate(PUVM pUVM, VMCPUID idCpu, + DBGFFLOWTRACEPROBE hFlowTraceProbeCommon, + PDBGFFLOWTRACEMOD phFlowTraceMod); +VMMR3DECL(int) DBGFR3FlowTraceModCreateFromFlowGraph(PUVM pUVM, VMCPUID idCpu, DBGFFLOW hFlow, + DBGFFLOWTRACEPROBE hFlowTraceProbeCommon, + DBGFFLOWTRACEPROBE hFlowTraceProbeEntry, + DBGFFLOWTRACEPROBE hFlowTraceProbeRegular, + DBGFFLOWTRACEPROBE hFlowTraceProbeExit, + PDBGFFLOWTRACEMOD phFlowTraceMod); +VMMR3DECL(uint32_t) DBGFR3FlowTraceModRetain(DBGFFLOWTRACEMOD hFlowTraceMod); +VMMR3DECL(uint32_t) DBGFR3FlowTraceModRelease(DBGFFLOWTRACEMOD hFlowTraceMod); +VMMR3DECL(int) DBGFR3FlowTraceModEnable(DBGFFLOWTRACEMOD hFlowTraceMod, uint32_t cHits, uint32_t cRecordsMax); +VMMR3DECL(int) DBGFR3FlowTraceModDisable(DBGFFLOWTRACEMOD hFlowTraceMod); +VMMR3DECL(int) DBGFR3FlowTraceModQueryReport(DBGFFLOWTRACEMOD hFlowTraceMod, + PDBGFFLOWTRACEREPORT phFlowTraceReport); +VMMR3DECL(int) DBGFR3FlowTraceModClear(DBGFFLOWTRACEMOD hFlowTraceMod); +VMMR3DECL(int) DBGFR3FlowTraceModAddProbe(DBGFFLOWTRACEMOD hFlowTraceMod, PCDBGFADDRESS pAddrProbe, + DBGFFLOWTRACEPROBE hFlowTraceProbe, uint32_t fFlags); + +VMMR3DECL(int) DBGFR3FlowTraceProbeCreate(PUVM pUVM, const char *pszDescr, PDBGFFLOWTRACEPROBE phFlowTraceProbe); +VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRetain(DBGFFLOWTRACEPROBE hFlowTraceProbe); +VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRelease(DBGFFLOWTRACEPROBE hFlowTraceProbe); +VMMR3DECL(int) DBGFR3FlowTraceProbeEntriesAdd(DBGFFLOWTRACEPROBE hFlowTraceProbe, + PCDBGFFLOWTRACEPROBEENTRY paEntries, uint32_t cEntries); + +VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRetain(DBGFFLOWTRACEREPORT hFlowTraceReport); +VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRelease(DBGFFLOWTRACEREPORT hFlowTraceReport); +VMMR3DECL(uint32_t) DBGFR3FlowTraceReportGetRecordCount(DBGFFLOWTRACEREPORT hFlowTraceReport); +VMMR3DECL(int) DBGFR3FlowTraceReportQueryRecord(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t idxRec, PDBGFFLOWTRACERECORD phFlowTraceRec); +VMMR3DECL(int) DBGFR3FlowTraceReportQueryFiltered(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t fFlags, + PDBGFFLOWTRACEREPORTFILTER paFilters, uint32_t cFilters, + DBGFFLOWTRACEREPORTFILTEROP enmOp, + PDBGFFLOWTRACEREPORT phFlowTraceReportFiltered); +VMMR3DECL(int) DBGFR3FlowTraceReportEnumRecords(DBGFFLOWTRACEREPORT hFlowTraceReport, + PFNDBGFFLOWTRACEREPORTENUMCLBK pfnEnum, + void *pvUser); + +VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRetain(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRelease(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetSeqNo(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetTimestamp(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(PDBGFADDRESS) DBGFR3FlowTraceRecordGetAddr(DBGFFLOWTRACERECORD hFlowTraceRecord, PDBGFADDRESS pAddr); +VMMR3DECL(DBGFFLOWTRACEPROBE) DBGFR3FlowTraceRecordGetProbe(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCount(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCommonCount(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetVals(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetValsCommon(DBGFFLOWTRACERECORD hFlowTraceRecord); +VMMR3DECL(VMCPUID) DBGFR3FlowTraceRecordGetCpuId(DBGFFLOWTRACERECORD hFlowTraceRecord); + +/** @} */ +RT_C_DECLS_END + +#endif /* !VBOX_INCLUDED_vmm_dbgfflowtrace_h */ + |