Crate crate_metadata

source ·
Expand description

Defines types that contain metadata about crates loaded in Theseus and their dependencies.

Representing dependencies between sections

If one section A references or uses another section B, then we colloquially say that A depends on B.

In this scenario, A has a StrongDependency on B, and B has a WeakDependent pointing back to A.

Assuming A and B are both LoadedSection objects, then A.sections_i_depend_on includes a StrongDependency(B) and B.sections_dependent_on_me includes a WeakDependent(A).

In this way, the dependency graphs are fully associative, allowing a given LoadedSection to easily find both its dependencies and its dependents instantly.

More importantly, it allows A to be dropped before B, but not the other way around. This correctly avoids dependency violations by ensuring that a section B is never dropped while any other section A relies on it.

When swapping crates, the WeakDependents are actually more useful. For example, if we want to swap the crate that contains section B1 with a new one B2, then we can immediately find all of the section As that depend on B1 by iterating over B1.sections_dependent_on_me. To complete the swap and fully replace B1 with B2, we would do the following (pseudocode):

for secA in B1.sections_dependent_on_me {     
    change secA's relocation to point to B1     
    add WeakDependent(secA) to B2.sections_dependent_on_me     
    remove StrongDependency(B1) from secA.sections_i_depend_on     
    add StrongDependency(B2) to secA.sections_i_depend_on      
    remove WeakDependent(secA) from B1.sections_dependent_on_me (current iterator)     
}

Structs

Represents a single crate whose object file has been loaded and linked into at least one CrateNamespace.
Represents a section that has been loaded and is part of a LoadedCrate. The containing SectionType enum determines which type of section it is.
The parts of a LoadedSection that may be mutable, i.e., only the parts that could change after a section is initially loaded and linked.
The information necessary to calculate and write a relocation value, based on a source section and a target section, in which a value based on the location of the source section is written somwhere in the target section.
A wrapper around an Arc<str>: an immutable shared reference to a string slice.
A representation that the owner A of (a LoadedSection object containing) this struct depends on the given section B in this struct. The dependent section A is not specifically included here; since it’s the owner of this struct, it’s implicit that it’s the dependent one.
A representation that the section A in this struct depends on the owner B of (the LoadedSection object containing) this struct. The target dependency B is not specifically included here; it’s implicitly the owner of this struct.

Enums

The type of a crate, based on its object file naming convention. This naming convention is only used for crate object files that come from bootloader-provided modules, which the Theseus makefile assigns at build time.
The possible types of sections that can be loaded from a crate object file.

Constants

A crate’s name and its hash are separated by “-”, i.e., “my_crate-hash”.
.data and .bss sections are read-write and non-executable.
The Theseus Makefile appends prefixes onto bootloader module names, which are separated by the “#” character. For example, “k#my_crate-hash.o”.
.rodata sections are read-only and non-executable.
A section’s demangled name and its hash are separated by “::h”, e.g., "my_crate::section_name::h<hash>".
.text sections are read-only and executable.

Functions

Returns the default name for the given SectionType as a StrRef.
Actually write the value of a relocation entry.

Type Definitions

A Section Header iNDeX (SHNDX), as specified by the ELF format. Even though this is typically encoded as a u16, its decoded form can exceed the max size of u16.
A Strong reference to a LoadedCrate.
A Strong reference (Arc) to a LoadedSection.
A Weak reference to a LoadedCrate.
A Weak reference (Weak) to a LoadedSection.