Struct crate_metadata::LoadedCrate

pub struct LoadedCrate {
    pub crate_name: StrRef,
    pub object_file: FileRef,
    pub debug_symbols_file: WeakFileRef,
    pub sections: HashMap<Shndx, StrongSectionRef>,
    pub text_pages: Option<(Arc<Mutex<MappedPages>>, Range<VirtualAddress>)>,
    pub rodata_pages: Option<(Arc<Mutex<MappedPages>>, Range<VirtualAddress>)>,
    pub data_pages: Option<(Arc<Mutex<MappedPages>>, Range<VirtualAddress>)>,
    pub global_sections: BTreeSet<Shndx>,
    pub tls_sections: BTreeSet<Shndx>,
    pub cls_sections: BTreeSet<Shndx>,
    pub data_sections: BTreeSet<Shndx>,
    pub reexported_symbols: BTreeSet<StrRef>,
}

Represents a single crate whose object file has been loaded and linked into at least one CrateNamespace.

Fields

crate_name: StrRef

The name of this crate.

object_file: FileRef

The object file that this crate was loaded from.

debug_symbols_file: WeakFileRef

The file that contains debug symbols for this crate. Debug symbols may exist in several forms:

• In the same file as the object_file above, i.e., not stripped,
• As a separate file that was stripped off from the original object file,
• Not at all (no debug symbols available for this crate).

By default, the constructor for LoadedCrate assumes the first form, so it will initialize this to a weak reference to the LoadedCrate’s object_file field. If that is not the case, then this field should be set differently once the crate is initialized or once a debug symbol file becomes available or requested.

sections: HashMap<Shndx, StrongSectionRef>

A map containing all the sections in this crate. In general we’re only interested the values (the LoadedSections themselves), but we keep each section’s shndx (section header index from its crate’s ELF file) as the key because it helps us quickly handle relocations and crate swapping.

text_pages: Option<(Arc<Mutex<MappedPages>>, Range<VirtualAddress>)>

A tuple of:

1. The MappedPages that contain sections that are readable and executable, but not writable, i.e., the .text sections for this crate,
2. The range of virtual addresses covered by this mapping.

rodata_pages: Option<(Arc<Mutex<MappedPages>>, Range<VirtualAddress>)>

A tuple of:

1. The MappedPages that contain sections that are read-only, not writable nor executable, i.e., the .rodata, .eh_frame, and .gcc_except_table sections for this crate,
2. The range of virtual addresses covered by this mapping.

data_pages: Option<(Arc<Mutex<MappedPages>>, Range<VirtualAddress>)>

A tuple of:

1. The MappedPages that contain sections that are readable and writable but not executable, i.e., the .data and .bss sections for this crate,
2. The range of virtual addresses covered by this mapping.

global_sections: BTreeSet<Shndx>

The set of global symbols in this crate, including regular ones that are prefixed with the crate_name and no_mangle symbols that are not. The Shndx values in this set are the section index (shndx) numbers, which can be used as the key to look up the actual LoadedSection in the sections list above.

tls_sections: BTreeSet<Shndx>

The set of thread-local storage (TLS) symbols in this crate. The Shndx values in this set are the section index (shndx) numbers, which can be used as the key to look up the actual LoadedSection in the sections list above.

cls_sections: BTreeSet<Shndx>

The set of CPU-local storage (CLS) symbols in this crate.

data_sections: BTreeSet<Shndx>

The set of .data and .bss sections in this crate. The Shndx values in this set are the section index (shndx) numbers, which can be used as the key to look up the actual LoadedSection in the sections list above.

reexported_symbols: BTreeSet<StrRef>

The set of symbols that this crate’s global symbols are reexported under, i.e., they have been added to the enclosing CrateNamespace’s symbol map under these names.

This is primarily used when swapping crates, and it is useful in the following way. If this crate is the new crate that is swapped in to replace another crate, and the caller of the swap_crates() function specifies that this crate should expose its symbols with names that match the old crate it’s replacing, then this will be populated with the names of corresponding symbols from the old crate that its replacing. For example, if this crate has a symbol keyboard::init::h456, and it replaced an older crate that had the symbol keyboard::init::123, and reexport_new_symbols_as_old was true, then keyboard::init::h123 will be added to this set.

When a crate is first loaded, this will be empty by default, because this crate will only have populated its global_sections set during loading.

Implementations

impl LoadedCrate

pub fn get_function_section(&self, func_name: &str) -> Option<&StrongSectionRef>

Returns the LoadedSection of type SectionType::Text that matches the requested function name, if it exists in this LoadedCrate. Only matches demangled names, e.g., “my_crate::foo”.

pub fn data_sections_iter(&self) -> impl Iterator<Item = &StrongSectionRef>

A convenience function to iterate over only the data (.data or .bss) sections in this crate.

pub fn global_sections_iter(&self) -> impl Iterator<Item = &StrongSectionRef>

A convenience function to iterate over only the global (public) sections in this crate.

pub fn find_section<F>(&self, predicate: F) -> Option<&StrongSectionRef>where F: Fn(&LoadedSection) -> bool,

Returns the first LoadedSection that matches the given predicate, i.e., for which the predicate closure returns true.

If you need to check for multiple matches, then it’s best to iterate over the sections in this crate yourself.

pub fn crate_name_without_hash(&self) -> &str

Returns the substring of this crate’s name that excludes the trailing hash. If there is no hash, then it returns the entire name.

pub fn crate_name_as_prefix(&self) -> String

Returns this crate name as a symbol prefix, including a trailing “::”. If there is no hash, then it returns the entire name with a trailing “::”.

Example

• Crate name: “device_manager-e3769b63863a4030”, return value: “device_manager::”
• Crate name: “hello” return value: "hello::`“

pub fn crates_dependent_on_me(&self) -> Vec<WeakCrateRef>

Currently may contain duplicates!

pub fn crates_i_depend_on(&self) -> Vec<WeakCrateRef>

Returns the set of crates that this crate depends on. Only includes direct dependencies “one hop” away, not recursive dependencies “multiples hops” away.

Currently, the list may include duplicates. The caller is responsible for filtering out duplicates when using the list.

Trait Implementations

impl Debug for LoadedCrate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for LoadedCrate

fn drop(&mut self)

Executes the destructor for this type.