michael@0: // -*- mode: c++ -*-
michael@0: 
michael@0: // Copyright (c) 2011, 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: // Author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com>
michael@0: 
michael@0: // dump_syms.h: Declaration of google_breakpad::DumpSymbols, a class for
michael@0: // reading debugging information from Mach-O files and writing it out as a
michael@0: // Breakpad symbol file.
michael@0: 
michael@0: #include <Foundation/Foundation.h>
michael@0: #include <mach-o/loader.h>
michael@0: #include <stdio.h>
michael@0: #include <stdlib.h>
michael@0: 
michael@0: #include <ostream>
michael@0: #include <string>
michael@0: #include <vector>
michael@0: 
michael@0: #include "common/byte_cursor.h"
michael@0: #include "common/mac/macho_reader.h"
michael@0: #include "common/module.h"
michael@0: #include "common/symbol_data.h"
michael@0: 
michael@0: namespace google_breakpad {
michael@0: 
michael@0: class DumpSymbols {
michael@0:  public:
michael@0:   explicit DumpSymbols(SymbolData symbol_data)
michael@0:       : symbol_data_(symbol_data),
michael@0:         input_pathname_(),
michael@0:         object_filename_(),
michael@0:         contents_(),
michael@0:         selected_object_file_(),
michael@0:         selected_object_name_() { }
michael@0:   ~DumpSymbols() {
michael@0:     [input_pathname_ release];
michael@0:     [object_filename_ release];
michael@0:     [contents_ release];
michael@0:   }
michael@0: 
michael@0:   // Prepare to read debugging information from |filename|. |filename| may be
michael@0:   // the name of a universal binary, a Mach-O file, or a dSYM bundle
michael@0:   // containing either of the above. On success, return true; if there is a
michael@0:   // problem reading |filename|, report it and return false.
michael@0:   //
michael@0:   // (This class uses NSString for filenames and related values,
michael@0:   // because the Mac Foundation framework seems to support
michael@0:   // filename-related operations more fully on NSString values.)
michael@0:   bool Read(NSString *filename);
michael@0: 
michael@0:   // If this dumper's file includes an object file for |cpu_type| and
michael@0:   // |cpu_subtype|, then select that object file for dumping, and return
michael@0:   // true. Otherwise, return false, and leave this dumper's selected
michael@0:   // architecture unchanged.
michael@0:   //
michael@0:   // By default, if this dumper's file contains only one object file, then
michael@0:   // the dumper will dump those symbols; and if it contains more than one
michael@0:   // object file, then the dumper will dump the object file whose
michael@0:   // architecture matches that of this dumper program.
michael@0:   bool SetArchitecture(cpu_type_t cpu_type, cpu_subtype_t cpu_subtype);
michael@0: 
michael@0:   // If this dumper's file includes an object file for |arch_name|, then select
michael@0:   // that object file for dumping, and return true. Otherwise, return false,
michael@0:   // and leave this dumper's selected architecture unchanged.
michael@0:   //
michael@0:   // By default, if this dumper's file contains only one object file, then
michael@0:   // the dumper will dump those symbols; and if it contains more than one
michael@0:   // object file, then the dumper will dump the object file whose
michael@0:   // architecture matches that of this dumper program.
michael@0:   bool SetArchitecture(const std::string &arch_name);
michael@0: 
michael@0:   // Return a pointer to an array of 'struct fat_arch' structures,
michael@0:   // describing the object files contained in this dumper's file. Set
michael@0:   // *|count| to the number of elements in the array. The returned array is
michael@0:   // owned by this DumpSymbols instance.
michael@0:   //
michael@0:   // If there are no available architectures, this function
michael@0:   // may return NULL.
michael@0:   const struct fat_arch *AvailableArchitectures(size_t *count) {
michael@0:     *count = object_files_.size();
michael@0:     if (object_files_.size() > 0)
michael@0:       return &object_files_[0];
michael@0:     return NULL;
michael@0:   }
michael@0: 
michael@0:   // Read the selected object file's debugging information, and write it out to
michael@0:   // |stream|. Return true on success; if an error occurs, report it and
michael@0:   // return false.
michael@0:   bool WriteSymbolFile(std::ostream &stream);
michael@0: 
michael@0:   // As above, but simply return the debugging information in module
michael@0:   // instead of writing it to a stream. The caller owns the resulting
michael@0:   // module object and must delete it when finished.
michael@0:   bool ReadSymbolData(Module** module);
michael@0: 
michael@0:  private:
michael@0:   // Used internally.
michael@0:   class DumperLineToModule;
michael@0:   class LoadCommandDumper;
michael@0: 
michael@0:   // Return an identifier string for the file this DumpSymbols is dumping.
michael@0:   std::string Identifier();
michael@0: 
michael@0:   // Read debugging information from |dwarf_sections|, which was taken from
michael@0:   // |macho_reader|, and add it to |module|. On success, return true;
michael@0:   // on failure, report the problem and return false.
michael@0:   bool ReadDwarf(google_breakpad::Module *module,
michael@0:                  const mach_o::Reader &macho_reader,
michael@0:                  const mach_o::SectionMap &dwarf_sections) const;
michael@0: 
michael@0:   // Read DWARF CFI or .eh_frame data from |section|, belonging to
michael@0:   // |macho_reader|, and record it in |module|.  If |eh_frame| is true,
michael@0:   // then the data is .eh_frame-format data; otherwise, it is standard DWARF
michael@0:   // .debug_frame data. On success, return true; on failure, report
michael@0:   // the problem and return false.
michael@0:   bool ReadCFI(google_breakpad::Module *module,
michael@0:                const mach_o::Reader &macho_reader,
michael@0:                const mach_o::Section &section,
michael@0:                bool eh_frame) const;
michael@0: 
michael@0:   // The selection of what type of symbol data to read/write.
michael@0:   const SymbolData symbol_data_;
michael@0: 
michael@0:   // The name of the file or bundle whose symbols this will dump.
michael@0:   // This is the path given to Read, for use in error messages.
michael@0:   NSString *input_pathname_;
michael@0: 
michael@0:   // The name of the file this DumpSymbols will actually read debugging
michael@0:   // information from. Normally, this is the same as input_pathname_, but if
michael@0:   // filename refers to a dSYM bundle, then this is the resource file
michael@0:   // within that bundle.
michael@0:   NSString *object_filename_;
michael@0: 
michael@0:   // The complete contents of object_filename_, mapped into memory.
michael@0:   NSData *contents_;
michael@0: 
michael@0:   // A vector of fat_arch structures describing the object files
michael@0:   // object_filename_ contains. If object_filename_ refers to a fat binary,
michael@0:   // this may have more than one element; if it refers to a Mach-O file, this
michael@0:   // has exactly one element.
michael@0:   vector<struct fat_arch> object_files_;
michael@0: 
michael@0:   // The object file in object_files_ selected to dump, or NULL if
michael@0:   // SetArchitecture hasn't been called yet.
michael@0:   const struct fat_arch *selected_object_file_;
michael@0: 
michael@0:   // A string that identifies the selected object file, for use in error
michael@0:   // messages.  This is usually object_filename_, but if that refers to a
michael@0:   // fat binary, it includes an indication of the particular architecture
michael@0:   // within that binary.
michael@0:   string selected_object_name_;
michael@0: };
michael@0: 
michael@0: }  // namespace google_breakpad