|
|
/*++
Copyright (c) 1990-2002 Microsoft Corporation
Module Name:
minidump.h
Abstract:
This module defines the prototypes and constants required for the image help routines.
Contains debugging support routines that are redistributable.
Revision History:
--*/
#if _MSC_VER > 1020
#pragma once
#endif
#ifdef __cplusplus
extern "C" { #endif
#include <pshpack4.h>
#pragma warning(disable:4200) // Zero length array
#define MINIDUMP_SIGNATURE ('PMDM')
#define MINIDUMP_VERSION (42899)
typedef unsigned char UINT8; typedef unsigned short UINT16; typedef DWORD RVA; typedef ULONG64 RVA64;
C_ASSERT (sizeof (UINT8) == 1); C_ASSERT (sizeof (UINT16) == 2);
typedef struct _MINIDUMP_LOCATION_DESCRIPTOR { ULONG32 DataSize; RVA Rva; } MINIDUMP_LOCATION_DESCRIPTOR;
typedef struct _MINIDUMP_LOCATION_DESCRIPTOR64 { ULONG64 DataSize; RVA64 Rva; } MINIDUMP_LOCATION_DESCRIPTOR64;
typedef struct _MINIDUMP_MEMORY_DESCRIPTOR { ULONG64 StartOfMemoryRange; MINIDUMP_LOCATION_DESCRIPTOR Memory; } MINIDUMP_MEMORY_DESCRIPTOR, *PMINIDUMP_MEMORY_DESCRIPTOR;
// DESCRIPTOR64 is used for full-memory minidumps where
// all of the raw memory is laid out sequentially at the
// end of the dump. There is no need for individual RVAs
// as the RVA is the base RVA plus the sum of the preceeding
// data blocks.
typedef struct _MINIDUMP_MEMORY_DESCRIPTOR64 { ULONG64 StartOfMemoryRange; ULONG64 DataSize; } MINIDUMP_MEMORY_DESCRIPTOR64, *PMINIDUMP_MEMORY_DESCRIPTOR64;
typedef struct _MINIDUMP_HEADER { ULONG32 Signature; ULONG32 Version; ULONG32 NumberOfStreams; RVA StreamDirectoryRva; ULONG32 CheckSum; union { ULONG32 Reserved; ULONG32 TimeDateStamp; }; ULONG64 Flags; } MINIDUMP_HEADER, *PMINIDUMP_HEADER;
//
// The MINIDUMP_HEADER field StreamDirectoryRva points to
// an array of MINIDUMP_DIRECTORY structures.
//
typedef struct _MINIDUMP_DIRECTORY { ULONG32 StreamType; MINIDUMP_LOCATION_DESCRIPTOR Location; } MINIDUMP_DIRECTORY, *PMINIDUMP_DIRECTORY;
typedef struct _MINIDUMP_STRING { ULONG32 Length; // Length in bytes of the string
WCHAR Buffer [0]; // Variable size buffer
} MINIDUMP_STRING, *PMINIDUMP_STRING;
//
// The MINIDUMP_DIRECTORY field StreamType may be one of the following types.
// Types will be added in the future, so if a program reading the minidump
// header encounters a stream type it does not understand it should ignore
// the data altogether. Any tag above LastReservedStream will not be used by
// the system and is reserved for program-specific information.
//
typedef enum _MINIDUMP_STREAM_TYPE {
UnusedStream = 0, ReservedStream0 = 1, ReservedStream1 = 2, ThreadListStream = 3, ModuleListStream = 4, MemoryListStream = 5, ExceptionStream = 6, SystemInfoStream = 7, ThreadExListStream = 8, Memory64ListStream = 9, CommentStreamA = 10, CommentStreamW = 11, HandleDataStream = 12, FunctionTableStream = 13, UnloadedModuleListStream = 14, MiscInfoStream = 15,
LastReservedStream = 0xffff
} MINIDUMP_STREAM_TYPE;
//
// The minidump system information contains processor and
// Operating System specific information.
//
//
// CPU information is obtained from one of two places.
//
// 1) On x86 computers, CPU_INFORMATION is obtained from the CPUID
// instruction. You must use the X86 portion of the union for X86
// computers.
//
// 2) On non-x86 architectures, CPU_INFORMATION is obtained by calling
// IsProcessorFeatureSupported().
//
typedef union _CPU_INFORMATION {
//
// X86 platforms use CPUID function to obtain processor information.
//
struct {
//
// CPUID Subfunction 0, register EAX (VendorId [0]),
// EBX (VendorId [1]) and ECX (VendorId [2]).
//
ULONG32 VendorId [ 3 ]; //
// CPUID Subfunction 1, register EAX
//
ULONG32 VersionInformation;
//
// CPUID Subfunction 1, register EDX
//
ULONG32 FeatureInformation;
//
// CPUID, Subfunction 80000001, register EBX. This will only
// be obtained if the vendor id is "AuthenticAMD".
//
ULONG32 AMDExtendedCpuFeatures;
} X86CpuInfo;
//
// Non-x86 platforms use processor feature flags.
//
struct {
ULONG64 ProcessorFeatures [ 2 ]; } OtherCpuInfo;
} CPU_INFORMATION, *PCPU_INFORMATION; typedef struct _MINIDUMP_SYSTEM_INFO {
//
// ProcessorArchitecture, ProcessorLevel and ProcessorRevision are all
// taken from the SYSTEM_INFO structure obtained by GetSystemInfo( ).
//
UINT16 ProcessorArchitecture; UINT16 ProcessorLevel; UINT16 ProcessorRevision;
union { UINT16 Reserved0; struct { UINT8 NumberOfProcessors; UINT8 ProductType; }; };
//
// MajorVersion, MinorVersion, BuildNumber, PlatformId and
// CSDVersion are all taken from the OSVERSIONINFO structure
// returned by GetVersionEx( ).
//
ULONG32 MajorVersion; ULONG32 MinorVersion; ULONG32 BuildNumber; ULONG32 PlatformId;
//
// RVA to a CSDVersion string in the string table.
//
RVA CSDVersionRva;
union { ULONG32 Reserved1; struct { UINT16 SuiteMask; UINT16 Reserved2; }; };
CPU_INFORMATION Cpu;
} MINIDUMP_SYSTEM_INFO, *PMINIDUMP_SYSTEM_INFO;
//
// The minidump thread contains standard thread
// information plus an RVA to the memory for this
// thread and an RVA to the CONTEXT structure for
// this thread.
//
//
// ThreadId must be 4 bytes on all architectures.
//
C_ASSERT (sizeof ( ((LPPROCESS_INFORMATION)0)->dwThreadId ) == 4);
typedef struct _MINIDUMP_THREAD { ULONG32 ThreadId; ULONG32 SuspendCount; ULONG32 PriorityClass; ULONG32 Priority; ULONG64 Teb; MINIDUMP_MEMORY_DESCRIPTOR Stack; MINIDUMP_LOCATION_DESCRIPTOR ThreadContext; } MINIDUMP_THREAD, *PMINIDUMP_THREAD;
//
// The thread list is a container of threads.
//
typedef struct _MINIDUMP_THREAD_LIST { ULONG32 NumberOfThreads; MINIDUMP_THREAD Threads [0]; } MINIDUMP_THREAD_LIST, *PMINIDUMP_THREAD_LIST;
typedef struct _MINIDUMP_THREAD_EX { ULONG32 ThreadId; ULONG32 SuspendCount; ULONG32 PriorityClass; ULONG32 Priority; ULONG64 Teb; MINIDUMP_MEMORY_DESCRIPTOR Stack; MINIDUMP_LOCATION_DESCRIPTOR ThreadContext; MINIDUMP_MEMORY_DESCRIPTOR BackingStore; } MINIDUMP_THREAD_EX, *PMINIDUMP_THREAD_EX;
//
// The thread list is a container of threads.
//
typedef struct _MINIDUMP_THREAD_EX_LIST { ULONG32 NumberOfThreads; MINIDUMP_THREAD_EX Threads [0]; } MINIDUMP_THREAD_EX_LIST, *PMINIDUMP_THREAD_EX_LIST;
//
// The MINIDUMP_EXCEPTION is the same as EXCEPTION on Win64.
//
typedef struct _MINIDUMP_EXCEPTION { ULONG32 ExceptionCode; ULONG32 ExceptionFlags; ULONG64 ExceptionRecord; ULONG64 ExceptionAddress; ULONG32 NumberParameters; ULONG32 __unusedAlignment; ULONG64 ExceptionInformation [ EXCEPTION_MAXIMUM_PARAMETERS ]; } MINIDUMP_EXCEPTION, *PMINIDUMP_EXCEPTION;
//
// The exception information stream contains the id of the thread that caused
// the exception (ThreadId), the exception record for the exception
// (ExceptionRecord) and an RVA to the thread context where the exception
// occured.
//
typedef struct MINIDUMP_EXCEPTION_STREAM { ULONG32 ThreadId; ULONG32 __alignment; MINIDUMP_EXCEPTION ExceptionRecord; MINIDUMP_LOCATION_DESCRIPTOR ThreadContext; } MINIDUMP_EXCEPTION_STREAM, *PMINIDUMP_EXCEPTION_STREAM;
//
// The MINIDUMP_MODULE contains information about a
// a specific module. It includes the CheckSum and
// the TimeDateStamp for the module so the module
// can be reloaded during the analysis phase.
//
typedef struct _MINIDUMP_MODULE { ULONG64 BaseOfImage; ULONG32 SizeOfImage; ULONG32 CheckSum; ULONG32 TimeDateStamp; RVA ModuleNameRva; VS_FIXEDFILEINFO VersionInfo; MINIDUMP_LOCATION_DESCRIPTOR CvRecord; MINIDUMP_LOCATION_DESCRIPTOR MiscRecord; ULONG64 Reserved0; // Reserved for future use.
ULONG64 Reserved1; // Reserved for future use.
} MINIDUMP_MODULE, *PMINIDUMP_MODULE;
//
// The minidump module list is a container for modules.
//
typedef struct _MINIDUMP_MODULE_LIST { ULONG32 NumberOfModules; MINIDUMP_MODULE Modules [ 0 ]; } MINIDUMP_MODULE_LIST, *PMINIDUMP_MODULE_LIST;
//
// Memory Ranges
//
typedef struct _MINIDUMP_MEMORY_LIST { ULONG32 NumberOfMemoryRanges; MINIDUMP_MEMORY_DESCRIPTOR MemoryRanges [0]; } MINIDUMP_MEMORY_LIST, *PMINIDUMP_MEMORY_LIST;
typedef struct _MINIDUMP_MEMORY64_LIST { ULONG64 NumberOfMemoryRanges; RVA64 BaseRva; MINIDUMP_MEMORY_DESCRIPTOR64 MemoryRanges [0]; } MINIDUMP_MEMORY64_LIST, *PMINIDUMP_MEMORY64_LIST;
//
// Support for user supplied exception information.
//
typedef struct _MINIDUMP_EXCEPTION_INFORMATION { DWORD ThreadId; PEXCEPTION_POINTERS ExceptionPointers; BOOL ClientPointers; } MINIDUMP_EXCEPTION_INFORMATION, *PMINIDUMP_EXCEPTION_INFORMATION;
typedef struct _MINIDUMP_EXCEPTION_INFORMATION64 { DWORD ThreadId; ULONG64 ExceptionRecord; ULONG64 ContextRecord; BOOL ClientPointers; } MINIDUMP_EXCEPTION_INFORMATION64, *PMINIDUMP_EXCEPTION_INFORMATION64;
//
// Support for capturing system handle state at the time of the dump.
//
typedef struct _MINIDUMP_HANDLE_DESCRIPTOR { ULONG64 Handle; RVA TypeNameRva; RVA ObjectNameRva; ULONG32 Attributes; ULONG32 GrantedAccess; ULONG32 HandleCount; ULONG32 PointerCount; } MINIDUMP_HANDLE_DESCRIPTOR, *PMINIDUMP_HANDLE_DESCRIPTOR;
typedef struct _MINIDUMP_HANDLE_DATA_STREAM { ULONG32 SizeOfHeader; ULONG32 SizeOfDescriptor; ULONG32 NumberOfDescriptors; ULONG32 Reserved; } MINIDUMP_HANDLE_DATA_STREAM, *PMINIDUMP_HANDLE_DATA_STREAM;
//
// Support for capturing dynamic function table state at the time of the dump.
//
typedef struct _MINIDUMP_FUNCTION_TABLE_DESCRIPTOR { ULONG64 MinimumAddress; ULONG64 MaximumAddress; ULONG64 BaseAddress; ULONG32 EntryCount; ULONG32 SizeOfAlignPad; } MINIDUMP_FUNCTION_TABLE_DESCRIPTOR, *PMINIDUMP_FUNCTION_TABLE_DESCRIPTOR;
typedef struct _MINIDUMP_FUNCTION_TABLE_STREAM { ULONG32 SizeOfHeader; ULONG32 SizeOfDescriptor; ULONG32 SizeOfNativeDescriptor; ULONG32 SizeOfFunctionEntry; ULONG32 NumberOfDescriptors; ULONG32 SizeOfAlignPad; } MINIDUMP_FUNCTION_TABLE_STREAM, *PMINIDUMP_FUNCTION_TABLE_STREAM;
//
// The MINIDUMP_UNLOADED_MODULE contains information about a
// a specific module that was previously loaded but no
// longer is. This can help with diagnosing problems where
// callers attempt to call code that is no longer loaded.
//
typedef struct _MINIDUMP_UNLOADED_MODULE { ULONG64 BaseOfImage; ULONG32 SizeOfImage; ULONG32 CheckSum; ULONG32 TimeDateStamp; RVA ModuleNameRva; } MINIDUMP_UNLOADED_MODULE, *PMINIDUMP_UNLOADED_MODULE;
//
// The minidump unloaded module list is a container for unloaded modules.
//
typedef struct _MINIDUMP_UNLOADED_MODULE_LIST { ULONG32 SizeOfHeader; ULONG32 SizeOfEntry; ULONG32 NumberOfEntries; } MINIDUMP_UNLOADED_MODULE_LIST, *PMINIDUMP_UNLOADED_MODULE_LIST;
//
// The miscellaneous information stream contains a variety
// of small pieces of information. A member is valid if
// it's within the available size and its corresponding
// bit is set.
//
#define MINIDUMP_MISC1_PROCESS_ID 0x00000001
#define MINIDUMP_MISC1_PROCESS_TIMES 0x00000002
typedef struct _MINIDUMP_MISC_INFO { ULONG32 SizeOfInfo; ULONG32 Flags1; ULONG32 ProcessId; ULONG32 ProcessCreateTime; ULONG32 ProcessUserTime; ULONG32 ProcessKernelTime; } MINIDUMP_MISC_INFO, *PMINIDUMP_MISC_INFO;
//
// Support for arbitrary user-defined information.
//
typedef struct _MINIDUMP_USER_RECORD { ULONG32 Type; MINIDUMP_LOCATION_DESCRIPTOR Memory; } MINIDUMP_USER_RECORD, *PMINIDUMP_USER_RECORD;
typedef struct _MINIDUMP_USER_STREAM { ULONG32 Type; ULONG BufferSize; PVOID Buffer;
} MINIDUMP_USER_STREAM, *PMINIDUMP_USER_STREAM;
typedef struct _MINIDUMP_USER_STREAM_INFORMATION { ULONG UserStreamCount; PMINIDUMP_USER_STREAM UserStreamArray; } MINIDUMP_USER_STREAM_INFORMATION, *PMINIDUMP_USER_STREAM_INFORMATION;
//
// Callback support.
//
typedef enum _MINIDUMP_CALLBACK_TYPE { ModuleCallback, ThreadCallback, ThreadExCallback, IncludeThreadCallback, IncludeModuleCallback, } MINIDUMP_CALLBACK_TYPE;
typedef struct _MINIDUMP_THREAD_CALLBACK { ULONG ThreadId; HANDLE ThreadHandle; CONTEXT Context; ULONG SizeOfContext; ULONG64 StackBase; ULONG64 StackEnd; } MINIDUMP_THREAD_CALLBACK, *PMINIDUMP_THREAD_CALLBACK;
typedef struct _MINIDUMP_THREAD_EX_CALLBACK { ULONG ThreadId; HANDLE ThreadHandle; CONTEXT Context; ULONG SizeOfContext; ULONG64 StackBase; ULONG64 StackEnd; ULONG64 BackingStoreBase; ULONG64 BackingStoreEnd; } MINIDUMP_THREAD_EX_CALLBACK, *PMINIDUMP_THREAD_EX_CALLBACK;
typedef struct _MINIDUMP_INCLUDE_THREAD_CALLBACK { ULONG ThreadId; } MINIDUMP_INCLUDE_THREAD_CALLBACK, *PMINIDUMP_INCLUDE_THREAD_CALLBACK;
typedef enum _THREAD_WRITE_FLAGS { ThreadWriteThread = 0x0001, ThreadWriteStack = 0x0002, ThreadWriteContext = 0x0004, ThreadWriteBackingStore = 0x0008, ThreadWriteInstructionWindow = 0x0010, ThreadWriteThreadData = 0x0020, } THREAD_WRITE_FLAGS;
typedef struct _MINIDUMP_MODULE_CALLBACK { PWCHAR FullPath; ULONG64 BaseOfImage; ULONG SizeOfImage; ULONG CheckSum; ULONG TimeDateStamp; VS_FIXEDFILEINFO VersionInfo; PVOID CvRecord; ULONG SizeOfCvRecord; PVOID MiscRecord; ULONG SizeOfMiscRecord; } MINIDUMP_MODULE_CALLBACK, *PMINIDUMP_MODULE_CALLBACK;
typedef struct _MINIDUMP_INCLUDE_MODULE_CALLBACK { ULONG64 BaseOfImage; } MINIDUMP_INCLUDE_MODULE_CALLBACK, *PMINIDUMP_INCLUDE_MODULE_CALLBACK;
typedef enum _MODULE_WRITE_FLAGS { ModuleWriteModule = 0x0001, ModuleWriteDataSeg = 0x0002, ModuleWriteMiscRecord = 0x0004, ModuleWriteCvRecord = 0x0008, ModuleReferencedByMemory = 0x0010 } MODULE_WRITE_FLAGS;
typedef struct _MINIDUMP_CALLBACK_INPUT { ULONG ProcessId; HANDLE ProcessHandle; ULONG CallbackType; union { MINIDUMP_THREAD_CALLBACK Thread; MINIDUMP_THREAD_EX_CALLBACK ThreadEx; MINIDUMP_MODULE_CALLBACK Module; MINIDUMP_INCLUDE_THREAD_CALLBACK IncludeThread; MINIDUMP_INCLUDE_MODULE_CALLBACK IncludeModule; }; } MINIDUMP_CALLBACK_INPUT, *PMINIDUMP_CALLBACK_INPUT;
typedef struct _MINIDUMP_CALLBACK_OUTPUT { union { ULONG ModuleWriteFlags; ULONG ThreadWriteFlags; }; } MINIDUMP_CALLBACK_OUTPUT, *PMINIDUMP_CALLBACK_OUTPUT;
//
// A normal minidump contains just the information
// necessary to capture stack traces for all of the
// existing threads in a process.
//
// A minidump with data segments includes all of the data
// sections from loaded modules in order to capture
// global variable contents. This can make the dump much
// larger if many modules have global data.
//
// A minidump with full memory includes all of the accessible
// memory in the process and can be very large. A minidump
// with full memory always has the raw memory data at the end
// of the dump so that the initial structures in the dump can
// be mapped directly without having to include the raw
// memory information.
//
// Stack and backing store memory can be filtered to remove
// data unnecessary for stack walking. This can improve
// compression of stacks and also deletes data that may
// be private and should not be stored in a dump.
// Memory can also be scanned to see what modules are
// referenced by stack and backing store memory to allow
// omission of other modules to reduce dump size.
// In either of these modes the ModuleReferencedByMemory flag
// is set for all modules referenced before the base
// module callbacks occur.
//
// On some operating systems a list of modules that were
// recently unloaded is kept in addition to the currently
// loaded module list. This information can be saved in
// the dump if desired.
//
// Stack and backing store memory can be scanned for referenced
// pages in order to pick up data referenced by locals or other
// stack memory. This can increase the size of a dump significantly.
//
// Module paths may contain undesired information such as user names
// or other important directory names so they can be stripped. This
// option reduces the ability to locate the proper image later
// and should only be used in certain situations.
//
// Complete operating system per-process and per-thread information can
// be gathered and stored in the dump.
//
// The virtual address space can be scanned for various types
// of memory to be included in the dump.
//
// Code which is concerned with potentially private information
// getting into the minidump can set a flag that automatically
// modifies all existing and future flags to avoid placing
// unnecessary data in the dump. Basic data, such as stack
// information, will still be included but optional data, such
// as indirect memory, will not.
//
typedef enum _MINIDUMP_TYPE { MiniDumpNormal = 0x0000, MiniDumpWithDataSegs = 0x0001, MiniDumpWithFullMemory = 0x0002, MiniDumpWithHandleData = 0x0004, MiniDumpFilterMemory = 0x0008, MiniDumpScanMemory = 0x0010, MiniDumpWithUnloadedModules = 0x0020, MiniDumpWithIndirectlyReferencedMemory = 0x0040, MiniDumpFilterModulePaths = 0x0080, MiniDumpWithProcessThreadData = 0x0100, MiniDumpWithPrivateReadWriteMemory = 0x0200, MiniDumpWithoutOptionalData = 0x0400, } MINIDUMP_TYPE;
//
// The minidump callback should modify the FieldsToWrite parameter to reflect
// what portions of the specified thread or module should be written to the
// file.
//
typedef BOOL (WINAPI * MINIDUMP_CALLBACK_ROUTINE) ( IN PVOID CallbackParam, IN CONST PMINIDUMP_CALLBACK_INPUT CallbackInput, IN OUT PMINIDUMP_CALLBACK_OUTPUT CallbackOutput );
typedef struct _MINIDUMP_CALLBACK_INFORMATION { MINIDUMP_CALLBACK_ROUTINE CallbackRoutine; PVOID CallbackParam; } MINIDUMP_CALLBACK_INFORMATION, *PMINIDUMP_CALLBACK_INFORMATION;
//++
//
// PVOID
// RVA_TO_ADDR(
// PVOID Mapping,
// ULONG Rva
// )
//
// Routine Description:
//
// Map an RVA that is contained within a mapped file to it's associated
// flat address.
//
// Arguments:
//
// Mapping - Base address of mapped file containing the RVA.
//
// Rva - An Rva to fixup.
//
// Return Values:
//
// A pointer to the desired data.
//
//--
#define RVA_TO_ADDR(Mapping,Rva) ((PVOID)(((ULONG_PTR) (Mapping)) + (Rva)))
BOOL WINAPI MiniDumpWriteDump( IN HANDLE hProcess, IN DWORD ProcessId, IN HANDLE hFile, IN MINIDUMP_TYPE DumpType, IN CONST PMINIDUMP_EXCEPTION_INFORMATION ExceptionParam, OPTIONAL IN CONST PMINIDUMP_USER_STREAM_INFORMATION UserStreamParam, OPTIONAL IN CONST PMINIDUMP_CALLBACK_INFORMATION CallbackParam OPTIONAL );
BOOL WINAPI MiniDumpReadDumpStream( IN PVOID BaseOfDump, IN ULONG StreamNumber, OUT PMINIDUMP_DIRECTORY * Dir, OPTIONAL OUT PVOID * StreamPointer, OPTIONAL OUT ULONG * StreamSize OPTIONAL );
#include <poppack.h>
#ifdef __cplusplus
} #endif
|