diff options
Diffstat (limited to 'externals/breakpad/docs/exception_handling.md')
| -rw-r--r-- | externals/breakpad/docs/exception_handling.md | 128 |
1 files changed, 0 insertions, 128 deletions
diff --git a/externals/breakpad/docs/exception_handling.md b/externals/breakpad/docs/exception_handling.md deleted file mode 100644 index e48a52ae2f..0000000000 --- a/externals/breakpad/docs/exception_handling.md +++ /dev/null @@ -1,128 +0,0 @@ -The goal of this document is to give an overview of the exception handling -options in breakpad. - -# Basics - -Exception handling is a mechanism designed to handle the occurrence of -exceptions, special conditions that change the normal flow of program execution. - -`SetUnhandledExceptionFilter` replaces all unhandled exceptions when Breakpad is -enabled. TODO: More on first and second change and vectored v. try/catch. - -There are two main types of exceptions across all platforms: in-process and -out-of-process. - -# In-Process - -In process exception handling is relatively simple since the crashing process -handles crash reporting. It is generally considered unsafe to write a minidump -from a crashed process. For example, key data structures could be corrupted or -the stack on which the exception handler runs could have been overwritten. For -this reason all platforms also support some level of out-of-process exception -handling. - -## Windows - -In-process exception handling Breakpad creates a 'handler head' that waits -infinitely on a semaphore at start up. When this thread is woken it writes the -minidump and signals to the excepting thread that it may continue. A filter will -tell the OS to kill the process if the minidump is written successfully. -Otherwise it continues. - -# Out-of-Process - -Out-of-process exception handling is more complicated than in-process exception -handling because of the need to set up a separate process that can read the -state of the crashing process. - -## Windows - -Breakpad uses two abstractions around the exception handler to make things work: -`CrashGenerationServer` and `CrashGenerationClient`. The constructor for these -takes a named pipe name. - -During server start up a named pipe and registers callbacks for client -connections are created. The named pipe is used for registration and all IO on -the pipe is done asynchronously. `OnPipeConnected` is called when a client -attempts to connect (call `CreateFile` on the pipe). `OnPipeConnected` does the -state machine transition from `Initial` to `Connecting` and on through -`Reading`, `Reading_Done`, `Writing`, `Writing_Done`, `Reading_ACK`, and -`Disconnecting`. - -When registering callbacks, the client passes in two pointers to pointers: 1. A -pointer to the `EXCEPTION_INFO` pointer 1. A pointer to the `MDRawAssertionInfo` -which handles various non-exception failures like assertions - -The essence of registration is adding a "`ClientInfo`" object that contains -handles used for synchronization with the crashing process to an array -maintained by the server. This is how we can keep track of all the clients on -the system that have registered for minidumps. These handles are: * -`server_died(mutex)` * `dump_requested(Event)` * `dump_generated(Event)` - -The server registers asynchronous waits on these events with the `ClientInfo` -object as the callback context. When the `dump_requested` event is set by the -client, the `OnDumpRequested()` callback is called. The server uses the handles -inside `ClientInfo` to communicate with the child process. Once the child sets -the event, it waits for two objects: 1. the `dump_generated` event 1. the -`server_died` mutex - -In the end handles are "duped" into the client process, and the clients use -`SetEvent` to request events, wait on the other event, or the `server_died` -mutex. - -## Linux - -### Current Status - -As of July 2011, Linux had a minidump generator that is not entirely -out-of-process. The minidump was generated from a separate process, but one that -shared an address space, file descriptors, signal handles and much else with the -crashing process. It worked by using the `clone()` system call to duplicate the -crashing process, and then uses `ptrace()` and the `/proc` file system to -retrieve the information required to write the minidump. Since then Breakpad has -updated Linux exception handling to provide more benefits of out-of-process -report generation. - -### Proposed Design - -#### Overview - -Breakpad would use a per-user daemon to write out a minidump that does not have, -interact with or depend on the crashing process. We don't want to start a new -separate process every time a user launches a Breakpad-enabled process. Doing -one daemon per machine is unacceptable for security concerns around one user -being able to initiate a minidump generation for another user's process. - -#### Client/Server Communication - -On Breakpad initialization in a process, the initializer would check if the -daemon is running and, if not, start it. The race condition between the check -and the initialization is not a problem because multiple daemons can check if -the IPC endpoint already exists and if a server is listening. Even if multiple -copies of the daemon try to `bind()` the filesystem to name the socket, all but -one will fail and can terminate. - -This point is relevant for error handling conditions. Linux does not clean the -file system representation of a UNIX domain socket even if both endpoints -terminate, so checking for existence is not strong enough. However checking the -process list or sending a ping on the socket can handle this. - -Breakpad uses UNIX domain sockets since they support full duplex communication -(unlike Windows, named pipes on Linux are half) and the kernal automatically -creates a private channel between the client and server once the client calls -`connect()`. - -#### Minidump Generation - -Breakpad could use the current system with `ptrace()` and `/proc` within the -daemon executable. - -Overall the operations look like: 1. Signal from OS indicating crash 1. Signal -Handler suspends all threads except itself 1. Signal Handler sends -`CRASH_DUMP_REQUEST` message to server and waits for response 1. Server inspects -1. Minidump is asynchronously written to disk by the server 1. Server responds -indicating inspection is done - -## Mac OSX - -Out-of-process exception handling is fully supported on Mac. |