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

cranelift_module/
module.rs
