cranelift_module/
module.rs

1//! Defines `Module` and related types.
2
3// TODO: Should `ir::Function` really have a `name`?
4
5// TODO: Factor out `ir::Function`'s `ext_funcs` and `global_values` into a struct
6// shared with `DataDescription`?
7
8use super::HashMap;
9use crate::data_context::DataDescription;
10use core::fmt::Display;
11use cranelift_codegen::binemit::{CodeOffset, Reloc};
12use cranelift_codegen::entity::{PrimaryMap, entity_impl};
13use cranelift_codegen::ir::ExternalName;
14use cranelift_codegen::ir::function::{Function, VersionMarker};
15use cranelift_codegen::settings::SetError;
16use cranelift_codegen::{CodegenError, CompileError, Context, MachReloc, RelocTarget, ir, isa};
17use cranelift_control::ControlPlane;
18use std::borrow::{Cow, ToOwned};
19use std::boxed::Box;
20use std::string::String;
21
22/// A module relocation.
23#[derive(Clone)]
24pub struct ModuleReloc {
25    /// The offset at which the relocation applies, *relative to the
26    /// containing section*.
27    pub offset: CodeOffset,
28    /// The kind of relocation.
29    pub kind: Reloc,
30    /// The external symbol / name to which this relocation refers.
31    pub name: ModuleRelocTarget,
32    /// The addend to add to the symbol value.
33    pub addend: i64,
34}
35
36impl ModuleReloc {
37    /// Converts a `MachReloc` produced from a `Function` into a `ModuleReloc`.
38    pub fn from_mach_reloc(mach_reloc: &MachReloc, func: &Function, func_id: FuncId) -> Self {
39        let name = match mach_reloc.target {
40            RelocTarget::ExternalName(ExternalName::User(reff)) => {
41                let name = &func.params.user_named_funcs()[reff];
42                ModuleRelocTarget::user(name.namespace, name.index)
43            }
44            RelocTarget::ExternalName(ExternalName::TestCase(_)) => unimplemented!(),
45            RelocTarget::ExternalName(ExternalName::LibCall(libcall)) => {
46                ModuleRelocTarget::LibCall(libcall)
47            }
48            RelocTarget::ExternalName(ExternalName::KnownSymbol(ks)) => {
49                ModuleRelocTarget::KnownSymbol(ks)
50            }
51            RelocTarget::Label(label) => {
52                let offset = label.as_offset();
53                ModuleRelocTarget::FunctionOffset(func_id, offset)
54            }
55        };
56        Self {
57            offset: mach_reloc.offset,
58            kind: mach_reloc.kind,
59            name,
60            addend: mach_reloc.addend,
61        }
62    }
63}
64
65/// A function identifier for use in the `Module` interface.
66#[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
67#[cfg_attr(
68    feature = "enable-serde",
69    derive(serde_derive::Serialize, serde_derive::Deserialize)
70)]
71pub struct FuncId(u32);
72entity_impl!(FuncId, "funcid");
73
74/// Function identifiers are namespace 0 in `ir::ExternalName`
75impl From<FuncId> for ModuleRelocTarget {
76    fn from(id: FuncId) -> Self {
77        Self::User {
78            namespace: 0,
79            index: id.0,
80        }
81    }
82}
83
84impl FuncId {
85    /// Get the `FuncId` for the function named by `name`.
86    pub fn from_name(name: &ModuleRelocTarget) -> FuncId {
87        if let ModuleRelocTarget::User { namespace, index } = name {
88            debug_assert_eq!(*namespace, 0);
89            FuncId::from_u32(*index)
90        } else {
91            panic!("unexpected name in DataId::from_name")
92        }
93    }
94}
95
96/// A data object identifier for use in the `Module` interface.
97#[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
98#[cfg_attr(
99    feature = "enable-serde",
100    derive(serde_derive::Serialize, serde_derive::Deserialize)
101)]
102pub struct DataId(u32);
103entity_impl!(DataId, "dataid");
104
105/// Data identifiers are namespace 1 in `ir::ExternalName`
106impl From<DataId> for ModuleRelocTarget {
107    fn from(id: DataId) -> Self {
108        Self::User {
109            namespace: 1,
110            index: id.0,
111        }
112    }
113}
114
115impl DataId {
116    /// Get the `DataId` for the data object named by `name`.
117    pub fn from_name(name: &ModuleRelocTarget) -> DataId {
118        if let ModuleRelocTarget::User { namespace, index } = name {
119            debug_assert_eq!(*namespace, 1);
120            DataId::from_u32(*index)
121        } else {
122            panic!("unexpected name in DataId::from_name")
123        }
124    }
125}
126
127/// Linkage refers to where an entity is defined and who can see it.
128#[derive(Copy, Clone, Debug, PartialEq, Eq)]
129#[cfg_attr(
130    feature = "enable-serde",
131    derive(serde_derive::Serialize, serde_derive::Deserialize)
132)]
133pub enum Linkage {
134    /// Defined outside of a module.
135    Import,
136    /// Defined inside the module, but not visible outside it.
137    Local,
138    /// Defined inside the module, visible outside it, and may be preempted.
139    Preemptible,
140    /// Defined inside the module, visible inside the current static linkage unit, but not outside.
141    ///
142    /// A static linkage unit is the combination of all object files passed to a linker to create
143    /// an executable or dynamic library.
144    Hidden,
145    /// Defined inside the module, and visible outside it.
146    Export,
147}
148
149impl Linkage {
150    fn merge(a: Self, b: Self) -> Self {
151        match a {
152            Self::Export => Self::Export,
153            Self::Hidden => match b {
154                Self::Export => Self::Export,
155                Self::Preemptible => Self::Preemptible,
156                _ => Self::Hidden,
157            },
158            Self::Preemptible => match b {
159                Self::Export => Self::Export,
160                _ => Self::Preemptible,
161            },
162            Self::Local => match b {
163                Self::Export => Self::Export,
164                Self::Hidden => Self::Hidden,
165                Self::Preemptible => Self::Preemptible,
166                Self::Local | Self::Import => Self::Local,
167            },
168            Self::Import => b,
169        }
170    }
171
172    /// Test whether this linkage can have a definition.
173    pub fn is_definable(self) -> bool {
174        match self {
175            Self::Import => false,
176            Self::Local | Self::Preemptible | Self::Hidden | Self::Export => true,
177        }
178    }
179
180    /// Test whether this linkage must have a definition.
181    pub fn requires_definition(self) -> bool {
182        match self {
183            Self::Import | Self::Preemptible => false,
184            Self::Local | Self::Hidden | Self::Export => true,
185        }
186    }
187
188    /// Test whether this linkage will have a definition that cannot be preempted.
189    pub fn is_final(self) -> bool {
190        match self {
191            Self::Import | Self::Preemptible => false,
192            Self::Local | Self::Hidden | Self::Export => true,
193        }
194    }
195}
196
197/// A declared name may refer to either a function or data declaration
198#[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Debug)]
199#[cfg_attr(
200    feature = "enable-serde",
201    derive(serde_derive::Serialize, serde_derive::Deserialize)
202)]
203pub enum FuncOrDataId {
204    /// When it's a FuncId
205    Func(FuncId),
206    /// When it's a DataId
207    Data(DataId),
208}
209
210/// Mapping to `ModuleExtName` is trivial based on the `FuncId` and `DataId` mapping.
211impl From<FuncOrDataId> for ModuleRelocTarget {
212    fn from(id: FuncOrDataId) -> Self {
213        match id {
214            FuncOrDataId::Func(funcid) => Self::from(funcid),
215            FuncOrDataId::Data(dataid) => Self::from(dataid),
216        }
217    }
218}
219
220/// Information about a function which can be called.
221#[derive(Debug)]
222#[cfg_attr(
223    feature = "enable-serde",
224    derive(serde_derive::Serialize, serde_derive::Deserialize)
225)]
226#[expect(missing_docs, reason = "self-describing fields")]
227pub struct FunctionDeclaration {
228    pub name: Option<String>,
229    pub linkage: Linkage,
230    pub signature: ir::Signature,
231}
232
233impl FunctionDeclaration {
234    /// The linkage name of the function.
235    ///
236    /// Synthesized from the given function id if it is an anonymous function.
237    pub fn linkage_name(&self, id: FuncId) -> Cow<'_, str> {
238        match &self.name {
239            Some(name) => Cow::Borrowed(name),
240            // Symbols starting with .L are completely omitted from the symbol table after linking.
241            // Using hexadecimal instead of decimal for slightly smaller symbol names and often
242            // slightly faster linking.
243            None => Cow::Owned(format!(".Lfn{:x}", id.as_u32())),
244        }
245    }
246
247    fn merge(
248        &mut self,
249        id: FuncId,
250        linkage: Linkage,
251        sig: &ir::Signature,
252    ) -> Result<(), ModuleError> {
253        self.linkage = Linkage::merge(self.linkage, linkage);
254        if &self.signature != sig {
255            return Err(ModuleError::IncompatibleSignature(
256                self.linkage_name(id).into_owned(),
257                self.signature.clone(),
258                sig.clone(),
259            ));
260        }
261        Ok(())
262    }
263}
264
265/// Error messages for all `Module` methods
266#[derive(Debug)]
267pub enum ModuleError {
268    /// Indicates an identifier was used before it was declared
269    Undeclared(String),
270
271    /// Indicates an identifier was used as data/function first, but then used as the other
272    IncompatibleDeclaration(String),
273
274    /// Indicates a function identifier was declared with a
275    /// different signature than declared previously
276    IncompatibleSignature(String, ir::Signature, ir::Signature),
277
278    /// Indicates a data object was declared as TLS but previously
279    /// declared as not TLS or vice versa.
280    IncompatibleDataTls(String, bool, bool),
281
282    /// Indicates an identifier was defined more than once
283    DuplicateDefinition(String),
284
285    /// Indicates an identifier was defined, but was declared as an import
286    InvalidImportDefinition(String),
287
288    /// Wraps a `cranelift-codegen` error
289    Compilation(CodegenError),
290
291    /// Memory allocation failure from a backend
292    ///
293    /// Only the `std` builds carry this variant: the payload is a
294    /// `std::io::Error` and the only producer is `cranelift-jit`, which needs
295    /// `std` anyway.
296    #[cfg(feature = "std")]
297    Allocation {
298        /// Io error the allocation failed with
299        err: std::io::Error,
300    },
301
302    /// Wraps a generic error from a backend
303    Backend(anyhow::Error),
304
305    /// Wraps an error from a flag definition.
306    Flag(SetError),
307}
308
309impl<'a> From<CompileError<'a>> for ModuleError {
310    fn from(err: CompileError<'a>) -> Self {
311        Self::Compilation(err.inner)
312    }
313}
314
315// This is manually implementing Error and Display instead of using thiserror to reduce the amount
316// of dependencies used by Cranelift.
317impl core::error::Error for ModuleError {
318    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
319        match self {
320            Self::Undeclared { .. }
321            | Self::IncompatibleDeclaration { .. }
322            | Self::IncompatibleSignature { .. }
323            | Self::IncompatibleDataTls { .. }
324            | Self::DuplicateDefinition { .. }
325            | Self::InvalidImportDefinition { .. } => None,
326            Self::Compilation(source) => Some(source),
327            #[cfg(feature = "std")]
328            Self::Allocation { err: source } => Some(source),
329            Self::Backend(source) => Some(&**source),
330            Self::Flag(source) => Some(source),
331        }
332    }
333}
334
335impl std::fmt::Display for ModuleError {
336    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
337        match self {
338            Self::Undeclared(name) => {
339                write!(f, "Undeclared identifier: {name}")
340            }
341            Self::IncompatibleDeclaration(name) => {
342                write!(f, "Incompatible declaration of identifier: {name}",)
343            }
344            Self::IncompatibleSignature(name, prev_sig, new_sig) => {
345                write!(
346                    f,
347                    "Function {name} signature {new_sig:?} is incompatible with previous declaration {prev_sig:?}",
348                )
349            }
350            Self::IncompatibleDataTls(name, prev_tls, new_tls) => {
351                write!(
352                    f,
353                    "Data object {name} TLS {new_tls:?} is incompatible with previous declaration TLS {prev_tls:?}",
354                )
355            }
356            Self::DuplicateDefinition(name) => {
357                write!(f, "Duplicate definition of identifier: {name}")
358            }
359            Self::InvalidImportDefinition(name) => {
360                write!(
361                    f,
362                    "Invalid to define identifier declared as an import: {name}",
363                )
364            }
365            Self::Compilation(err) => {
366                write!(f, "Compilation error: {err}")
367            }
368            #[cfg(feature = "std")]
369            Self::Allocation { err } => {
370                write!(f, "Allocation error: {err}")
371            }
372            Self::Backend(err) => write!(f, "Backend error: {err}"),
373            Self::Flag(err) => write!(f, "Flag error: {err}"),
374        }
375    }
376}
377
378impl From<CodegenError> for ModuleError {
379    fn from(source: CodegenError) -> Self {
380        Self::Compilation { 0: source }
381    }
382}
383
384impl From<SetError> for ModuleError {
385    fn from(source: SetError) -> Self {
386        Self::Flag { 0: source }
387    }
388}
389
390/// A convenient alias for a `Result` that uses `ModuleError` as the error type.
391pub type ModuleResult<T> = Result<T, ModuleError>;
392
393/// Information about a data object which can be accessed.
394#[derive(Debug)]
395#[cfg_attr(
396    feature = "enable-serde",
397    derive(serde_derive::Serialize, serde_derive::Deserialize)
398)]
399#[expect(missing_docs, reason = "self-describing fields")]
400pub struct DataDeclaration {
401    pub name: Option<String>,
402    pub linkage: Linkage,
403    pub writable: bool,
404    pub tls: bool,
405}
406
407impl DataDeclaration {
408    /// The linkage name of the data object.
409    ///
410    /// Synthesized from the given data id if it is an anonymous function.
411    pub fn linkage_name(&self, id: DataId) -> Cow<'_, str> {
412        match &self.name {
413            Some(name) => Cow::Borrowed(name),
414            // Symbols starting with .L are completely omitted from the symbol table after linking.
415            // Using hexadecimal instead of decimal for slightly smaller symbol names and often
416            // slightly faster linking.
417            None => Cow::Owned(format!(".Ldata{:x}", id.as_u32())),
418        }
419    }
420
421    fn merge(&mut self, linkage: Linkage, writable: bool, tls: bool) -> Result<(), ModuleError> {
422        self.linkage = Linkage::merge(self.linkage, linkage);
423        self.writable = self.writable || writable;
424        if self.tls != tls {
425            return Err(ModuleError::IncompatibleDataTls(
426                self.name.clone().unwrap(),
427                self.tls,
428                tls,
429            ));
430        }
431        Ok(())
432    }
433}
434
435/// A translated `ExternalName` into something global we can handle.
436#[derive(Clone, Debug)]
437#[cfg_attr(
438    feature = "enable-serde",
439    derive(serde_derive::Serialize, serde_derive::Deserialize)
440)]
441pub enum ModuleRelocTarget {
442    /// User defined function, converted from `ExternalName::User`.
443    User {
444        /// Arbitrary.
445        namespace: u32,
446        /// Arbitrary.
447        index: u32,
448    },
449    /// Call into a library function.
450    LibCall(ir::LibCall),
451    /// Symbols known to the linker.
452    KnownSymbol(ir::KnownSymbol),
453    /// A offset inside a function
454    FunctionOffset(FuncId, CodeOffset),
455}
456
457impl ModuleRelocTarget {
458    /// Creates a user-defined external name.
459    pub fn user(namespace: u32, index: u32) -> Self {
460        Self::User { namespace, index }
461    }
462}
463
464impl Display for ModuleRelocTarget {
465    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
466        match self {
467            Self::User { namespace, index } => write!(f, "u{namespace}:{index}"),
468            Self::LibCall(lc) => write!(f, "%{lc}"),
469            Self::KnownSymbol(ks) => write!(f, "{ks}"),
470            Self::FunctionOffset(fname, offset) => write!(f, "{fname}+{offset}"),
471        }
472    }
473}
474
475/// This provides a view to the state of a module which allows `ir::ExternalName`s to be translated
476/// into `FunctionDeclaration`s and `DataDeclaration`s.
477#[derive(Debug, Default)]
478pub struct ModuleDeclarations {
479    /// A version marker used to ensure that serialized clif ir is never deserialized with a
480    /// different version of Cranelift.
481    // Note: This must be the first field to ensure that Serde will deserialize it before
482    // attempting to deserialize other fields that are potentially changed between versions.
483    _version_marker: VersionMarker,
484
485    names: HashMap<String, FuncOrDataId>,
486    functions: PrimaryMap<FuncId, FunctionDeclaration>,
487    data_objects: PrimaryMap<DataId, DataDeclaration>,
488}
489
490#[cfg(feature = "enable-serde")]
491mod serialize {
492    // This is manually implementing Serialize and Deserialize to avoid serializing the names field,
493    // which can be entirely reconstructed from the functions and data_objects fields, saving space.
494
495    use super::*;
496
497    use serde::de::{Deserialize, Deserializer, Error, MapAccess, SeqAccess, Unexpected, Visitor};
498    use serde::ser::{Serialize, SerializeStruct, Serializer};
499    use std::fmt;
500
501    fn get_names<E: Error>(
502        functions: &PrimaryMap<FuncId, FunctionDeclaration>,
503        data_objects: &PrimaryMap<DataId, DataDeclaration>,
504    ) -> Result<HashMap<String, FuncOrDataId>, E> {
505        let mut names = HashMap::new();
506        for (func_id, decl) in functions.iter() {
507            if let Some(name) = &decl.name {
508                let old = names.insert(name.clone(), FuncOrDataId::Func(func_id));
509                if old.is_some() {
510                    return Err(E::invalid_value(
511                        Unexpected::Other("duplicate name"),
512                        &"FunctionDeclaration's with no duplicate names",
513                    ));
514                }
515            }
516        }
517        for (data_id, decl) in data_objects.iter() {
518            if let Some(name) = &decl.name {
519                let old = names.insert(name.clone(), FuncOrDataId::Data(data_id));
520                if old.is_some() {
521                    return Err(E::invalid_value(
522                        Unexpected::Other("duplicate name"),
523                        &"DataDeclaration's with no duplicate names",
524                    ));
525                }
526            }
527        }
528        Ok(names)
529    }
530
531    impl Serialize for ModuleDeclarations {
532        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
533            let ModuleDeclarations {
534                _version_marker,
535                functions,
536                data_objects,
537                names: _,
538            } = self;
539
540            let mut state = s.serialize_struct("ModuleDeclarations", 4)?;
541            state.serialize_field("_version_marker", _version_marker)?;
542            state.serialize_field("functions", functions)?;
543            state.serialize_field("data_objects", data_objects)?;
544            state.end()
545        }
546    }
547
548    enum ModuleDeclarationsField {
549        VersionMarker,
550        Functions,
551        DataObjects,
552        Ignore,
553    }
554
555    struct ModuleDeclarationsFieldVisitor;
556
557    impl<'de> serde::de::Visitor<'de> for ModuleDeclarationsFieldVisitor {
558        type Value = ModuleDeclarationsField;
559
560        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
561            f.write_str("field identifier")
562        }
563
564        fn visit_u64<E: Error>(self, val: u64) -> Result<Self::Value, E> {
565            match val {
566                0u64 => Ok(ModuleDeclarationsField::VersionMarker),
567                1u64 => Ok(ModuleDeclarationsField::Functions),
568                2u64 => Ok(ModuleDeclarationsField::DataObjects),
569                _ => Ok(ModuleDeclarationsField::Ignore),
570            }
571        }
572
573        fn visit_str<E: Error>(self, val: &str) -> Result<Self::Value, E> {
574            match val {
575                "_version_marker" => Ok(ModuleDeclarationsField::VersionMarker),
576                "functions" => Ok(ModuleDeclarationsField::Functions),
577                "data_objects" => Ok(ModuleDeclarationsField::DataObjects),
578                _ => Ok(ModuleDeclarationsField::Ignore),
579            }
580        }
581
582        fn visit_bytes<E: Error>(self, val: &[u8]) -> Result<Self::Value, E> {
583            match val {
584                b"_version_marker" => Ok(ModuleDeclarationsField::VersionMarker),
585                b"functions" => Ok(ModuleDeclarationsField::Functions),
586                b"data_objects" => Ok(ModuleDeclarationsField::DataObjects),
587                _ => Ok(ModuleDeclarationsField::Ignore),
588            }
589        }
590    }
591
592    impl<'de> Deserialize<'de> for ModuleDeclarationsField {
593        #[inline]
594        fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
595            d.deserialize_identifier(ModuleDeclarationsFieldVisitor)
596        }
597    }
598
599    struct ModuleDeclarationsVisitor;
600
601    impl<'de> Visitor<'de> for ModuleDeclarationsVisitor {
602        type Value = ModuleDeclarations;
603
604        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
605            f.write_str("struct ModuleDeclarations")
606        }
607
608        #[inline]
609        fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Self::Value, A::Error> {
610            let _version_marker = match seq.next_element()? {
611                Some(val) => val,
612                None => {
613                    return Err(Error::invalid_length(
614                        0usize,
615                        &"struct ModuleDeclarations with 4 elements",
616                    ));
617                }
618            };
619            let functions = match seq.next_element()? {
620                Some(val) => val,
621                None => {
622                    return Err(Error::invalid_length(
623                        2usize,
624                        &"struct ModuleDeclarations with 4 elements",
625                    ));
626                }
627            };
628            let data_objects = match seq.next_element()? {
629                Some(val) => val,
630                None => {
631                    return Err(Error::invalid_length(
632                        3usize,
633                        &"struct ModuleDeclarations with 4 elements",
634                    ));
635                }
636            };
637            let names = get_names(&functions, &data_objects)?;
638            Ok(ModuleDeclarations {
639                _version_marker,
640                names,
641                functions,
642                data_objects,
643            })
644        }
645
646        #[inline]
647        fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
648            let mut _version_marker: Option<VersionMarker> = None;
649            let mut functions: Option<PrimaryMap<FuncId, FunctionDeclaration>> = None;
650            let mut data_objects: Option<PrimaryMap<DataId, DataDeclaration>> = None;
651            while let Some(key) = map.next_key::<ModuleDeclarationsField>()? {
652                match key {
653                    ModuleDeclarationsField::VersionMarker => {
654                        if _version_marker.is_some() {
655                            return Err(Error::duplicate_field("_version_marker"));
656                        }
657                        _version_marker = Some(map.next_value()?);
658                    }
659                    ModuleDeclarationsField::Functions => {
660                        if functions.is_some() {
661                            return Err(Error::duplicate_field("functions"));
662                        }
663                        functions = Some(map.next_value()?);
664                    }
665                    ModuleDeclarationsField::DataObjects => {
666                        if data_objects.is_some() {
667                            return Err(Error::duplicate_field("data_objects"));
668                        }
669                        data_objects = Some(map.next_value()?);
670                    }
671                    _ => {
672                        map.next_value::<serde::de::IgnoredAny>()?;
673                    }
674                }
675            }
676            let _version_marker = match _version_marker {
677                Some(_version_marker) => _version_marker,
678                None => return Err(Error::missing_field("_version_marker")),
679            };
680            let functions = match functions {
681                Some(functions) => functions,
682                None => return Err(Error::missing_field("functions")),
683            };
684            let data_objects = match data_objects {
685                Some(data_objects) => data_objects,
686                None => return Err(Error::missing_field("data_objects")),
687            };
688            let names = get_names(&functions, &data_objects)?;
689            Ok(ModuleDeclarations {
690                _version_marker,
691                names,
692                functions,
693                data_objects,
694            })
695        }
696    }
697
698    impl<'de> Deserialize<'de> for ModuleDeclarations {
699        fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
700            d.deserialize_struct(
701                "ModuleDeclarations",
702                &["_version_marker", "functions", "data_objects"],
703                ModuleDeclarationsVisitor,
704            )
705        }
706    }
707}
708
709impl ModuleDeclarations {
710    /// Get the module identifier for a given name, if that name
711    /// has been declared.
712    pub fn get_name(&self, name: &str) -> Option<FuncOrDataId> {
713        self.names.get(name).copied()
714    }
715
716    /// Get an iterator of all function declarations
717    pub fn get_functions(&self) -> impl Iterator<Item = (FuncId, &FunctionDeclaration)> {
718        self.functions.iter()
719    }
720
721    /// Return whether `name` names a function, rather than a data object.
722    pub fn is_function(name: &ModuleRelocTarget) -> bool {
723        match name {
724            ModuleRelocTarget::User { namespace, .. } => *namespace == 0,
725            ModuleRelocTarget::LibCall(_)
726            | ModuleRelocTarget::KnownSymbol(_)
727            | ModuleRelocTarget::FunctionOffset(..) => {
728                panic!("unexpected module ext name")
729            }
730        }
731    }
732
733    /// Get the `FunctionDeclaration` for the function named by `name`.
734    pub fn get_function_decl(&self, func_id: FuncId) -> &FunctionDeclaration {
735        &self.functions[func_id]
736    }
737
738    /// Get an iterator of all data declarations
739    pub fn get_data_objects(&self) -> impl Iterator<Item = (DataId, &DataDeclaration)> {
740        self.data_objects.iter()
741    }
742
743    /// Get the `DataDeclaration` for the data object named by `name`.
744    pub fn get_data_decl(&self, data_id: DataId) -> &DataDeclaration {
745        &self.data_objects[data_id]
746    }
747
748    /// Declare a function in this module.
749    pub fn declare_function(
750        &mut self,
751        name: &str,
752        linkage: Linkage,
753        signature: &ir::Signature,
754    ) -> ModuleResult<(FuncId, Linkage)> {
755        // TODO: Can we avoid allocating names so often?
756        use super::hash_map::Entry::*;
757        match self.names.entry(name.to_owned()) {
758            Occupied(entry) => match *entry.get() {
759                FuncOrDataId::Func(id) => {
760                    let existing = &mut self.functions[id];
761                    existing.merge(id, linkage, signature)?;
762                    Ok((id, existing.linkage))
763                }
764                FuncOrDataId::Data(..) => {
765                    Err(ModuleError::IncompatibleDeclaration(name.to_owned()))
766                }
767            },
768            Vacant(entry) => {
769                let id = self.functions.push(FunctionDeclaration {
770                    name: Some(name.to_owned()),
771                    linkage,
772                    signature: signature.clone(),
773                });
774                entry.insert(FuncOrDataId::Func(id));
775                Ok((id, self.functions[id].linkage))
776            }
777        }
778    }
779
780    /// Declare an anonymous function in this module.
781    pub fn declare_anonymous_function(
782        &mut self,
783        signature: &ir::Signature,
784    ) -> ModuleResult<FuncId> {
785        let id = self.functions.push(FunctionDeclaration {
786            name: None,
787            linkage: Linkage::Local,
788            signature: signature.clone(),
789        });
790        Ok(id)
791    }
792
793    /// Declare a data object in this module.
794    pub fn declare_data(
795        &mut self,
796        name: &str,
797        linkage: Linkage,
798        writable: bool,
799        tls: bool,
800    ) -> ModuleResult<(DataId, Linkage)> {
801        // TODO: Can we avoid allocating names so often?
802        use super::hash_map::Entry::*;
803        match self.names.entry(name.to_owned()) {
804            Occupied(entry) => match *entry.get() {
805                FuncOrDataId::Data(id) => {
806                    let existing = &mut self.data_objects[id];
807                    existing.merge(linkage, writable, tls)?;
808                    Ok((id, existing.linkage))
809                }
810
811                FuncOrDataId::Func(..) => {
812                    Err(ModuleError::IncompatibleDeclaration(name.to_owned()))
813                }
814            },
815            Vacant(entry) => {
816                let id = self.data_objects.push(DataDeclaration {
817                    name: Some(name.to_owned()),
818                    linkage,
819                    writable,
820                    tls,
821                });
822                entry.insert(FuncOrDataId::Data(id));
823                Ok((id, self.data_objects[id].linkage))
824            }
825        }
826    }
827
828    /// Declare an anonymous data object in this module.
829    pub fn declare_anonymous_data(&mut self, writable: bool, tls: bool) -> ModuleResult<DataId> {
830        let id = self.data_objects.push(DataDeclaration {
831            name: None,
832            linkage: Linkage::Local,
833            writable,
834            tls,
835        });
836        Ok(id)
837    }
838}
839
840/// A `Module` is a utility for collecting functions and data objects, and linking them together.
841pub trait Module {
842    /// Return the `TargetIsa` to compile for.
843    fn isa(&self) -> &dyn isa::TargetIsa;
844
845    /// Get all declarations in this module.
846    fn declarations(&self) -> &ModuleDeclarations;
847
848    /// Get the module identifier for a given name, if that name
849    /// has been declared.
850    fn get_name(&self, name: &str) -> Option<FuncOrDataId> {
851        self.declarations().get_name(name)
852    }
853
854    /// Return the target information needed by frontends to produce Cranelift IR
855    /// for the current target.
856    fn target_config(&self) -> isa::TargetFrontendConfig {
857        self.isa().frontend_config()
858    }
859
860    /// Create a new `Context` initialized for use with this `Module`.
861    ///
862    /// This ensures that the `Context` is initialized with the default calling
863    /// convention for the `TargetIsa`.
864    fn make_context(&self) -> Context {
865        let mut ctx = Context::new();
866        ctx.func.signature.call_conv = self.isa().default_call_conv();
867        ctx
868    }
869
870    /// Clear the given `Context` and reset it for use with a new function.
871    ///
872    /// This ensures that the `Context` is initialized with the default calling
873    /// convention for the `TargetIsa`.
874    fn clear_context(&self, ctx: &mut Context) {
875        ctx.clear();
876        ctx.func.signature.call_conv = self.isa().default_call_conv();
877    }
878
879    /// Create a new empty `Signature` with the default calling convention for
880    /// the `TargetIsa`, to which parameter and return types can be added for
881    /// declaring a function to be called by this `Module`.
882    fn make_signature(&self) -> ir::Signature {
883        ir::Signature::new(self.isa().default_call_conv())
884    }
885
886    /// Clear the given `Signature` and reset for use with a new function.
887    ///
888    /// This ensures that the `Signature` is initialized with the default
889    /// calling convention for the `TargetIsa`.
890    fn clear_signature(&self, sig: &mut ir::Signature) {
891        sig.clear(self.isa().default_call_conv());
892    }
893
894    /// Declare a function in this module.
895    fn declare_function(
896        &mut self,
897        name: &str,
898        linkage: Linkage,
899        signature: &ir::Signature,
900    ) -> ModuleResult<FuncId>;
901
902    /// Declare an anonymous function in this module.
903    fn declare_anonymous_function(&mut self, signature: &ir::Signature) -> ModuleResult<FuncId>;
904
905    /// Declare a data object in this module.
906    fn declare_data(
907        &mut self,
908        name: &str,
909        linkage: Linkage,
910        writable: bool,
911        tls: bool,
912    ) -> ModuleResult<DataId>;
913
914    /// Declare an anonymous data object in this module.
915    fn declare_anonymous_data(&mut self, writable: bool, tls: bool) -> ModuleResult<DataId>;
916
917    /// Use this when you're building the IR of a function to reference a function.
918    ///
919    /// TODO: Coalesce redundant decls and signatures.
920    /// TODO: Look into ways to reduce the risk of using a FuncRef in the wrong function.
921    fn declare_func_in_func(&mut self, func_id: FuncId, func: &mut ir::Function) -> ir::FuncRef {
922        let decl = &self.declarations().functions[func_id];
923        let signature = func.import_signature(decl.signature.clone());
924        let user_name_ref = func.declare_imported_user_function(ir::UserExternalName {
925            namespace: 0,
926            index: func_id.as_u32(),
927        });
928        let colocated = decl.linkage.is_final();
929        func.import_function(ir::ExtFuncData {
930            name: ir::ExternalName::user(user_name_ref),
931            signature,
932            colocated,
933            patchable: false,
934        })
935    }
936
937    /// Use this when you're building the IR of a function to reference a data object.
938    ///
939    /// TODO: Same as above.
940    fn declare_data_in_func(&self, data: DataId, func: &mut ir::Function) -> ir::GlobalValue {
941        let decl = &self.declarations().data_objects[data];
942        let colocated = decl.linkage.is_final();
943        let user_name_ref = func.declare_imported_user_function(ir::UserExternalName {
944            namespace: 1,
945            index: data.as_u32(),
946        });
947        func.create_global_value(ir::GlobalValueData::Symbol {
948            name: ir::ExternalName::user(user_name_ref),
949            offset: ir::immediates::Imm64::new(0),
950            colocated,
951            tls: decl.tls,
952        })
953    }
954
955    /// TODO: Same as above.
956    fn declare_func_in_data(&self, func_id: FuncId, data: &mut DataDescription) -> ir::FuncRef {
957        data.import_function(ModuleRelocTarget::user(0, func_id.as_u32()))
958    }
959
960    /// TODO: Same as above.
961    fn declare_data_in_data(&self, data_id: DataId, data: &mut DataDescription) -> ir::GlobalValue {
962        data.import_global_value(ModuleRelocTarget::user(1, data_id.as_u32()))
963    }
964
965    /// Define a function, producing the function body from the given `Context`.
966    ///
967    /// Returns the size of the function's code and constant data.
968    ///
969    /// Unlike [`define_function_with_control_plane`] this uses a default [`ControlPlane`] for
970    /// convenience.
971    ///
972    /// Note: After calling this function the given `Context` will contain the compiled function.
973    ///
974    /// [`define_function_with_control_plane`]: Self::define_function_with_control_plane
975    fn define_function(&mut self, func: FuncId, ctx: &mut Context) -> ModuleResult<()> {
976        self.define_function_with_control_plane(func, ctx, &mut ControlPlane::default())
977    }
978
979    /// Define a function, producing the function body from the given `Context`.
980    ///
981    /// Returns the size of the function's code and constant data.
982    ///
983    /// Note: After calling this function the given `Context` will contain the compiled function.
984    fn define_function_with_control_plane(
985        &mut self,
986        func: FuncId,
987        ctx: &mut Context,
988        ctrl_plane: &mut ControlPlane,
989    ) -> ModuleResult<()>;
990
991    /// Define a function, taking the function body from the given `bytes`.
992    ///
993    /// This function is generally only useful if you need to precisely specify
994    /// the emitted instructions for some reason; otherwise, you should use
995    /// `define_function`.
996    ///
997    /// Returns the size of the function's code.
998    fn define_function_bytes(
999        &mut self,
1000        func_id: FuncId,
1001        alignment: u64,
1002        bytes: &[u8],
1003        relocs: &[ModuleReloc],
1004    ) -> ModuleResult<()>;
1005
1006    /// Define a data object, producing the data contents from the given `DataDescription`.
1007    fn define_data(&mut self, data_id: DataId, data: &DataDescription) -> ModuleResult<()>;
1008}
1009
1010impl<M: Module + ?Sized> Module for &mut M {
1011    fn isa(&self) -> &dyn isa::TargetIsa {
1012        (**self).isa()
1013    }
1014
1015    fn declarations(&self) -> &ModuleDeclarations {
1016        (**self).declarations()
1017    }
1018
1019    fn get_name(&self, name: &str) -> Option<FuncOrDataId> {
1020        (**self).get_name(name)
1021    }
1022
1023    fn target_config(&self) -> isa::TargetFrontendConfig {
1024        (**self).target_config()
1025    }
1026
1027    fn make_context(&self) -> Context {
1028        (**self).make_context()
1029    }
1030
1031    fn clear_context(&self, ctx: &mut Context) {
1032        (**self).clear_context(ctx)
1033    }
1034
1035    fn make_signature(&self) -> ir::Signature {
1036        (**self).make_signature()
1037    }
1038
1039    fn clear_signature(&self, sig: &mut ir::Signature) {
1040        (**self).clear_signature(sig)
1041    }
1042
1043    fn declare_function(
1044        &mut self,
1045        name: &str,
1046        linkage: Linkage,
1047        signature: &ir::Signature,
1048    ) -> ModuleResult<FuncId> {
1049        (**self).declare_function(name, linkage, signature)
1050    }
1051
1052    fn declare_anonymous_function(&mut self, signature: &ir::Signature) -> ModuleResult<FuncId> {
1053        (**self).declare_anonymous_function(signature)
1054    }
1055
1056    fn declare_data(
1057        &mut self,
1058        name: &str,
1059        linkage: Linkage,
1060        writable: bool,
1061        tls: bool,
1062    ) -> ModuleResult<DataId> {
1063        (**self).declare_data(name, linkage, writable, tls)
1064    }
1065
1066    fn declare_anonymous_data(&mut self, writable: bool, tls: bool) -> ModuleResult<DataId> {
1067        (**self).declare_anonymous_data(writable, tls)
1068    }
1069
1070    fn declare_func_in_func(&mut self, func: FuncId, in_func: &mut ir::Function) -> ir::FuncRef {
1071        (**self).declare_func_in_func(func, in_func)
1072    }
1073
1074    fn declare_data_in_func(&self, data: DataId, func: &mut ir::Function) -> ir::GlobalValue {
1075        (**self).declare_data_in_func(data, func)
1076    }
1077
1078    fn declare_func_in_data(&self, func_id: FuncId, data: &mut DataDescription) -> ir::FuncRef {
1079        (**self).declare_func_in_data(func_id, data)
1080    }
1081
1082    fn declare_data_in_data(&self, data_id: DataId, data: &mut DataDescription) -> ir::GlobalValue {
1083        (**self).declare_data_in_data(data_id, data)
1084    }
1085
1086    fn define_function(&mut self, func: FuncId, ctx: &mut Context) -> ModuleResult<()> {
1087        (**self).define_function(func, ctx)
1088    }
1089
1090    fn define_function_with_control_plane(
1091        &mut self,
1092        func: FuncId,
1093        ctx: &mut Context,
1094        ctrl_plane: &mut ControlPlane,
1095    ) -> ModuleResult<()> {
1096        (**self).define_function_with_control_plane(func, ctx, ctrl_plane)
1097    }
1098
1099    fn define_function_bytes(
1100        &mut self,
1101        func_id: FuncId,
1102        alignment: u64,
1103        bytes: &[u8],
1104        relocs: &[ModuleReloc],
1105    ) -> ModuleResult<()> {
1106        (**self).define_function_bytes(func_id, alignment, bytes, relocs)
1107    }
1108
1109    fn define_data(&mut self, data_id: DataId, data: &DataDescription) -> ModuleResult<()> {
1110        (**self).define_data(data_id, data)
1111    }
1112}
1113
1114impl<M: Module + ?Sized> Module for Box<M> {
1115    fn isa(&self) -> &dyn isa::TargetIsa {
1116        (**self).isa()
1117    }
1118
1119    fn declarations(&self) -> &ModuleDeclarations {
1120        (**self).declarations()
1121    }
1122
1123    fn get_name(&self, name: &str) -> Option<FuncOrDataId> {
1124        (**self).get_name(name)
1125    }
1126
1127    fn target_config(&self) -> isa::TargetFrontendConfig {
1128        (**self).target_config()
1129    }
1130
1131    fn make_context(&self) -> Context {
1132        (**self).make_context()
1133    }
1134
1135    fn clear_context(&self, ctx: &mut Context) {
1136        (**self).clear_context(ctx)
1137    }
1138
1139    fn make_signature(&self) -> ir::Signature {
1140        (**self).make_signature()
1141    }
1142
1143    fn clear_signature(&self, sig: &mut ir::Signature) {
1144        (**self).clear_signature(sig)
1145    }
1146
1147    fn declare_function(
1148        &mut self,
1149        name: &str,
1150        linkage: Linkage,
1151        signature: &ir::Signature,
1152    ) -> ModuleResult<FuncId> {
1153        (**self).declare_function(name, linkage, signature)
1154    }
1155
1156    fn declare_anonymous_function(&mut self, signature: &ir::Signature) -> ModuleResult<FuncId> {
1157        (**self).declare_anonymous_function(signature)
1158    }
1159
1160    fn declare_data(
1161        &mut self,
1162        name: &str,
1163        linkage: Linkage,
1164        writable: bool,
1165        tls: bool,
1166    ) -> ModuleResult<DataId> {
1167        (**self).declare_data(name, linkage, writable, tls)
1168    }
1169
1170    fn declare_anonymous_data(&mut self, writable: bool, tls: bool) -> ModuleResult<DataId> {
1171        (**self).declare_anonymous_data(writable, tls)
1172    }
1173
1174    fn declare_func_in_func(&mut self, func: FuncId, in_func: &mut ir::Function) -> ir::FuncRef {
1175        (**self).declare_func_in_func(func, in_func)
1176    }
1177
1178    fn declare_data_in_func(&self, data: DataId, func: &mut ir::Function) -> ir::GlobalValue {
1179        (**self).declare_data_in_func(data, func)
1180    }
1181
1182    fn declare_func_in_data(&self, func_id: FuncId, data: &mut DataDescription) -> ir::FuncRef {
1183        (**self).declare_func_in_data(func_id, data)
1184    }
1185
1186    fn declare_data_in_data(&self, data_id: DataId, data: &mut DataDescription) -> ir::GlobalValue {
1187        (**self).declare_data_in_data(data_id, data)
1188    }
1189
1190    fn define_function(&mut self, func: FuncId, ctx: &mut Context) -> ModuleResult<()> {
1191        (**self).define_function(func, ctx)
1192    }
1193
1194    fn define_function_with_control_plane(
1195        &mut self,
1196        func: FuncId,
1197        ctx: &mut Context,
1198        ctrl_plane: &mut ControlPlane,
1199    ) -> ModuleResult<()> {
1200        (**self).define_function_with_control_plane(func, ctx, ctrl_plane)
1201    }
1202
1203    fn define_function_bytes(
1204        &mut self,
1205        func_id: FuncId,
1206        alignment: u64,
1207        bytes: &[u8],
1208        relocs: &[ModuleReloc],
1209    ) -> ModuleResult<()> {
1210        (**self).define_function_bytes(func_id, alignment, bytes, relocs)
1211    }
1212
1213    fn define_data(&mut self, data_id: DataId, data: &DataDescription) -> ModuleResult<()> {
1214        (**self).define_data(data_id, data)
1215    }
1216}
cranelift_module/module.rs

cranelift_module/
module.rs
