elf_utils 0.3.0

data/lib/elf_utils/elf_file.rb

@@ -0,0 +1,312 @@
+require "forwardable"
+require_relative "string_pread"
+
+module ElfUtils
+  # Read ELF and DWARF data from any class that provides a #pread method.
+  #
+  # @example dump the symbols found in an ELF file
+  #   ElfUtils::ElfFile.open("spec/data/complex_64be-dwarf64-v5") do |elf_file|
+  #     pp elf_file.symbols
+  #   end
+  #
+  # @example read complex structure from running process
+  #   # open an ELF file, in this case an executable
+  #   elf_file = ElfUtils.open("a.out")
+  #
+  #   # get the Symbol instance for a global variable
+  #   symbol = elf_file.symbol(:some_global_var)      # => #<ElfUtils::Symbol ...>
+  #
+  #   # get the address of the symbol
+  #   addr = symbol.addr                              # => 0x40001000
+  #
+  #   # relocate the load segments to account for ASLR.  Addresses for load segments
+  #   # gleaned manually from /proc/pid/map.
+  #   elf_file.load_segments[0].relocate(text_addr)
+  #   elf_file.load_segments[1].relocate(data_addr)
+  #
+  #   # get the address of the symbol after relocation
+  #   addr = symbol.addr                              # => 0x90301000
+  #
+  #   # get the data type for the symbol; requires DWARF debug information
+  #   type = symbol.ctype                             # => #<CTypes::Struct ...>
+  #
+  #   # open the memory for a process running this executable, and read the value of
+  #   # the global variable.
+  #   value = File.open(File.join("/proc", pid, "mem")) do |mem|
+  #       # read the raw bytes for the variable
+  #       bytes = mem.pread(type.size, addr)          # => "\xef\x99\xde... "
+  #
+  #       # unpack the bytes
+  #       type.unpack_one(bytes)                      # => { field: val, ... }
+  #   end
+  class ElfFile
+    extend Forwardable
+    using StringPread
+
+    # open a file path, and return an ElfFile instance
+    # @overload open(path)
+    #   @param path [String] file path
+    #   @return [ElfFile]
+    #
+    # @overload open(path)
+    #   @param path [String] file path
+    #   @yield [ElfFile] invokes block with opened file, will close when block
+    #     returns
+    #
+    # @example
+    #   elf_file = ElfFile.open("spec/data/complex_64be-dwarf64-v5")
+    #   pp(elf_file.symbols)
+    #   elf_file.close
+    #
+    # @example
+    #   ElfFile.open("spec/data/complex_64be-dwarf64-v5") do |elf_file|
+    #     pp(elf_file.symbols)
+    #   end
+    #
+    def self.open(path)
+      if block_given?
+        File.open(path) do |f|
+          yield new(f)
+        end
+      else
+        new(File.open(path))
+      end
+    end
+
+    # create an instance of ElfFile
+    # @param io [IO, String, #pread] Anything that provides
+    #   the #pread(max_len, offset) method
+    def initialize(io)
+      io.force_encoding("ASCII-8BIT") if io.is_a?(String)
+      @io = io
+      @header = load_header(io)
+      @type_prefix = (elf_class == :elf32) ? "Elf32" : "Elf64"
+    end
+
+    # @api private
+    attr_reader :header
+
+    # return the path of the ElfFile
+    # @return [String, nil] path of the ElfFile
+    def path
+      @io.path if @io.respond_to?(:path)
+    end
+
+    # Return the ELF class according to the ident in the header
+    # @return [Symbol] :elf32 or :elf64
+    def elf_class
+      case @header.e_ident.ei_class
+      when Types::ELFCLASS32
+        :elf32
+      when Types::ELFCLASS64
+        :elf64
+      else
+        raise InvalidFormat, "Unsupported ELF ident.ei_class: %p", @header
+      end
+    end
+
+    # get the endian according to the ELF header
+    # @return [Symbol] :big or :little
+    def endian
+      case @header.e_ident.ei_data
+      when :lsb
+        :little
+      when :msb
+        :big
+      else
+        raise "Invalid EI_DATA value in ELF header ident: %p", @header
+      end
+    end
+
+    # check if this is a relocatable ELF file
+    # @return [Boolean] true if the file is relocatable
+    def relocatable?
+      @header.e_type == :rel
+    end
+
+    # Get the segments
+    # @return [Array<Segment::Base>] segments present in ELF file
+    def segments
+      @segments ||= pread([:Phdr, @header.e_phnum], @header.e_phoff).map do |hdr|
+        Segment.from_header(self, hdr)
+      end
+    end
+
+    # Return the list of load segments
+    # @return [Array<Segment::Base>] load segments present in ELF file
+    def load_segments
+      segments.select { |s| s.type == :load }
+    end
+
+    # Return the .shstrtab section
+    # @return [Section]
+    def shstrtab
+      # XXX we end up with a duplicate copy of this section, but we need to
+      # get the shstrtab while building the full sections list
+      @shstrtab ||= begin
+        hdr_class = elf_type(:Shdr)
+        offset = hdr_class.size * @header.e_shstrndx
+        hdr = pread(hdr_class, @header.e_shoff + offset)
+        Section.from_header(self, hdr)
+      end
+    end
+
+    # Return the .strtab section
+    # @return [Section::Strtab]
+    def strtab
+      section(".strtab")
+    end
+
+    # return the .symtab section
+    # @return [Section::Symtab]
+    def symtab
+      @symtab ||= section(".symtab") || section(".dynsym")
+    end
+
+    # return the .symtab section
+    # @return [Section::DebugInfo]
+    def debug_info
+      section(".debug_info")
+    end
+
+    # get the sections present in the ELF file
+    # @return [Array<Section::Base>]
+    def sections
+      @sections ||= pread([:Shdr, @header.e_shnum], @header.e_shoff)
+        .map do |hdr|
+          Section.from_header(self, hdr)
+        end
+    end
+
+    # lookup a section by name
+    # @return [Section::Base, nil] section instance if found, nil otherwise
+    def section(name)
+      @sections_by_name ||= sections.each_with_object({}) do |section, cache|
+        cache[section.name] = section
+      end
+      @sections_by_name[name]
+    end
+
+    # return the list of symbols found in the ELF file
+    # @return [Array<Symbol>]
+    def symbols
+      symtab&.symbols || []
+    end
+
+    # lookup a symbol by name
+    # @param [String, Symbol] symbol name
+    # @return [Symbol, name]
+    def symbol(name)
+      name = name.to_s
+      symbols.find { |s| s.name == name }
+    end
+
+    # lookup a symbol by memory address
+    # @param [Integer] in-memory address
+    # @return [Symbol, name]
+    def symbol_at_addr(addr)
+      symbols.find do |sym|
+        next unless sym.section&.alloc?
+        sym.to_range.include?(addr)
+      end
+    end
+
+    # Get the ctypes datatype for a type defined in the .debug_info section
+    # @param name [String] name of type
+    #
+    # @example lookup a structure type by name from .debug_info section
+    #   ElfFile.open("spec/data/complex_64be-dwarf64-v5") do |elf_file|
+    #     elf_file.type("struct tlv")
+    #   end   # => #<CTypes::Struct ... >
+    def type(name)
+      raise Error, "File does not contain .debug_info section: #{path}" unless
+        (debug_info = section(".debug_info"))
+      debug_info.type(name)
+    end
+    alias_method :ctype, :type
+
+    # pread wrapper providing support for type lookup by name
+    # @api private
+    def pread(type_or_size, offset)
+      type, size = parse_type(type_or_size)
+      buf = @io.pread(size, offset)
+      return buf unless type
+      type.unpack(buf)
+    end
+
+    # lookup the ctypes datatype for this file's bitsize (ELF32 vs ELF64)
+    # @param name [Symbol, String] name of type
+    # @see Types
+    # @api private
+    def elf_type(name)
+      Types.const_get("#{@type_prefix}_#{name}").with_endian(endian)
+    end
+
+    # get the ctype that represents an address for this ELF file
+    # @api private
+    def addr_type
+      elf_type(:Addr)
+    end
+
+    private
+
+    # load the correct header type from the file
+    # @api private
+    def load_header(io)
+      ident = pread(Types::Elf_Ident, 0)
+      raise InvalidFormat, "Invalid ELF ident: %p" % ident unless
+        ident.ei_magic == Types::ELFMAGIC
+      endian = case ident.ei_data
+      when :lsb
+        :little
+      when :msb
+        :big
+      else
+        raise "Invalid EI_DATA value in ELF header ident: %p", @header
+      end
+
+      case ident.ei_class
+      when Types::ELFCLASS32
+        pread(Types::Elf32_Ehdr.with_endian(endian), 0)
+      when Types::ELFCLASS64
+        pread(Types::Elf64_Ehdr.with_endian(endian), 0)
+      else
+        raise InvalidFormat, "Unsupported ELF ident.ei_class: %p",
+          ident
+      end
+    rescue Dry::Types::ConstraintError
+      raise InvalidFormat, "Invalid ELF header"
+    end
+
+    # Return a type & size given a type or size argument; used by pread()
+    # @api private
+    def parse_type(type)
+      case type
+      when Integer
+        [nil, type] # just a plain old size
+      when CTypes::Type
+        [type, type.size]
+      when ::Symbol
+        # This is an elf type we'll need to conver to the correct size
+        type = elf_type(type)
+        [type, type.size]
+      when Array
+        if type.size != 2
+          raise Error, "array type must be of the form `[type, count]`; got %p" %
+            [type]
+        end
+
+        type, count = type
+        inner, _ = parse_type(type)
+        type = CTypes::Helpers
+          .array(inner, count).with_endian(inner.default_endian)
+        [type, type.size]
+      else
+        raise Error, "unsupported type: %p" % [type]
+      end
+    end
+  end
+end
+
+require_relative "section"
+require_relative "segment"

data/lib/elf_utils/section/base.rb

@@ -0,0 +1,77 @@
+module ElfUtils
+  class Section::Base
+    def initialize(file, header)
+      @file = file
+      @header = header
+      @offset = 0
+    end
+    attr_reader :header
+
+    def name
+      @file.shstrtab[@header.sh_name]
+    end
+
+    def inspect
+      "<%p %s %p 0x%08x %p>" % [self.class, name, @header.sh_type, addr, flags]
+    end
+
+    def bytes
+      @file.pread(@header.sh_size, @header.sh_offset)
+    end
+
+    def addr
+      @header.sh_addr + @offset
+    end
+
+    def size
+      @header.sh_size
+    end
+
+    def flags
+      @header.sh_flags
+    end
+
+    def offset
+      @header.sh_offset
+    end
+
+    def alloc?
+      flags.include?(:alloc)
+    end
+
+    def to_range
+      (addr...addr + size)
+    end
+
+    def symbols
+      @file.symtab.symbols.select { |s| s.section == self }
+    end
+
+    def symbol(name)
+      @file.symtab.symbols.find { |s| s.section == self && s.name == name }
+    end
+
+    # relocate this section
+    #
+    # @param addr address for section; `nil` clears relocation
+    def relocate(addr, relative: false)
+      @offset = if addr.nil?
+        0
+      elsif relative
+        addr
+      else
+        addr - @header.sh_addr
+      end
+    end
+
+    # return the relocation offset for this section
+    def relocation_offset
+      @offset
+    end
+
+    # get the load_segment this section belongs to
+    def load_segment
+      @file.load_segments.find { |s| s.sections.include?(self) }
+    end
+  end
+end

data/lib/elf_utils/section/debug_abbrev/abbreviation.rb

@@ -0,0 +1,171 @@
+require "forwardable"
+
+module ElfUtils
+  class Section::DebugAbbrev::Abbreviation
+    extend Forwardable
+
+    class UnsupportedDwarfAttributeFormError < ElfUtils::Error; end
+
+    def initialize(table, decl)
+      @table = table
+      @decl = decl
+    end
+    attr_reader :decl
+    def_delegators :@decl, :code, :tag
+
+    def pretty_print(q)
+      q.group(4,
+        "<%p [%d] DW_TAG_%s DW_CHILDREN_%s" %
+          [self.class, code, tag, children? ? "yes" : "no"],
+        ">") do
+        q.text("\n" + " " * q.indent)
+        q.seplist(@decl.attribute_specifications) do |attr|
+          q.text("DW_AT_%-15s  DW_FORM_%s" % [attr.name, attr.form])
+        end
+      end
+    end
+    alias_method :inspect, :pretty_inspect
+
+    def children?
+      @decl.children == 1
+    end
+
+    def attrs
+      @attrs ||= begin
+        attrs = {}
+        @decl.attribute_specifications.each do |attr|
+          attrs[attr.name] = attr.form
+        end
+        attrs.freeze
+      end
+    end
+
+    def die_size(addr_size:, offset_size:)
+      return nil if @variable_size
+
+      size = 0
+      @decl.attribute_specifications.each do |attr|
+        if (s = form_size(form: attr.form, addr_size:, offset_size:))
+          size += s
+        else
+          @variable_size = true
+          return nil
+        end
+      end
+      size
+    end
+
+    def variable_sized_attrs(addr_size:, offset_size:)
+      out = []
+      @decl.attribute_specifications.each do |attr|
+        next if form_size(form: attr.form, addr_size:, offset_size:)
+        out << attr
+      end
+      out
+    end
+
+    def unpack_die(buf:, endian:, offset_type:, addr_type:)
+      out = []
+      @decl.attribute_specifications.each do |attr|
+        value, buf = case attr.form
+        when :addr
+          addr_type.unpack_one(buf, endian: endian)
+        when :strp, :sec_offset
+          offset_type.unpack_one(buf, endian: endian)
+        when :data1, :flag, :ref1, :strx1
+          CTypes::UInt8.unpack_one(buf, endian: endian)
+        when :data2, :ref2
+          CTypes::UInt16.unpack_one(buf, endian: endian)
+        when :data4, :ref4
+          CTypes::UInt32.unpack_one(buf, endian: endian)
+        when :data8, :ref8
+          CTypes::UInt64.unpack_one(buf, endian: endian)
+        when :udata, :addrx
+          Types::ULEB128.unpack_one(buf)
+        when :sdata
+          Types::SLEB128.unpack_one(buf)
+        when :string
+          CTypes::String.terminated.unpack_one(buf, endian: endian)
+        when :block1
+          len, buf = CTypes::UInt8.unpack_one(buf, endian: endian)
+          [buf.byteslice(0, len), buf.byteslice(len..)]
+        when :block2
+          len, buf = CTypes::UInt16.unpack_one(buf, endian: endian)
+          [buf.byteslice(0, len), buf.byteslice(len..)]
+        when :exprloc
+          len, buf = Types::ULEB128.unpack_one(buf)
+          [buf.byteslice(0, len), buf.byteslice(len..)]
+        when :loclistx
+          Types::ULEB128.unpack_one(buf)
+        when :flag_present
+          [1, buf]
+        else
+          raise UnsupportedDwarfAttributeFormError,
+            "unsupported DWARF form: %p" % [attr.form]
+        end
+
+        out << [attr.name, attr.form, value]
+      end
+      [out, buf]
+    end
+
+    private
+
+    # return the size of a given dwarf attribute form
+    def form_size(form:, addr_size:, offset_size:)
+      case form
+      when :addr
+        addr_size
+      when :data1, :ref1
+        1
+      when :data2, :ref2
+        2
+      when :data4, :ref4
+        4
+      when :data8, :ref8
+        8
+      when :flag
+        1
+      when :strp
+        offset_size
+      when :ref_addr
+        addr_size
+      when :sec_offset
+        offset_size
+      when :flag_present
+        0
+      when :ref_sup4
+        4
+      when :strp_sup
+        offset_size
+      when :data16
+        16
+      when :line_strp
+        offset_size
+      when :ref_sig8
+        8
+      when :ref_sup8
+        8
+      when :strx1
+        1
+      when :strx2
+        2
+      when :strx3
+        3
+      when :strx4
+        4
+      when :addrx1
+        1
+      when :addrx2
+        2
+      when :addrx3
+        3
+      when :addrx4
+        4
+      else
+        # variable sized
+        nil
+      end
+    end
+  end
+end

data/lib/elf_utils/section/debug_abbrev/abbreviation_table.rb

@@ -0,0 +1,27 @@
+class ElfUtils::Section::DebugAbbrev
+  class AbbreviationTable
+    def initialize(buf)
+      @declarations = {}
+      @abbrevs = {}
+
+      # XXX CTypes needs a terminated array where we check the remaining bytes
+      # before decoding.
+      until buf[0].ord == 0
+        decl, buf = ElfUtils::Types::Dwarf::AbbreviationDeclaration.unpack_one(buf)
+        @declarations[decl.code] = decl
+        @abbrevs[decl.code] = Abbreviation.new(self, decl)
+      end
+    end
+    attr_reader :declarations
+
+    def [](code)
+      @abbrevs[code]
+    end
+
+    def entries
+      @abbrevs.values
+    end
+  end
+end
+
+require_relative "abbreviation"

data/lib/elf_utils/section/debug_abbrev.rb

@@ -0,0 +1,15 @@
+module ElfUtils
+  class Section::DebugAbbrev < Section::Base
+    def initialize(*args)
+      super
+      @abbreviation_tables = {}
+    end
+
+    def abbreviation_table(offset)
+      @abbreviation_tables[offset] ||= AbbreviationTable.new(bytes[offset..])
+    end
+  end
+end
+
+require_relative "debug_abbrev/abbreviation_table"
+require_relative "debug_abbrev/abbreviation"

data/lib/elf_utils/section/debug_addr.rb

@@ -0,0 +1,9 @@
+module ElfUtils
+  class Section::DebugAddr < Section::Base
+    def get(base:, index:)
+      @addr_type ||= @file.elf_type(:Addr)
+      offset = base + index * @addr_type.size
+      @addr_type.unpack(bytes[offset..])
+    end
+  end
+end

data/lib/elf_utils/section/debug_arange.rb

@@ -0,0 +1,54 @@
+module ElfUtils
+  class Section::DebugArange < Section::Base
+    extend CTypes::Helpers
+
+    Tuple32 = struct(addr: uint32, size: uint32)
+    Tuple64 = struct(addr: uint64, size: uint64)
+
+    class Entry < CTypes::Struct
+      layout do
+        attribute :length, uint32
+        attribute :version, uint16
+        attribute :debug_info_offset, uint32
+        attribute :addr_size, uint8
+        attribute :seg_desc_size, uint8
+        pad 4 # XXX not needed for dwarf64
+        attribute :tuple_bytes, string(trim: false)
+        size { |hdr| offsetof(:version) + hdr[:length] }
+      end
+
+      def tuples
+        @tuples ||= begin
+          type = (addr_size == 4) ? Tuple32 : Tuple64
+          type.unpack_all(self[:tuple_data], endian: @file.endian)
+        end
+      end
+    end
+
+    def entries
+      @entries ||= Entry.unpack_all(bytes, endian: @file.endian)
+    end
+
+    def ranges
+      @ranges ||= begin
+        ranges = []
+        entries.each do |entry|
+          tuple_type = (entry.addr_size == 4) ? Tuple32 : Tuple64
+          tuple_type
+            .unpack_all(entry.tuple_bytes, endian: @file.endian)
+            .each do |tuple|
+              next if tuple.addr == 0 && tuple.size == 0
+              range = tuple.addr...(tuple.addr + tuple.size)
+              ranges << [range, entry.debug_info_offset]
+            end
+        end
+        ranges
+      end
+    end
+
+    def cu_offset(addr)
+      ranges.each { |range, offset| return offset if range.include?(addr) }
+      nil
+    end
+  end
+end