Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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 */
+