Skip to main content

kh_loader/
link.rs

1//! Nlist export/import extraction and nlist→GOT fallback bind.
2//!
3//! Prefer classic dyld bind opcodes via [`crate::bind`] when
4//! `LC_DYLD_INFO` / `LC_DYLD_INFO_ONLY` is present. This module still
5//! implements the Phase 6 nlist → `__DATA,__got` path for images without
6//! bind streams.
7
8use std::collections::HashMap;
9use std::ops::Range;
10
11use goblin::mach::Mach;
12use goblin::mach::load_command::CommandVariant;
13use goblin::mach::symbols::{N_EXT, N_SECT, N_TYPE, N_UNDF, N_WEAK_REF, Symbols};
14
15use kh_runtime::{mprotect_darwin, mprotect_rw};
16
17use crate::error::LoadError;
18use crate::image::MachOImage;
19use crate::parse::{read_thin_arm64, thin_arm64_bytes};
20use crate::session::{ImageLoadStatus, LoadSession, ProcessImage};
21
22/// Defined external nlist symbol (`N_SECT | N_EXT`, non-STAB).
23#[derive(Debug, Clone, PartialEq, Eq)]
24pub struct DefinedSymbol {
25    /// Exact nlist string (e.g. `_kh_add`).
26    pub name: String,
27    /// `n_value` at slide 0 (preferred VA).
28    pub value: u64,
29    /// Section ordinal (`n_sect`).
30    pub sect: u8,
31}
32
33/// Undefined external nlist symbol.
34#[derive(Debug, Clone, PartialEq, Eq)]
35pub struct UndefinedSymbol {
36    /// Exact nlist string.
37    pub name: String,
38    /// `N_WEAK_REF` in `n_desc`.
39    pub weak_ref: bool,
40}
41
42/// External defined symbols from the nlist (empty if no symtab).
43///
44/// Does **not** use dyld export tries or bind opcodes.
45///
46/// When `LC_DYSYMTAB` is present, only walks the **externally defined** range
47/// (`iextdefsym`..`+nextdefsym`). Product tools like CLT `clang` have hundreds
48/// of thousands of local nlists and **zero** external defs — a full table walk
49/// was pure waste (~tens of ms per image). Missing dysymtab → full walk
50/// (fixtures / tiny images).
51pub fn defined_exports(bytes: &[u8]) -> Result<Vec<DefinedSymbol>, LoadError> {
52    let thin = thin_arm64_bytes(bytes)?;
53    let macho = parse_macho_binary(thin)?;
54    let Some(symbols) = macho.symbols.as_ref() else {
55        return Ok(Vec::new());
56    };
57    let mut out = Vec::new();
58    match dysym_extdef_range(&macho) {
59        Some(r) if r.is_empty() => return Ok(out),
60        Some(r) => {
61            out.reserve(r.len().min(4096));
62            for_each_nlist_index(symbols, r, |name, nlist| {
63                push_defined_export(&mut out, name, &nlist);
64            })?;
65        }
66        None => {
67            // No / vacuous dysymtab (many fixtures): full nlist walk.
68            for entry in symbols {
69                match entry {
70                    Ok((name, nlist)) => push_defined_export(&mut out, name, &nlist),
71                    Err(err) => return Err(LoadError::NotMachO(format!("nlist: {err}"))),
72                }
73            }
74        }
75    }
76    Ok(out)
77}
78
79fn push_defined_export(
80    out: &mut Vec<DefinedSymbol>,
81    name: &str,
82    nlist: &goblin::mach::symbols::Nlist,
83) {
84    if nlist.is_stab() || (nlist.n_type & N_EXT) == 0 {
85        return;
86    }
87    if nlist.n_type & N_TYPE != N_SECT {
88        return;
89    }
90    out.push(DefinedSymbol {
91        name: name.to_owned(),
92        value: nlist.n_value,
93        sect: u8::try_from(nlist.n_sect).unwrap_or(u8::MAX),
94    });
95}
96
97/// External undefined symbols from the nlist in table order (empty if no symtab).
98///
99/// Does **not** call goblin `MachO::imports()` / bind opcodes.
100///
101/// With `LC_DYSYMTAB`, only walks `iundefsym`..`+nundefsym` (skip locals/extdefs).
102pub fn undefined_imports(bytes: &[u8]) -> Result<Vec<UndefinedSymbol>, LoadError> {
103    let thin = thin_arm64_bytes(bytes)?;
104    let macho = parse_macho_binary(thin)?;
105    let Some(symbols) = macho.symbols.as_ref() else {
106        return Ok(Vec::new());
107    };
108    let mut out = Vec::new();
109    match dysym_undef_range(&macho) {
110        Some(r) if r.is_empty() => return Ok(out),
111        Some(r) => {
112            out.reserve(r.len().min(1024));
113            for_each_nlist_index(symbols, r, |name, nlist| {
114                push_undefined_import(&mut out, name, &nlist);
115            })?;
116        }
117        None => {
118            for entry in symbols {
119                match entry {
120                    Ok((name, nlist)) => push_undefined_import(&mut out, name, &nlist),
121                    Err(err) => return Err(LoadError::NotMachO(format!("nlist: {err}"))),
122                }
123            }
124        }
125    }
126    Ok(out)
127}
128
129fn push_undefined_import(
130    out: &mut Vec<UndefinedSymbol>,
131    name: &str,
132    nlist: &goblin::mach::symbols::Nlist,
133) {
134    if nlist.is_stab() || (nlist.n_type & N_EXT) == 0 {
135        return;
136    }
137    // N_UNDF external (and prebound-undef treated the same for Micro).
138    if nlist.n_type & N_TYPE != N_UNDF {
139        return;
140    }
141    if nlist.n_sect != 0 {
142        return;
143    }
144    out.push(UndefinedSymbol {
145        name: name.to_owned(),
146        weak_ref: nlist.n_desc & N_WEAK_REF != 0,
147    });
148}
149
150/// Bind main external undefined nlist symbols into contiguous `__got` slots.
151///
152/// Used when no image in the process set has classic bind opcodes.
153/// No-op when the main image has no external undefined nlist symbols.
154pub(crate) fn bind_main_got_nlist(session: &mut LoadSession) -> Result<(), LoadError> {
155    let main_path = session
156        .images
157        .first()
158        .map(|i| i.path.clone())
159        .ok_or(LoadError::NotImplemented("main missing before bind"))?;
160    let main_bytes = read_thin_arm64(&main_path)?;
161    let undefs = undefined_imports(&main_bytes)?;
162    if undefs.is_empty() {
163        return Ok(());
164    }
165
166    let main = session
167        .images
168        .first()
169        .ok_or(LoadError::NotImplemented("main missing before bind"))?;
170    // ADRP/ADR to the main image's own __got are PC-relative, so a uniform
171    // main slide is fine. (Plan's ImageSlid was over-conservative; keep the
172    // error variant for a future non-uniform / absolute-address case.)
173    let main_slide = main.slide();
174
175    let export_map = build_export_map(session.images());
176    let (got_pref, got_size) =
177        find_got_section(main.image.as_ref()).ok_or(LoadError::MissingGot {
178            count: undefs.len(),
179        })?;
180    let need = undefs.len().checked_mul(8).ok_or(LoadError::MissingGot {
181        count: undefs.len(),
182    })?;
183    let need_u64 = u64::try_from(need).unwrap_or(u64::MAX);
184    if got_size < need_u64 {
185        return Err(LoadError::MissingGot {
186            count: undefs.len(),
187        });
188    }
189    let got_va = got_pref.wrapping_add(main_slide);
190
191    let named_handler = export_map.get("_kh_missing_symbol_named").copied();
192    let missing_stub = export_map.get("_kh_missing_symbol").copied();
193    let mut values = Vec::with_capacity(undefs.len());
194    for u in &undefs {
195        match export_map.get(&u.name) {
196            Some(&va) => {
197                tracing::debug!(name = %u.name, va, "bind GOT nlist");
198                values.push(va);
199            }
200            None if u.weak_ref => {
201                tracing::debug!(name = %u.name, "weak undef → GOT 0");
202                values.push(0);
203            }
204            None => {
205                if let Some(handler) = named_handler {
206                    match crate::missing_stub::trampoline_for(&u.name, handler) {
207                        Ok(va) => {
208                            tracing::warn!(
209                                name = %u.name,
210                                stub = format_args!("{va:#x}"),
211                                "unresolved strong nlist; bound to named missing trampoline"
212                            );
213                            values.push(va);
214                            continue;
215                        }
216                        Err(err) => {
217                            tracing::warn!(
218                                name = %u.name,
219                                error = %err,
220                                "missing trampoline emit failed; falling back"
221                            );
222                        }
223                    }
224                }
225                if let Some(stub) = missing_stub {
226                    tracing::warn!(
227                        name = %u.name,
228                        "unresolved strong nlist; bound to _kh_missing_symbol"
229                    );
230                    values.push(stub);
231                } else if let Some(handler) = named_handler {
232                    values.push(handler);
233                } else {
234                    return Err(LoadError::UnresolvedSymbol {
235                        name: u.name.clone(),
236                    });
237                }
238            }
239        }
240    }
241
242    write_got_slots(session, got_va, &values)?;
243    Ok(())
244}
245
246pub(crate) fn fill_exports(session: &mut LoadSession) -> Result<(), LoadError> {
247    for img in &mut session.images {
248        if !matches!(img.status, ImageLoadStatus::Mapped) {
249            img.exports.clear();
250            img.export_by_name.clear();
251            continue;
252        }
253        if img.path.as_os_str().is_empty() {
254            img.exports.clear();
255            img.export_by_name.clear();
256            continue;
257        }
258        // Prefer container retained from parse (no second full-file read).
259        img.exports = if let Some(container) = img.file_bytes.as_ref() {
260            let thin = thin_arm64_bytes(container.as_slice())?;
261            defined_exports(thin)?
262        } else {
263            let bytes = read_thin_arm64(&img.path)?;
264            defined_exports(&bytes)?
265        };
266        // O(1) bind/chained lookup; same preferred VAs as `exports`.
267        img.export_by_name.clear();
268        img.export_by_name.reserve(img.exports.len().saturating_add(1));
269        for exp in &img.exports {
270            img.export_by_name
271                .entry(exp.name.clone())
272                .or_insert(exp.value);
273        }
274        // Darwin clients (e.g. curl) import the unadorned dyld helper name;
275        // freestanding libSystem exports `_dyld_stub_binder`.
276        if let Some(v) = img.export_by_name.get("_dyld_stub_binder").copied() {
277            img.export_by_name
278                .entry("dyld_stub_binder".into())
279                .or_insert(v);
280        }
281    }
282    Ok(())
283}
284
285/// Flat export map: first definition in load order wins (slid absolute VA).
286///
287/// Prefer [`crate::bind::BindResolveCache`] during bind — this rebuilds the map
288/// and is kept for the nlist-GOT fallback path only.
289pub(crate) fn build_export_map(images: &[ProcessImage]) -> HashMap<String, u64> {
290    let mut map = HashMap::new();
291    for img in images {
292        if !matches!(img.status, ImageLoadStatus::Mapped) {
293            continue;
294        }
295        let slide = img.slide();
296        if img.export_by_name.is_empty() {
297            for exp in &img.exports {
298                map.entry(exp.name.clone())
299                    .or_insert_with(|| exp.value.wrapping_add(slide));
300            }
301        } else {
302            for (name, &pref) in &img.export_by_name {
303                map.entry(name.clone())
304                    .or_insert_with(|| pref.wrapping_add(slide));
305            }
306        }
307    }
308    map
309}
310
311fn find_got_section(image: Option<&MachOImage>) -> Option<(u64, u64)> {
312    let image = image?;
313    for seg in &image.segments {
314        for sect in &seg.sections {
315            if sect.name == "__got" {
316                return Some((sect.addr, sect.size));
317            }
318        }
319    }
320    None
321}
322
323fn write_got_slots(
324    session: &mut LoadSession,
325    got_va: u64,
326    values: &[u64],
327) -> Result<(), LoadError> {
328    let main = session
329        .images
330        .first_mut()
331        .ok_or(LoadError::NotImplemented("main missing for GOT write"))?;
332    let memory = main.memory.as_mut().ok_or(LoadError::NotImplemented(
333        "main memory missing for GOT write",
334    ))?;
335
336    // Locate the region that covers the GOT, mprotect RW, write, restore.
337    let region_idx = memory
338        .regions()
339        .iter()
340        .position(|r| {
341            let start = r.guest_addr;
342            let end = start.saturating_add(r.vmsize);
343            got_va >= start && got_va < end
344        })
345        .ok_or(LoadError::MissingGot {
346            count: values.len(),
347        })?;
348
349    let region = memory
350        .regions_mut()
351        .get_mut(region_idx)
352        .ok_or(LoadError::MissingGot {
353            count: values.len(),
354        })?;
355    let region_base = region.guest_addr;
356    let restore = region.prot;
357    mprotect_rw(region).map_err(LoadError::Map)?;
358
359    for (i, &va) in values.iter().enumerate() {
360        let slot = got_va.saturating_add(u64::try_from(i).unwrap_or(0).saturating_mul(8));
361        let offset = usize::try_from(slot.saturating_sub(region_base)).map_err(|_| {
362            LoadError::MissingGot {
363                count: values.len(),
364            }
365        })?;
366        let end = offset.saturating_add(8);
367        let host = region.host_bytes_mut();
368        let Some(slot_bytes) = host.get_mut(offset..end) else {
369            return Err(LoadError::MissingGot {
370                count: values.len(),
371            });
372        };
373        slot_bytes.copy_from_slice(&va.to_le_bytes());
374    }
375
376    mprotect_darwin(region, restore).map_err(LoadError::Map)?;
377    Ok(())
378}
379
380fn parse_macho_binary(thin: &[u8]) -> Result<goblin::mach::MachO<'_>, LoadError> {
381    match Mach::parse(thin) {
382        Ok(Mach::Binary(m)) => Ok(m),
383        Ok(Mach::Fat(_)) => Err(LoadError::NotMachO(
384            "nested fat image inside arm64 slice".into(),
385        )),
386        Err(err) => Err(LoadError::NotMachO(err.to_string())),
387    }
388}
389
390/// `LC_DYSYMTAB` externally-defined range, when the command is trustworthy.
391///
392/// Returns `None` when there is no dysymtab **or** the command is all zeros
393/// (some synthetic fixtures ship `LC_DYSYMTAB` with empty counts while still
394/// having nlist symbols). Real tools (CLT `clang`: hundreds of thousands of
395/// locals, `nextdefsym == 0`) keep the empty range so we skip the local walk.
396fn dysym_extdef_range(macho: &goblin::mach::MachO<'_>) -> Option<Range<usize>> {
397    for lc in &macho.load_commands {
398        if let CommandVariant::Dysymtab(d) = &lc.command {
399            if dysymtab_is_vacuous(d) {
400                return None;
401            }
402            let start = usize::try_from(d.iextdefsym).ok()?;
403            let count = usize::try_from(d.nextdefsym).ok()?;
404            return Some(start..start.saturating_add(count));
405        }
406    }
407    None
408}
409
410/// `LC_DYSYMTAB` undefined range, when the command is trustworthy.
411fn dysym_undef_range(macho: &goblin::mach::MachO<'_>) -> Option<Range<usize>> {
412    for lc in &macho.load_commands {
413        if let CommandVariant::Dysymtab(d) = &lc.command {
414            if dysymtab_is_vacuous(d) {
415                return None;
416            }
417            let start = usize::try_from(d.iundefsym).ok()?;
418            let count = usize::try_from(d.nundefsym).ok()?;
419            return Some(start..start.saturating_add(count));
420        }
421    }
422    None
423}
424
425/// True when `LC_DYSYMTAB` has no local/extdef/undef counts at all (unusable).
426fn dysymtab_is_vacuous(d: &goblin::mach::load_command::DysymtabCommand) -> bool {
427    d.nlocalsym == 0 && d.nextdefsym == 0 && d.nundefsym == 0
428}
429
430fn for_each_nlist_index<F>(
431    symbols: &Symbols<'_>,
432    range: Range<usize>,
433    mut f: F,
434) -> Result<(), LoadError>
435where
436    F: FnMut(&str, goblin::mach::symbols::Nlist),
437{
438    for i in range {
439        match symbols.get(i) {
440            Ok((name, nlist)) => f(name, nlist),
441            Err(err) => {
442                return Err(LoadError::NotMachO(format!("nlist[{i}]: {err}")));
443            }
444        }
445    }
446    Ok(())
447}
448
449#[cfg(test)]
450#[allow(clippy::expect_used, clippy::unwrap_used)]
451mod tests {
452    use super::*;
453    use crate::fixture::{
454        KH_BOTTLE_MARK_SYMBOL, arm64_dylib_add, arm64_libsystem_stub, call_dylib_exit,
455        call_libsystem_exit, minimal_arm64_execute,
456    };
457    use crate::session::{ImageLoadStatus, ImageRole, LoadSession};
458    use crate::test_util::map_test_lock;
459    use std::io::Write;
460    use std::sync::atomic::{AtomicU64, Ordering};
461
462    #[test]
463    fn no_symtab_means_zero_undefs() {
464        let bytes = minimal_arm64_execute();
465        let undefs = undefined_imports(&bytes).expect("undefs");
466        assert!(undefs.is_empty());
467        let exports = defined_exports(&bytes).expect("exports");
468        assert!(exports.is_empty());
469    }
470
471    #[test]
472    fn fixture_export_and_import_names() {
473        let dylib = arm64_dylib_add();
474        let exports = defined_exports(&dylib).expect("exports");
475        assert_eq!(exports.len(), 1);
476        let exp = exports.first().expect("one export");
477        assert_eq!(exp.name, "_kh_add");
478        assert!(
479            exp.value >= crate::fixture::LIBKH_ADD_TEXT_VA
480                && exp.value < crate::fixture::LIBKH_ADD_TEXT_VA + 0x4000,
481            "export VA in dylib TEXT: {:#x}",
482            exp.value
483        );
484
485        let main = call_dylib_exit();
486        let undefs = undefined_imports(&main).expect("undefs");
487        assert_eq!(undefs.len(), 1);
488        let und = undefs.first().expect("one undef");
489        assert_eq!(und.name, "_kh_add");
490        assert!(!und.weak_ref);
491    }
492
493    #[test]
494    fn bind_one_got_slot() {
495        static N: AtomicU64 = AtomicU64::new(0);
496        let _guard = map_test_lock();
497        let n = N.fetch_add(1, Ordering::Relaxed);
498        let dir = std::env::temp_dir().join(format!("kh-bind-{}-{n}", std::process::id()));
499        std::fs::create_dir_all(&dir).expect("mkdir");
500        let main_path = dir.join("call_dylib.macho");
501        let dylib_path = dir.join("libkh_add.dylib");
502        {
503            let mut f = std::fs::File::create(&main_path).expect("create main");
504            f.write_all(&call_dylib_exit()).expect("write main");
505        }
506        {
507            let mut f = std::fs::File::create(&dylib_path).expect("create dylib");
508            f.write_all(&arm64_dylib_add()).expect("write dylib");
509        }
510
511        let mut session = LoadSession::open(&main_path, None).expect("open");
512        let _ = session.map_process().expect("map_process");
513        let mapped_count = session
514            .images()
515            .iter()
516            .filter(|i| matches!(i.status, ImageLoadStatus::Mapped))
517            .count();
518        assert!(
519            mapped_count >= 2,
520            "main + dylib should map: {:?}",
521            session
522                .images()
523                .iter()
524                .map(|i| (i.role, i.status.as_str(), i.install_name.as_str()))
525                .collect::<Vec<_>>()
526        );
527        let main = session.images().first().expect("main");
528        assert_eq!(main.role, ImageRole::Main);
529        let main_slide = main.slide();
530
531        let export_va = session
532            .images()
533            .iter()
534            .find(|i| i.role == ImageRole::Dylib && matches!(i.status, ImageLoadStatus::Mapped))
535            .and_then(|dylib| {
536                dylib
537                    .exports
538                    .iter()
539                    .find(|e| e.name == "_kh_add")
540                    .map(|e| e.value.wrapping_add(dylib.slide()))
541            })
542            .expect("dylib export");
543
544        let got_va = crate::fixture::CALL_DYLIB_GOT_VA.wrapping_add(main_slide);
545        let main_mem = session
546            .images()
547            .first()
548            .and_then(|i| i.memory.as_ref())
549            .expect("main mem");
550        let region = main_mem
551            .regions()
552            .iter()
553            .find(|r| got_va >= r.guest_addr && got_va < r.guest_addr.saturating_add(r.vmsize))
554            .expect("DATA region");
555        let off = usize::try_from(got_va.saturating_sub(region.guest_addr)).unwrap();
556        let end = off.saturating_add(8);
557        let bytes = region.host_bytes().get(off..end).expect("got bytes");
558        let mut le = [0_u8; 8];
559        le.copy_from_slice(bytes);
560        assert_eq!(u64::from_le_bytes(le), export_va);
561
562        drop(session);
563        drop(std::fs::remove_dir_all(dir));
564    }
565
566    #[test]
567    fn libsystem_stub_export_name() {
568        use crate::fixture::{
569            LIBSYSTEM_EXIT_SYMBOL, LIBSYSTEM_PRINTF_SYMBOL, LIBSYSTEM_PUTS_SYMBOL,
570            LIBSYSTEM_WRITE_SYMBOL,
571        };
572
573        let exports = defined_exports(&arm64_libsystem_stub()).expect("exports");
574        assert_eq!(exports.len(), 5);
575        let names: Vec<&str> = exports.iter().map(|e| e.name.as_str()).collect();
576        assert!(names.contains(&LIBSYSTEM_WRITE_SYMBOL));
577        assert!(names.contains(&LIBSYSTEM_EXIT_SYMBOL));
578        assert!(names.contains(&LIBSYSTEM_PUTS_SYMBOL));
579        assert!(names.contains(&LIBSYSTEM_PRINTF_SYMBOL));
580        assert!(names.contains(&KH_BOTTLE_MARK_SYMBOL));
581        for exp in &exports {
582            assert!(
583                exp.value >= crate::fixture::LIBSYSTEM_TEXT_VA
584                    && exp.value < crate::fixture::LIBSYSTEM_TEXT_VA + 0x4000,
585                "export VA in stub TEXT: {} @ {:#x}",
586                exp.name,
587                exp.value
588            );
589        }
590
591        let undefs = undefined_imports(&call_libsystem_exit()).expect("undefs");
592        assert_eq!(undefs.len(), 1);
593        assert_eq!(undefs.first().expect("one").name, KH_BOTTLE_MARK_SYMBOL);
594    }
595}