Crash and signals handler in Apache Harmony

Apache Harmony Crash and signals handler (CH) is used for a platform-independent +handling of runtime errors and exceptions in a program. CH may be used as a portable +signal abstraction layer, but its main purpose is to provide a facility for +post mortem analysis of managed runtime applications that use just-in-time +compilers (JITs) to generate user application +executable code. This makes crash handling library of Apache Harmony unique +among other facilities because they cannot analyze the native stack of compiled +code. An application that does not utilize runtime compilers can use this +library as well, such an application would provide no information +about compiled methods to crash handler and therefore it would analyze only its +native code.

1. Terminology

CH – acronym used to identify the component crash and signals handling of Apache Harmony.

Signal – an event delivered by the operating system to an application under +certain conditions. Signal is a name traditionally used on UNIX systems. On +Windows* OS, such events are called exceptions. In this document, the term signal is used to define both signal and +exception depending on the target platform, unless stated otherwise.

2. How the crash handler works

Upon its initialization, the crash handler library registers to receive a +big number of signals (exceptions on Windows), all of which are usually considered +fatal for most applications. CH allows the application to make a decision +whether the crash sequence should be started when a signal is delivered to the +application. To filter such events, the application can register callbacks for +each signal type that it is interested in, so the execution flow follows one of +these paths:

+If a +callback returns a non-zero value, the signal is considered handled and the +application does not crash. Instead, CH transfers execution control to the +register context that the application may update in order not to receive the +signal again. +
+If a callback +returns zero, the signal is considered fatal, and a crash sequence is started.

CH +outputs information about the location of the crash based on the crash +information flags that the application set. These flags control the amount of +information that CH prints. In addition, the application may specify its own +callbacks to dump some application specific information, e.g. its data tables.

The following sequence describes signal handling in detail.

+An +operating system delivers a signal to the application. The signal is handled by +the crash handler's registered signal handler.
+CH exits +the signal handler context, because the OS signal handler context may be unsafe +for performing certain operations, such as synchronization. To exit the +context, CH: +
1. Modifies the system-specific register context.
2. Saves the original register context at the position pointed by stack pointer register +from the crash register context for future use.
3. Exits the signal handler.
CH checks +whether the application has registered a callback for the type of the received +signal. Callbacks must be thread-safe, because signals may occur simultaneously +in different threads. +
1. +If the signal type has no registered callback, CH considers the signal fatal and initiates +the crash sequence.
2. +If the signal type has a registered callback, CH calls the callback to determine +whether such signal is fatal for the application. +
  1. +If the application +handles the signal, CH transfers execution control to the registers that +application specified in its callback.
  2. If the application +doesn't handle the signal, CH considers the signal fatal and initiates the crash +sequence.
+CH locks a +global synchronization lock, so that no other crashes can be processed. If the application +crashes in a different thread, that crash is ignored.
+CH goes +through the list of flags and outputs the information about the crashed +application based on their values. The application may change these flags at +any moment; e.g. if some types of signals require a special type of output. +When CH prints the stack trace for the crash point, it may use the function +specified by the application to iterate over the compiled code. See section 3.2 +for its description.
+After all +information is dumped, CH calls application crash callbacks one by one. +Different application components may register their crash actions to dump their +specific data. If a crash happens while dumping such tables, the next +application crash callback is called (this functionality is in development). Because +these kinds of callbacks are called in a synchronized region, they don't have +to be thread-safe.
+CH unregisters signal handlers previously registered to define +default OS specific action depending on the signal that was received by the +application.
+CH +transfers control to the original register's context. If the application +previously set the CH flag to call the debugger, CH unlocks the global crash +lock and calls the platform-specific debugger for analyzing the crash at the +point where the original signal occurred. If some other threads also crashed +and are waiting on the crash handler lock, the behavior depends on OS +processing for multiple crashes in different threads.

3. Using crash and signals handler from an +application

The crash handler API is defined in port_crash_handler.h +and port_frame_info.h header files. The API consists +of 2 parts, initialization and output management.

3.1 +Initialization

Initialization is the main part of the CH library. It is done with a +function port_init_crash_handler(). To process +signals in a specific way, the application must supply an array of signal +handling callbacks (see section 2) and a pointer to the stack iteration +function, which performs lookup through compiled methods and returns method +names and other relevant information (see section 3.2 for details).

3.2 +Stack +iteration callback

To iterate over compiled methods, CH uses the application defined +function. It has quite complicated semantics, for exact specification see port_frame_info.h header file.

When a signal is considered fatal, CH prints the execution stack for the +crashed thread. For that, CH identifies methods in the stack via the IP +register and finds out whether the crash happened in a compiled method using +stack iteration callback in the following algorithm:

+CH +initializes port_stack_frame_info with zeroes and +calls stack iteration callback.
+If stack +iteration callback returns non-zero value, it means that it requires some +internal state to be allocated in port_stack_frame_info +structure. CH allocates a buffer of requested size, initializes it with zeroes +and continues. +
1. a. +If stack +iteration returns zero, it means that it knows method pointed to by IP in +register context, and it filled up information about it in port_stack_frame_info. +Fields that were filled up by stack iteration callback are printed by CH. +
  Optionally when stack iteration callback returns zero, it updates +register context and internal stack iteration information in port_stack_frame_info to point to a previous method in the +stack. This functionality necessary if application needs to +display a continuous stack of compiled method.
2. +If stack iteration +callback returns -1 it means that register context points to a method not known +by the application as compiled. In this case CH switches to iteration through +native code using its platform depending heuristics. In any case, the +application can return information about the current frame in the port_stack_frame_info structure. If some zeroed fields of +the structure are filled by the application, they are displayed in the stack +dump.
+CH goes +back to step 2 until it reaches the condition that stack iteration callback +returned -1 and native unwinding heuristics is unable to unwind the stack +further (see section 4.2).

3.3 +Output +management

CH has a set of flags that control its output in case of a crash. The application +may specify its own mode of output using the port_crash_handler_set_flags() function. These +flags may be changed at any time to adjust the output of information depending +on the crash that happened. For example, for a failed assertion it is probably +not necessary to print a register context because it gives no useful +information.

Additionally, CH allows the application to dump additional information +in case of a crash. The application may add multiple callbacks using the port_crash_handler_add_action() function. Each application component may then dump its +internal data separately.

3.4 +Shutdown

When the application shuts down, it may unregister +CH so that all signal handlers are assigned their default values. This option +is useful at the late stages of shutdown when the application cannot handle +crashes and output any application-specific data (e.g. all tables are already +de-allocated). To unregister the crash handler, +application may use the port_shutdown_crash_handler() +function.

4. Implementation notes

The crash handler has some design decisions that may affect its usage in +specific scenarios. This section describes them.

4.1 +Stack +overflow handling

Application callbacks for the signals are called when the OS signal +handler has already exited. When CH starts processing the signal, some signal +information needed is already lost. Because storing this information for every +received signal may reduce the application performance, in case of a crash, CH +sets thread-local indicators and continues execution in the original register +context to catch the same signal again and perform required crash processing +inside the OS signal handler. This technique does not work for the stack +overflow exception on Windows, because access to the protected memory region which +caused the signal is restored automatically in OS signal delivery. The problem +affects creating minidumps on Windows and displaying a message box for calling +a debugger. This limitation can disappear together with fixing HARMONY-5617.

4.2 +Compiled +and native stack

In the previous CH implementation, stack iteration was based on the +compiled stack. Even if native stack unwinding was not done, stack iteration +continued and printed the whole compiled stack even with no native stack +information; the whole compiled stack was printed with or without native stack +information. In the current CH implementation, native stack unwinding takes a +lead in stack iteration. When the current frame cannot be unwound with the application +callback and the native stack unwinding algorithm, the iteration stops, even if +more compiled frames are present.

4.3 +Creating +core dumps on Linux

Core dump is created on Linux when the default signal handler is called +for some signals. When application requests to call the debugger in case of a crash, +the application does not actually crash, but continues execution as a debugged +application. Therefore, when the debugger is called on Linux, core dump is not +generated.

4.4 +Working +with libraries

The Harmony Crash Handler is mostly designed as a crash handler for a +standalone application. There may be problems using it with libraries linked to +another application, which may have its own signal handling routines.

4.5 +Windows +compatibility

On Windows, CH uses VEH (Vectored Exception Handler) for centralized signals +catching. This functionality is unavailable on Windows versions earlier than +Windows XP/Windows Server 2003, so CH cannot be used on Windows 2000 and +earlier.

+ + +