From 1b6a04ca5504955c571d1c97504fb45ea0befee4 Mon Sep 17 00:00:00 2001 From: Valentin Popov Date: Mon, 8 Jan 2024 01:21:28 +0400 Subject: Initial vendor packages Signed-off-by: Valentin Popov --- vendor/object/src/read/traits.rs | 551 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 551 insertions(+) create mode 100644 vendor/object/src/read/traits.rs (limited to 'vendor/object/src/read/traits.rs') diff --git a/vendor/object/src/read/traits.rs b/vendor/object/src/read/traits.rs new file mode 100644 index 0000000..67105d3 --- /dev/null +++ b/vendor/object/src/read/traits.rs @@ -0,0 +1,551 @@ +use alloc::borrow::Cow; +use alloc::vec::Vec; + +use crate::read::{ + self, Architecture, CodeView, ComdatKind, CompressedData, CompressedFileRange, Export, + FileFlags, Import, ObjectKind, ObjectMap, Relocation, Result, SectionFlags, SectionIndex, + SectionKind, SegmentFlags, SubArchitecture, SymbolFlags, SymbolIndex, SymbolKind, SymbolMap, + SymbolMapName, SymbolScope, SymbolSection, +}; +use crate::Endianness; + +/// An object file. +/// +/// This is the primary trait for the unified read API. +pub trait Object<'data: 'file, 'file>: read::private::Sealed { + /// A loadable segment in the object file. + type Segment: ObjectSegment<'data>; + + /// An iterator for the loadable segments in the object file. + type SegmentIterator: Iterator; + + /// A section in the object file. + type Section: ObjectSection<'data>; + + /// An iterator for the sections in the object file. + type SectionIterator: Iterator; + + /// A COMDAT section group in the object file. + type Comdat: ObjectComdat<'data>; + + /// An iterator for the COMDAT section groups in the object file. + type ComdatIterator: Iterator; + + /// A symbol in the object file. + type Symbol: ObjectSymbol<'data>; + + /// An iterator for symbols in the object file. + type SymbolIterator: Iterator; + + /// A symbol table in the object file. + type SymbolTable: ObjectSymbolTable< + 'data, + Symbol = Self::Symbol, + SymbolIterator = Self::SymbolIterator, + >; + + /// An iterator for the dynamic relocations in the file. + /// + /// The first field in the item tuple is the address + /// that the relocation applies to. + type DynamicRelocationIterator: Iterator; + + /// Get the architecture type of the file. + fn architecture(&self) -> Architecture; + + /// Get the sub-architecture type of the file if known. + /// + /// A value of `None` has a range of meanings: the file supports all + /// sub-architectures, the file does not explicitly specify a + /// sub-architecture, or the sub-architecture is currently unrecognized. + fn sub_architecture(&self) -> Option { + None + } + + /// Get the endianness of the file. + #[inline] + fn endianness(&self) -> Endianness { + if self.is_little_endian() { + Endianness::Little + } else { + Endianness::Big + } + } + + /// Return true if the file is little endian, false if it is big endian. + fn is_little_endian(&self) -> bool; + + /// Return true if the file can contain 64-bit addresses. + fn is_64(&self) -> bool; + + /// Return the kind of this object. + fn kind(&self) -> ObjectKind; + + /// Get an iterator for the loadable segments in the file. + /// + /// For ELF, this is program headers with type [`PT_LOAD`](crate::elf::PT_LOAD). + /// For Mach-O, this is load commands with type [`LC_SEGMENT`](crate::macho::LC_SEGMENT) + /// or [`LC_SEGMENT_64`](crate::macho::LC_SEGMENT_64). + /// For PE, this is all sections. + fn segments(&'file self) -> Self::SegmentIterator; + + /// Get the section named `section_name`, if such a section exists. + /// + /// If `section_name` starts with a '.' then it is treated as a system section name, + /// and is compared using the conventions specific to the object file format. This + /// includes: + /// - if ".debug_str_offsets" is requested for a Mach-O object file, then the actual + /// section name that is searched for is "__debug_str_offs". + /// - if ".debug_info" is requested for an ELF object file, then + /// ".zdebug_info" may be returned (and similarly for other debug sections). + /// + /// For some object files, multiple segments may contain sections with the same + /// name. In this case, the first matching section will be used. + /// + /// This method skips over sections with invalid names. + fn section_by_name(&'file self, section_name: &str) -> Option { + self.section_by_name_bytes(section_name.as_bytes()) + } + + /// Like [`Self::section_by_name`], but allows names that are not UTF-8. + fn section_by_name_bytes(&'file self, section_name: &[u8]) -> Option; + + /// Get the section at the given index. + /// + /// The meaning of the index depends on the object file. + /// + /// For some object files, this requires iterating through all sections. + /// + /// Returns an error if the index is invalid. + fn section_by_index(&'file self, index: SectionIndex) -> Result; + + /// Get an iterator for the sections in the file. + fn sections(&'file self) -> Self::SectionIterator; + + /// Get an iterator for the COMDAT section groups in the file. + fn comdats(&'file self) -> Self::ComdatIterator; + + /// Get the debugging symbol table, if any. + fn symbol_table(&'file self) -> Option; + + /// Get the debugging symbol at the given index. + /// + /// The meaning of the index depends on the object file. + /// + /// Returns an error if the index is invalid. + fn symbol_by_index(&'file self, index: SymbolIndex) -> Result; + + /// Get an iterator for the debugging symbols in the file. + /// + /// This may skip over symbols that are malformed or unsupported. + /// + /// For Mach-O files, this does not include STAB entries. + fn symbols(&'file self) -> Self::SymbolIterator; + + /// Get the symbol named `symbol_name`, if the symbol exists. + fn symbol_by_name(&'file self, symbol_name: &str) -> Option { + self.symbol_by_name_bytes(symbol_name.as_bytes()) + } + + /// Like [`Self::symbol_by_name`], but allows names that are not UTF-8. + fn symbol_by_name_bytes(&'file self, symbol_name: &[u8]) -> Option { + self.symbols() + .find(|sym| sym.name_bytes() == Ok(symbol_name)) + } + + /// Get the dynamic linking symbol table, if any. + /// + /// Only ELF has a separate dynamic linking symbol table. + /// Consider using [`Self::exports`] or [`Self::imports`] instead. + fn dynamic_symbol_table(&'file self) -> Option; + + /// Get an iterator for the dynamic linking symbols in the file. + /// + /// This may skip over symbols that are malformed or unsupported. + /// + /// Only ELF has dynamic linking symbols. + /// Other file formats will return an empty iterator. + /// Consider using [`Self::exports`] or [`Self::imports`] instead. + fn dynamic_symbols(&'file self) -> Self::SymbolIterator; + + /// Get the dynamic relocations for this file. + /// + /// Symbol indices in these relocations refer to the dynamic symbol table. + /// + /// Only ELF has dynamic relocations. + fn dynamic_relocations(&'file self) -> Option; + + /// Construct a map from addresses to symbol names. + /// + /// The map will only contain defined text and data symbols. + /// The dynamic symbol table will only be used if there are no debugging symbols. + fn symbol_map(&'file self) -> SymbolMap> { + let mut symbols = Vec::new(); + if let Some(table) = self.symbol_table().or_else(|| self.dynamic_symbol_table()) { + // Sometimes symbols share addresses. Collect them all then choose the "best". + let mut all_symbols = Vec::new(); + for symbol in table.symbols() { + // Must have an address. + if !symbol.is_definition() { + continue; + } + // Must have a name. + let name = match symbol.name() { + Ok(name) => name, + _ => continue, + }; + if name.is_empty() { + continue; + } + + // Lower is better. + let mut priority = 0u32; + + // Prefer known kind. + match symbol.kind() { + SymbolKind::Text | SymbolKind::Data => {} + SymbolKind::Unknown => priority += 1, + _ => continue, + } + priority *= 2; + + // Prefer global visibility. + priority += match symbol.scope() { + SymbolScope::Unknown => 3, + SymbolScope::Compilation => 2, + SymbolScope::Linkage => 1, + SymbolScope::Dynamic => 0, + }; + priority *= 4; + + // Prefer later entries (earlier symbol is likely to be less specific). + let index = !0 - symbol.index().0; + + // Tuple is ordered for sort. + all_symbols.push((symbol.address(), priority, index, name)); + } + // Unstable sort is okay because tuple includes index. + all_symbols.sort_unstable(); + + let mut previous_address = !0; + for (address, _priority, _index, name) in all_symbols { + if address != previous_address { + symbols.push(SymbolMapName::new(address, name)); + previous_address = address; + } + } + } + SymbolMap::new(symbols) + } + + /// Construct a map from addresses to symbol names and object file names. + /// + /// This is derived from Mach-O STAB entries. + fn object_map(&'file self) -> ObjectMap<'data> { + ObjectMap::default() + } + + /// Get the imported symbols. + fn imports(&self) -> Result>>; + + /// Get the exported symbols that expose both a name and an address. + /// + /// Some file formats may provide other kinds of symbols that can be retrieved using + /// the low level API. + fn exports(&self) -> Result>>; + + /// Return true if the file contains DWARF debug information sections, false if not. + fn has_debug_symbols(&self) -> bool; + + /// The UUID from a Mach-O [`LC_UUID`](crate::macho::LC_UUID) load command. + #[inline] + fn mach_uuid(&self) -> Result> { + Ok(None) + } + + /// The build ID from an ELF [`NT_GNU_BUILD_ID`](crate::elf::NT_GNU_BUILD_ID) note. + #[inline] + fn build_id(&self) -> Result> { + Ok(None) + } + + /// The filename and CRC from a `.gnu_debuglink` section. + #[inline] + fn gnu_debuglink(&self) -> Result> { + Ok(None) + } + + /// The filename and build ID from a `.gnu_debugaltlink` section. + #[inline] + fn gnu_debugaltlink(&self) -> Result> { + Ok(None) + } + + /// The filename and GUID from the PE CodeView section. + #[inline] + fn pdb_info(&self) -> Result>> { + Ok(None) + } + + /// Get the base address used for relative virtual addresses. + /// + /// Currently this is only non-zero for PE. + fn relative_address_base(&'file self) -> u64; + + /// Get the virtual address of the entry point of the binary. + fn entry(&'file self) -> u64; + + /// File flags that are specific to each file format. + fn flags(&self) -> FileFlags; +} + +/// A loadable segment in an [`Object`]. +/// +/// This trait is part of the unified read API. +pub trait ObjectSegment<'data>: read::private::Sealed { + /// Returns the virtual address of the segment. + fn address(&self) -> u64; + + /// Returns the size of the segment in memory. + fn size(&self) -> u64; + + /// Returns the alignment of the segment in memory. + fn align(&self) -> u64; + + /// Returns the offset and size of the segment in the file. + fn file_range(&self) -> (u64, u64); + + /// Returns a reference to the file contents of the segment. + /// + /// The length of this data may be different from the size of the + /// segment in memory. + fn data(&self) -> Result<&'data [u8]>; + + /// Return the segment data in the given range. + /// + /// Returns `Ok(None)` if the segment does not contain the given range. + fn data_range(&self, address: u64, size: u64) -> Result>; + + /// Returns the name of the segment. + fn name_bytes(&self) -> Result>; + + /// Returns the name of the segment. + /// + /// Returns an error if the name is not UTF-8. + fn name(&self) -> Result>; + + /// Return the flags of segment. + fn flags(&self) -> SegmentFlags; +} + +/// A section in an [`Object`]. +/// +/// This trait is part of the unified read API. +pub trait ObjectSection<'data>: read::private::Sealed { + /// An iterator for the relocations for a section. + /// + /// The first field in the item tuple is the section offset + /// that the relocation applies to. + type RelocationIterator: Iterator; + + /// Returns the section index. + fn index(&self) -> SectionIndex; + + /// Returns the address of the section. + fn address(&self) -> u64; + + /// Returns the size of the section in memory. + fn size(&self) -> u64; + + /// Returns the alignment of the section in memory. + fn align(&self) -> u64; + + /// Returns offset and size of on-disk segment (if any). + fn file_range(&self) -> Option<(u64, u64)>; + + /// Returns the raw contents of the section. + /// + /// The length of this data may be different from the size of the + /// section in memory. + /// + /// This does not do any decompression. + fn data(&self) -> Result<&'data [u8]>; + + /// Return the raw contents of the section data in the given range. + /// + /// This does not do any decompression. + /// + /// Returns `Ok(None)` if the section does not contain the given range. + fn data_range(&self, address: u64, size: u64) -> Result>; + + /// Returns the potentially compressed file range of the section, + /// along with information about the compression. + fn compressed_file_range(&self) -> Result; + + /// Returns the potentially compressed contents of the section, + /// along with information about the compression. + fn compressed_data(&self) -> Result>; + + /// Returns the uncompressed contents of the section. + /// + /// The length of this data may be different from the size of the + /// section in memory. + /// + /// If no compression is detected, then returns the data unchanged. + /// Returns `Err` if decompression fails. + fn uncompressed_data(&self) -> Result> { + self.compressed_data()?.decompress() + } + + /// Returns the name of the section. + fn name_bytes(&self) -> Result<&[u8]>; + + /// Returns the name of the section. + /// + /// Returns an error if the name is not UTF-8. + fn name(&self) -> Result<&str>; + + /// Returns the name of the segment for this section. + fn segment_name_bytes(&self) -> Result>; + + /// Returns the name of the segment for this section. + /// + /// Returns an error if the name is not UTF-8. + fn segment_name(&self) -> Result>; + + /// Return the kind of this section. + fn kind(&self) -> SectionKind; + + /// Get the relocations for this section. + fn relocations(&self) -> Self::RelocationIterator; + + /// Section flags that are specific to each file format. + fn flags(&self) -> SectionFlags; +} + +/// A COMDAT section group in an [`Object`]. +/// +/// This trait is part of the unified read API. +pub trait ObjectComdat<'data>: read::private::Sealed { + /// An iterator for the sections in the section group. + type SectionIterator: Iterator; + + /// Returns the COMDAT selection kind. + fn kind(&self) -> ComdatKind; + + /// Returns the index of the symbol used for the name of COMDAT section group. + fn symbol(&self) -> SymbolIndex; + + /// Returns the name of the COMDAT section group. + fn name_bytes(&self) -> Result<&[u8]>; + + /// Returns the name of the COMDAT section group. + /// + /// Returns an error if the name is not UTF-8. + fn name(&self) -> Result<&str>; + + /// Get the sections in this section group. + fn sections(&self) -> Self::SectionIterator; +} + +/// A symbol table in an [`Object`]. +/// +/// This trait is part of the unified read API. +pub trait ObjectSymbolTable<'data>: read::private::Sealed { + /// A symbol table entry. + type Symbol: ObjectSymbol<'data>; + + /// An iterator for the symbols in a symbol table. + type SymbolIterator: Iterator; + + /// Get an iterator for the symbols in the table. + /// + /// This may skip over symbols that are malformed or unsupported. + fn symbols(&self) -> Self::SymbolIterator; + + /// Get the symbol at the given index. + /// + /// The meaning of the index depends on the object file. + /// + /// Returns an error if the index is invalid. + fn symbol_by_index(&self, index: SymbolIndex) -> Result; +} + +/// A symbol table entry in an [`Object`]. +/// +/// This trait is part of the unified read API. +pub trait ObjectSymbol<'data>: read::private::Sealed { + /// The index of the symbol. + fn index(&self) -> SymbolIndex; + + /// The name of the symbol. + fn name_bytes(&self) -> Result<&'data [u8]>; + + /// The name of the symbol. + /// + /// Returns an error if the name is not UTF-8. + fn name(&self) -> Result<&'data str>; + + /// The address of the symbol. May be zero if the address is unknown. + fn address(&self) -> u64; + + /// The size of the symbol. May be zero if the size is unknown. + fn size(&self) -> u64; + + /// Return the kind of this symbol. + fn kind(&self) -> SymbolKind; + + /// Returns the section where the symbol is defined. + fn section(&self) -> SymbolSection; + + /// Returns the section index for the section containing this symbol. + /// + /// May return `None` if the symbol is not defined in a section. + fn section_index(&self) -> Option { + self.section().index() + } + + /// Return true if the symbol is undefined. + fn is_undefined(&self) -> bool; + + /// Return true if the symbol is a definition of a function or data object + /// that has a known address. + /// + /// This is primarily used to implement [`Object::symbol_map`]. + fn is_definition(&self) -> bool; + + /// Return true if the symbol is common data. + /// + /// Note: does not check for [`SymbolSection::Section`] with [`SectionKind::Common`]. + fn is_common(&self) -> bool; + + /// Return true if the symbol is weak. + fn is_weak(&self) -> bool; + + /// Returns the symbol scope. + fn scope(&self) -> SymbolScope; + + /// Return true if the symbol visible outside of the compilation unit. + /// + /// This treats [`SymbolScope::Unknown`] as global. + fn is_global(&self) -> bool; + + /// Return true if the symbol is only visible within the compilation unit. + fn is_local(&self) -> bool; + + /// Symbol flags that are specific to each file format. + fn flags(&self) -> SymbolFlags; +} + +/// An iterator for files that don't have dynamic relocations. +#[derive(Debug)] +pub struct NoDynamicRelocationIterator; + +impl Iterator for NoDynamicRelocationIterator { + type Item = (u64, Relocation); + + #[inline] + fn next(&mut self) -> Option { + None + } +} -- cgit v1.2.3