Skip to main content

cranelift_codegen/binemit/
mod.rs

1//! Binary machine code emission.
2//!
3//! The `binemit` module contains code for translating Cranelift's intermediate representation into
4//! binary machine code.
5
6use core::fmt;
7#[cfg(feature = "enable-serde")]
8use serde_derive::{Deserialize, Serialize};
9
10/// Offset in bytes from the beginning of the function.
11///
12/// Cranelift can be used as a cross compiler, so we don't want to use a type like `usize` which
13/// depends on the *host* platform, not the *target* platform.
14pub type CodeOffset = u32;
15
16/// Addend to add to the symbol value.
17pub type Addend = i64;
18
19/// Relocation kinds for every ISA
20#[derive(Copy, Clone, Debug, PartialEq, Eq)]
21#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
22pub enum Reloc {
23    /// absolute 4-byte
24    Abs4,
25    /// absolute 8-byte
26    Abs8,
27    /// x86 PC-relative 4-byte
28    X86PCRel4,
29    /// x86 call to PC-relative 4-byte.
30    ///
31    /// This relocation is only ever applied to the displacement of a `call`
32    /// or `jmp` instruction, never to address materialization (e.g. `lea`,
33    /// which uses [`Reloc::X86PCRel4`] instead). Consumers may therefore
34    /// redirect the control transfer through a veneer when the target is out
35    /// of range of the 32-bit displacement.
36    X86CallPCRel4,
37    /// x86 call to PLT-relative 4-byte
38    X86CallPLTRel4,
39    /// x86 GOT PC-relative 4-byte
40    X86GOTPCRel4,
41    /// The 32-bit offset of the target from the beginning of its section.
42    /// Equivalent to `IMAGE_REL_AMD64_SECREL`.
43    /// See: [PE Format](https://docs.microsoft.com/en-us/windows/win32/debug/pe-format)
44    X86SecRel,
45    /// Arm32 call target
46    Arm32Call,
47    /// Arm64 call target. Encoded as bottom 26 bits of instruction. This
48    /// value is sign-extended, multiplied by 4, and added to the PC of
49    /// the call instruction to form the destination address.
50    Arm64Call,
51    /// s390x PC-relative 4-byte offset
52    S390xPCRel32Dbl,
53    /// s390x PC-relative 4-byte offset to PLT
54    S390xPLTRel32Dbl,
55    /// s390x PC-relative 4-byte doubled offset to GOT entry (R_390_GOTENT).
56    ///
57    /// Applied to the 32-bit doubled-offset field of a LARL instruction.
58    /// The linker fills in the PC-relative distance (in doublewords) to the
59    /// GOT entry for the referenced symbol.
60    S390xGOTRel32Dbl,
61
62    /// Elf x86_64 32 bit signed PC relative offset to two GOT entries for GD symbol.
63    ElfX86_64TlsGd,
64
65    /// Mach-O x86_64 32 bit signed PC relative offset to a `__thread_vars` entry.
66    MachOX86_64Tlv,
67
68    /// Mach-O Aarch64 TLS
69    /// PC-relative distance to the page of the TLVP slot.
70    MachOAarch64TlsAdrPage21,
71
72    /// Mach-O Aarch64 TLS
73    /// Offset within page of TLVP slot.
74    MachOAarch64TlsAdrPageOff12,
75
76    /// Aarch64 TLSDESC Adr Page21
77    /// This is equivalent to `R_AARCH64_TLSDESC_ADR_PAGE21` in the [aaelf64](https://github.com/ARM-software/abi-aa/blob/2bcab1e3b22d55170c563c3c7940134089176746/aaelf64/aaelf64.rst#57105thread-local-storage-descriptors)
78    Aarch64TlsDescAdrPage21,
79
80    /// Aarch64 TLSDESC Ld64 Lo12
81    /// This is equivalent to `R_AARCH64_TLSDESC_LD64_LO12` in the [aaelf64](https://github.com/ARM-software/abi-aa/blob/2bcab1e3b22d55170c563c3c7940134089176746/aaelf64/aaelf64.rst#57105thread-local-storage-descriptors)
82    Aarch64TlsDescLd64Lo12,
83
84    /// Aarch64 TLSDESC Add Lo12
85    /// This is equivalent to `R_AARCH64_TLSGD_ADD_LO12` in the [aaelf64](https://github.com/ARM-software/abi-aa/blob/2bcab1e3b22d55170c563c3c7940134089176746/aaelf64/aaelf64.rst#57105thread-local-storage-descriptors)
86    Aarch64TlsDescAddLo12,
87
88    /// Aarch64 TLSDESC Call
89    /// This is equivalent to `R_AARCH64_TLSDESC_CALL` in the [aaelf64](https://github.com/ARM-software/abi-aa/blob/2bcab1e3b22d55170c563c3c7940134089176746/aaelf64/aaelf64.rst#57105thread-local-storage-descriptors)
90    Aarch64TlsDescCall,
91
92    /// AArch64 GOT Page
93    /// Set the immediate value of an ADRP to bits 32:12 of X; check that –2^32 <= X < 2^32
94    /// This is equivalent to `R_AARCH64_ADR_GOT_PAGE` (311) in the  [aaelf64](https://github.com/ARM-software/abi-aa/blob/2bcab1e3b22d55170c563c3c7940134089176746/aaelf64/aaelf64.rst#static-aarch64-relocations)
95    Aarch64AdrGotPage21,
96
97    /// Equivalent of `R_AARCH64_ADR_PREL_PG_HI21`.
98    Aarch64AdrPrelPgHi21,
99    /// Equivalent of `R_AARCH64_ADD_ABS_LO12_NC`.
100    Aarch64AddAbsLo12Nc,
101
102    /// AArch64 GOT Low bits
103
104    /// Set the LD/ST immediate field to bits 11:3 of X. No overflow check; check that X&7 = 0
105    /// This is equivalent to `R_AARCH64_LD64_GOT_LO12_NC` (312) in the  [aaelf64](https://github.com/ARM-software/abi-aa/blob/2bcab1e3b22d55170c563c3c7940134089176746/aaelf64/aaelf64.rst#static-aarch64-relocations)
106    Aarch64Ld64GotLo12Nc,
107
108    /// RISC-V Call PLT: 32-bit PC-relative function call, macros call, tail (PIC)
109    ///
110    /// Despite having PLT in the name, this relocation is also used for normal calls.
111    /// The non-PLT version of this relocation has been deprecated.
112    ///
113    /// This is the `R_RISCV_CALL_PLT` relocation from the RISC-V ELF psABI document.
114    /// <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-elf.adoc#procedure-calls>
115    RiscvCallPlt,
116
117    /// RISC-V TLS GD: High 20 bits of 32-bit PC-relative TLS GD GOT reference,
118    ///
119    /// This is the `R_RISCV_TLS_GD_HI20` relocation from the RISC-V ELF psABI document.
120    /// <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-elf.adoc#global-dynamic>
121    RiscvTlsGdHi20,
122
123    /// Low 12 bits of a 32-bit PC-relative relocation (I-Type instruction)
124    ///
125    /// This is the `R_RISCV_PCREL_LO12_I` relocation from the RISC-V ELF psABI document.
126    /// <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-elf.adoc#pc-relative-symbol-addresses>
127    RiscvPCRelLo12I,
128
129    /// High 20 bits of a 32-bit PC-relative GOT offset relocation
130    ///
131    /// This is the `R_RISCV_GOT_HI20` relocation from the RISC-V ELF psABI document.
132    /// <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-elf.adoc#pc-relative-symbol-addresses>
133    RiscvGotHi20,
134
135    /// High 20 bits of a 32-bit PC-relative offset relocation
136    ///
137    /// This is the `R_RISCV_PCREL_HI20` relocation from the RISC-V ELF psABI document.
138    /// <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-elf.adoc#pc-relative-symbol-addresses>
139    RiscvPCRelHi20,
140
141    /// s390x TLS GD64 - 64-bit offset of tls_index for GD symbol in GOT
142    S390xTlsGd64,
143    /// s390x TLS GDCall - marker to enable optimization of TLS calls
144    S390xTlsGdCall,
145
146    /// Pulley - a relocation which is a pc-relative offset.
147    PulleyPcRel,
148
149    /// Pulley - call a host function indirectly where the embedder resolving
150    /// this relocation needs to fill the 8-bit immediate that's part of the
151    /// `call_indirect_host` opcode (an opaque identifier used by the host).
152    PulleyCallIndirectHost,
153}
154
155impl Reloc {
156    /// The number of bytes from the relocation's offset that applying it, or a
157    /// linker relaxing it, may read or write.
158    ///
159    /// This runs to the end of the instruction, or of the whole sequence for
160    /// relocations such as [`Reloc::ElfX86_64TlsGd`] that a linker rewrites
161    /// together. Bytes before the offset are not counted.
162    pub fn patched_len(self) -> u32 {
163        match self {
164            Self::Abs4
165            | Self::X86PCRel4
166            | Self::X86CallPCRel4
167            | Self::X86CallPLTRel4
168            | Self::X86GOTPCRel4
169            | Self::X86SecRel
170            | Self::Arm32Call
171            | Self::Arm64Call
172            | Self::S390xPCRel32Dbl
173            | Self::S390xPLTRel32Dbl
174            | Self::S390xGOTRel32Dbl
175            | Self::MachOX86_64Tlv
176            | Self::MachOAarch64TlsAdrPage21
177            | Self::MachOAarch64TlsAdrPageOff12
178            | Self::Aarch64TlsDescAdrPage21
179            | Self::Aarch64TlsDescLd64Lo12
180            | Self::Aarch64TlsDescAddLo12
181            | Self::Aarch64TlsDescCall
182            | Self::Aarch64AdrGotPage21
183            | Self::Aarch64AdrPrelPgHi21
184            | Self::Aarch64AddAbsLo12Nc
185            | Self::Aarch64Ld64GotLo12Nc
186            | Self::RiscvTlsGdHi20
187            | Self::RiscvPCRelLo12I
188            | Self::RiscvGotHi20
189            | Self::RiscvPCRelHi20
190            | Self::PulleyPcRel
191            | Self::PulleyCallIndirectHost => 4,
192            // The `lea` displacement and the `call` after it. The linker rewrites
193            // the whole general-dynamic sequence when it relaxes it.
194            Self::ElfX86_64TlsGd => 12,
195            // The `brasl` that the marker is attached to.
196            Self::S390xTlsGdCall => 6,
197            // `RiscvCallPlt` patches the `auipc` and `jalr` pair of a call.
198            Self::Abs8 | Self::S390xTlsGd64 | Self::RiscvCallPlt => 8,
199        }
200    }
201}
202
203impl fmt::Display for Reloc {
204    /// Display trait implementation drops the arch, since its used in contexts where the arch is
205    /// already unambiguous, e.g. clif syntax with isa specified. In other contexts, use Debug.
206    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
207        match *self {
208            Self::Abs4 => write!(f, "Abs4"),
209            Self::Abs8 => write!(f, "Abs8"),
210            Self::S390xPCRel32Dbl => write!(f, "PCRel32Dbl"),
211            Self::S390xPLTRel32Dbl => write!(f, "PLTRel32Dbl"),
212            Self::S390xGOTRel32Dbl => write!(f, "GOTRel32Dbl"),
213            Self::X86PCRel4 => write!(f, "PCRel4"),
214            Self::X86CallPCRel4 => write!(f, "CallPCRel4"),
215            Self::X86CallPLTRel4 => write!(f, "CallPLTRel4"),
216            Self::X86GOTPCRel4 => write!(f, "GOTPCRel4"),
217            Self::X86SecRel => write!(f, "SecRel"),
218            Self::Arm32Call | Self::Arm64Call => write!(f, "Call"),
219            Self::RiscvCallPlt => write!(f, "RiscvCallPlt"),
220            Self::RiscvTlsGdHi20 => write!(f, "RiscvTlsGdHi20"),
221            Self::RiscvGotHi20 => write!(f, "RiscvGotHi20"),
222            Self::RiscvPCRelHi20 => write!(f, "RiscvPCRelHi20"),
223            Self::RiscvPCRelLo12I => write!(f, "RiscvPCRelLo12I"),
224            Self::ElfX86_64TlsGd => write!(f, "ElfX86_64TlsGd"),
225            Self::MachOX86_64Tlv => write!(f, "MachOX86_64Tlv"),
226            Self::MachOAarch64TlsAdrPage21 => write!(f, "MachOAarch64TlsAdrPage21"),
227            Self::MachOAarch64TlsAdrPageOff12 => write!(f, "MachOAarch64TlsAdrPageOff12"),
228            Self::Aarch64TlsDescAdrPage21 => write!(f, "Aarch64TlsDescAdrPage21"),
229            Self::Aarch64TlsDescLd64Lo12 => write!(f, "Aarch64TlsDescLd64Lo12"),
230            Self::Aarch64TlsDescAddLo12 => write!(f, "Aarch64TlsDescAddLo12"),
231            Self::Aarch64TlsDescCall => write!(f, "Aarch64TlsDescCall"),
232            Self::Aarch64AdrGotPage21 => write!(f, "Aarch64AdrGotPage21"),
233            Self::Aarch64Ld64GotLo12Nc => write!(f, "Aarch64AdrGotLo12Nc"),
234            Self::Aarch64AdrPrelPgHi21 => write!(f, "Aarch64AdrPrelPgHi21"),
235            Self::Aarch64AddAbsLo12Nc => write!(f, "Aarch64AddAbsLo12Nc"),
236            Self::S390xTlsGd64 => write!(f, "TlsGd64"),
237            Self::S390xTlsGdCall => write!(f, "TlsGdCall"),
238            Self::PulleyPcRel => write!(f, "PulleyPcRel"),
239            Self::PulleyCallIndirectHost => write!(f, "PulleyCallIndirectHost"),
240        }
241    }
242}
243
244/// Container for information about a vector of compiled code and its supporting read-only data.
245///
246/// The code starts at offset 0 and is followed optionally by relocatable jump tables and copyable
247/// (raw binary) read-only data.  Any padding between sections is always part of the section that
248/// precedes the boundary between the sections.
249#[derive(Debug, PartialEq)]
250pub struct CodeInfo {
251    /// Number of bytes in total.
252    pub total_size: CodeOffset,
253}