The Tor Browser: toolkit/crashreporter/google-breakpad/src/common/dwarf/dwarf2diehandler.h@b8a032363ba2 (annotated)

toolkit/crashreporter/google-breakpad/src/common/dwarf/dwarf2diehandler.h@b8a032363ba2 (annotated)

toolkit/crashreporter/google-breakpad/src/common/dwarf/dwarf2diehandler.h

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 // -*- mode: c++ -*-
 // Copyright (c) 2010 Google Inc. All Rights Reserved.
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are
 // met:
 //
 //     * Redistributions of source code must retain the above copyright
 // notice, this list of conditions and the following disclaimer.
 //     * Redistributions in binary form must reproduce the above
 // copyright notice, this list of conditions and the following disclaimer
 // in the documentation and/or other materials provided with the
 // distribution.
 //     * Neither the name of Google Inc. nor the names of its
 // contributors may be used to endorse or promote products derived from
 // this software without specific prior written permission.
 //
 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 // Original author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com>
 // dwarf2reader::CompilationUnit is a simple and direct parser for
 // DWARF data, but its handler interface is not convenient to use.  In
 // particular:
 //
 // - CompilationUnit calls Dwarf2Handler's member functions to report
 //   every attribute's value, regardless of what sort of DIE it is.
 //   As a result, the ProcessAttributeX functions end up looking like
 //   this:
 //
 //     switch (parent_die_tag) {
 //       case DW_TAG_x:
 //         switch (attribute_name) {
 //           case DW_AT_y:
 //             handle attribute y of DIE type x
 //           ...
 //         } break;
 //       ...
 //     }
 //
 //   In C++ it's much nicer to use virtual function dispatch to find
 //   the right code for a given case than to switch on the DIE tag
 //   like this.
 //
 // - Processing different kinds of DIEs requires different sets of
 //   data: lexical block DIEs have start and end addresses, but struct
 //   type DIEs don't.  It would be nice to be able to have separate
 //   handler classes for separate kinds of DIEs, each with the members
 //   appropriate to its role, instead of having one handler class that
 //   needs to hold data for every DIE type.
 //
 // - There should be a separate instance of the appropriate handler
 //   class for each DIE, instead of a single object with tables
 //   tracking all the dies in the compilation unit.
 //
 // - It's not convenient to take some action after all a DIE's
 //   attributes have been seen, but before visiting any of its
 //   children.  The only indication you have that a DIE's attribute
 //   list is complete is that you get either a StartDIE or an EndDIE
 //   call.
 //
 // - It's not convenient to make use of the tree structure of the
 //   DIEs.  Skipping all the children of a given die requires
 //   maintaining state and returning false from StartDIE until we get
 //   an EndDIE call with the appropriate offset.
 //
 // This interface tries to take care of all that.  (You're shocked, I'm sure.)
 //
 // Using the classes here, you provide an initial handler for the root
 // DIE of the compilation unit.  Each handler receives its DIE's
 // attributes, and provides fresh handler objects for children of
 // interest, if any.  The three classes are:
 //
 // - DIEHandler: the base class for your DIE-type-specific handler
 //   classes.
 //
 // - RootDIEHandler: derived from DIEHandler, the base class for your
 //   root DIE handler class.
 //
 // - DIEDispatcher: derived from Dwarf2Handler, an instance of this
 //   invokes your DIE-type-specific handler objects.
 //
 // In detail:
 //
 // - Define handler classes specialized for the DIE types you're
 //   interested in.  These handler classes must inherit from
 //   DIEHandler.  Thus:
 //
 //     class My_DW_TAG_X_Handler: public DIEHandler { ... };
 //     class My_DW_TAG_Y_Handler: public DIEHandler { ... };
 //
 //   DIEHandler subclasses needn't correspond exactly to single DIE
 //   types, as shown here; the point is that you can have several
 //   different classes appropriate to different kinds of DIEs.
 //
 // - In particular, define a handler class for the compilation
 //   unit's root DIE, that inherits from RootDIEHandler:
 //
 //     class My_DW_TAG_compile_unit_Handler: public RootDIEHandler { ... };
 //
 //   RootDIEHandler inherits from DIEHandler, adding a few additional
 //   member functions for examining the compilation unit as a whole,
 //   and other quirks of rootness.
 //
 // - Then, create a DIEDispatcher instance, passing it an instance of
 //   your root DIE handler class, and use that DIEDispatcher as the
 //   dwarf2reader::CompilationUnit's handler:
 //
 //     My_DW_TAG_compile_unit_Handler root_die_handler(...);
 //     DIEDispatcher die_dispatcher(&root_die_handler);
 //     CompilationUnit reader(sections, offset, bytereader, &die_dispatcher);
 //
 //   Here, 'die_dispatcher' acts as a shim between 'reader' and the
 //   various DIE-specific handlers you have defined.
 //
 // - When you call reader.Start(), die_dispatcher behaves as follows,
 //   starting with your root die handler and the compilation unit's
 //   root DIE:
 //
 //   - It calls the handler's ProcessAttributeX member functions for
 //     each of the DIE's attributes.
 //
 //   - It calls the handler's EndAttributes member function.  This
 //     should return true if any of the DIE's children should be
 //     visited, in which case:
 //
 //     - For each of the DIE's children, die_dispatcher calls the
 //       DIE's handler's FindChildHandler member function.  If that
 //       returns a pointer to a DIEHandler instance, then
 //       die_dispatcher uses that handler to process the child, using
 //       this procedure recursively.  Alternatively, if
 //       FindChildHandler returns NULL, die_dispatcher ignores that
 //       child and its descendants.
 //
 //   - When die_dispatcher has finished processing all the DIE's
 //     children, it invokes the handler's Finish() member function,
 //     and destroys the handler.  (As a special case, it doesn't
 //     destroy the root DIE handler.)
 //
 // This allows the code for handling a particular kind of DIE to be
 // gathered together in a single class, makes it easy to skip all the
 // children or individual children of a particular DIE, and provides
 // appropriate parental context for each die.
 #ifndef COMMON_DWARF_DWARF2DIEHANDLER_H__
 #define COMMON_DWARF_DWARF2DIEHANDLER_H__
 #include <stack>
 #include <string>
 #include "common/dwarf/types.h"
 #include "common/dwarf/dwarf2enums.h"
 #include "common/dwarf/dwarf2reader.h"
 #include "common/using_std_string.h"
 namespace dwarf2reader {
 // A base class for handlers for specific DIE types.  The series of
 // calls made on a DIE handler is as follows:
 //
 // - for each attribute of the DIE:
 //   - ProcessAttributeX()
 // - EndAttributes()
 // - if that returned true, then for each child:
 //   - FindChildHandler()
 //   - if that returns a non-NULL pointer to a new handler:
 //     - recurse, with the new handler and the child die
 // - Finish()
 // - destruction
 class DIEHandler {
  public:
   DIEHandler() { }
   virtual ~DIEHandler() { }
   // When we visit a DIE, we first use these member functions to
   // report the DIE's attributes and their values.  These have the
   // same restrictions as the corresponding member functions of
   // dwarf2reader::Dwarf2Handler.
   //
   // Since DWARF does not specify in what order attributes must
   // appear, avoid making decisions in these functions that would be
   // affected by the presence of other attributes. The EndAttributes
   // function is a more appropriate place for such work, as all the
   // DIE's attributes have been seen at that point.
   //
   // The default definitions ignore the values they are passed.
   virtual void ProcessAttributeUnsigned(enum DwarfAttribute attr,
                                         enum DwarfForm form,
                                         uint64 data) { }
   virtual void ProcessAttributeSigned(enum DwarfAttribute attr,
                                       enum DwarfForm form,
                                       int64 data) { }
   virtual void ProcessAttributeReference(enum DwarfAttribute attr,
                                          enum DwarfForm form,
                                          uint64 data) { }
   virtual void ProcessAttributeBuffer(enum DwarfAttribute attr,
                                       enum DwarfForm form,
                                       const char* data,
                                       uint64 len) { }
   virtual void ProcessAttributeString(enum DwarfAttribute attr,
                                       enum DwarfForm form,
                                       const string& data) { }
   virtual void ProcessAttributeSignature(enum DwarfAttribute attr,
                                          enum DwarfForm form,
                                          uint64 signture) { }
   // Once we have reported all the DIE's attributes' values, we call
   // this member function.  If it returns false, we skip all the DIE's
   // children.  If it returns true, we call FindChildHandler on each
   // child.  If that returns a handler object, we use that to visit
   // the child; otherwise, we skip the child.
   //
   // This is a good place to make decisions that depend on more than
   // one attribute. DWARF does not specify in what order attributes
   // must appear, so only when the EndAttributes function is called
   // does the handler have a complete picture of the DIE's attributes.
   //
   // The default definition elects to ignore the DIE's children.
   // You'll need to override this if you override FindChildHandler,
   // but at least the default behavior isn't to pass the children to
   // FindChildHandler, which then ignores them all.
   virtual bool EndAttributes() { return false; }
   // If EndAttributes returns true to indicate that some of the DIE's
   // children might be of interest, then we apply this function to
   // each of the DIE's children.  If it returns a handler object, then
   // we use that to visit the child DIE.  If it returns NULL, we skip
   // that child DIE (and all its descendants).
   //
   // OFFSET is the offset of the child; TAG indicates what kind of DIE
   // it is.
   //
   // The default definition skips all children.
   virtual DIEHandler *FindChildHandler(uint64 offset, enum DwarfTag tag) {
     return NULL;
   }
   // When we are done processing a DIE, we call this member function.
   // This happens after the EndAttributes call, all FindChildHandler
   // calls (if any), and all operations on the children themselves (if
   // any). We call Finish on every handler --- even if EndAttributes
   // returns false.
   virtual void Finish() { };
 };
 // A subclass of DIEHandler, with additional kludges for handling the
 // compilation unit's root die.
 class RootDIEHandler: public DIEHandler {
  public:
   RootDIEHandler() { }
   virtual ~RootDIEHandler() { }
   // We pass the values reported via Dwarf2Handler::StartCompilationUnit
   // to this member function, and skip the entire compilation unit if it
   // returns false.  So the root DIE handler is actually also
   // responsible for handling the compilation unit metadata.
   // The default definition always visits the compilation unit.
   virtual bool StartCompilationUnit(uint64 offset, uint8 address_size,
                                     uint8 offset_size, uint64 cu_length,
                                     uint8 dwarf_version) { return true; }
   // For the root DIE handler only, we pass the offset, tag and
   // attributes of the compilation unit's root DIE.  This is the only
   // way the root DIE handler can find the root DIE's tag.  If this
   // function returns true, we will visit the root DIE using the usual
   // DIEHandler methods; otherwise, we skip the entire compilation
   // unit.
   //
   // The default definition elects to visit the root DIE.
   virtual bool StartRootDIE(uint64 offset, enum DwarfTag tag) { return true; }
 };
 class DIEDispatcher: public Dwarf2Handler {
  public:
   // Create a Dwarf2Handler which uses ROOT_HANDLER as the handler for
   // the compilation unit's root die, as described for the DIEHandler
   // class.
   DIEDispatcher(RootDIEHandler *root_handler) : root_handler_(root_handler) { }
   // Destroying a DIEDispatcher destroys all active handler objects
   // except the root handler.
   ~DIEDispatcher();
   bool StartCompilationUnit(uint64 offset, uint8 address_size,
                             uint8 offset_size, uint64 cu_length,
                             uint8 dwarf_version);
   bool StartDIE(uint64 offset, enum DwarfTag tag);
   void ProcessAttributeUnsigned(uint64 offset,
                                 enum DwarfAttribute attr,
                                 enum DwarfForm form,
                                 uint64 data);
   void ProcessAttributeSigned(uint64 offset,
                               enum DwarfAttribute attr,
                               enum DwarfForm form,
                               int64 data);
   void ProcessAttributeReference(uint64 offset,
                                  enum DwarfAttribute attr,
                                  enum DwarfForm form,
                                  uint64 data);
   void ProcessAttributeBuffer(uint64 offset,
                               enum DwarfAttribute attr,
                               enum DwarfForm form,
                               const char* data,
                               uint64 len);
   void ProcessAttributeString(uint64 offset,
                               enum DwarfAttribute attr,
                               enum DwarfForm form,
                               const string &data);
   void ProcessAttributeSignature(uint64 offset,
                                  enum DwarfAttribute attr,
                                  enum DwarfForm form,
                                  uint64 signature);
   void EndDIE(uint64 offset);
  private:
   // The type of a handler stack entry.  This includes some fields
   // which don't really need to be on the stack --- they could just be
   // single data members of DIEDispatcher --- but putting them here
   // makes it easier to see that the code is correct.
   struct HandlerStack {
     // The offset of the DIE for this handler stack entry.
     uint64 offset_;
     // The handler object interested in this DIE's attributes and
     // children.  If NULL, we're not interested in either.
     DIEHandler *handler_;
     // Have we reported the end of this DIE's attributes to the handler?
     bool reported_attributes_end_;
   };
   // Stack of DIE attribute handlers.  At StartDIE(D), the top of the
   // stack is the handler of D's parent, whom we may ask for a handler
   // for D itself.  At EndDIE(D), the top of the stack is D's handler.
   // Special cases:
   //
   // - Before we've seen the compilation unit's root DIE, the stack is
   //   empty; we'll call root_handler_'s special member functions, and
   //   perhaps push root_handler_ on the stack to look at the root's
   //   immediate children.
   //
   // - When we decide to ignore a subtree, we only push an entry on
   //   the stack for the root of the tree being ignored, rather than
   //   pushing lots of stack entries with handler_ set to NULL.
   std::stack<HandlerStack> die_handlers_;
   // The root handler.  We don't push it on die_handlers_ until we
   // actually get the StartDIE call for the root.
   RootDIEHandler *root_handler_;
 };
 } // namespace dwarf2reader
 #endif  // COMMON_DWARF_DWARF2DIEHANDLER_H__

The Tor Browser / annotate

toolkit/crashreporter/google-breakpad/src/common/dwarf/dwarf2diehandler.h@b8a032363ba2 (annotated)

toolkit/crashreporter/google-breakpad/src/common/dwarf/dwarf2diehandler.h