/thirdparty/breakpad/processor/synth_minidump.h

  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 "google_breakpad/common/breakpad_types.h"
118#include "google_breakpad/common/minidump_format.h"
119
120namespace google_breakpad {
121
122namespace SynthMinidump {
123
124using std::string;
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, u_int32_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  u_int32_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, u_int64_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  u_int64_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  // Add constructors for other architectures here. Remember to byteswap.
232};
233
234class Thread: public Section {
235 public:
236  // Create a thread belonging to DUMP with the given values, citing
237  // STACK and CONTEXT (which you must Add to the dump separately).
238  Thread(const Dump &dump,
239         u_int32_t thread_id,
240         const Memory &stack,
241         const Context &context,
242         u_int32_t suspend_count = 0,
243         u_int32_t priority_class = 0,
244         u_int32_t priority = 0,
245         u_int64_t teb = 0);
246};
247
248class Module: public Section {
249 public:
250  // Create a module with the given values. Note that CV_RECORD and
251  // MISC_RECORD can be NULL, in which case the corresponding location
252  // descriptior in the minidump will have a length of zero.
253  Module(const Dump &dump,
254         u_int64_t base_of_image,
255         u_int32_t size_of_image,
256         const String &name,
257         u_int32_t time_date_stamp = 1262805309,
258         u_int32_t checksum = 0,
259         const MDVSFixedFileInfo &version_info = Module::stock_version_info,
260         const Section *cv_record = NULL,
261         const Section *misc_record = NULL);
262
263 private:
264  // A standard MDVSFixedFileInfo structure to use as a default for
265  // minidumps.  There's no reason to make users write out all this crap
266  // over and over.
267  static const MDVSFixedFileInfo stock_version_info;
268};
269
270class Exception : public Stream {
271public:
272  Exception(const Dump &dump,
273            const Context &context,
274            u_int32_t thread_id = 0,
275            u_int32_t exception_code = 0,
276            u_int32_t exception_flags = 0,
277            u_int64_t exception_address = 0);
278};
279
280// A list of entries starting with a 32-bit count, like a memory list
281// or a thread list.
282template<typename Element>
283class List: public Stream {
284 public:
285  List(const Dump &dump, u_int32_t type) : Stream(dump, type), count_(0) {
286    D32(count_label_);
287  }
288
289  // Add ELEMENT to this list.
290  void Add(Element *element) {
291    element->Finish(file_offset_ + Size());
292    Append(*element);
293    count_++;
294  }
295
296  // Return true if this List is empty, false otherwise.
297  bool Empty() { return count_ == 0; }
298
299  // Finish up the contents of this section, mark it as having been
300  // placed at OFFSET.
301  virtual void Finish(const Label &offset) {
302    Stream::Finish(offset);
303    count_label_ = count_;
304  }
305
306 private:
307  size_t count_;
308  Label count_label_;
309};
310
311class Dump: public test_assembler::Section {
312 public:
313
314  // Create a test_assembler::Section containing a minidump file whose
315  // header uses the given values. ENDIANNESS determines the
316  // endianness of the signature; we set this section's default
317  // endianness by this.
318  Dump(u_int64_t flags,
319       Endianness endianness = kLittleEndian,
320       u_int32_t version = MD_HEADER_VERSION,
321       u_int32_t date_time_stamp = 1262805309);
322
323  // The following functions call OBJECT->Finish(), and append the
324  // contents of OBJECT to this minidump. They also record OBJECT in
325  // whatever directory or list is appropriate for its type. The
326  // stream directory, memory list, thread list, and module list are
327  // accumulated this way.
328  Dump &Add(SynthMinidump::Section *object); // simply append data
329  Dump &Add(Stream *object); // append, record in stream directory
330  Dump &Add(Memory *object); // append, record in memory list
331  Dump &Add(Thread *object); // append, record in thread list
332  Dump &Add(Module *object); // append, record in module list
333
334  // Complete the construction of the minidump, given the Add calls
335  // we've seen up to this point. After this call, this Dump's
336  // contents are complete, all labels should be defined if everything
337  // Cited has been Added, and you may call GetContents on it.
338  void Finish();
339
340 private:
341  // A label representing the start of the minidump file.
342  Label file_start_;
343
344  // The stream directory.  We construct this incrementally from
345  // Add(Stream *) calls.
346  SynthMinidump::Section stream_directory_; // The directory's contents.
347  size_t stream_count_;                 // The number of streams so far.
348  Label stream_count_label_;            // Cited in file header.
349  Label stream_directory_rva_;          // The directory's file offset.
350
351  // This minidump's thread list. We construct this incrementally from
352  // Add(Thread *) calls.
353  List<Thread> thread_list_;
354
355  // This minidump's module list. We construct this incrementally from
356  // Add(Module *) calls.
357  List<Module> module_list_;
358
359  // This minidump's memory list. We construct this incrementally from
360  // Add(Memory *) calls. This is actually a list of MDMemoryDescriptors,
361  // not memory ranges --- thus the odd type.
362  List<SynthMinidump::Section> memory_list_;
363};
364
365} // namespace SynthMinidump
366
367} // namespace google_breakpad
368
369#endif  // PROCESSOR_SYNTH_MINIDUMP_H_