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    Allocation {
294        /// Tell where the allocation came from
295        message: &'static str,
296        /// Io error the allocation failed with
297        err: std::io::Error,
298    },
299
300    /// Wraps a generic error from a backend
301    Backend(anyhow::Error),
302
303    /// Wraps an error from a flag definition.
304    Flag(SetError),
305}
306
307impl<'a> From<CompileError<'a>> for ModuleError {
308    fn from(err: CompileError<'a>) -> Self {
309        Self::Compilation(err.inner)
310    }
311}
312
313// This is manually implementing Error and Display instead of using thiserror to reduce the amount
314// of dependencies used by Cranelift.
315impl std::error::Error for ModuleError {
316    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
317        match self {
318            Self::Undeclared { .. }
319            | Self::IncompatibleDeclaration { .. }
320            | Self::IncompatibleSignature { .. }
321            | Self::DuplicateDefinition { .. }
322            | Self::InvalidImportDefinition { .. } => None,
323            Self::Compilation(source) => Some(source),
324            Self::Allocation { err: source, .. } => Some(source),
325            Self::Backend(source) => Some(&**source),
326            Self::Flag(source) => Some(source),
327        }
328    }
329}
330
331impl std::fmt::Display for ModuleError {
332    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
333        match self {
334            Self::Undeclared(name) => {
335                write!(f, "Undeclared identifier: {name}")
336            }
337            Self::IncompatibleDeclaration(name) => {
338                write!(f, "Incompatible declaration of identifier: {name}",)
339            }
340            Self::IncompatibleSignature(name, prev_sig, new_sig) => {
341                write!(
342                    f,
343                    "Function {name} signature {new_sig:?} is incompatible with previous declaration {prev_sig:?}",
344                )
345            }
346            Self::DuplicateDefinition(name) => {
347                write!(f, "Duplicate definition of identifier: {name}")
348            }
349            Self::InvalidImportDefinition(name) => {
350                write!(
351                    f,
352                    "Invalid to define identifier declared as an import: {name}",
353                )
354            }
355            Self::Compilation(err) => {
356                write!(f, "Compilation error: {err}")
357            }
358            Self::Allocation { message, err } => {
359                write!(f, "Allocation error: {message}: {err}")
360            }
361            Self::Backend(err) => write!(f, "Backend error: {err}"),
362            Self::Flag(err) => write!(f, "Flag error: {err}"),
363        }
364    }
365}
366
367impl std::convert::From<CodegenError> for ModuleError {
368    fn from(source: CodegenError) -> Self {
369        Self::Compilation { 0: source }
370    }
371}
372
373impl std::convert::From<SetError> for ModuleError {
374    fn from(source: SetError) -> Self {
375        Self::Flag { 0: source }
376    }
377}
378
379/// A convenient alias for a `Result` that uses `ModuleError` as the error type.
380pub type ModuleResult<T> = Result<T, ModuleError>;
381
382/// Information about a data object which can be accessed.
383#[derive(Debug)]
384#[cfg_attr(
385    feature = "enable-serde",
386    derive(serde_derive::Serialize, serde_derive::Deserialize)
387)]
388#[expect(missing_docs, reason = "self-describing fields")]
389pub struct DataDeclaration {
390    pub name: Option<String>,
391    pub linkage: Linkage,
392    pub writable: bool,
393    pub tls: bool,
394}
395
396impl DataDeclaration {
397    /// The linkage name of the data object.
398    ///
399    /// Synthesized from the given data id if it is an anonymous function.
400    pub fn linkage_name(&self, id: DataId) -> Cow<'_, str> {
401        match &self.name {
402            Some(name) => Cow::Borrowed(name),
403            // Symbols starting with .L are completely omitted from the symbol table after linking.
404            // Using hexadecimal instead of decimal for slightly smaller symbol names and often
405            // slightly faster linking.
406            None => Cow::Owned(format!(".Ldata{:x}", id.as_u32())),
407        }
408    }
409
410    fn merge(&mut self, linkage: Linkage, writable: bool, tls: bool) {
411        self.linkage = Linkage::merge(self.linkage, linkage);
412        self.writable = self.writable || writable;
413        assert_eq!(
414            self.tls, tls,
415            "Can't change TLS data object to normal or in the opposite way",
416        );
417    }
418}
419
420/// A translated `ExternalName` into something global we can handle.
421#[derive(Clone, Debug)]
422#[cfg_attr(
423    feature = "enable-serde",
424    derive(serde_derive::Serialize, serde_derive::Deserialize)
425)]
426pub enum ModuleRelocTarget {
427    /// User defined function, converted from `ExternalName::User`.
428    User {
429        /// Arbitrary.
430        namespace: u32,
431        /// Arbitrary.
432        index: u32,
433    },
434    /// Call into a library function.
435    LibCall(ir::LibCall),
436    /// Symbols known to the linker.
437    KnownSymbol(ir::KnownSymbol),
438    /// A offset inside a function
439    FunctionOffset(FuncId, CodeOffset),
440}
441
442impl ModuleRelocTarget {
443    /// Creates a user-defined external name.
444    pub fn user(namespace: u32, index: u32) -> Self {
445        Self::User { namespace, index }
446    }
447}
448
449impl Display for ModuleRelocTarget {
450    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
451        match self {
452            Self::User { namespace, index } => write!(f, "u{namespace}:{index}"),
453            Self::LibCall(lc) => write!(f, "%{lc}"),
454            Self::KnownSymbol(ks) => write!(f, "{ks}"),
455            Self::FunctionOffset(fname, offset) => write!(f, "{fname}+{offset}"),
456        }
457    }
458}
459
460/// This provides a view to the state of a module which allows `ir::ExternalName`s to be translated
461/// into `FunctionDeclaration`s and `DataDeclaration`s.
462#[derive(Debug, Default)]
463pub struct ModuleDeclarations {
464    /// A version marker used to ensure that serialized clif ir is never deserialized with a
465    /// different version of Cranelift.
466    // Note: This must be the first field to ensure that Serde will deserialize it before
467    // attempting to deserialize other fields that are potentially changed between versions.
468    _version_marker: VersionMarker,
469
470    names: HashMap<String, FuncOrDataId>,
471    functions: PrimaryMap<FuncId, FunctionDeclaration>,
472    data_objects: PrimaryMap<DataId, DataDeclaration>,
473}
474
475#[cfg(feature = "enable-serde")]
476mod serialize {
477    // This is manually implementing Serialize and Deserialize to avoid serializing the names field,
478    // which can be entirely reconstructed from the functions and data_objects fields, saving space.
479
480    use super::*;
481
482    use serde::de::{Deserialize, Deserializer, Error, MapAccess, SeqAccess, Unexpected, Visitor};
483    use serde::ser::{Serialize, SerializeStruct, Serializer};
484    use std::fmt;
485
486    fn get_names<E: Error>(
487        functions: &PrimaryMap<FuncId, FunctionDeclaration>,
488        data_objects: &PrimaryMap<DataId, DataDeclaration>,
489    ) -> Result<HashMap<String, FuncOrDataId>, E> {
490        let mut names = HashMap::new();
491        for (func_id, decl) in functions.iter() {
492            if let Some(name) = &decl.name {
493                let old = names.insert(name.clone(), FuncOrDataId::Func(func_id));
494                if old.is_some() {
495                    return Err(E::invalid_value(
496                        Unexpected::Other("duplicate name"),
497                        &"FunctionDeclaration's with no duplicate names",
498                    ));
499                }
500            }
501        }
502        for (data_id, decl) in data_objects.iter() {
503            if let Some(name) = &decl.name {
504                let old = names.insert(name.clone(), FuncOrDataId::Data(data_id));
505                if old.is_some() {
506                    return Err(E::invalid_value(
507                        Unexpected::Other("duplicate name"),
508                        &"DataDeclaration's with no duplicate names",
509                    ));
510                }
511            }
512        }
513        Ok(names)
514    }
515
516    impl Serialize for ModuleDeclarations {
517        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
518            let ModuleDeclarations {
519                _version_marker,
520                functions,
521                data_objects,
522                names: _,
523            } = self;
524
525            let mut state = s.serialize_struct("ModuleDeclarations", 4)?;
526            state.serialize_field("_version_marker", _version_marker)?;
527            state.serialize_field("functions", functions)?;
528            state.serialize_field("data_objects", data_objects)?;
529            state.end()
530        }
531    }
532
533    enum ModuleDeclarationsField {
534        VersionMarker,
535        Functions,
536        DataObjects,
537        Ignore,
538    }
539
540    struct ModuleDeclarationsFieldVisitor;
541
542    impl<'de> serde::de::Visitor<'de> for ModuleDeclarationsFieldVisitor {
543        type Value = ModuleDeclarationsField;
544
545        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
546            f.write_str("field identifier")
547        }
548
549        fn visit_u64<E: Error>(self, val: u64) -> Result<Self::Value, E> {
550            match val {
551                0u64 => Ok(ModuleDeclarationsField::VersionMarker),
552                1u64 => Ok(ModuleDeclarationsField::Functions),
553                2u64 => Ok(ModuleDeclarationsField::DataObjects),
554                _ => Ok(ModuleDeclarationsField::Ignore),
555            }
556        }
557
558        fn visit_str<E: Error>(self, val: &str) -> Result<Self::Value, E> {
559            match val {
560                "_version_marker" => Ok(ModuleDeclarationsField::VersionMarker),
561                "functions" => Ok(ModuleDeclarationsField::Functions),
562                "data_objects" => Ok(ModuleDeclarationsField::DataObjects),
563                _ => Ok(ModuleDeclarationsField::Ignore),
564            }
565        }
566
567        fn visit_bytes<E: Error>(self, val: &[u8]) -> Result<Self::Value, E> {
568            match val {
569                b"_version_marker" => Ok(ModuleDeclarationsField::VersionMarker),
570                b"functions" => Ok(ModuleDeclarationsField::Functions),
571                b"data_objects" => Ok(ModuleDeclarationsField::DataObjects),
572                _ => Ok(ModuleDeclarationsField::Ignore),
573            }
574        }
575    }
576
577    impl<'de> Deserialize<'de> for ModuleDeclarationsField {
578        #[inline]
579        fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
580            d.deserialize_identifier(ModuleDeclarationsFieldVisitor)
581        }
582    }
583
584    struct ModuleDeclarationsVisitor;
585
586    impl<'de> Visitor<'de> for ModuleDeclarationsVisitor {
587        type Value = ModuleDeclarations;
588
589        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
590            f.write_str("struct ModuleDeclarations")
591        }
592
593        #[inline]
594        fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Self::Value, A::Error> {
595            let _version_marker = match seq.next_element()? {
596                Some(val) => val,
597                None => {
598                    return Err(Error::invalid_length(
599                        0usize,
600                        &"struct ModuleDeclarations with 4 elements",
601                    ));
602                }
603            };
604            let functions = match seq.next_element()? {
605                Some(val) => val,
606                None => {
607                    return Err(Error::invalid_length(
608                        2usize,
609                        &"struct ModuleDeclarations with 4 elements",
610                    ));
611                }
612            };
613            let data_objects = match seq.next_element()? {
614                Some(val) => val,
615                None => {
616                    return Err(Error::invalid_length(
617                        3usize,
618                        &"struct ModuleDeclarations with 4 elements",
619                    ));
620                }
621            };
622            let names = get_names(&functions, &data_objects)?;
623            Ok(ModuleDeclarations {
624                _version_marker,
625                names,
626                functions,
627                data_objects,
628            })
629        }
630
631        #[inline]
632        fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
633            let mut _version_marker: Option<VersionMarker> = None;
634            let mut functions: Option<PrimaryMap<FuncId, FunctionDeclaration>> = None;
635            let mut data_objects: Option<PrimaryMap<DataId, DataDeclaration>> = None;
636            while let Some(key) = map.next_key::<ModuleDeclarationsField>()? {
637                match key {
638                    ModuleDeclarationsField::VersionMarker => {
639                        if _version_marker.is_some() {
640                            return Err(Error::duplicate_field("_version_marker"));
641                        }
642                        _version_marker = Some(map.next_value()?);
643                    }
644                    ModuleDeclarationsField::Functions => {
645                        if functions.is_some() {
646                            return Err(Error::duplicate_field("functions"));
647                        }
648                        functions = Some(map.next_value()?);
649                    }
650                    ModuleDeclarationsField::DataObjects => {
651                        if data_objects.is_some() {
652                            return Err(Error::duplicate_field("data_objects"));
653                        }
654                        data_objects = Some(map.next_value()?);
655                    }
656                    _ => {
657                        map.next_value::<serde::de::IgnoredAny>()?;
658                    }
659                }
660            }
661            let _version_marker = match _version_marker {
662                Some(_version_marker) => _version_marker,
663                None => return Err(Error::missing_field("_version_marker")),
664            };
665            let functions = match functions {
666                Some(functions) => functions,
667                None => return Err(Error::missing_field("functions")),
668            };
669            let data_objects = match data_objects {
670                Some(data_objects) => data_objects,
671                None => return Err(Error::missing_field("data_objects")),
672            };
673            let names = get_names(&functions, &data_objects)?;
674            Ok(ModuleDeclarations {
675                _version_marker,
676                names,
677                functions,
678                data_objects,
679            })
680        }
681    }
682
683    impl<'de> Deserialize<'de> for ModuleDeclarations {
684        fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
685            d.deserialize_struct(
686                "ModuleDeclarations",
687                &["_version_marker", "functions", "data_objects"],
688                ModuleDeclarationsVisitor,
689            )
690        }
691    }
692}
693
694impl ModuleDeclarations {
695    /// Get the module identifier for a given name, if that name
696    /// has been declared.
697    pub fn get_name(&self, name: &str) -> Option<FuncOrDataId> {
698        self.names.get(name).copied()
699    }
700
701    /// Get an iterator of all function declarations
702    pub fn get_functions(&self) -> impl Iterator<Item = (FuncId, &FunctionDeclaration)> {
703        self.functions.iter()
704    }
705
706    /// Return whether `name` names a function, rather than a data object.
707    pub fn is_function(name: &ModuleRelocTarget) -> bool {
708        match name {
709            ModuleRelocTarget::User { namespace, .. } => *namespace == 0,
710            ModuleRelocTarget::LibCall(_)
711            | ModuleRelocTarget::KnownSymbol(_)
712            | ModuleRelocTarget::FunctionOffset(..) => {
713                panic!("unexpected module ext name")
714            }
715        }
716    }
717
718    /// Get the `FunctionDeclaration` for the function named by `name`.
719    pub fn get_function_decl(&self, func_id: FuncId) -> &FunctionDeclaration {
720        &self.functions[func_id]
721    }
722
723    /// Get an iterator of all data declarations
724    pub fn get_data_objects(&self) -> impl Iterator<Item = (DataId, &DataDeclaration)> {
725        self.data_objects.iter()
726    }
727
728    /// Get the `DataDeclaration` for the data object named by `name`.
729    pub fn get_data_decl(&self, data_id: DataId) -> &DataDeclaration {
730        &self.data_objects[data_id]
731    }
732
733    /// Declare a function in this module.
734    pub fn declare_function(
735        &mut self,
736        name: &str,
737        linkage: Linkage,
738        signature: &ir::Signature,
739    ) -> ModuleResult<(FuncId, Linkage)> {
740        // TODO: Can we avoid allocating names so often?
741        use super::hash_map::Entry::*;
742        match self.names.entry(name.to_owned()) {
743            Occupied(entry) => match *entry.get() {
744                FuncOrDataId::Func(id) => {
745                    let existing = &mut self.functions[id];
746                    existing.merge(id, linkage, signature)?;
747                    Ok((id, existing.linkage))
748                }
749                FuncOrDataId::Data(..) => {
750                    Err(ModuleError::IncompatibleDeclaration(name.to_owned()))
751                }
752            },
753            Vacant(entry) => {
754                let id = self.functions.push(FunctionDeclaration {
755                    name: Some(name.to_owned()),
756                    linkage,
757                    signature: signature.clone(),
758                });
759                entry.insert(FuncOrDataId::Func(id));
760                Ok((id, self.functions[id].linkage))
761            }
762        }
763    }
764
765    /// Declare an anonymous function in this module.
766    pub fn declare_anonymous_function(
767        &mut self,
768        signature: &ir::Signature,
769    ) -> ModuleResult<FuncId> {
770        let id = self.functions.push(FunctionDeclaration {
771            name: None,
772            linkage: Linkage::Local,
773            signature: signature.clone(),
774        });
775        Ok(id)
776    }
777
778    /// Declare a data object in this module.
779    pub fn declare_data(
780        &mut self,
781        name: &str,
782        linkage: Linkage,
783        writable: bool,
784        tls: bool,
785    ) -> ModuleResult<(DataId, Linkage)> {
786        // TODO: Can we avoid allocating names so often?
787        use super::hash_map::Entry::*;
788        match self.names.entry(name.to_owned()) {
789            Occupied(entry) => match *entry.get() {
790                FuncOrDataId::Data(id) => {
791                    let existing = &mut self.data_objects[id];
792                    existing.merge(linkage, writable, tls);
793                    Ok((id, existing.linkage))
794                }
795
796                FuncOrDataId::Func(..) => {
797                    Err(ModuleError::IncompatibleDeclaration(name.to_owned()))
798                }
799            },
800            Vacant(entry) => {
801                let id = self.data_objects.push(DataDeclaration {
802                    name: Some(name.to_owned()),
803                    linkage,
804                    writable,
805                    tls,
806                });
807                entry.insert(FuncOrDataId::Data(id));
808                Ok((id, self.data_objects[id].linkage))
809            }
810        }
811    }
812
813    /// Declare an anonymous data object in this module.
814    pub fn declare_anonymous_data(&mut self, writable: bool, tls: bool) -> ModuleResult<DataId> {
815        let id = self.data_objects.push(DataDeclaration {
816            name: None,
817            linkage: Linkage::Local,
818            writable,
819            tls,
820        });
821        Ok(id)
822    }
823}
824
825/// A `Module` is a utility for collecting functions and data objects, and linking them together.
826pub trait Module {
827    /// Return the `TargetIsa` to compile for.
828    fn isa(&self) -> &dyn isa::TargetIsa;
829
830    /// Get all declarations in this module.
831    fn declarations(&self) -> &ModuleDeclarations;
832
833    /// Get the module identifier for a given name, if that name
834    /// has been declared.
835    fn get_name(&self, name: &str) -> Option<FuncOrDataId> {
836        self.declarations().get_name(name)
837    }
838
839    /// Return the target information needed by frontends to produce Cranelift IR
840    /// for the current target.
841    fn target_config(&self) -> isa::TargetFrontendConfig {
842        self.isa().frontend_config()
843    }
844
845    /// Create a new `Context` initialized for use with this `Module`.
846    ///
847    /// This ensures that the `Context` is initialized with the default calling
848    /// convention for the `TargetIsa`.
849    fn make_context(&self) -> Context {
850        let mut ctx = Context::new();
851        ctx.func.signature.call_conv = self.isa().default_call_conv();
852        ctx
853    }
854
855    /// Clear the given `Context` and reset it for use with a new function.
856    ///
857    /// This ensures that the `Context` is initialized with the default calling
858    /// convention for the `TargetIsa`.
859    fn clear_context(&self, ctx: &mut Context) {
860        ctx.clear();
861        ctx.func.signature.call_conv = self.isa().default_call_conv();
862    }
863
864    /// Create a new empty `Signature` with the default calling convention for
865    /// the `TargetIsa`, to which parameter and return types can be added for
866    /// declaring a function to be called by this `Module`.
867    fn make_signature(&self) -> ir::Signature {
868        ir::Signature::new(self.isa().default_call_conv())
869    }
870
871    /// Clear the given `Signature` and reset for use with a new function.
872    ///
873    /// This ensures that the `Signature` is initialized with the default
874    /// calling convention for the `TargetIsa`.
875    fn clear_signature(&self, sig: &mut ir::Signature) {
876        sig.clear(self.isa().default_call_conv());
877    }
878
879    /// Declare a function in this module.
880    fn declare_function(
881        &mut self,
882        name: &str,
883        linkage: Linkage,
884        signature: &ir::Signature,
885    ) -> ModuleResult<FuncId>;
886
887    /// Declare an anonymous function in this module.
888    fn declare_anonymous_function(&mut self, signature: &ir::Signature) -> ModuleResult<FuncId>;
889
890    /// Declare a data object in this module.
891    fn declare_data(
892        &mut self,
893        name: &str,
894        linkage: Linkage,
895        writable: bool,
896        tls: bool,
897    ) -> ModuleResult<DataId>;
898
899    /// Declare an anonymous data object in this module.
900    fn declare_anonymous_data(&mut self, writable: bool, tls: bool) -> ModuleResult<DataId>;
901
902    /// Use this when you're building the IR of a function to reference a function.
903    ///
904    /// TODO: Coalesce redundant decls and signatures.
905    /// TODO: Look into ways to reduce the risk of using a FuncRef in the wrong function.
906    fn declare_func_in_func(&mut self, func_id: FuncId, func: &mut ir::Function) -> ir::FuncRef {
907        let decl = &self.declarations().functions[func_id];
908        let signature = func.import_signature(decl.signature.clone());
909        let user_name_ref = func.declare_imported_user_function(ir::UserExternalName {
910            namespace: 0,
911            index: func_id.as_u32(),
912        });
913        let colocated = decl.linkage.is_final();
914        func.import_function(ir::ExtFuncData {
915            name: ir::ExternalName::user(user_name_ref),
916            signature,
917            colocated,
918            patchable: false,
919        })
920    }
921
922    /// Use this when you're building the IR of a function to reference a data object.
923    ///
924    /// TODO: Same as above.
925    fn declare_data_in_func(&self, data: DataId, func: &mut ir::Function) -> ir::GlobalValue {
926        let decl = &self.declarations().data_objects[data];
927        let colocated = decl.linkage.is_final();
928        let user_name_ref = func.declare_imported_user_function(ir::UserExternalName {
929            namespace: 1,
930            index: data.as_u32(),
931        });
932        func.create_global_value(ir::GlobalValueData::Symbol {
933            name: ir::ExternalName::user(user_name_ref),
934            offset: ir::immediates::Imm64::new(0),
935            colocated,
936            tls: decl.tls,
937        })
938    }
939
940    /// TODO: Same as above.
941    fn declare_func_in_data(&self, func_id: FuncId, data: &mut DataDescription) -> ir::FuncRef {
942        data.import_function(ModuleRelocTarget::user(0, func_id.as_u32()))
943    }
944
945    /// TODO: Same as above.
946    fn declare_data_in_data(&self, data_id: DataId, data: &mut DataDescription) -> ir::GlobalValue {
947        data.import_global_value(ModuleRelocTarget::user(1, data_id.as_u32()))
948    }
949
950    /// Define a function, producing the function body from the given `Context`.
951    ///
952    /// Returns the size of the function's code and constant data.
953    ///
954    /// Unlike [`define_function_with_control_plane`] this uses a default [`ControlPlane`] for
955    /// convenience.
956    ///
957    /// Note: After calling this function the given `Context` will contain the compiled function.
958    ///
959    /// [`define_function_with_control_plane`]: Self::define_function_with_control_plane
960    fn define_function(&mut self, func: FuncId, ctx: &mut Context) -> ModuleResult<()> {
961        self.define_function_with_control_plane(func, ctx, &mut ControlPlane::default())
962    }
963
964    /// Define a function, producing the function body from the given `Context`.
965    ///
966    /// Returns the size of the function's code and constant data.
967    ///
968    /// Note: After calling this function the given `Context` will contain the compiled function.
969    fn define_function_with_control_plane(
970        &mut self,
971        func: FuncId,
972        ctx: &mut Context,
973        ctrl_plane: &mut ControlPlane,
974    ) -> ModuleResult<()>;
975
976    /// Define a function, taking the function body from the given `bytes`.
977    ///
978    /// This function is generally only useful if you need to precisely specify
979    /// the emitted instructions for some reason; otherwise, you should use
980    /// `define_function`.
981    ///
982    /// Returns the size of the function's code.
983    fn define_function_bytes(
984        &mut self,
985        func_id: FuncId,
986        alignment: u64,
987        bytes: &[u8],
988        relocs: &[ModuleReloc],
989    ) -> ModuleResult<()>;
990
991    /// Define a data object, producing the data contents from the given `DataDescription`.
992    fn define_data(&mut self, data_id: DataId, data: &DataDescription) -> ModuleResult<()>;
993}
994
995impl<M: Module + ?Sized> Module for &mut M {
996    fn isa(&self) -> &dyn isa::TargetIsa {
997        (**self).isa()
998    }
999
1000    fn declarations(&self) -> &ModuleDeclarations {
1001        (**self).declarations()
1002    }
1003
1004    fn get_name(&self, name: &str) -> Option<FuncOrDataId> {
1005        (**self).get_name(name)
1006    }
1007
1008    fn target_config(&self) -> isa::TargetFrontendConfig {
1009        (**self).target_config()
1010    }
1011
1012    fn make_context(&self) -> Context {
1013        (**self).make_context()
1014    }
1015
1016    fn clear_context(&self, ctx: &mut Context) {
1017        (**self).clear_context(ctx)
1018    }
1019
1020    fn make_signature(&self) -> ir::Signature {
1021        (**self).make_signature()
1022    }
1023
1024    fn clear_signature(&self, sig: &mut ir::Signature) {
1025        (**self).clear_signature(sig)
1026    }
1027
1028    fn declare_function(
1029        &mut self,
1030        name: &str,
1031        linkage: Linkage,
1032        signature: &ir::Signature,
1033    ) -> ModuleResult<FuncId> {
1034        (**self).declare_function(name, linkage, signature)
1035    }
1036
1037    fn declare_anonymous_function(&mut self, signature: &ir::Signature) -> ModuleResult<FuncId> {
1038        (**self).declare_anonymous_function(signature)
1039    }
1040
1041    fn declare_data(
1042        &mut self,
1043        name: &str,
1044        linkage: Linkage,
1045        writable: bool,
1046        tls: bool,
1047    ) -> ModuleResult<DataId> {
1048        (**self).declare_data(name, linkage, writable, tls)
1049    }
1050
1051    fn declare_anonymous_data(&mut self, writable: bool, tls: bool) -> ModuleResult<DataId> {
1052        (**self).declare_anonymous_data(writable, tls)
1053    }
1054
1055    fn declare_func_in_func(&mut self, func: FuncId, in_func: &mut ir::Function) -> ir::FuncRef {
1056        (**self).declare_func_in_func(func, in_func)
1057    }
1058
1059    fn declare_data_in_func(&self, data: DataId, func: &mut ir::Function) -> ir::GlobalValue {
1060        (**self).declare_data_in_func(data, func)
1061    }
1062
1063    fn declare_func_in_data(&self, func_id: FuncId, data: &mut DataDescription) -> ir::FuncRef {
1064        (**self).declare_func_in_data(func_id, data)
1065    }
1066
1067    fn declare_data_in_data(&self, data_id: DataId, data: &mut DataDescription) -> ir::GlobalValue {
1068        (**self).declare_data_in_data(data_id, data)
1069    }
1070
1071    fn define_function(&mut self, func: FuncId, ctx: &mut Context) -> ModuleResult<()> {
1072        (**self).define_function(func, ctx)
1073    }
1074
1075    fn define_function_with_control_plane(
1076        &mut self,
1077        func: FuncId,
1078        ctx: &mut Context,
1079        ctrl_plane: &mut ControlPlane,
1080    ) -> ModuleResult<()> {
1081        (**self).define_function_with_control_plane(func, ctx, ctrl_plane)
1082    }
1083
1084    fn define_function_bytes(
1085        &mut self,
1086        func_id: FuncId,
1087        alignment: u64,
1088        bytes: &[u8],
1089        relocs: &[ModuleReloc],
1090    ) -> ModuleResult<()> {
1091        (**self).define_function_bytes(func_id, alignment, bytes, relocs)
1092    }
1093
1094    fn define_data(&mut self, data_id: DataId, data: &DataDescription) -> ModuleResult<()> {
1095        (**self).define_data(data_id, data)
1096    }
1097}
1098
1099impl<M: Module + ?Sized> Module for Box<M> {
1100    fn isa(&self) -> &dyn isa::TargetIsa {
1101        (**self).isa()
1102    }
1103
1104    fn declarations(&self) -> &ModuleDeclarations {
1105        (**self).declarations()
1106    }
1107
1108    fn get_name(&self, name: &str) -> Option<FuncOrDataId> {
1109        (**self).get_name(name)
1110    }
1111
1112    fn target_config(&self) -> isa::TargetFrontendConfig {
1113        (**self).target_config()
1114    }
1115
1116    fn make_context(&self) -> Context {
1117        (**self).make_context()
1118    }
1119
1120    fn clear_context(&self, ctx: &mut Context) {
1121        (**self).clear_context(ctx)
1122    }
1123
1124    fn make_signature(&self) -> ir::Signature {
1125        (**self).make_signature()
1126    }
1127
1128    fn clear_signature(&self, sig: &mut ir::Signature) {
1129        (**self).clear_signature(sig)
1130    }
1131
1132    fn declare_function(
1133        &mut self,
1134        name: &str,
1135        linkage: Linkage,
1136        signature: &ir::Signature,
1137    ) -> ModuleResult<FuncId> {
1138        (**self).declare_function(name, linkage, signature)
1139    }
1140
1141    fn declare_anonymous_function(&mut self, signature: &ir::Signature) -> ModuleResult<FuncId> {
1142        (**self).declare_anonymous_function(signature)
1143    }
1144
1145    fn declare_data(
1146        &mut self,
1147        name: &str,
1148        linkage: Linkage,
1149        writable: bool,
1150        tls: bool,
1151    ) -> ModuleResult<DataId> {
1152        (**self).declare_data(name, linkage, writable, tls)
1153    }
1154
1155    fn declare_anonymous_data(&mut self, writable: bool, tls: bool) -> ModuleResult<DataId> {
1156        (**self).declare_anonymous_data(writable, tls)
1157    }
1158
1159    fn declare_func_in_func(&mut self, func: FuncId, in_func: &mut ir::Function) -> ir::FuncRef {
1160        (**self).declare_func_in_func(func, in_func)
1161    }
1162
1163    fn declare_data_in_func(&self, data: DataId, func: &mut ir::Function) -> ir::GlobalValue {
1164        (**self).declare_data_in_func(data, func)
1165    }
1166
1167    fn declare_func_in_data(&self, func_id: FuncId, data: &mut DataDescription) -> ir::FuncRef {
1168        (**self).declare_func_in_data(func_id, data)
1169    }
1170
1171    fn declare_data_in_data(&self, data_id: DataId, data: &mut DataDescription) -> ir::GlobalValue {
1172        (**self).declare_data_in_data(data_id, data)
1173    }
1174
1175    fn define_function(&mut self, func: FuncId, ctx: &mut Context) -> ModuleResult<()> {
1176        (**self).define_function(func, ctx)
1177    }
1178
1179    fn define_function_with_control_plane(
1180        &mut self,
1181        func: FuncId,
1182        ctx: &mut Context,
1183        ctrl_plane: &mut ControlPlane,
1184    ) -> ModuleResult<()> {
1185        (**self).define_function_with_control_plane(func, ctx, ctrl_plane)
1186    }
1187
1188    fn define_function_bytes(
1189        &mut self,
1190        func_id: FuncId,
1191        alignment: u64,
1192        bytes: &[u8],
1193        relocs: &[ModuleReloc],
1194    ) -> ModuleResult<()> {
1195        (**self).define_function_bytes(func_id, alignment, bytes, relocs)
1196    }
1197
1198    fn define_data(&mut self, data_id: DataId, data: &DataDescription) -> ModuleResult<()> {
1199        (**self).define_data(data_id, data)
1200    }
1201}
cranelift_module/module.rs

cranelift_module/
module.rs
