michael@0: // -*- mode: C++ -*- michael@0: michael@0: // Copyright (c) 2010, Google Inc. michael@0: // All rights reserved. michael@0: // michael@0: // Redistribution and use in source and binary forms, with or without michael@0: // modification, are permitted provided that the following conditions are michael@0: // met: michael@0: // michael@0: // * Redistributions of source code must retain the above copyright michael@0: // notice, this list of conditions and the following disclaimer. michael@0: // * Redistributions in binary form must reproduce the above michael@0: // copyright notice, this list of conditions and the following disclaimer michael@0: // in the documentation and/or other materials provided with the michael@0: // distribution. michael@0: // * Neither the name of Google Inc. nor the names of its michael@0: // contributors may be used to endorse or promote products derived from michael@0: // this software without specific prior written permission. michael@0: // michael@0: // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS michael@0: // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT michael@0: // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR michael@0: // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT michael@0: // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, michael@0: // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT michael@0: // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, michael@0: // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY michael@0: // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT michael@0: // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE michael@0: // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. michael@0: michael@0: // Original author: Jim Blandy michael@0: michael@0: // synth_minidump.h: Interface to SynthMinidump: fake minidump generator. michael@0: // michael@0: // We treat a minidump file as the concatenation of a bunch of michael@0: // test_assembler::Sections. The file header, stream directory, michael@0: // streams, memory regions, strings, and so on --- each is a Section michael@0: // that eventually gets appended to the minidump. Dump, Memory, michael@0: // Context, Thread, and so on all inherit from test_assembler::Section. michael@0: // For example: michael@0: // michael@0: // using google_breakpad::test_assembler::kLittleEndian; michael@0: // using google_breakpad::SynthMinidump::Context; michael@0: // using google_breakpad::SynthMinidump::Dump; michael@0: // using google_breakpad::SynthMinidump::Memory; michael@0: // using google_breakpad::SynthMinidump::Thread; michael@0: // michael@0: // Dump minidump(MD_NORMAL, kLittleEndian); michael@0: // michael@0: // Memory stack1(minidump, 0x569eb0a9); michael@0: // ... build contents of stack1 with test_assembler::Section functions ... michael@0: // michael@0: // MDRawContextX86 x86_context1; michael@0: // x86_context1.context_flags = MD_CONTEXT_X86; michael@0: // x86_context1.eip = 0x7c90eb94; michael@0: // x86_context1.esp = 0x569eb0a9; michael@0: // x86_context1.ebp = x86_context1.esp + something appropriate; michael@0: // Context context1(minidump, x86_context1); michael@0: // michael@0: // Thread thread1(minidump, 0xe4a4821d, stack1, context1); michael@0: // michael@0: // minidump.Add(&stack1); michael@0: // minidump.Add(&context1); michael@0: // minidump.Add(&thread1); michael@0: // minidump.Finish(); michael@0: // michael@0: // string contents; michael@0: // EXPECT_TRUE(minidump.GetContents(&contents)); michael@0: // // contents now holds the bytes of a minidump file michael@0: // michael@0: // Because the test_assembler classes let us write Label references to michael@0: // sections before the Labels' values are known, this gives us michael@0: // flexibility in how we put the dump together: minidump pieces can michael@0: // hold the file offsets of other minidump pieces before the michael@0: // referents' positions have been decided. As long as everything has michael@0: // been placed by the time we call dump.GetContents to obtain the michael@0: // bytes, all the Labels' values will be known, and everything will michael@0: // get patched up appropriately. michael@0: // michael@0: // The dump.Add(thing) functions append THINGS's contents to the michael@0: // minidump, but they also do two other things: michael@0: // michael@0: // - dump.Add(thing) invokes thing->Finish, which tells *thing the michael@0: // offset within the file at which it was placed, and allows *thing michael@0: // to do any final content generation. michael@0: // michael@0: // - If THING is something which should receive an entry in some sort michael@0: // of list or directory, then dump.Add(THING) automatically creates michael@0: // the appropriate directory or list entry. Streams must appear in michael@0: // the stream directory; memory ranges should be listed in the michael@0: // memory list; threads should be placed in the thread list; and so michael@0: // on. michael@0: // michael@0: // By convention, Section subclass constructors that take references michael@0: // to other Sections do not take care of 'Add'ing their arguments to michael@0: // the dump. For example, although the Thread constructor takes michael@0: // references to a Memory and a Context, it does not add them to the michael@0: // dump on the caller's behalf. Rather, the caller is responsible for michael@0: // 'Add'ing every section they create. This allows Sections to be michael@0: // cited from more than one place; for example, Memory ranges are michael@0: // cited both from Thread objects (as their stack contents) and by the michael@0: // memory list stream. michael@0: // michael@0: // If you forget to Add some Section, the Dump::GetContents call will michael@0: // fail, as the test_assembler::Labels used to cite the Section's michael@0: // contents from elsewhere will still be undefined. michael@0: #ifndef PROCESSOR_SYNTH_MINIDUMP_H_ michael@0: #define PROCESSOR_SYNTH_MINIDUMP_H_ michael@0: michael@0: #include michael@0: michael@0: #include michael@0: #include michael@0: michael@0: #include "common/test_assembler.h" michael@0: #include "common/using_std_string.h" michael@0: #include "google_breakpad/common/breakpad_types.h" michael@0: #include "google_breakpad/common/minidump_format.h" michael@0: michael@0: namespace google_breakpad { michael@0: michael@0: namespace SynthMinidump { michael@0: michael@0: using test_assembler::Endianness; michael@0: using test_assembler::kBigEndian; michael@0: using test_assembler::kLittleEndian; michael@0: using test_assembler::kUnsetEndian; michael@0: using test_assembler::Label; michael@0: michael@0: class Dump; michael@0: class Memory; michael@0: class String; michael@0: michael@0: // A test_assembler::Section which will be appended to a minidump. michael@0: class Section: public test_assembler::Section { michael@0: public: michael@0: explicit Section(const Dump &dump); michael@0: michael@0: // Append an MDLocationDescriptor referring to this section to SECTION. michael@0: // If 'this' is NULL, append a descriptor with a zero length and MDRVA. michael@0: // michael@0: // (I couldn't find the language in the C++ standard that says that michael@0: // invoking member functions of a NULL pointer to a class type is michael@0: // bad, if such language exists. Having this function handle NULL michael@0: // 'this' is convenient, but if it causes trouble, it's not hard to michael@0: // do differently.) michael@0: void CiteLocationIn(test_assembler::Section *section) const; michael@0: michael@0: // Note that this section's contents are complete, and that it has michael@0: // been placed in the minidump file at OFFSET. The 'Add' member michael@0: // functions call the Finish member function of the object being michael@0: // added for you; if you are 'Add'ing this section, you needn't Finish it. michael@0: virtual void Finish(const Label &offset) { michael@0: file_offset_ = offset; size_ = Size(); michael@0: } michael@0: michael@0: protected: michael@0: // This section's size and offset within the minidump file. michael@0: Label file_offset_, size_; michael@0: }; michael@0: michael@0: // A stream within a minidump file. 'Add'ing a stream to a minidump michael@0: // creates an entry for it in the minidump's stream directory. michael@0: class Stream: public Section { michael@0: public: michael@0: // Create a stream of type TYPE. You can append whatever contents michael@0: // you like to this stream using the test_assembler::Section methods. michael@0: Stream(const Dump &dump, uint32_t type) : Section(dump), type_(type) { } michael@0: michael@0: // Append an MDRawDirectory referring to this stream to SECTION. michael@0: void CiteStreamIn(test_assembler::Section *section) const; michael@0: michael@0: private: michael@0: // The type of this stream. michael@0: uint32_t type_; michael@0: }; michael@0: michael@0: class SystemInfo: public Stream { michael@0: public: michael@0: // Create an MD_SYSTEM_INFO_STREAM stream belonging to DUMP holding michael@0: // an MDRawSystem info structure initialized with the values from michael@0: // SYSTEM_INFO, except that the csd_version field is replaced with michael@0: // the file offset of the string CSD_VERSION, which can be 'Add'ed michael@0: // to the dump at the desired location. michael@0: // michael@0: // Remember that you are still responsible for 'Add'ing CSD_VERSION michael@0: // to the dump yourself. michael@0: SystemInfo(const Dump &dump, michael@0: const MDRawSystemInfo &system_info, michael@0: const String &csd_version); michael@0: michael@0: // Stock MDRawSystemInfo information and associated strings, for michael@0: // writing tests. michael@0: static const MDRawSystemInfo windows_x86; michael@0: static const string windows_x86_csd_version; michael@0: }; michael@0: michael@0: // An MDString: a string preceded by a 32-bit length. michael@0: class String: public Section { michael@0: public: michael@0: String(const Dump &dump, const string &value); michael@0: michael@0: // Append an MDRVA referring to this string to SECTION. michael@0: void CiteStringIn(test_assembler::Section *section) const; michael@0: }; michael@0: michael@0: // A range of memory contents. 'Add'ing a memory range to a minidump michael@0: // creates n entry for it in the minidump's memory list. By michael@0: // convention, the 'start', 'Here', and 'Mark' member functions refer michael@0: // to memory addresses. michael@0: class Memory: public Section { michael@0: public: michael@0: Memory(const Dump &dump, uint64_t address) michael@0: : Section(dump), address_(address) { start() = address; } michael@0: michael@0: // Append an MDMemoryDescriptor referring to this memory range to SECTION. michael@0: void CiteMemoryIn(test_assembler::Section *section) const; michael@0: michael@0: private: michael@0: // The process address from which these memory contents were taken. michael@0: // Shouldn't this be a Label? michael@0: uint64_t address_; michael@0: }; michael@0: michael@0: class Context: public Section { michael@0: public: michael@0: // Create a context belonging to DUMP whose contents are a copy of CONTEXT. michael@0: Context(const Dump &dump, const MDRawContextX86 &context); michael@0: Context(const Dump &dump, const MDRawContextARM &context); michael@0: // Add an empty context to the dump. michael@0: Context(const Dump &dump) : Section(dump) {} michael@0: // Add constructors for other architectures here. Remember to byteswap. michael@0: }; michael@0: michael@0: class Thread: public Section { michael@0: public: michael@0: // Create a thread belonging to DUMP with the given values, citing michael@0: // STACK and CONTEXT (which you must Add to the dump separately). michael@0: Thread(const Dump &dump, michael@0: uint32_t thread_id, michael@0: const Memory &stack, michael@0: const Context &context, michael@0: uint32_t suspend_count = 0, michael@0: uint32_t priority_class = 0, michael@0: uint32_t priority = 0, michael@0: uint64_t teb = 0); michael@0: }; michael@0: michael@0: class Module: public Section { michael@0: public: michael@0: // Create a module with the given values. Note that CV_RECORD and michael@0: // MISC_RECORD can be NULL, in which case the corresponding location michael@0: // descriptior in the minidump will have a length of zero. michael@0: Module(const Dump &dump, michael@0: uint64_t base_of_image, michael@0: uint32_t size_of_image, michael@0: const String &name, michael@0: uint32_t time_date_stamp = 1262805309, michael@0: uint32_t checksum = 0, michael@0: const MDVSFixedFileInfo &version_info = Module::stock_version_info, michael@0: const Section *cv_record = NULL, michael@0: const Section *misc_record = NULL); michael@0: michael@0: private: michael@0: // A standard MDVSFixedFileInfo structure to use as a default for michael@0: // minidumps. There's no reason to make users write out all this crap michael@0: // over and over. michael@0: static const MDVSFixedFileInfo stock_version_info; michael@0: }; michael@0: michael@0: class Exception : public Stream { michael@0: public: michael@0: Exception(const Dump &dump, michael@0: const Context &context, michael@0: uint32_t thread_id = 0, michael@0: uint32_t exception_code = 0, michael@0: uint32_t exception_flags = 0, michael@0: uint64_t exception_address = 0); michael@0: }; michael@0: michael@0: // A list of entries starting with a 32-bit count, like a memory list michael@0: // or a thread list. michael@0: template michael@0: class List: public Stream { michael@0: public: michael@0: List(const Dump &dump, uint32_t type) : Stream(dump, type), count_(0) { michael@0: D32(count_label_); michael@0: } michael@0: michael@0: // Add ELEMENT to this list. michael@0: void Add(Element *element) { michael@0: element->Finish(file_offset_ + Size()); michael@0: Append(*element); michael@0: count_++; michael@0: } michael@0: michael@0: // Return true if this List is empty, false otherwise. michael@0: bool Empty() { return count_ == 0; } michael@0: michael@0: // Finish up the contents of this section, mark it as having been michael@0: // placed at OFFSET. michael@0: virtual void Finish(const Label &offset) { michael@0: Stream::Finish(offset); michael@0: count_label_ = count_; michael@0: } michael@0: michael@0: private: michael@0: size_t count_; michael@0: Label count_label_; michael@0: }; michael@0: michael@0: class Dump: public test_assembler::Section { michael@0: public: michael@0: michael@0: // Create a test_assembler::Section containing a minidump file whose michael@0: // header uses the given values. ENDIANNESS determines the michael@0: // endianness of the signature; we set this section's default michael@0: // endianness by this. michael@0: Dump(uint64_t flags, michael@0: Endianness endianness = kLittleEndian, michael@0: uint32_t version = MD_HEADER_VERSION, michael@0: uint32_t date_time_stamp = 1262805309); michael@0: michael@0: // The following functions call OBJECT->Finish(), and append the michael@0: // contents of OBJECT to this minidump. They also record OBJECT in michael@0: // whatever directory or list is appropriate for its type. The michael@0: // stream directory, memory list, thread list, and module list are michael@0: // accumulated this way. michael@0: Dump &Add(SynthMinidump::Section *object); // simply append data michael@0: Dump &Add(Stream *object); // append, record in stream directory michael@0: Dump &Add(Memory *object); // append, record in memory list michael@0: Dump &Add(Thread *object); // append, record in thread list michael@0: Dump &Add(Module *object); // append, record in module list michael@0: michael@0: // Complete the construction of the minidump, given the Add calls michael@0: // we've seen up to this point. After this call, this Dump's michael@0: // contents are complete, all labels should be defined if everything michael@0: // Cited has been Added, and you may call GetContents on it. michael@0: void Finish(); michael@0: michael@0: private: michael@0: // A label representing the start of the minidump file. michael@0: Label file_start_; michael@0: michael@0: // The stream directory. We construct this incrementally from michael@0: // Add(Stream *) calls. michael@0: SynthMinidump::Section stream_directory_; // The directory's contents. michael@0: size_t stream_count_; // The number of streams so far. michael@0: Label stream_count_label_; // Cited in file header. michael@0: Label stream_directory_rva_; // The directory's file offset. michael@0: michael@0: // This minidump's thread list. We construct this incrementally from michael@0: // Add(Thread *) calls. michael@0: List thread_list_; michael@0: michael@0: // This minidump's module list. We construct this incrementally from michael@0: // Add(Module *) calls. michael@0: List module_list_; michael@0: michael@0: // This minidump's memory list. We construct this incrementally from michael@0: // Add(Memory *) calls. This is actually a list of MDMemoryDescriptors, michael@0: // not memory ranges --- thus the odd type. michael@0: List memory_list_; michael@0: }; michael@0: michael@0: } // namespace SynthMinidump michael@0: michael@0: } // namespace google_breakpad michael@0: michael@0: #endif // PROCESSOR_SYNTH_MINIDUMP_H_