/thirdparty/breakpad/common/mac/dump_syms.h

  1// -*- mode: c++ -*-
  2
  3// Copyright (c) 2011, 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// Author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com>
 33
 34// dump_syms.h: Declaration of google_breakpad::DumpSymbols, a class for
 35// reading debugging information from Mach-O files and writing it out as a
 36// Breakpad symbol file.
 37
 38#include <Foundation/Foundation.h>
 39#include <mach-o/loader.h>
 40#include <stdio.h>
 41#include <stdlib.h>
 42
 43#include <ostream>
 44#include <string>
 45#include <vector>
 46
 47#include "common/byte_cursor.h"
 48#include "common/mac/macho_reader.h"
 49#include "common/module.h"
 50
 51namespace google_breakpad {
 52
 53class DumpSymbols {
 54 public:
 55  DumpSymbols()
 56      : input_pathname_(),
 57        object_filename_(),
 58        contents_(),
 59        selected_object_file_(),
 60        selected_object_name_() { }
 61  ~DumpSymbols() {
 62    [input_pathname_ release];
 63    [object_filename_ release];
 64    [contents_ release];
 65  }
 66
 67  // Prepare to read debugging information from |filename|. |filename| may be
 68  // the name of a universal binary, a Mach-O file, or a dSYM bundle
 69  // containing either of the above. On success, return true; if there is a
 70  // problem reading |filename|, report it and return false.
 71  //
 72  // (This class uses NSString for filenames and related values,
 73  // because the Mac Foundation framework seems to support
 74  // filename-related operations more fully on NSString values.)
 75  bool Read(NSString *filename);
 76
 77  // If this dumper's file includes an object file for |cpu_type| and
 78  // |cpu_subtype|, then select that object file for dumping, and return
 79  // true. Otherwise, return false, and leave this dumper's selected
 80  // architecture unchanged.
 81  //
 82  // By default, if this dumper's file contains only one object file, then
 83  // the dumper will dump those symbols; and if it contains more than one
 84  // object file, then the dumper will dump the object file whose
 85  // architecture matches that of this dumper program.
 86  bool SetArchitecture(cpu_type_t cpu_type, cpu_subtype_t cpu_subtype);
 87
 88  // If this dumper's file includes an object file for |arch_name|, then select
 89  // that object file for dumping, and return true. Otherwise, return false,
 90  // and leave this dumper's selected architecture unchanged.
 91  //
 92  // By default, if this dumper's file contains only one object file, then
 93  // the dumper will dump those symbols; and if it contains more than one
 94  // object file, then the dumper will dump the object file whose
 95  // architecture matches that of this dumper program.
 96  bool SetArchitecture(const std::string &arch_name);
 97
 98  // Return a pointer to an array of 'struct fat_arch' structures,
 99  // describing the object files contained in this dumper's file. Set
100  // *|count| to the number of elements in the array. The returned array is
101  // owned by this DumpSymbols instance.
102  //
103  // If there are no available architectures, this function
104  // may return NULL.
105  const struct fat_arch *AvailableArchitectures(size_t *count) {
106    *count = object_files_.size();
107    if (object_files_.size() > 0)
108      return &object_files_[0];
109    return NULL;
110  }
111
112  // Read the selected object file's debugging information, and write it out to
113  // |stream|. Write the CFI section if |cfi| is true. Return true on success;
114  // if an error occurs, report it and return false.
115  bool WriteSymbolFile(std::ostream &stream, bool cfi);
116
117 private:
118  // Used internally.
119  class DumperLineToModule;
120  class LoadCommandDumper;
121
122  // Return an identifier string for the file this DumpSymbols is dumping.
123  std::string Identifier();
124
125  // Read debugging information from |dwarf_sections|, which was taken from
126  // |macho_reader|, and add it to |module|. On success, return true;
127  // on failure, report the problem and return false.
128  bool ReadDwarf(google_breakpad::Module *module,
129                 const mach_o::Reader &macho_reader,
130                 const mach_o::SectionMap &dwarf_sections) const;
131
132  // Read DWARF CFI or .eh_frame data from |section|, belonging to
133  // |macho_reader|, and record it in |module|.  If |eh_frame| is true,
134  // then the data is .eh_frame-format data; otherwise, it is standard DWARF
135  // .debug_frame data. On success, return true; on failure, report
136  // the problem and return false.
137  bool ReadCFI(google_breakpad::Module *module,
138               const mach_o::Reader &macho_reader,
139               const mach_o::Section &section,
140               bool eh_frame) const;
141
142  // The name of the file or bundle whose symbols this will dump.
143  // This is the path given to Read, for use in error messages.
144  NSString *input_pathname_;
145
146  // The name of the file this DumpSymbols will actually read debugging
147  // information from. Normally, this is the same as input_pathname_, but if
148  // filename refers to a dSYM bundle, then this is the resource file
149  // within that bundle.
150  NSString *object_filename_;
151
152  // The complete contents of object_filename_, mapped into memory.
153  NSData *contents_;
154
155  // A vector of fat_arch structures describing the object files
156  // object_filename_ contains. If object_filename_ refers to a fat binary,
157  // this may have more than one element; if it refers to a Mach-O file, this
158  // has exactly one element.
159  vector<struct fat_arch> object_files_;
160
161  // The object file in object_files_ selected to dump, or NULL if
162  // SetArchitecture hasn't been called yet.
163  const struct fat_arch *selected_object_file_;
164
165  // A string that identifies the selected object file, for use in error
166  // messages.  This is usually object_filename_, but if that refers to a
167  // fat binary, it includes an indication of the particular architecture
168  // within that binary.
169  string selected_object_name_;
170};
171
172}  // namespace google_breakpad