Struct crate_metadata::LoadedSection

#[non_exhaustive]
pub struct LoadedSection {
    pub name: StrRef,
    pub typ: SectionType,
    pub global: bool,
    pub mapped_pages: Arc<Mutex<MappedPages>>,
    pub mapped_pages_offset: usize,
    pub virt_addr: VirtualAddress,
    pub size: usize,
    pub parent_crate: WeakCrateRef,
    pub inner: RwLock<LoadedSectionInner>,
}

Represents a section that has been loaded and is part of a LoadedCrate. The containing SectionType enum determines which type of section it is.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: StrRef

The full string name of this section, a fully-qualified symbol, with the format <crate>::[<module>::][<struct>::]<fn_name>::<hash>. The unique hash is generated for each section by the Rust compiler, which can be used as a version identifier. Not all symbols will have a hash, e.g., ones that are not mangled.

Examples

• test_lib::MyStruct::new::h843a613894da0c24
• my_crate::my_function::hbce878984534ceda

typ: SectionType

The type of this section, e.g., .text, .rodata, .data, .bss, etc.

global: bool

Whether or not this section’s symbol was exported globally (is public)

mapped_pages: Arc<Mutex<MappedPages>>

The MappedPages that cover this section.

mapped_pages_offset: usize

The offset into the mapped_pages where this section starts

virt_addr: VirtualAddress

The starting VirtualAddress of this section (except for TLS sections).

For TLS sections, this is not a VirtualAddress, but rather the offset (from the TLS base) into the TLS area where this section’s data exists.

For all other sections, this is simply a performance optimization that avoids having to calculate its starting virtual address by invoking self.mapped_pages.address_at_offset(self.mapped_pages_offset).

size: usize

The size in bytes of this section.

parent_crate: WeakCrateRef

The LoadedCrate object that contains/owns this section

inner: RwLock<LoadedSectionInner>

The inner contents of a section that could possibly change after the section was initially loaded and linked.

Implementations

impl LoadedSection

pub fn new( typ: SectionType, name: StrRef, mapped_pages: Arc<Mutex<MappedPages>>, mapped_pages_offset: usize, virt_addr: VirtualAddress, size: usize, global: bool, parent_crate: WeakCrateRef ) -> LoadedSection

Create a new LoadedSection, with an empty dependencies list.

pub fn with_dependencies( typ: SectionType, name: StrRef, mapped_pages: Arc<Mutex<MappedPages>>, mapped_pages_offset: usize, virt_addr: VirtualAddress, size: usize, global: bool, parent_crate: WeakCrateRef, sections_i_depend_on: Vec<StrongDependency>, sections_dependent_on_me: Vec<WeakDependent> ) -> LoadedSection

Same as [new()](#method.new), but uses the given dependencies` instead of the default empty list.

pub fn name_without_hash(&self) -> &str

Returns the substring of this section’s name that excludes the trailing hash.

See the identical associated function section_name_without_hash() for more.

pub fn section_name_without_hash(sec_name: &str) -> &str

Returns the substring of the given section’s name that excludes the trailing hash, but includes the hash delimiter “::h”. If there is no hash, then it returns the full section name unchanged.

Examples

name: “keyboard_new::init::h832430094f98e56b”, return value: “keyboard_new::init::h” name: “start_me”, return value: “start_me”

pub fn find_weak_dependent( &self, matching_section: &StrongSectionRef ) -> Option<usize>

Returns the index of the first WeakDependent object in this LoadedSection’s sections_dependent_on_me list in which the section matches the given matching_section

pub fn copy_section_data_to( &self, destination_section: &LoadedSection ) -> Result<(), &'static str>

Copies the actual data contents of this LoadedSection to the given destination_section. The following conditions must be met:

• The two sections must be from different crates (different parent crates),
• The two sections must have the same size,
• The given destination_section must be mapped as writable, basically, it must be a .data or .bss section.

pub unsafe fn as_func<F>(&self) -> Result<&F, &'static str>

Reinterprets this section’s underlying MappedPages memory region as an executable function.

The generic F parameter is the function type signature itself, e.g., fn(String) -> u8.

Returns a reference to the function that is formed from the underlying memory region, with a lifetime dependent upon the lifetime of this section.

Safety

The type signature of F must match the type signature of the function.

Locking

Obtains the lock on this section’s MappedPages object.

Note

Ideally, we would use debug information to know the size of the entire function and test whether that fits within the bounds of the memory region, rather than just checking the size of F, the function pointer/signature. Without debug information, checking the size is restricted to in-bounds memory safety rather than actual functional correctness.

Examples

Here’s how you might call this function:

type MyPrintFuncSignature = fn(&str) -> Result<(), &'static str>;
let section = mod_mgmt::get_symbol_starting_with("my_crate::print::").upgrade().unwrap();
let print_func: &MyPrintFuncSignature = unsafe { section.as_func() }.unwrap();
print_func("hello there");

Trait Implementations

impl Debug for LoadedSection

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

Formats the value using the given formatter.

impl Display for LoadedSection

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

Formats the value using the given formatter.