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

cranelift_module/
module.rs
