1// -*- mode: C++ -*- 2 3// Copyright (c) 2010, Google Inc. 4// All rights reserved. 5// 6// Redistribution and use in source and binary forms, with or without 7// modification, are permitted provided that the following conditions are 8// met: 9// 10// * Redistributions of source code must retain the above copyright 11// notice, this list of conditions and the following disclaimer. 12// * Redistributions in binary form must reproduce the above 13// copyright notice, this list of conditions and the following disclaimer 14// in the documentation and/or other materials provided with the 15// distribution. 16// * Neither the name of Google Inc. nor the names of its 17// contributors may be used to endorse or promote products derived from 18// this software without specific prior written permission. 19// 20// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 24// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 26// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 32// Original author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com> 33 34// synth_minidump.h: Interface to SynthMinidump: fake minidump generator. 35// 36// We treat a minidump file as the concatenation of a bunch of 37// test_assembler::Sections. The file header, stream directory, 38// streams, memory regions, strings, and so on --- each is a Section 39// that eventually gets appended to the minidump. Dump, Memory, 40// Context, Thread, and so on all inherit from test_assembler::Section. 41// For example: 42// 43// using google_breakpad::test_assembler::kLittleEndian; 44// using google_breakpad::SynthMinidump::Context; 45// using google_breakpad::SynthMinidump::Dump; 46// using google_breakpad::SynthMinidump::Memory; 47// using google_breakpad::SynthMinidump::Thread; 48// 49// Dump minidump(MD_NORMAL, kLittleEndian); 50// 51// Memory stack1(minidump, 0x569eb0a9); 52// ... build contents of stack1 with test_assembler::Section functions ... 53// 54// MDRawContextX86 x86_context1; 55// x86_context1.context_flags = MD_CONTEXT_X86; 56// x86_context1.eip = 0x7c90eb94; 57// x86_context1.esp = 0x569eb0a9; 58// x86_context1.ebp = x86_context1.esp + something appropriate; 59// Context context1(minidump, x86_context1); 60// 61// Thread thread1(minidump, 0xe4a4821d, stack1, context1); 62// 63// minidump.Add(&stack1); 64// minidump.Add(&context1); 65// minidump.Add(&thread1); 66// minidump.Finish(); 67// 68// string contents; 69// EXPECT_TRUE(minidump.GetContents(&contents)); 70// // contents now holds the bytes of a minidump file 71// 72// Because the test_assembler classes let us write Label references to 73// sections before the Labels' values are known, this gives us 74// flexibility in how we put the dump together: minidump pieces can 75// hold the file offsets of other minidump pieces before the 76// referents' positions have been decided. As long as everything has 77// been placed by the time we call dump.GetContents to obtain the 78// bytes, all the Labels' values will be known, and everything will 79// get patched up appropriately. 80// 81// The dump.Add(thing) functions append THINGS's contents to the 82// minidump, but they also do two other things: 83// 84// - dump.Add(thing) invokes thing->Finish, which tells *thing the 85// offset within the file at which it was placed, and allows *thing 86// to do any final content generation. 87// 88// - If THING is something which should receive an entry in some sort 89// of list or directory, then dump.Add(THING) automatically creates 90// the appropriate directory or list entry. Streams must appear in 91// the stream directory; memory ranges should be listed in the 92// memory list; threads should be placed in the thread list; and so 93// on. 94// 95// By convention, Section subclass constructors that take references 96// to other Sections do not take care of 'Add'ing their arguments to 97// the dump. For example, although the Thread constructor takes 98// references to a Memory and a Context, it does not add them to the 99// dump on the caller's behalf. Rather, the caller is responsible for 100// 'Add'ing every section they create. This allows Sections to be 101// cited from more than one place; for example, Memory ranges are 102// cited both from Thread objects (as their stack contents) and by the 103// memory list stream. 104// 105// If you forget to Add some Section, the Dump::GetContents call will 106// fail, as the test_assembler::Labels used to cite the Section's 107// contents from elsewhere will still be undefined. 108#ifndef PROCESSOR_SYNTH_MINIDUMP_H_ 109#define PROCESSOR_SYNTH_MINIDUMP_H_ 110 111#include <assert.h> 112 113#include <iostream> 114#include <string> 115 116#include "common/test_assembler.h" 117#include "common/using_std_string.h" 118#include "google_breakpad/common/breakpad_types.h" 119#include "google_breakpad/common/minidump_format.h" 120 121namespace google_breakpad { 122 123namespace SynthMinidump { 124 125using test_assembler::Endianness; 126using test_assembler::kBigEndian; 127using test_assembler::kLittleEndian; 128using test_assembler::kUnsetEndian; 129using test_assembler::Label; 130 131class Dump; 132class Memory; 133class String; 134 135// A test_assembler::Section which will be appended to a minidump. 136class Section: public test_assembler::Section { 137 public: 138 explicit Section(const Dump &dump); 139 140 // Append an MDLocationDescriptor referring to this section to SECTION. 141 // If 'this' is NULL, append a descriptor with a zero length and MDRVA. 142 // 143 // (I couldn't find the language in the C++ standard that says that 144 // invoking member functions of a NULL pointer to a class type is 145 // bad, if such language exists. Having this function handle NULL 146 // 'this' is convenient, but if it causes trouble, it's not hard to 147 // do differently.) 148 void CiteLocationIn(test_assembler::Section *section) const; 149 150 // Note that this section's contents are complete, and that it has 151 // been placed in the minidump file at OFFSET. The 'Add' member 152 // functions call the Finish member function of the object being 153 // added for you; if you are 'Add'ing this section, you needn't Finish it. 154 virtual void Finish(const Label &offset) { 155 file_offset_ = offset; size_ = Size(); 156 } 157 158 protected: 159 // This section's size and offset within the minidump file. 160 Label file_offset_, size_; 161}; 162 163// A stream within a minidump file. 'Add'ing a stream to a minidump 164// creates an entry for it in the minidump's stream directory. 165class Stream: public Section { 166 public: 167 // Create a stream of type TYPE. You can append whatever contents 168 // you like to this stream using the test_assembler::Section methods. 169 Stream(const Dump &dump, uint32_t type) : Section(dump), type_(type) { } 170 171 // Append an MDRawDirectory referring to this stream to SECTION. 172 void CiteStreamIn(test_assembler::Section *section) const; 173 174 private: 175 // The type of this stream. 176 uint32_t type_; 177}; 178 179class SystemInfo: public Stream { 180 public: 181 // Create an MD_SYSTEM_INFO_STREAM stream belonging to DUMP holding 182 // an MDRawSystem info structure initialized with the values from 183 // SYSTEM_INFO, except that the csd_version field is replaced with 184 // the file offset of the string CSD_VERSION, which can be 'Add'ed 185 // to the dump at the desired location. 186 // 187 // Remember that you are still responsible for 'Add'ing CSD_VERSION 188 // to the dump yourself. 189 SystemInfo(const Dump &dump, 190 const MDRawSystemInfo &system_info, 191 const String &csd_version); 192 193 // Stock MDRawSystemInfo information and associated strings, for 194 // writing tests. 195 static const MDRawSystemInfo windows_x86; 196 static const string windows_x86_csd_version; 197}; 198 199// An MDString: a string preceded by a 32-bit length. 200class String: public Section { 201 public: 202 String(const Dump &dump, const string &value); 203 204 // Append an MDRVA referring to this string to SECTION. 205 void CiteStringIn(test_assembler::Section *section) const; 206}; 207 208// A range of memory contents. 'Add'ing a memory range to a minidump 209// creates n entry for it in the minidump's memory list. By 210// convention, the 'start', 'Here', and 'Mark' member functions refer 211// to memory addresses. 212class Memory: public Section { 213 public: 214 Memory(const Dump &dump, uint64_t address) 215 : Section(dump), address_(address) { start() = address; } 216 217 // Append an MDMemoryDescriptor referring to this memory range to SECTION. 218 void CiteMemoryIn(test_assembler::Section *section) const; 219 220 private: 221 // The process address from which these memory contents were taken. 222 // Shouldn't this be a Label? 223 uint64_t address_; 224}; 225 226class Context: public Section { 227 public: 228 // Create a context belonging to DUMP whose contents are a copy of CONTEXT. 229 Context(const Dump &dump, const MDRawContextX86 &context); 230 Context(const Dump &dump, const MDRawContextARM &context); 231 Context(const Dump &dump, const MDRawContextMIPS &context); 232 // Add an empty context to the dump. 233 Context(const Dump &dump) : Section(dump) {} 234 // Add constructors for other architectures here. Remember to byteswap. 235}; 236 237class Thread: public Section { 238 public: 239 // Create a thread belonging to DUMP with the given values, citing 240 // STACK and CONTEXT (which you must Add to the dump separately). 241 Thread(const Dump &dump, 242 uint32_t thread_id, 243 const Memory &stack, 244 const Context &context, 245 uint32_t suspend_count = 0, 246 uint32_t priority_class = 0, 247 uint32_t priority = 0, 248 uint64_t teb = 0); 249}; 250 251class Module: public Section { 252 public: 253 // Create a module with the given values. Note that CV_RECORD and 254 // MISC_RECORD can be NULL, in which case the corresponding location 255 // descriptior in the minidump will have a length of zero. 256 Module(const Dump &dump, 257 uint64_t base_of_image, 258 uint32_t size_of_image, 259 const String &name, 260 uint32_t time_date_stamp = 1262805309, 261 uint32_t checksum = 0, 262 const MDVSFixedFileInfo &version_info = Module::stock_version_info, 263 const Section *cv_record = NULL, 264 const Section *misc_record = NULL); 265 266 private: 267 // A standard MDVSFixedFileInfo structure to use as a default for 268 // minidumps. There's no reason to make users write out all this crap 269 // over and over. 270 static const MDVSFixedFileInfo stock_version_info; 271}; 272 273class Exception : public Stream { 274public: 275 Exception(const Dump &dump, 276 const Context &context, 277 uint32_t thread_id = 0, 278 uint32_t exception_code = 0, 279 uint32_t exception_flags = 0, 280 uint64_t exception_address = 0); 281}; 282 283// A list of entries starting with a 32-bit count, like a memory list 284// or a thread list. 285template<typename Element> 286class List: public Stream { 287 public: 288 List(const Dump &dump, uint32_t type) : Stream(dump, type), count_(0) { 289 D32(count_label_); 290 } 291 292 // Add ELEMENT to this list. 293 void Add(Element *element) { 294 element->Finish(file_offset_ + Size()); 295 Append(*element); 296 count_++; 297 } 298 299 // Return true if this List is empty, false otherwise. 300 bool Empty() { return count_ == 0; } 301 302 // Finish up the contents of this section, mark it as having been 303 // placed at OFFSET. 304 virtual void Finish(const Label &offset) { 305 Stream::Finish(offset); 306 count_label_ = count_; 307 } 308 309 private: 310 size_t count_; 311 Label count_label_; 312}; 313 314class Dump: public test_assembler::Section { 315 public: 316 317 // Create a test_assembler::Section containing a minidump file whose 318 // header uses the given values. ENDIANNESS determines the 319 // endianness of the signature; we set this section's default 320 // endianness by this. 321 Dump(uint64_t flags, 322 Endianness endianness = kLittleEndian, 323 uint32_t version = MD_HEADER_VERSION, 324 uint32_t date_time_stamp = 1262805309); 325 326 // The following functions call OBJECT->Finish(), and append the 327 // contents of OBJECT to this minidump. They also record OBJECT in 328 // whatever directory or list is appropriate for its type. The 329 // stream directory, memory list, thread list, and module list are 330 // accumulated this way. 331 Dump &Add(SynthMinidump::Section *object); // simply append data 332 Dump &Add(Stream *object); // append, record in stream directory 333 Dump &Add(Memory *object); // append, record in memory list 334 Dump &Add(Thread *object); // append, record in thread list 335 Dump &Add(Module *object); // append, record in module list 336 337 // Complete the construction of the minidump, given the Add calls 338 // we've seen up to this point. After this call, this Dump's 339 // contents are complete, all labels should be defined if everything 340 // Cited has been Added, and you may call GetContents on it. 341 void Finish(); 342 343 private: 344 // A label representing the start of the minidump file. 345 Label file_start_; 346 347 // The stream directory. We construct this incrementally from 348 // Add(Stream *) calls. 349 SynthMinidump::Section stream_directory_; // The directory's contents. 350 size_t stream_count_; // The number of streams so far. 351 Label stream_count_label_; // Cited in file header. 352 Label stream_directory_rva_; // The directory's file offset. 353 354 // This minidump's thread list. We construct this incrementally from 355 // Add(Thread *) calls. 356 List<Thread> thread_list_; 357 358 // This minidump's module list. We construct this incrementally from 359 // Add(Module *) calls. 360 List<Module> module_list_; 361 362 // This minidump's memory list. We construct this incrementally from 363 // Add(Memory *) calls. This is actually a list of MDMemoryDescriptors, 364 // not memory ranges --- thus the odd type. 365 List<SynthMinidump::Section> memory_list_; 366}; 367 368} // namespace SynthMinidump 369 370} // namespace google_breakpad 371 372#endif // PROCESSOR_SYNTH_MINIDUMP_H_ 373