Line data Source code
1 : use super::Command;
2 : use crate::common::FromFFI;
3 : use crate::{declare_iterator, to_slice};
4 : use lief_ffi as ffi;
5 : use std::marker::PhantomData;
6 :
7 : /// Class representing the `LC_FUNCTION_VARIANTS` load command.
8 : ///
9 : /// Introduced publicly in `dyld-1284.13` (April 2025), this command supports
10 : /// **function multiversioning**, the ability to associate multiple implementations
11 : /// of the same function, each optimized for a specific platform, architecture,
12 : /// or runtime context.
13 : ///
14 : /// At runtime, the system dispatches the most appropriate variant based on
15 : /// hardware capabilities or execution environment.
16 : ///
17 : /// For example:
18 : ///
19 : /// ```cpp
20 : /// FUNCTION_VARIANT_TABLE(my_function,
21 : /// { (void*)my_function$Rosetta, "rosetta" }, // Rosetta translation
22 : /// { (void*)my_function$Haswell, "haswell" }, // Haswell-optimized
23 : /// { (void*)my_function$Base, "default" } // Default fallback
24 : /// );
25 : /// ```
26 : pub struct FunctionVariants<'a> {
27 : ptr: cxx::UniquePtr<ffi::MachO_FunctionVariants>,
28 : _owner: PhantomData<&'a ffi::MachO_Binary>,
29 : }
30 :
31 : impl FunctionVariants<'_> {
32 : /// Offset in the `__LINKEDIT` segment where the payload is located
33 26 : pub fn data_offset(&self) -> u32 {
34 26 : self.ptr.data_offset()
35 26 : }
36 :
37 : /// Size of the payload
38 26 : pub fn data_size(&self) -> u32 {
39 26 : self.ptr.data_size()
40 26 : }
41 :
42 : /// Raw payload as a slice of bytes
43 0 : pub fn content(&self) -> &[u8] {
44 0 : to_slice!(self.ptr.content());
45 0 : }
46 :
47 : /// Iterator over the different [`RuntimeTable`] entries located in the content
48 : /// of this `__LINKEDIT` command
49 13 : pub fn runtime_table(&self) -> RuntimeTables<'_> {
50 13 : RuntimeTables::new(self.ptr.runtime_table())
51 13 : }
52 : }
53 :
54 : impl std::fmt::Debug for FunctionVariants<'_> {
55 26 : fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
56 26 : let base = self as &dyn Command;
57 26 : f.debug_struct("FunctionVariants")
58 26 : .field("base", &base)
59 26 : .field("data_offset", &self.data_offset())
60 26 : .field("data_size", &self.data_size())
61 26 : .finish()
62 26 : }
63 : }
64 :
65 : impl FromFFI<ffi::MachO_FunctionVariants> for FunctionVariants<'_> {
66 13 : fn from_ffi(cmd: cxx::UniquePtr<ffi::MachO_FunctionVariants>) -> Self {
67 13 : Self {
68 13 : ptr: cmd,
69 13 : _owner: PhantomData,
70 13 : }
71 13 : }
72 : }
73 :
74 : impl Command for FunctionVariants<'_> {
75 104 : fn get_base(&self) -> &ffi::MachO_Command {
76 104 : self.ptr.as_ref().unwrap().as_ref()
77 104 : }
78 : }
79 :
80 : /// Represents a runtime table of function variants sharing a common namespace
81 : /// (referred to internally as `FunctionVariantsRuntimeTable` in `dyld`).
82 : ///
83 : /// Each table holds multiple [`RuntimeTableEntry`] instances that map to
84 : /// function implementations optimized for a given [`Kind`].
85 : pub struct RuntimeTable<'a> {
86 : ptr: cxx::UniquePtr<ffi::MachO_FunctionVariants_RuntimeTable>,
87 : _owner: PhantomData<&'a ffi::MachO_FunctionVariants>,
88 : }
89 :
90 : impl FromFFI<ffi::MachO_FunctionVariants_RuntimeTable> for RuntimeTable<'_> {
91 26 : fn from_ffi(cmd: cxx::UniquePtr<ffi::MachO_FunctionVariants_RuntimeTable>) -> Self {
92 26 : Self {
93 26 : ptr: cmd,
94 26 : _owner: PhantomData,
95 26 : }
96 26 : }
97 : }
98 :
99 : impl RuntimeTable<'_> {
100 : /// Kind of this runtime table
101 26 : pub fn kind(&self) -> Kind {
102 26 : Kind::from(self.ptr.kind())
103 26 : }
104 :
105 : /// Original offset in the payload
106 26 : pub fn offset(&self) -> u32 {
107 26 : self.ptr.offset()
108 26 : }
109 :
110 : /// Iterator over the different [`RuntimeTableEntry`] entries
111 26 : pub fn entries(&self) -> RuntimeTableEntries<'_> {
112 26 : RuntimeTableEntries::new(self.ptr.entries())
113 26 : }
114 : }
115 :
116 : impl std::fmt::Debug for RuntimeTable<'_> {
117 26 : fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
118 26 : f.debug_struct("RuntimeTable")
119 26 : .field("kind", &self.kind())
120 26 : .field("offset", &self.offset())
121 26 : .finish()
122 26 : }
123 : }
124 :
125 : impl std::fmt::Display for RuntimeTable<'_> {
126 26 : fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
127 26 : write!(f, "{}", self.ptr.to_string())
128 26 : }
129 : }
130 :
131 : #[allow(non_camel_case_types)]
132 26 : #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
133 : /// Enumeration describing the namespace or category of a function variant.
134 : ///
135 : /// Each [`RuntimeTable`] is associated with one [`Kind`],
136 : /// which indicates the domain or context under which its variant entries
137 : /// should be considered valid or applicable.
138 : ///
139 : /// These categories map to the runtime dispatch logic used by `dyld`
140 : /// when selecting the optimal function variant.
141 : pub enum Kind {
142 : /// Variants that apply on a per-process basis
143 : PER_PROCESS,
144 :
145 : /// Variants that are selected based on system-wide capabilities or configurations.
146 : SYSTEM_WIDE,
147 :
148 : /// Variants optimized for the ARM64 architecture.
149 : ARM64,
150 :
151 : /// Variants optimized for the x86-64 architecture.
152 : X86_64,
153 :
154 : /// Fallback/default kind when the category is not recognized.
155 : UNKNOWN(u32),
156 : }
157 :
158 : impl From<u32> for Kind {
159 26 : fn from(value: u32) -> Self {
160 26 : match value {
161 0 : 0x00000001 => Kind::PER_PROCESS,
162 0 : 0x00000002 => Kind::SYSTEM_WIDE,
163 0 : 0x00000003 => Kind::ARM64,
164 26 : 0x00000004 => Kind::X86_64,
165 0 : _ => Kind::UNKNOWN(value),
166 : }
167 26 : }
168 : }
169 : impl From<Kind> for u32 {
170 0 : fn from(value: Kind) -> u32 {
171 0 : match value {
172 0 : Kind::PER_PROCESS => 0x00000001,
173 0 : Kind::SYSTEM_WIDE => 0x00000002,
174 0 : Kind::ARM64 => 0x00000003,
175 0 : Kind::X86_64 => 0x00000004,
176 0 : Kind::UNKNOWN(value) => value,
177 : }
178 0 : }
179 : }
180 :
181 : /// This class exposes information about a given implementation.
182 : pub struct RuntimeTableEntry<'a> {
183 : ptr: cxx::UniquePtr<ffi::MachO_FunctionVariants_RuntimeTableEntry>,
184 : _owner: PhantomData<&'a ffi::MachO_FunctionVariants_RuntimeTable>,
185 : }
186 :
187 : impl FromFFI<ffi::MachO_FunctionVariants_RuntimeTableEntry> for RuntimeTableEntry<'_> {
188 78 : fn from_ffi(cmd: cxx::UniquePtr<ffi::MachO_FunctionVariants_RuntimeTableEntry>) -> Self {
189 78 : Self {
190 78 : ptr: cmd,
191 78 : _owner: PhantomData,
192 78 : }
193 78 : }
194 : }
195 :
196 : impl RuntimeTableEntry<'_> {
197 : /// The relative address of the implementation or an index if [`RuntimeTableEntry::another_table`] is set.
198 78 : pub fn implementation(&self) -> u32 {
199 78 : self.ptr.implementation()
200 78 : }
201 :
202 : /// Indicates whether [`RuntimeTableEntry::implementation`] refers to an entry in another runtime table,
203 : /// rather than a direct function implementation address.
204 78 : pub fn another_table(&self) -> bool {
205 78 : self.ptr.another_table()
206 78 : }
207 :
208 : /// The `flagBitNums` value as a slice of bytes
209 78 : pub fn flag_bit_nums(&self) -> &[u8] {
210 78 : to_slice!(self.ptr.flag_bit_nums());
211 78 : }
212 :
213 : /// Return the **interpreted** [`RuntimeTableEntry::flag_bit_nums`]
214 78 : pub fn flags(&self) -> Vec<Flag> {
215 78 : let vec = Vec::from(self.ptr.flags().as_slice());
216 78 : vec.iter().map(|e| Flag::from(*e)).collect()
217 78 : }
218 : }
219 :
220 : impl std::fmt::Debug for RuntimeTableEntry<'_> {
221 78 : fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
222 78 : f.debug_struct("RuntimeTableEntry")
223 78 : .field("implementation", &self.implementation())
224 78 : .field("another_table", &self.another_table())
225 78 : .field("flag_bit_nums", &self.flag_bit_nums())
226 78 : .field("flags", &self.flags())
227 78 : .finish()
228 78 : }
229 : }
230 :
231 : impl std::fmt::Display for RuntimeTableEntry<'_> {
232 78 : fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
233 78 : write!(f, "{}", self.ptr.to_string())
234 78 : }
235 : }
236 :
237 : #[allow(non_camel_case_types)]
238 52 : #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
239 : /// Flags describing the target platform, environment, or architecture
240 : /// for a given function implementation.
241 : ///
242 : /// These are encoded as a `uint32_t`, where high bits determine the namespace
243 : /// ([`Kind`]), and the lower bits encode the specific capability.
244 : pub enum Flag {
245 : ARM64_DEFAULT,
246 : ARM64_FLAGM,
247 : ARM64_FLAGM2,
248 : ARM64_FHM,
249 : ARM64_DOTPROD,
250 : ARM64_SHA3,
251 : ARM64_RDM,
252 : ARM64_LSE,
253 : ARM64_SHA256,
254 : ARM64_SHA512,
255 : ARM64_SHA1,
256 : ARM64_AES,
257 : ARM64_PMULL,
258 : ARM64_SPECRES,
259 : ARM64_SB,
260 : ARM64_FRINTTS,
261 : ARM64_LRCPC,
262 : ARM64_LRCPC2,
263 : ARM64_FCMA,
264 : ARM64_JSCVT,
265 : ARM64_PAUTH,
266 : ARM64_PAUTH2,
267 : ARM64_FPAC,
268 : ARM64_DPB,
269 : ARM64_DPB2,
270 : ARM64_BF16,
271 : ARM64_I8MM,
272 : ARM64_WFXT,
273 : ARM64_RPRES,
274 : ARM64_ECV,
275 : ARM64_AFP,
276 : ARM64_LSE2,
277 : ARM64_CSV2,
278 : ARM64_CVS3,
279 : ARM64_DIT,
280 : ARM64_FP16,
281 : ARM64_SSBS,
282 : ARM64_BTI,
283 : ARM64_SME,
284 : ARM64_SME2,
285 : ARM64_SMEF64F64,
286 : ARM64_SMEI16I64,
287 : ARM64_SMEF32F32,
288 : ARM64_SMEBI32I32,
289 : ARM64_SMEB16F32,
290 : ARM64_SMEF16F32,
291 : ARM64_SMEI8I32,
292 : ARM64_SMEI16I32,
293 : ARM64_ADVSIMD,
294 : ARM64_ADVSIMDHPFP,
295 : ARM64_CRC32,
296 : X86_64_DEFAULT,
297 : X86_64_SSE41,
298 : X86_64_FMA,
299 : X86_64_AVX,
300 : X86_64_AVX2,
301 : X86_64_AVX512F,
302 : X86_64_AVX512BW,
303 : X86_64_BMI1,
304 : X86_64_ROSETTA,
305 : X86_64_HASWELL,
306 : X86_64_IVYBRIDGE,
307 : X86_64_NEHALEM,
308 : SYSTEM_WIDE_DEFAULT,
309 : SYSTEM_WIDE_INTERNAL_INSTALL,
310 : SYSTEM_WIDE_CUSTOMER_INSTALL,
311 : SYSTEM_WIDE_LOCKDOWN,
312 : PER_PROCESS_DEFAULT,
313 : PER_PROCESS_TRANSLATED,
314 : PER_PROCESS_NO_OVERREAD,
315 : UNKNOWN(u32),
316 : }
317 :
318 : impl From<u32> for Flag {
319 52 : fn from(value: u32) -> Self {
320 52 : match value {
321 0 : 0x00300000 => Flag::ARM64_DEFAULT,
322 0 : 0x00300001 => Flag::ARM64_FLAGM,
323 0 : 0x00300002 => Flag::ARM64_FLAGM2,
324 0 : 0x00300003 => Flag::ARM64_FHM,
325 0 : 0x00300004 => Flag::ARM64_DOTPROD,
326 0 : 0x00300005 => Flag::ARM64_SHA3,
327 0 : 0x00300006 => Flag::ARM64_RDM,
328 0 : 0x00300007 => Flag::ARM64_LSE,
329 0 : 0x00300008 => Flag::ARM64_SHA256,
330 0 : 0x00300009 => Flag::ARM64_SHA512,
331 0 : 0x0030000a => Flag::ARM64_SHA1,
332 0 : 0x0030000b => Flag::ARM64_AES,
333 0 : 0x0030000c => Flag::ARM64_PMULL,
334 0 : 0x0030000d => Flag::ARM64_SPECRES,
335 0 : 0x0030000e => Flag::ARM64_SB,
336 0 : 0x0030000f => Flag::ARM64_FRINTTS,
337 0 : 0x00300010 => Flag::ARM64_LRCPC,
338 0 : 0x00300011 => Flag::ARM64_LRCPC2,
339 0 : 0x00300012 => Flag::ARM64_FCMA,
340 0 : 0x00300013 => Flag::ARM64_JSCVT,
341 0 : 0x00300014 => Flag::ARM64_PAUTH,
342 0 : 0x00300015 => Flag::ARM64_PAUTH2,
343 0 : 0x00300016 => Flag::ARM64_FPAC,
344 0 : 0x00300017 => Flag::ARM64_DPB,
345 0 : 0x00300018 => Flag::ARM64_DPB2,
346 0 : 0x00300019 => Flag::ARM64_BF16,
347 0 : 0x0030001a => Flag::ARM64_I8MM,
348 0 : 0x0030001b => Flag::ARM64_WFXT,
349 0 : 0x0030001c => Flag::ARM64_RPRES,
350 0 : 0x0030001d => Flag::ARM64_ECV,
351 0 : 0x0030001e => Flag::ARM64_AFP,
352 0 : 0x0030001f => Flag::ARM64_LSE2,
353 0 : 0x00300020 => Flag::ARM64_CSV2,
354 0 : 0x00300021 => Flag::ARM64_CVS3,
355 0 : 0x00300022 => Flag::ARM64_DIT,
356 0 : 0x00300023 => Flag::ARM64_FP16,
357 0 : 0x00300024 => Flag::ARM64_SSBS,
358 0 : 0x00300025 => Flag::ARM64_BTI,
359 0 : 0x0030002c => Flag::ARM64_SME,
360 0 : 0x0030002d => Flag::ARM64_SME2,
361 0 : 0x0030002e => Flag::ARM64_SMEF64F64,
362 0 : 0x0030002f => Flag::ARM64_SMEI16I64,
363 0 : 0x00300030 => Flag::ARM64_SMEF32F32,
364 0 : 0x00300031 => Flag::ARM64_SMEBI32I32,
365 0 : 0x00300032 => Flag::ARM64_SMEB16F32,
366 0 : 0x00300033 => Flag::ARM64_SMEF16F32,
367 0 : 0x00300034 => Flag::ARM64_SMEI8I32,
368 0 : 0x00300035 => Flag::ARM64_SMEI16I32,
369 0 : 0x00300036 => Flag::ARM64_ADVSIMD,
370 0 : 0x00300037 => Flag::ARM64_ADVSIMDHPFP,
371 0 : 0x00300038 => Flag::ARM64_CRC32,
372 0 : 0x00400000 => Flag::X86_64_DEFAULT,
373 0 : 0x00400001 => Flag::X86_64_SSE41,
374 0 : 0x00400002 => Flag::X86_64_FMA,
375 0 : 0x00400003 => Flag::X86_64_AVX,
376 0 : 0x00400004 => Flag::X86_64_AVX2,
377 0 : 0x00400005 => Flag::X86_64_AVX512F,
378 0 : 0x00400006 => Flag::X86_64_AVX512BW,
379 0 : 0x00400007 => Flag::X86_64_BMI1,
380 26 : 0x00400008 => Flag::X86_64_ROSETTA,
381 26 : 0x00400009 => Flag::X86_64_HASWELL,
382 0 : 0x0040000a => Flag::X86_64_IVYBRIDGE,
383 0 : 0x0040000b => Flag::X86_64_NEHALEM,
384 0 : 0x00200000 => Flag::SYSTEM_WIDE_DEFAULT,
385 0 : 0x00200001 => Flag::SYSTEM_WIDE_INTERNAL_INSTALL,
386 0 : 0x00200002 => Flag::SYSTEM_WIDE_CUSTOMER_INSTALL,
387 0 : 0x00200003 => Flag::SYSTEM_WIDE_LOCKDOWN,
388 0 : 0x00100000 => Flag::PER_PROCESS_DEFAULT,
389 0 : 0x00100001 => Flag::PER_PROCESS_TRANSLATED,
390 0 : 0x00100003 => Flag::PER_PROCESS_NO_OVERREAD,
391 0 : _ => Flag::UNKNOWN(value),
392 : }
393 52 : }
394 : }
395 : impl From<Flag> for u32 {
396 0 : fn from(value: Flag) -> u32 {
397 0 : match value {
398 0 : Flag::ARM64_DEFAULT => 0x00300000,
399 0 : Flag::ARM64_FLAGM => 0x00300001,
400 0 : Flag::ARM64_FLAGM2 => 0x00300002,
401 0 : Flag::ARM64_FHM => 0x00300003,
402 0 : Flag::ARM64_DOTPROD => 0x00300004,
403 0 : Flag::ARM64_SHA3 => 0x00300005,
404 0 : Flag::ARM64_RDM => 0x00300006,
405 0 : Flag::ARM64_LSE => 0x00300007,
406 0 : Flag::ARM64_SHA256 => 0x00300008,
407 0 : Flag::ARM64_SHA512 => 0x00300009,
408 0 : Flag::ARM64_SHA1 => 0x0030000a,
409 0 : Flag::ARM64_AES => 0x0030000b,
410 0 : Flag::ARM64_PMULL => 0x0030000c,
411 0 : Flag::ARM64_SPECRES => 0x0030000d,
412 0 : Flag::ARM64_SB => 0x0030000e,
413 0 : Flag::ARM64_FRINTTS => 0x0030000f,
414 0 : Flag::ARM64_LRCPC => 0x00300010,
415 0 : Flag::ARM64_LRCPC2 => 0x00300011,
416 0 : Flag::ARM64_FCMA => 0x00300012,
417 0 : Flag::ARM64_JSCVT => 0x00300013,
418 0 : Flag::ARM64_PAUTH => 0x00300014,
419 0 : Flag::ARM64_PAUTH2 => 0x00300015,
420 0 : Flag::ARM64_FPAC => 0x00300016,
421 0 : Flag::ARM64_DPB => 0x00300017,
422 0 : Flag::ARM64_DPB2 => 0x00300018,
423 0 : Flag::ARM64_BF16 => 0x00300019,
424 0 : Flag::ARM64_I8MM => 0x0030001a,
425 0 : Flag::ARM64_WFXT => 0x0030001b,
426 0 : Flag::ARM64_RPRES => 0x0030001c,
427 0 : Flag::ARM64_ECV => 0x0030001d,
428 0 : Flag::ARM64_AFP => 0x0030001e,
429 0 : Flag::ARM64_LSE2 => 0x0030001f,
430 0 : Flag::ARM64_CSV2 => 0x00300020,
431 0 : Flag::ARM64_CVS3 => 0x00300021,
432 0 : Flag::ARM64_DIT => 0x00300022,
433 0 : Flag::ARM64_FP16 => 0x00300023,
434 0 : Flag::ARM64_SSBS => 0x00300024,
435 0 : Flag::ARM64_BTI => 0x00300025,
436 0 : Flag::ARM64_SME => 0x0030002c,
437 0 : Flag::ARM64_SME2 => 0x0030002d,
438 0 : Flag::ARM64_SMEF64F64 => 0x0030002e,
439 0 : Flag::ARM64_SMEI16I64 => 0x0030002f,
440 0 : Flag::ARM64_SMEF32F32 => 0x00300030,
441 0 : Flag::ARM64_SMEBI32I32 => 0x00300031,
442 0 : Flag::ARM64_SMEB16F32 => 0x00300032,
443 0 : Flag::ARM64_SMEF16F32 => 0x00300033,
444 0 : Flag::ARM64_SMEI8I32 => 0x00300034,
445 0 : Flag::ARM64_SMEI16I32 => 0x00300035,
446 0 : Flag::ARM64_ADVSIMD => 0x00300036,
447 0 : Flag::ARM64_ADVSIMDHPFP => 0x00300037,
448 0 : Flag::ARM64_CRC32 => 0x00300038,
449 0 : Flag::X86_64_DEFAULT => 0x00400000,
450 0 : Flag::X86_64_SSE41 => 0x00400001,
451 0 : Flag::X86_64_FMA => 0x00400002,
452 0 : Flag::X86_64_AVX => 0x00400003,
453 0 : Flag::X86_64_AVX2 => 0x00400004,
454 0 : Flag::X86_64_AVX512F => 0x00400005,
455 0 : Flag::X86_64_AVX512BW => 0x00400006,
456 0 : Flag::X86_64_BMI1 => 0x00400007,
457 0 : Flag::X86_64_ROSETTA => 0x00400008,
458 0 : Flag::X86_64_HASWELL => 0x00400009,
459 0 : Flag::X86_64_IVYBRIDGE => 0x0040000a,
460 0 : Flag::X86_64_NEHALEM => 0x0040000b,
461 0 : Flag::SYSTEM_WIDE_DEFAULT => 0x00200000,
462 0 : Flag::SYSTEM_WIDE_INTERNAL_INSTALL => 0x00200001,
463 0 : Flag::SYSTEM_WIDE_CUSTOMER_INSTALL => 0x00200002,
464 0 : Flag::SYSTEM_WIDE_LOCKDOWN => 0x00200003,
465 0 : Flag::PER_PROCESS_DEFAULT => 0x00100000,
466 0 : Flag::PER_PROCESS_TRANSLATED => 0x00100001,
467 0 : Flag::PER_PROCESS_NO_OVERREAD => 0x00100003,
468 0 : Flag::UNKNOWN(value) => value,
469 : }
470 0 : }
471 : }
472 :
473 26 : declare_iterator!(
474 26 : RuntimeTables,
475 26 : RuntimeTable<'a>,
476 26 : ffi::MachO_FunctionVariants_RuntimeTable,
477 26 : ffi::MachO_FunctionVariants,
478 26 : ffi::MachO_FunctionVariants_it_runtime_table
479 26 : );
480 :
481 78 : declare_iterator!(
482 78 : RuntimeTableEntries,
483 78 : RuntimeTableEntry<'a>,
484 78 : ffi::MachO_FunctionVariants_RuntimeTableEntry,
485 78 : ffi::MachO_FunctionVariants_RuntimeTable,
486 78 : ffi::MachO_FunctionVariants_RuntimeTable_it_entries
487 78 : );
|
