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}