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
269            .reserve(img.exports.len().saturating_add(1));
270        for exp in &img.exports {
271            img.export_by_name
272                .entry(exp.name.clone())
273                .or_insert(exp.value);
274        }
275        // Darwin clients (e.g. curl) import the unadorned dyld helper name;
276        // freestanding libSystem exports `_dyld_stub_binder`.
277        if let Some(v) = img.export_by_name.get("_dyld_stub_binder").copied() {
278            img.export_by_name
279                .entry("dyld_stub_binder".into())
280                .or_insert(v);
281        }
282    }
283    Ok(())
284}
285
286/// Flat export map: first definition in load order wins (slid absolute VA).
287///
288/// Prefer [`crate::bind::BindResolveCache`] during bind — this rebuilds the map
289/// and is kept for the nlist-GOT fallback path only.
290pub(crate) fn build_export_map(images: &[ProcessImage]) -> HashMap<String, u64> {
291    let mut map = HashMap::new();
292    for img in images {
293        if !matches!(img.status, ImageLoadStatus::Mapped) {
294            continue;
295        }
296        let slide = img.slide();
297        if img.export_by_name.is_empty() {
298            for exp in &img.exports {
299                map.entry(exp.name.clone())
300                    .or_insert_with(|| exp.value.wrapping_add(slide));
301            }
302        } else {
303            for (name, &pref) in &img.export_by_name {
304                map.entry(name.clone())
305                    .or_insert_with(|| pref.wrapping_add(slide));
306            }
307        }
308    }
309    map
310}
311
312fn find_got_section(image: Option<&MachOImage>) -> Option<(u64, u64)> {
313    let image = image?;
314    for seg in &image.segments {
315        for sect in &seg.sections {
316            if sect.name == "__got" {
317                return Some((sect.addr, sect.size));
318            }
319        }
320    }
321    None
322}
323
324fn write_got_slots(
325    session: &mut LoadSession,
326    got_va: u64,
327    values: &[u64],
328) -> Result<(), LoadError> {
329    let main = session
330        .images
331        .first_mut()
332        .ok_or(LoadError::NotImplemented("main missing for GOT write"))?;
333    let memory = main.memory.as_mut().ok_or(LoadError::NotImplemented(
334        "main memory missing for GOT write",
335    ))?;
336
337    // Locate the region that covers the GOT, mprotect RW, write, restore.
338    let region_idx = memory
339        .regions()
340        .iter()
341        .position(|r| {
342            let start = r.guest_addr;
343            let end = start.saturating_add(r.vmsize);
344            got_va >= start && got_va < end
345        })
346        .ok_or(LoadError::MissingGot {
347            count: values.len(),
348        })?;
349
350    let region = memory
351        .regions_mut()
352        .get_mut(region_idx)
353        .ok_or(LoadError::MissingGot {
354            count: values.len(),
355        })?;
356    let region_base = region.guest_addr;
357    let restore = region.prot;
358    mprotect_rw(region).map_err(LoadError::Map)?;
359
360    for (i, &va) in values.iter().enumerate() {
361        let slot = got_va.saturating_add(u64::try_from(i).unwrap_or(0).saturating_mul(8));
362        let offset = usize::try_from(slot.saturating_sub(region_base)).map_err(|_| {
363            LoadError::MissingGot {
364                count: values.len(),
365            }
366        })?;
367        let end = offset.saturating_add(8);
368        let host = region.host_bytes_mut();
369        let Some(slot_bytes) = host.get_mut(offset..end) else {
370            return Err(LoadError::MissingGot {
371                count: values.len(),
372            });
373        };
374        slot_bytes.copy_from_slice(&va.to_le_bytes());
375    }
376
377    mprotect_darwin(region, restore).map_err(LoadError::Map)?;
378    Ok(())
379}
380
381fn parse_macho_binary(thin: &[u8]) -> Result<goblin::mach::MachO<'_>, LoadError> {
382    match Mach::parse(thin) {
383        Ok(Mach::Binary(m)) => Ok(m),
384        Ok(Mach::Fat(_)) => Err(LoadError::NotMachO(
385            "nested fat image inside arm64 slice".into(),
386        )),
387        Err(err) => Err(LoadError::NotMachO(err.to_string())),
388    }
389}
390
391/// `LC_DYSYMTAB` externally-defined range, when the command is trustworthy.
392///
393/// Returns `None` when there is no dysymtab **or** the command is all zeros
394/// (some synthetic fixtures ship `LC_DYSYMTAB` with empty counts while still
395/// having nlist symbols). Real tools (CLT `clang`: hundreds of thousands of
396/// locals, `nextdefsym == 0`) keep the empty range so we skip the local walk.
397fn dysym_extdef_range(macho: &goblin::mach::MachO<'_>) -> Option<Range<usize>> {
398    for lc in &macho.load_commands {
399        if let CommandVariant::Dysymtab(d) = &lc.command {
400            if dysymtab_is_vacuous(d) {
401                return None;
402            }
403            let start = usize::try_from(d.iextdefsym).ok()?;
404            let count = usize::try_from(d.nextdefsym).ok()?;
405            return Some(start..start.saturating_add(count));
406        }
407    }
408    None
409}
410
411/// `LC_DYSYMTAB` undefined range, when the command is trustworthy.
412fn dysym_undef_range(macho: &goblin::mach::MachO<'_>) -> Option<Range<usize>> {
413    for lc in &macho.load_commands {
414        if let CommandVariant::Dysymtab(d) = &lc.command {
415            if dysymtab_is_vacuous(d) {
416                return None;
417            }
418            let start = usize::try_from(d.iundefsym).ok()?;
419            let count = usize::try_from(d.nundefsym).ok()?;
420            return Some(start..start.saturating_add(count));
421        }
422    }
423    None
424}
425
426/// True when `LC_DYSYMTAB` has no local/extdef/undef counts at all (unusable).
427fn dysymtab_is_vacuous(d: &goblin::mach::load_command::DysymtabCommand) -> bool {
428    d.nlocalsym == 0 && d.nextdefsym == 0 && d.nundefsym == 0
429}
430
431fn for_each_nlist_index<F>(
432    symbols: &Symbols<'_>,
433    range: Range<usize>,
434    mut f: F,
435) -> Result<(), LoadError>
436where
437    F: FnMut(&str, goblin::mach::symbols::Nlist),
438{
439    for i in range {
440        match symbols.get(i) {
441            Ok((name, nlist)) => f(name, nlist),
442            Err(err) => {
443                return Err(LoadError::NotMachO(format!("nlist[{i}]: {err}")));
444            }
445        }
446    }
447    Ok(())
448}