/*++ 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 #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 #ifdef __cplusplus } #endif