1 // Copyright (c) 2010 Google Inc. 2 // All rights reserved. 3 // 4 // Redistribution and use in source and binary forms, with or without 5 // modification, are permitted provided that the following conditions are 6 // met: 7 // 8 // * Redistributions of source code must retain the above copyright 9 // notice, this list of conditions and the following disclaimer. 10 // * Redistributions in binary form must reproduce the above 11 // copyright notice, this list of conditions and the following disclaimer 12 // in the documentation and/or other materials provided with the 13 // distribution. 14 // * Neither the name of Google Inc. nor the names of its 15 // contributors may be used to endorse or promote products derived from 16 // this software without specific prior written permission. 17 // 18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30 #ifndef CLIENT_LINUX_HANDLER_EXCEPTION_HANDLER_H_ 31 #define CLIENT_LINUX_HANDLER_EXCEPTION_HANDLER_H_ 32 33 #include <signal.h> 34 #include <stdint.h> 35 #include <stdio.h> 36 #include <sys/ucontext.h> 37 38 #include <string> 39 40 #include "linux/crash_generation/crash_generation_client.h" 41 #include "linux/handler/minidump_descriptor.h" 42 #include "linux/minidump_writer/minidump_writer.h" 43 #include "common/scoped_ptr.h" 44 #include "common/using_std_string.h" 45 #include "google_breakpad/common/minidump_format.h" 46 47 #ifdef MOZ_PHC 48 #include "PHC.h" 49 #else 50 namespace mozilla { namespace phc { class AddrInfo {}; } } 51 #endif 52 53 namespace google_breakpad { 54 55 // ExceptionHandler 56 // 57 // ExceptionHandler can write a minidump file when an exception occurs, 58 // or when WriteMinidump() is called explicitly by your program. 59 // 60 // To have the exception handler write minidumps when an uncaught exception 61 // (crash) occurs, you should create an instance early in the execution 62 // of your program, and keep it around for the entire time you want to 63 // have crash handling active (typically, until shutdown). 64 // (NOTE): There should be only be one this kind of exception handler 65 // object per process. 66 // 67 // If you want to write minidumps without installing the exception handler, 68 // you can create an ExceptionHandler with install_handler set to false, 69 // then call WriteMinidump. You can also use this technique if you want to 70 // use different minidump callbacks for different call sites. 71 // 72 // In either case, a callback function is called when a minidump is written, 73 // which receives the full path or file descriptor of the minidump. The 74 // caller can collect and write additional application state to that minidump, 75 // and launch an external crash-reporting application. 76 // 77 // Caller should try to make the callbacks as crash-friendly as possible, 78 // it should avoid use heap memory allocation as much as possible. 79 80 class ExceptionHandler { 81 public: 82 // A callback function to run before Breakpad performs any substantial 83 // processing of an exception. A FilterCallback is called before writing 84 // a minidump. |context| is the parameter supplied by the user as 85 // callback_context when the handler was created. 86 // 87 // If a FilterCallback returns true, Breakpad will continue processing, 88 // attempting to write a minidump. If a FilterCallback returns false, 89 // Breakpad will immediately report the exception as unhandled without 90 // writing a minidump, allowing another handler the opportunity to handle it. 91 typedef bool (*FilterCallback)(void *context); 92 93 // A callback function to run after the minidump has been written. 94 // |descriptor| contains the file descriptor or file path containing the 95 // minidump. |context| is the parameter supplied by the user as 96 // callback_context when the handler was created. |succeeded| indicates 97 // whether a minidump file was successfully written. 98 // 99 // If an exception occurred and the callback returns true, Breakpad will 100 // treat the exception as fully-handled, suppressing any other handlers from 101 // being notified of the exception. If the callback returns false, Breakpad 102 // will treat the exception as unhandled, and allow another handler to handle 103 // it. If there are no other handlers, Breakpad will report the exception to 104 // the system as unhandled, allowing a debugger or native crash dialog the 105 // opportunity to handle the exception. Most callback implementations 106 // should normally return the value of |succeeded|, or when they wish to 107 // not report an exception of handled, false. Callbacks will rarely want to 108 // return true directly (unless |succeeded| is true). 109 typedef bool (*MinidumpCallback)(const MinidumpDescriptor& descriptor, 110 void* context, 111 const mozilla::phc::AddrInfo* addr_info, 112 bool succeeded); 113 114 // In certain cases, a user may wish to handle the generation of the minidump 115 // themselves. In this case, they can install a handler callback which is 116 // called when a crash has occurred. If this function returns true, no other 117 // processing of occurs and the process will shortly be crashed. If this 118 // returns false, the normal processing continues. 119 typedef bool (*HandlerCallback)(const void* crash_context, 120 size_t crash_context_size, 121 void* context); 122 123 // Creates a new ExceptionHandler instance to handle writing minidumps. 124 // Before writing a minidump, the optional |filter| callback will be called. 125 // Its return value determines whether or not Breakpad should write a 126 // minidump. The minidump content will be written to the file path or file 127 // descriptor from |descriptor|, and the optional |callback| is called after 128 // writing the dump file, as described above. 129 // If install_handler is true, then a minidump will be written whenever 130 // an unhandled exception occurs. If it is false, minidumps will only 131 // be written when WriteMinidump is called. 132 // If |server_fd| is valid, the minidump is generated out-of-process. If it 133 // is -1, in-process generation will always be used. 134 ExceptionHandler(const MinidumpDescriptor& descriptor, 135 FilterCallback filter, 136 MinidumpCallback callback, 137 void* callback_context, 138 bool install_handler, 139 const int server_fd); 140 ~ExceptionHandler(); 141 minidump_descriptor()142 const MinidumpDescriptor& minidump_descriptor() const { 143 return minidump_descriptor_; 144 } 145 set_minidump_descriptor(const MinidumpDescriptor & descriptor)146 void set_minidump_descriptor(const MinidumpDescriptor& descriptor) { 147 minidump_descriptor_ = descriptor; 148 } 149 set_crash_handler(HandlerCallback callback)150 void set_crash_handler(HandlerCallback callback) { 151 crash_handler_ = callback; 152 } 153 set_crash_generation_client(CrashGenerationClient * client)154 void set_crash_generation_client(CrashGenerationClient* client) { 155 crash_generation_client_.reset(client); 156 } 157 158 // Writes a minidump immediately. This can be used to capture the execution 159 // state independently of a crash. 160 // Returns true on success. 161 // If the ExceptionHandler has been created with a path, a new file is 162 // generated for each minidump. The file path can be retrieved in the 163 // MinidumpDescriptor passed to the MinidumpCallback or by accessing the 164 // MinidumpDescriptor directly from the ExceptionHandler (with 165 // minidump_descriptor()). 166 // If the ExceptionHandler has been created with a file descriptor, the file 167 // descriptor is repositioned to its beginning and the previous generated 168 // minidump is overwritten. 169 // Note that this method is not supposed to be called from a compromised 170 // context as it uses the heap. 171 bool WriteMinidump(); 172 173 // Convenience form of WriteMinidump which does not require an 174 // ExceptionHandler instance. 175 static bool WriteMinidump(const string& dump_path, 176 MinidumpCallback callback, 177 void* callback_context); 178 179 // Write a minidump of |child| immediately. This can be used to 180 // capture the execution state of |child| independently of a crash. 181 // Pass a meaningful |child_blamed_thread| to make that thread in 182 // the child process the one from which a crash signature is 183 // extracted. 184 // 185 // WARNING: the return of this function *must* happen before 186 // the code that will eventually reap |child| executes. 187 // Otherwise there's a pernicious race condition in which |child| 188 // exits, is reaped, another process created with its pid, then that 189 // new process dumped. 190 static bool WriteMinidumpForChild(pid_t child, 191 pid_t child_blamed_thread, 192 const string& dump_path, 193 MinidumpCallback callback, 194 void* callback_context); 195 196 // This structure is passed to minidump_writer.h:WriteMinidump via an opaque 197 // blob. It shouldn't be needed in any user code. 198 struct CrashContext { 199 siginfo_t siginfo; 200 pid_t tid; // the crashing thread. 201 ucontext_t context; 202 #if !defined(__ARM_EABI__) && !defined(__mips__) 203 // #ifdef this out because FP state is not part of user ABI for Linux ARM. 204 // In case of MIPS Linux FP state is already part of ucontext_t so 205 // 'float_state' is not required. 206 fpstate_t float_state; 207 #endif 208 }; 209 210 // Returns whether out-of-process dump generation is used or not. IsOutOfProcess()211 bool IsOutOfProcess() const { 212 return crash_generation_client_.get() != NULL; 213 } 214 215 // Add information about a memory mapping. This can be used if 216 // a custom library loader is used that maps things in a way 217 // that the linux dumper can't handle by reading the maps file. 218 void AddMappingInfo(const string& name, 219 const wasteful_vector<uint8_t>& identifier, 220 uintptr_t start_address, 221 size_t mapping_size, 222 size_t file_offset); 223 224 // Register a block of memory of length bytes starting at address ptr 225 // to be copied to the minidump when a crash happens. 226 void RegisterAppMemory(void* ptr, size_t length); 227 228 // Unregister a block of memory that was registered with RegisterAppMemory. 229 void UnregisterAppMemory(void* ptr); 230 231 // Force signal handling for the specified signal. 232 bool SimulateSignalDelivery(int sig); 233 234 // Report a crash signal from an SA_SIGINFO signal handler. 235 bool HandleSignal(int sig, siginfo_t* info, void* uc); 236 237 private: 238 // Save the old signal handlers and install new ones. 239 static bool InstallHandlersLocked(); 240 // Restore the old signal handlers. 241 static void RestoreHandlersLocked(); 242 243 void PreresolveSymbols(); 244 bool GenerateDump(CrashContext *context, 245 const mozilla::phc::AddrInfo* addr_info); 246 void SendContinueSignalToChild(); 247 void WaitForContinueSignal(); 248 249 static void SignalHandler(int sig, siginfo_t* info, void* uc); 250 static int ThreadEntry(void* arg); 251 bool DoDump(pid_t crashing_process, const void* context, 252 size_t context_size); 253 254 const FilterCallback filter_; 255 const MinidumpCallback callback_; 256 void* const callback_context_; 257 258 scoped_ptr<CrashGenerationClient> crash_generation_client_; 259 260 MinidumpDescriptor minidump_descriptor_; 261 262 // Must be volatile. The compiler is unaware of the code which runs in 263 // the signal handler which reads this variable. Without volatile the 264 // compiler is free to optimise away writes to this variable which it 265 // believes are never read. 266 volatile HandlerCallback crash_handler_; 267 268 // We need to explicitly enable ptrace of parent processes on some 269 // kernels, but we need to know the PID of the cloned process before we 270 // can do this. We create a pipe which we can use to block the 271 // cloned process after creating it, until we have explicitly enabled 272 // ptrace. This is used to store the file descriptors for the pipe 273 int fdes[2] = {-1, -1}; 274 275 // Callers can add extra info about mappings for cases where the 276 // dumper code cannot extract enough information from /proc/<pid>/maps. 277 MappingList mapping_list_; 278 279 // Callers can request additional memory regions to be included in 280 // the dump. 281 AppMemoryList app_memory_list_; 282 }; 283 284 typedef bool (*FirstChanceHandler)(int, siginfo_t*, void*); 285 void SetFirstChanceExceptionHandler(FirstChanceHandler callback); 286 287 } // namespace google_breakpad 288 289 #endif // CLIENT_LINUX_HANDLER_EXCEPTION_HANDLER_H_ 290