wasmtime_environ/
obj.rs

1//! Utilities for working with object files that operate as Wasmtime's
2//! serialization and intermediate format for compiled modules.
3
4use core::fmt;
5
6/// Filler for the `os_abi` field of the ELF header.
7///
8/// This is just a constant that seems reasonable in the sense it's unlikely to
9/// clash with others.
10pub const ELFOSABI_WASMTIME: u8 = 200;
11
12/// Flag for the `e_flags` field in the ELF header indicating a compiled
13/// module.
14pub const EF_WASMTIME_MODULE: u32 = 1 << 0;
15
16/// Flag for the `e_flags` field in the ELF header indicating a compiled
17/// component.
18pub const EF_WASMTIME_COMPONENT: u32 = 1 << 1;
19
20/// Flag for the `e_flags` field in the ELF header indicating compiled code for
21/// pulley32
22pub const EF_WASMTIME_PULLEY32: u32 = 1 << 2;
23
24/// Flag for the `e_flags` field in the ELF header indicating compiled code for
25/// pulley64
26pub const EF_WASMTIME_PULLEY64: u32 = 1 << 3;
27
28/// Flag for the `sh_flags` field in the ELF text section that indicates that
29/// the text section does not itself need to be executable. This is used for the
30/// Pulley target, for example, to indicate that it does not need to be made
31/// natively executable as it does not contain actual native code.
32pub const SH_WASMTIME_NOT_EXECUTED: u64 = 1 << 0;
33
34/// A custom Wasmtime-specific section of our compilation image which stores
35/// mapping data from offsets in the image to offset in the original wasm
36/// binary.
37///
38/// This section's format is defined by the documentation of the
39/// `crate::compile::AddressMapSection` data structure, which builds it. It is
40/// decoded by `lookup_file_pos`. Its offsets are relative to the start of the
41/// text section.
42pub const ELF_WASMTIME_ADDRMAP: &str = ".wasmtime.addrmap";
43
44/// A custom Wasmtime-specific section of compilation which store information
45/// about live gc references at various locations in the text section (stack
46/// maps).
47///
48/// This section has a custom binary encoding described in `stack_maps.rs` which
49/// is used to implement the single query we want to satisfy of: where are the
50/// live GC references at this pc? Like the addrmap section this has an
51/// alignment of 1 with unaligned reads, and it additionally doesn't support
52/// >=4gb text sections.
53pub const ELF_WASMTIME_STACK_MAP: &str = ".wasmtime.stackmap";
54
55/// A custom binary-encoded section of wasmtime compilation artifacts which
56/// encodes the ability to map an offset in the text section to the trap code
57/// that it corresponds to.
58///
59/// This section is used at runtime to determine what flavor of trap happened
60/// to ensure that embedders and debuggers know the reason for the wasm trap.
61///
62/// This section's format is defined by the documentation of the
63/// `crate::compile::TrapEncodingBuilder` data structure, which builds it. It
64/// is decoded by `lookup_trap_code`. Its offsets are relative to the start of
65/// the text section.
66pub const ELF_WASMTIME_TRAPS: &str = ".wasmtime.traps";
67
68/// A custom binary-encoded section of the wasmtime compilation
69/// artifacts which encodes exception tables.
70///
71/// This section is used at runtime to allow the unwinder to find
72/// exception handler blocks active at particular callsites.
73///
74/// This section's format is defined by the `ExceptionTableBuilder` data
75/// structure. Its code offsets are relative to the start of the text segment.
76pub const ELF_WASMTIME_EXCEPTIONS: &str = ".wasmtime.exceptions";
77
78/// A custom binary-encoded section of the wasmtime compilation
79/// artifacts which encodes frame tables.
80///
81/// This section is used at runtime to allow debug APIs to decode Wasm
82/// VM-level state from state stack slots.
83///
84/// This section's format is defined by the
85/// [`crate::compile::FrameTableBuilder`] data structure. Its code
86/// offsets are relative to the start of the text segment.
87pub const ELF_WASMTIME_FRAMES: &str = ".wasmtime.frames";
88
89/// A custom section which consists of just 1 byte which is either 0 or 1 as to
90/// whether BTI is enabled.
91pub const ELF_WASM_BTI: &str = ".wasmtime.bti";
92
93/// A bincode-encoded section containing engine-specific metadata used to
94/// double-check that an artifact can be loaded into the current host.
95pub const ELF_WASM_ENGINE: &str = ".wasmtime.engine";
96
97/// This is the name of the section in the final ELF image which contains
98/// concatenated data segments from the original wasm module.
99///
100/// This section is simply a list of bytes and ranges into this section are
101/// stored within a `Module` for each data segment. Memory initialization and
102/// passive segment management all index data directly located in this section.
103///
104/// Note that this implementation does not afford any method of leveraging the
105/// `data.drop` instruction to actually release the data back to the OS. The
106/// data section is simply always present in the ELF image. If we wanted to
107/// release the data it's probably best to figure out what the best
108/// implementation is for it at the time given a particular set of constraints.
109pub const ELF_WASM_DATA: &'static str = ".rodata.wasm";
110
111/// This is the name of the section in the final ELF image which contains a
112/// `bincode`-encoded `CompiledModuleInfo`.
113///
114/// This section is optionally decoded in `CompiledModule::from_artifacts`
115/// depending on whether or not a `CompiledModuleInfo` is already available. In
116/// cases like `Module::new` where compilation directly leads into consumption,
117/// it's available. In cases like `Module::deserialize` this section must be
118/// decoded to get all the relevant information.
119pub const ELF_WASMTIME_INFO: &'static str = ".wasmtime.info";
120
121/// This is the name of the section in the final ELF image which contains a
122/// concatenated list of all function names.
123///
124/// This section is optionally included in the final artifact depending on
125/// whether the wasm module has any name data at all (or in the future if we add
126/// an option to not preserve name data). This section is a concatenated list of
127/// strings where `CompiledModuleInfo::func_names` stores offsets/lengths into
128/// this section.
129///
130/// Note that the goal of this section is to avoid having to decode names at
131/// module-load time if we can. Names are typically only used for debugging or
132/// things like backtraces so there's no need to eagerly load all of them. By
133/// storing the data in a separate section the hope is that the data, which is
134/// sometimes quite large (3MB seen for spidermonkey-compiled-to-wasm), can be
135/// paged in lazily from an mmap and is never paged in if we never reference it.
136pub const ELF_NAME_DATA: &'static str = ".name.wasm";
137
138/// This is the name of the section in the final ELF image that contains the
139/// concatenation of all the native DWARF information found in the original wasm
140/// files.
141///
142/// This concatenation is not intended to be read by external tools at this time
143/// and is instead indexed directly by relative indices stored in compilation
144/// metadata.
145pub const ELF_WASMTIME_DWARF: &str = ".wasmtime.dwarf";
146
147/// This is the name of the section in the final ELF image which contains the
148/// original Wasm bytecode for the module, preserved verbatim to support
149/// debugger access to the source bytecode.
150///
151/// This section is only emitted when the `guest-debug` tunable is enabled at
152/// compile time. Its contents are the concatenated raw bytes of all core
153/// module Wasm binaries in the artifact.
154pub const ELF_WASMTIME_WASM_BYTECODE: &str = ".wasmtime.wasm_bytecode";
155
156/// This is the name of the companion section to [`ELF_WASMTIME_WASM_BYTECODE`]
157/// that stores the end-offset table used to locate individual module bytecodes
158/// within the concatenated data.
159///
160/// The section contains one little-endian `u32` per core module in
161/// the artifact giving the *end* of that module's bytecode in the
162/// concatenated bytecode section above.
163pub const ELF_WASMTIME_WASM_BYTECODE_ENDS: &str = ".wasmtime.wasm_bytecode_ends";
164
165/// Workaround to implement `core::error::Error` until
166/// gimli-rs/object#747 is settled.
167pub struct ObjectCrateErrorWrapper(pub object::Error);
168
169impl fmt::Debug for ObjectCrateErrorWrapper {
170    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
171        self.0.fmt(f)
172    }
173}
174
175impl fmt::Display for ObjectCrateErrorWrapper {
176    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
177        self.0.fmt(f)
178    }
179}
180
181impl core::error::Error for ObjectCrateErrorWrapper {}
wasmtime_environ/obj.rs

wasmtime_environ/
obj.rs
