diff options
Diffstat (limited to 'LibOVR/Src/Kernel/OVR_DebugHelp.h')
| -rw-r--r-- | LibOVR/Src/Kernel/OVR_DebugHelp.h | 461 |
1 files changed, 461 insertions, 0 deletions
diff --git a/LibOVR/Src/Kernel/OVR_DebugHelp.h b/LibOVR/Src/Kernel/OVR_DebugHelp.h new file mode 100644 index 0000000..2430ae4 --- /dev/null +++ b/LibOVR/Src/Kernel/OVR_DebugHelp.h @@ -0,0 +1,461 @@ +/************************************************************************************ + +Filename : OVR_DebugHelp.h +Content : Platform-independent exception handling interface +Created : October 6, 2014 + +Copyright : Copyright 2014 Oculus VR, LLC. All Rights reserved. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +************************************************************************************/ + +#ifndef OVR_ExceptionHandler_h +#define OVR_ExceptionHandler_h + + +#include "OVR_Types.h" +#include "OVR_String.h" +#include "OVR_Threads.h" +#include "OVR_Atomic.h" +#include "OVR_Nullptr.h" +#include <stdio.h> +#include <time.h> + +#if defined(OVR_OS_WIN32) || defined(OVR_OS_WIN64) + #include <Windows.h> + +#elif defined(OVR_OS_APPLE) + #include <pthread.h> + #include <mach/thread_status.h> + #include <mach/mach_types.h> + + extern "C" void* MachHandlerThreadFunctionStatic(void*); + extern "C" int catch_mach_exception_raise_state_identity_OVR(mach_port_t, mach_port_t, mach_port_t, exception_type_t, mach_exception_data_type_t*, + mach_msg_type_number_t, int*, thread_state_t, mach_msg_type_number_t, thread_state_t, mach_msg_type_number_t*); +#elif defined(OVR_OS_LINUX) + #include <pthread.h> +#endif + + +OVR_DISABLE_MSVC_WARNING(4351) // new behavior: elements of array will be default initialized + + +namespace OVR { + + // Thread identifiers + //typedef void* ThreadHandle; // Already defined by OVR Threads. Same as Windows thread handle, Unix pthread_t. + //typedef void* ThreadId; // Already defined by OVR Threads. Used by Windows as DWORD thread id, by Unix as pthread_t. + typedef uintptr_t ThreadSysId; // System thread identifier. Used by Windows the same as ThreadId (DWORD), thread_act_t on Mac/BSD, lwp id on Linux. + + // Thread constants + // To do: Move to OVR Threads + #define OVR_THREADHANDLE_INVALID ((ThreadHandle*)nullptr) + #define OVR_THREADID_INVALID ((ThreadId*)nullptr) + #define OVR_THREADSYSID_INVALID ((uintptr_t)0) + + OVR::ThreadSysId ConvertThreadHandleToThreadSysId(OVR::ThreadHandle threadHandle); + OVR::ThreadHandle ConvertThreadSysIdToThreadHandle(OVR::ThreadSysId threadSysId); // The returned handle must be freed with FreeThreadHandle. + void FreeThreadHandle(OVR::ThreadHandle threadHandle); // Frees the handle returned by ConvertThreadSysIdToThreadHandle. + OVR::ThreadSysId GetCurrentThreadSysId(); + + // CPUContext + #if defined(OVR_OS_MS) + typedef CONTEXT CPUContext; + #elif defined(OVR_OS_MAC) + struct CPUContext + { + x86_thread_state_t threadState; // This works for both x86 and x64. + x86_float_state_t floatState; + x86_debug_state_t debugState; + x86_avx_state_t avxState; + x86_exception_state exceptionState; + + CPUContext() { memset(this, 0, sizeof(CPUContext)); } + }; + #elif defined(OVR_OS_LINUX) + typedef int CPUContext; // To do. + #endif + + + // Tells if the current process appears to be running under a debugger. Does not attempt to + // detect the case of sleath debuggers (malware-related for example). + bool OVRIsDebuggerPresent(); + + // Exits the process with the given exit code. + #if !defined(OVR_NORETURN) + #if defined(OVR_CC_MSVC) + #define OVR_NORETURN __declspec(noreturn) + #else + #define OVR_NORETURN __attribute__((noreturn)) + #endif + #endif + OVR_NORETURN void ExitProcess(intptr_t processReturnValue); + + // Returns the instruction pointer of the caller for the position right after the call. + OVR_NO_INLINE void GetInstructionPointer(void*& pInstruction); + + // Returns the stack base and limit addresses for the given thread, or for the current thread if the threadHandle is default. + // The stack limit is a value less than the stack base on most platforms, as stacks usually grow downward. + // Some platforms (e.g. Microsoft) have dynamically resizing stacks, in which case the stack limit reflects the current limit. + void GetThreadStackBounds(void*& pStackBase, void*& pStackLimit, ThreadHandle threadHandle = OVR_THREADHANDLE_INVALID); + + + // Equates to VirtualAlloc/VirtualFree on Windows, mmap/munmap on Unix. + // These are useful for when you need system-supplied memory pages. + // These are also useful for when you need to allocate memory in a way + // that doesn't affect the application heap. + void* SafeMMapAlloc(size_t size); + void SafeMMapFree(const void* memory, size_t size); + + + // OVR_MAX_PATH + // Max file path length (for most uses). + // To do: move this to OVR_File. + #if defined(OVR_OS_MS) // http://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx + #define OVR_MAX_PATH 260 // Windows can use paths longer than this in some cases (network paths, UNC paths). + #else + #define OVR_MAX_PATH 1024 // This isn't a strict limit on all Unix-based platforms. + #endif + + + // ModuleHandle + #if defined(OVR_OS_MS) + typedef void* ModuleHandle; // from LoadLibrary() + #elif defined(OVR_OS_APPLE) || defined(OVR_OS_UNIX) + typedef void* ModuleHandle; // from dlopen() + #endif + + #define OVR_MODULEHANDLE_INVALID ((ModuleHandle*)nullptr) + + + + // Module info constants + static const ModuleHandle kMIHandleInvalid = OVR_MODULEHANDLE_INVALID; + static const uint64_t kMIAddressInvalid = 0xffffffffffffffffull; + static const uint64_t kMISizeInvalid = 0xffffffffffffffffull; + static const int32_t kMILineNumberInvalid = -1; + static const int32_t kMIFunctionOffsetInvalid = -1; + static const uint64_t kMIBaseAddressInvalid = 0xffffffffffffffffull; + static const uint64_t kMIBaseAddressUnspecified = 0xffffffffffffffffull; + + struct ModuleInfo + { + ModuleHandle handle; + uint64_t baseAddress; // The actual runtime base address of the module. May be different from the base address specified in the debug symbol file. + uint64_t size; + char filePath[OVR_MAX_PATH]; + char name[32]; + char type[8]; // Unix-specific. e.g. __TEXT + char permissions[8]; // Unix specific. e.g. "drwxr-xr-x" + + ModuleInfo() : handle(kMIHandleInvalid), baseAddress(kMIBaseAddressInvalid), size(0), filePath(), name(){} + }; + + + // Refers to symbol info for an instruction address. + // Info includes function name, source code file/line, and source code itself. + struct SymbolInfo + { + uint64_t address; + uint64_t size; + const ModuleInfo* pModuleInfo; + char filePath[OVR_MAX_PATH]; + int32_t fileLineNumber; + char function[128]; // This is a fixed size because we need to use it during application exceptions. + int32_t functionOffset; + char sourceCode[1024]; // This is a string representing the code itself and not a file path to the code. + + SymbolInfo() : address(kMIAddressInvalid), size(kMISizeInvalid), pModuleInfo(nullptr), filePath(), + fileLineNumber(kMILineNumberInvalid), function(), functionOffset(kMIFunctionOffsetInvalid), sourceCode() {} + }; + + + // Implements support for reading thread lists, module lists, backtraces, and backtrace symbols. + class SymbolLookup + { + public: + SymbolLookup(); + ~SymbolLookup(); + + void AddSourceCodeDirectory(const char* pDirectory); + + bool Initialize(); + void Shutdown(); + + // Should be disabled when within an exception handler. + void EnableMemoryAllocation(bool enabled); + + // Retrieves the backtrace (call stack) of the given thread. There may be some per-platform restrictions on this. + // Returns the number written, which will be <= addressArrayCapacity. + // This may not work on some platforms unless stack frames are enabled. + // For Microsoft platforms the platformThreadContext is CONTEXT*. + // For Apple platforms the platformThreadContext is x86_thread_state_t* or arm_thread_state_t*. + // If threadSysIdHelp is non-zero, it may be used by the implementation to help produce a better backtrace. + size_t GetBacktrace(void* addressArray[], size_t addressArrayCapacity, size_t skipCount = 0, void* platformThreadContext = nullptr, OVR::ThreadSysId threadSysIdHelp = OVR_THREADSYSID_INVALID); + + // Retrieves the backtrace for the given ThreadHandle. + // Returns the number written, which will be <= addressArrayCapacity. + size_t GetBacktraceFromThreadHandle(void* addressArray[], size_t addressArrayCapacity, size_t skipCount = 0, OVR::ThreadHandle threadHandle = OVR_THREADHANDLE_INVALID); + + // Retrieves the backtrace for the given ThreadSysId. + // Returns the number written, which will be <= addressArrayCapacity. + size_t GetBacktraceFromThreadSysId(void* addressArray[], size_t addressArrayCapacity, size_t skipCount = 0, OVR::ThreadSysId threadSysId = OVR_THREADSYSID_INVALID); + + // Gets a list of the modules (e.g. DLLs) present in the current process. + // Writes as many ModuleInfos as possible to pModuleInfoArray. + // Returns the required count of ModuleInfos, which will be > moduleInfoArrayCapacity if the capacity needs to be larger. + size_t GetModuleInfoArray(ModuleInfo* pModuleInfoArray, size_t moduleInfoArrayCapacity); + + // Retrieves a list of the current threads. Unless the process is paused the list is volatile. + // Returns the required capacity, which may be larger than threadArrayCapacity. + // Either array can be NULL to specify that it's not written to. + // For Windows the caller needs to CloseHandle the returned ThreadHandles. This can be done by calling DoneThreadList. + size_t GetThreadList(ThreadHandle* threadHandleArray, ThreadSysId* threadSysIdArray, size_t threadArrayCapacity); + + // Frees any references to thread handles or ids returned by GetThreadList; + void DoneThreadList(ThreadHandle* threadHandleArray, ThreadSysId* threadSysIdArray, size_t threadArrayCount); + + // Writes a given thread's callstack with symbols to the given output. + // It may not be safe to call this from an exception handler, as sOutput allocates memory. + bool ReportThreadCallstack(OVR::String& sOutput, size_t skipCount = 0, ThreadSysId threadSysId = OVR_THREADSYSID_INVALID); + + // Writes all thread's callstacks with symbols to the given output. + // It may not be safe to call this from an exception handler, as sOutput allocates memory. + bool ReportThreadCallstacks(OVR::String& sOutput, size_t skipCount = 0); + + // Retrieves symbol info for the given address. + bool LookupSymbol(uint64_t address, SymbolInfo& symbolInfo); + bool LookupSymbols(uint64_t* addressArray, SymbolInfo* pSymbolInfoArray, size_t arraySize); + + const ModuleInfo* GetModuleInfoForAddress(uint64_t address); // The returned ModuleInfo points to an internal structure. + + protected: + bool RefreshModuleList(); + + protected: + bool initialized; + bool allowMemoryAllocation; // True by default. If true then we allow allocating memory (and as a result provide less information). This is useful for when in an exception handler. + bool moduleListUpdated; + ModuleInfo moduleInfoArray[96]; // Cached list of modules we use. This is a fixed size because we need to use it during application exceptions. + size_t moduleInfoArraySize; + }; + + + + // ExceptionInfo + // We need to be careful to avoid data types that can allocate memory while we are + // handling an exception, as the memory system may be corrupted at that point in time. + struct ExceptionInfo + { + tm time; // GM time. + time_t timeVal; // GM time_t (seconds since 1970). + void* backtrace[64]; + size_t backtraceCount; + ThreadHandle threadHandle; // + ThreadSysId threadSysId; // + char threadName[32]; // Cannot be an allocating String object. + void* pExceptionInstructionAddress; + void* pExceptionMemoryAddress; + CPUContext cpuContext; + char exceptionDescription[1024]; // Cannot be an allocating String object. + SymbolInfo symbolInfo; // SymbolInfo for the exception location. + + #if defined(OVR_OS_MS) + EXCEPTION_RECORD exceptionRecord; // This is a Windows SDK struct. + #elif defined(OVR_OS_APPLE) + uint64_t exceptionType; // e.g. EXC_BAD_INSTRUCTION, EXC_BAD_ACCESS, etc. + uint32_t cpuExceptionId; // The x86/x64 CPU trap id. + uint32_t cpuExceptionIdError; // The x86/x64 CPU trap id extra info. + int64_t machExceptionDetail[4]; // Kernel exception code info. + int machExceptionDetailCount; // Count of valid entries. + #endif + + ExceptionInfo(); + }; + + + // Implments support for asynchronous exception handling and basic exception report generation. + // If you are implementing exception handling for a commercial application and want auto-uploading + // functionality you may want to consider using something like Google Breakpad. This exception handler + // is for in-application debug/diagnostic services, though it can write a report that has similar + // information to Breakpad or OS-provided reports such as Apple .crash files. + // + // Example usage: + // ExceptionHandler exceptionHandler; + // + // int main(int, char**) + // { + // exceptionHandler.Enable(true); + // exceptionHandler.SetExceptionListener(pSomeListener, 0); // Optional listener hook. + // } + // + class ExceptionHandler + { + public: + ExceptionHandler(); + ~ExceptionHandler(); + + bool Enable(bool enable); + + // Some report info can be considered private information of the user, such as the current process list, + // computer name, IP address or other identifying info, etc. We should not report this information for + // external users unless they agree to this. + void EnableReportPrivacy(bool enable); + + struct ExceptionListener + { + virtual ~ExceptionListener(){} + virtual int HandleException(uintptr_t userValue, ExceptionHandler* pExceptionHandler, ExceptionInfo* pExceptionInfo, const char* reportFilePath) = 0; + }; + + void SetExceptionListener(ExceptionListener* pExceptionListener, uintptr_t userValue); + + // What we do after handling the exception. + enum ExceptionResponse + { + kERContinue, // Continue execution. Will result in the exception being re-generated unless the application has fixed the cause. Similar to Windows EXCEPTION_CONTINUE_EXECUTION. + kERHandle, // Causes the OS to handle the exception as it normally would. Similar to Windows EXCEPTION_EXECUTE_HANDLER. + kERTerminate, // Exit the application. + kERThrow, // Re-throw the exception. Other handlers may catch it. Similar to Windows EXCEPTION_CONTINUE_SEARCH. + kERDefault // Usually set to kERTerminate. + }; + + void SetExceptionResponse(ExceptionResponse er) + { exceptionResponse = er; } + + // Allws you to add an arbitrary description of the current application, which will be added to exception reports. + void SetAppDescription(const char* appDescription); + + // If the report path has a "%s" in its name, then assume the path is a sprintf format and write it + // with the %s specified as a date/time string. + // The report path can be "default" to signify that you want to use the default user location. + // Example usage: + // handler.SetExceptionPaths("/Users/Current/Exceptions/Exception %s.txt"); + void SetExceptionPaths(const char* exceptionReportPath, const char* exceptionMinidumpPath = nullptr); + + // Allows you to specify base directories for code paths, which can be used to associate exception addresses to lines + // of code as opposed to just file names and line numbers, or function names plus binary offsets. + void SetCodeBaseDirectoryPaths(const char* codeBaseDirectoryPathArray[], size_t codeBaseDirectoryPathCount); + + // Given an exception report at a given file path, returns a string suitable for displaying in a message + // box or similar user interface during the handling of an exception. The returned string must be passed + // to FreeMessageBoxText when complete. + static const char* GetExceptionUIText(const char* exceptionReportPath); + static void FreeExceptionUIText(const char* messageBoxText); + + protected: + void WriteExceptionDescription(); + void WriteReport(); + void WriteReportLine(const char* pLine); + void WriteReportLineF(const char* format, ...); + void WriteThreadCallstack(ThreadHandle threadHandle, ThreadSysId threadSysId, const char* additionalInfo); + void WriteMiniDump(); + + // Runtime constants + bool enabled; + bool reportPrivacyEnabled; // Defaults to true. + ExceptionResponse exceptionResponse; // Defaults to kERHandle + ExceptionListener* exceptionListener; + uintptr_t exceptionListenerUserValue; + String appDescription; + String codeBasePathArray[6]; // 6 is arbitrary. + char reportFilePath[OVR_MAX_PATH];// May be an encoded path, in that it has "%s" in it or is named "default". See reporFiletPathActual for the runtime actual report path. + int miniDumpFlags; + char miniDumpFilePath[OVR_MAX_PATH]; + FILE* file; // Can/should we use OVR Files for this? + char scratchBuffer[4096]; + SymbolLookup symbolLookup; + + // Runtime variables + bool exceptionOccurred; + OVR::AtomicInt<uint32_t> handlingBusy; + char reportFilePathActual[OVR_MAX_PATH]; + char minidumpFilePathActual[OVR_MAX_PATH]; + int terminateReturnValue; + ExceptionInfo exceptionInfo; + + #if defined(OVR_OS_MS) + void* vectoredHandle; + LPTOP_LEVEL_EXCEPTION_FILTER previousFilter; + LPEXCEPTION_POINTERS pExceptionPointers; + + friend LONG WINAPI Win32ExceptionFilter(LPEXCEPTION_POINTERS pExceptionPointers); + LONG ExceptionFilter(LPEXCEPTION_POINTERS pExceptionPointers); + + #elif defined(OVR_OS_APPLE) + struct SavedExceptionPorts + { + SavedExceptionPorts() : count(0) { memset(this, 0, sizeof(SavedExceptionPorts)); } + + mach_msg_type_number_t count; + exception_mask_t masks[6]; + exception_handler_t ports[6]; + exception_behavior_t behaviors[6]; + thread_state_flavor_t flavors[6]; + }; + + friend void* ::MachHandlerThreadFunctionStatic(void*); + friend int ::catch_mach_exception_raise_state_identity_OVR(mach_port_t, mach_port_t, mach_port_t, exception_type_t, + mach_exception_data_type_t*, mach_msg_type_number_t, int*, thread_state_t, + mach_msg_type_number_t, thread_state_t, mach_msg_type_number_t*); + + bool InitMachExceptionHandler(); + void ShutdownMachExceptionHandler(); + void* MachHandlerThreadFunction(); + kern_return_t HandleMachException(mach_port_t port, mach_port_t thread, mach_port_t task, exception_type_t exceptionType, + mach_exception_data_type_t* pExceptionDetail, mach_msg_type_number_t exceptionDetailCount, + int* pFlavor, thread_state_t pOldState, mach_msg_type_number_t oldStateCount, thread_state_t pNewState, + mach_msg_type_number_t* pNewStateCount); + kern_return_t ForwardMachException(mach_port_t thread, mach_port_t task, exception_type_t exceptionType, + mach_exception_data_t pExceptionDetail, mach_msg_type_number_t exceptionDetailCount); + + bool machHandlerInitialized; + mach_port_t machExceptionPort; + SavedExceptionPorts machExceptionPortsSaved; + volatile bool machThreadShouldContinue; + volatile bool machThreadExecuting; + pthread_t machThread; + + #elif defined(OVR_OS_LINUX) + // To do. + #endif + }; + + + // Identifies basic exception types for the CreateException function. + enum CreateExceptionType + { + kCETAccessViolation, // Read or write to inaccessable memory. + kCETAlignment, // Misaligned read or write. + kCETDivideByZero, // Integer divide by zero. + kCETFPU, // Floating point / VPU exception. + kCETIllegalInstruction, // Illegal opcode. + kCETStackCorruption, // Stack frame was corrupted. + kCETStackOverflow, // Stack ran out of space, often due to infinite recursion. + kCETTrap // System/OS trap (system call). + }; + + + // Creates an exception of the given type, primarily for testing. + void CreateException(CreateExceptionType exceptionType); + + + +} // namespace OVR + + +OVR_RESTORE_MSVC_WARNING() + + +#endif // Header include guard |