Crate crate_metadata

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

LoadedCrate

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

LoadedSection

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

LoadedSectionInner

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.

RelocationEntry

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.

StrRef

A wrapper around an Arc<str>: an immutable shared reference to a string slice.

StrongDependency

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.

WeakDependent

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

CrateType

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.

SectionType

The possible types of sections that can be loaded from a crate object file.

Constants

BSS_SECTION_NAME

CRATE_HASH_DELIMITER

A crate’s name and its hash are separated by “-”, i.e., “my_crate-hash”.

DATA_BSS_SECTION_FLAGS

.data and .bss sections are read-write and non-executable.

DATA_SECTION_NAME

EH_FRAME_SECTION_NAME

GCC_EXCEPT_TABLE_SECTION_NAME

MODULE_PREFIX_DELIMITER

The Theseus Makefile appends prefixes onto bootloader module names, which are separated by the “#” character. For example, “k#my_crate-hash.o”.

RODATA_SECTION_FLAGS

.rodata sections are read-only and non-executable.

RODATA_SECTION_NAME

SECTION_HASH_DELIMITER

A section’s demangled name and its hash are separated by “::h”, e.g., "my_crate::section_name::h<hash>".

TEXT_SECTION_FLAGS

.text sections are read-only and executable.

TEXT_SECTION_NAME

TLS_BSS_SECTION_NAME

TLS_DATA_SECTION_NAME

Functions

section_name_str_ref

Returns the default name for the given SectionType as a StrRef.

write_relocation

Actually write the value of a relocation entry.

Type Definitions

Shndx

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.

StrongCrateRef

A Strong reference to a LoadedCrate.

StrongSectionRef

A Strong reference (Arc) to a LoadedSection.

WeakCrateRef

A Weak reference to a LoadedCrate.

WeakSectionRef

A Weak reference (Weak) to a LoadedSection.