Skip to main content

kh_loader/
bind.rs

1//! Classic dyld bind opcodes (`LC_DYLD_INFO` / `LC_DYLD_INFO_ONLY`).
2//!
3//! Interprets the non-lazy and lazy bind streams and writes resolved absolute
4//! pointers into guest memory (eager bind for Micro — no lazy stub helper).
5//! When an image has no bind opcodes, falls back to nlist → `__got` for the
6//! main executable (Phase 6 fixtures / tools without dyld info).
7
8use std::collections::BTreeMap;
9
10use goblin::mach::Mach;
11use goblin::mach::bind_opcodes::{
12    BIND_IMMEDIATE_MASK, BIND_OPCODE_ADD_ADDR_ULEB, BIND_OPCODE_DO_BIND,
13    BIND_OPCODE_DO_BIND_ADD_ADDR_IMM_SCALED, BIND_OPCODE_DO_BIND_ADD_ADDR_ULEB,
14    BIND_OPCODE_DO_BIND_ULEB_TIMES_SKIPPING_ULEB, BIND_OPCODE_DONE, BIND_OPCODE_MASK,
15    BIND_OPCODE_SET_ADDEND_SLEB, BIND_OPCODE_SET_DYLIB_ORDINAL_IMM,
16    BIND_OPCODE_SET_DYLIB_ORDINAL_ULEB, BIND_OPCODE_SET_DYLIB_SPECIAL_IMM,
17    BIND_OPCODE_SET_SEGMENT_AND_OFFSET_ULEB, BIND_OPCODE_SET_SYMBOL_TRAILING_FLAGS_IMM,
18    BIND_OPCODE_SET_TYPE_IMM, BIND_SPECIAL_DYLIB_FLAT_LOOKUP, BIND_SPECIAL_DYLIB_MAIN_EXECUTABLE,
19    BIND_SPECIAL_DYLIB_SELF, BIND_SYMBOL_FLAGS_WEAK_IMPORT, BIND_TYPE_POINTER,
20};
21use goblin::mach::load_command::{CommandVariant, DyldInfoCommand};
22use kh_runtime::{GuestMemory, VM_PROT_WRITE, mprotect_darwin, mprotect_rw};
23use scroll::{Sleb128, Uleb128};
24
25use crate::error::LoadError;
26use crate::image::{DylibKind, MachOImage};
27use crate::link::{self, build_export_map, fill_exports};
28use crate::parse::{read_thin_arm64, thin_arm64_bytes};
29use crate::session::{ImageLoadStatus, LoadSession, ProcessImage};
30
31/// One pointer write derived from a bind opcode stream.
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct BindSite {
34    /// Symbol name (nlist / bind spelling, e.g. `_kh_add`).
35    pub name: String,
36    /// Preferred (slide-0) virtual address of the slot.
37    pub preferred_va: u64,
38    /// Addend applied after symbol resolution.
39    pub addend: i64,
40    /// `BIND_SYMBOL_FLAGS_WEAK_IMPORT`.
41    pub weak: bool,
42    /// Bind type (`BIND_TYPE_POINTER`, …).
43    pub bind_type: u8,
44    /// Library ordinal (1-based dylib index, or special ≤ 0).
45    pub lib_ordinal: i16,
46    /// From the lazy bind stream.
47    pub is_lazy: bool,
48}
49
50/// Fill exports, then bind each mapped image.
51///
52/// Preference per image:
53/// 1. [`crate::chained`] fixups (`LC_DYLD_CHAINED_FIXUPS`) — rebase + bind
54/// 2. classic dyld bind opcodes (`LC_DYLD_INFO`)
55/// 3. if nothing applied for any image → nlist → `__got` on main
56///
57/// Call **after** map and (non-chained) section rebase.
58pub fn bind_process(session: &mut LoadSession) -> Result<(), LoadError> {
59    fill_exports(session)?;
60
61    let paths: Vec<_> = session
62        .images
63        .iter()
64        .map(|img| {
65            (
66                img.path.clone(),
67                matches!(img.status, ImageLoadStatus::Mapped),
68            )
69        })
70        .collect();
71
72    let mut used_any = false;
73    for (idx, (path, mapped)) in paths.into_iter().enumerate() {
74        if !mapped || path.as_os_str().is_empty() {
75            continue;
76        }
77        let bytes = read_thin_arm64(&path)?;
78        if crate::chained::bytes_have_chained_fixups(&bytes)? {
79            crate::chained::apply_chained_fixups(session, idx, &bytes)?;
80            used_any = true;
81            continue;
82        }
83        let sites = collect_bind_sites(&bytes)?;
84        if sites.is_empty() {
85            continue;
86        }
87        used_any = true;
88        apply_bind_sites(session, idx, &sites)?;
89    }
90
91    if !used_any {
92        link::bind_main_got_nlist(session)?;
93    }
94    crate::missing_stub::seal_pool();
95    Ok(())
96}
97
98/// Bind an unresolved strong import to a named missing trampoline (or anonymous
99/// `_kh_missing_symbol` if the named handler is absent).
100fn resolve_missing_stub(images: &[ProcessImage], name: &str) -> Result<u64, LoadError> {
101    let named = lookup_flat(images, "_kh_missing_symbol_named", false).ok();
102    let anon = lookup_flat(images, "_kh_missing_symbol", false).ok();
103    if let Some(handler) = named {
104        match crate::missing_stub::trampoline_for(name, handler) {
105            Ok(va) => {
106                tracing::warn!(
107                    name = %name,
108                    stub = format_args!("{va:#x}"),
109                    "unresolved strong symbol; bound to named missing trampoline"
110                );
111                return Ok(va);
112            }
113            Err(err) => {
114                tracing::warn!(
115                    name = %name,
116                    error = %err,
117                    "missing trampoline emit failed; falling back"
118                );
119            }
120        }
121    }
122    if let Some(stub) = anon {
123        tracing::warn!(
124            name = %name,
125            "unresolved strong symbol; bound to _kh_missing_symbol"
126        );
127        return Ok(stub);
128    }
129    if let Some(handler) = named {
130        // No trampoline path; still better than hard fail for load.
131        tracing::warn!(
132            name = %name,
133            "unresolved strong symbol; bound to _kh_missing_symbol_named (no trampoline)"
134        );
135        return Ok(handler);
136    }
137    Err(LoadError::UnresolvedSymbol {
138        name: name.to_owned(),
139    })
140}
141
142/// Collect POINTER bind sites from `LC_DYLD_INFO` / `LC_DYLD_INFO_ONLY`.
143///
144/// Empty when the image has no dyld info or zero-sized bind streams.
145/// Weak-bind is not interpreted yet (Phase 10).
146pub fn collect_bind_sites(bytes: &[u8]) -> Result<Vec<BindSite>, LoadError> {
147    let thin = thin_arm64_bytes(bytes)?;
148    let macho = match Mach::parse(thin) {
149        Ok(Mach::Binary(m)) => m,
150        Ok(Mach::Fat(_)) => {
151            return Err(LoadError::NotMachO(
152                "nested fat image inside arm64 slice".into(),
153            ));
154        }
155        Err(err) => return Err(LoadError::NotMachO(err.to_string())),
156    };
157
158    let Some(cmd) = dyld_info_command(&macho) else {
159        return Ok(Vec::new());
160    };
161
162    let seg_vmaddrs: Vec<u64> = macho.segments.iter().map(|s| s.vmaddr).collect();
163    let mut sites = Vec::new();
164
165    if cmd.bind_size > 0 {
166        let range = file_range(cmd.bind_off, cmd.bind_size, thin.len())?;
167        interpret_stream(thin, range, false, &seg_vmaddrs, &mut sites)?;
168    }
169    if cmd.lazy_bind_size > 0 {
170        let range = file_range(cmd.lazy_bind_off, cmd.lazy_bind_size, thin.len())?;
171        interpret_stream(thin, range, true, &seg_vmaddrs, &mut sites)?;
172    }
173
174    Ok(sites)
175}
176
177fn dyld_info_command<'a>(macho: &'a goblin::mach::MachO<'a>) -> Option<&'a DyldInfoCommand> {
178    for lc in &macho.load_commands {
179        match &lc.command {
180            CommandVariant::DyldInfo(c) | CommandVariant::DyldInfoOnly(c) => return Some(c),
181            _ => {}
182        }
183    }
184    None
185}
186
187fn file_range(off: u32, size: u32, len: usize) -> Result<std::ops::Range<usize>, LoadError> {
188    let start = usize::try_from(off).map_err(|_| LoadError::Resolve("bind off overflow".into()))?;
189    let size =
190        usize::try_from(size).map_err(|_| LoadError::Resolve("bind size overflow".into()))?;
191    let end = start
192        .checked_add(size)
193        .ok_or_else(|| LoadError::Resolve("bind range overflow".into()))?;
194    if end > len {
195        return Err(LoadError::Resolve(format!(
196            "bind stream {start:#x}..{end:#x} past file end {len:#x}"
197        )));
198    }
199    Ok(start..end)
200}
201
202#[derive(Clone)]
203struct BindState {
204    seg_index: u8,
205    seg_offset: u64,
206    bind_type: u8,
207    lib_ordinal: i16,
208    symbol_name: String,
209    symbol_flags: u8,
210    addend: i64,
211}
212
213impl BindState {
214    fn new(is_lazy: bool) -> Self {
215        Self {
216            seg_index: 0,
217            seg_offset: 0,
218            bind_type: if is_lazy { BIND_TYPE_POINTER } else { 0 },
219            lib_ordinal: 0,
220            symbol_name: String::new(),
221            symbol_flags: 0,
222            addend: 0,
223        }
224    }
225
226    fn is_weak(&self) -> bool {
227        self.symbol_flags & BIND_SYMBOL_FLAGS_WEAK_IMPORT != 0
228    }
229}
230
231fn interpret_stream(
232    data: &[u8],
233    range: std::ops::Range<usize>,
234    is_lazy: bool,
235    seg_vmaddrs: &[u64],
236    out: &mut Vec<BindSite>,
237) -> Result<(), LoadError> {
238    const PTR_SIZE: u64 = 8;
239    let mut state = BindState::new(is_lazy);
240    let mut offset = range.start;
241
242    while offset < range.end {
243        let opcode_byte = *data
244            .get(offset)
245            .ok_or_else(|| LoadError::Resolve("bind stream truncated".into()))?;
246        offset = offset.saturating_add(1);
247        let opcode = opcode_byte & BIND_OPCODE_MASK;
248        let imm = opcode_byte & BIND_IMMEDIATE_MASK;
249
250        match opcode {
251            BIND_OPCODE_DONE => {
252                state = BindState::new(is_lazy);
253            }
254            BIND_OPCODE_SET_DYLIB_ORDINAL_IMM => {
255                state.lib_ordinal = i16::from(imm);
256            }
257            BIND_OPCODE_SET_DYLIB_ORDINAL_ULEB => {
258                let v = read_uleb(data, &mut offset)?;
259                state.lib_ordinal = i16::try_from(v).map_err(|_| {
260                    LoadError::Resolve(format!("bind dylib ordinal too large: {v}"))
261                })?;
262            }
263            BIND_OPCODE_SET_DYLIB_SPECIAL_IMM => {
264                // dyld: imm==0 → SELF; else sign-extend nibble with high nibble 0xF.
265                if imm == 0 {
266                    state.lib_ordinal = i16::from(BIND_SPECIAL_DYLIB_SELF);
267                } else {
268                    let raw = BIND_OPCODE_MASK | imm;
269                    let sign_ext = raw.cast_signed();
270                    state.lib_ordinal = i16::from(sign_ext);
271                }
272            }
273            BIND_OPCODE_SET_SYMBOL_TRAILING_FLAGS_IMM => {
274                state.symbol_flags = imm;
275                let name = read_cstring(data, &mut offset, range.end)?;
276                state.symbol_name = name;
277            }
278            BIND_OPCODE_SET_TYPE_IMM => {
279                state.bind_type = imm;
280            }
281            BIND_OPCODE_SET_ADDEND_SLEB => {
282                state.addend = read_sleb(data, &mut offset)?;
283            }
284            BIND_OPCODE_SET_SEGMENT_AND_OFFSET_ULEB => {
285                state.seg_index = imm;
286                state.seg_offset = read_uleb(data, &mut offset)?;
287            }
288            BIND_OPCODE_ADD_ADDR_ULEB => {
289                let addr = read_uleb(data, &mut offset)?;
290                state.seg_offset = state.seg_offset.wrapping_add(addr);
291            }
292            BIND_OPCODE_DO_BIND => {
293                push_site(&state, is_lazy, seg_vmaddrs, out)?;
294                state.seg_offset = state.seg_offset.wrapping_add(PTR_SIZE);
295            }
296            BIND_OPCODE_DO_BIND_ADD_ADDR_ULEB => {
297                push_site(&state, is_lazy, seg_vmaddrs, out)?;
298                let addr = read_uleb(data, &mut offset)?;
299                state.seg_offset = state.seg_offset.wrapping_add(addr).wrapping_add(PTR_SIZE);
300            }
301            BIND_OPCODE_DO_BIND_ADD_ADDR_IMM_SCALED => {
302                push_site(&state, is_lazy, seg_vmaddrs, out)?;
303                let scale = u64::from(imm);
304                state.seg_offset = state
305                    .seg_offset
306                    .wrapping_add(scale.wrapping_mul(PTR_SIZE))
307                    .wrapping_add(PTR_SIZE);
308            }
309            BIND_OPCODE_DO_BIND_ULEB_TIMES_SKIPPING_ULEB => {
310                let count = read_uleb(data, &mut offset)?;
311                let skip = read_uleb(data, &mut offset)?;
312                let step = skip.wrapping_add(PTR_SIZE);
313                for _ in 0..count {
314                    push_site(&state, is_lazy, seg_vmaddrs, out)?;
315                    state.seg_offset = state.seg_offset.wrapping_add(step);
316                }
317            }
318            _ => {
319                return Err(LoadError::Resolve(format!(
320                    "unknown bind opcode {opcode_byte:#x}"
321                )));
322            }
323        }
324    }
325    Ok(())
326}
327
328fn push_site(
329    state: &BindState,
330    is_lazy: bool,
331    seg_vmaddrs: &[u64],
332    out: &mut Vec<BindSite>,
333) -> Result<(), LoadError> {
334    if state.symbol_name.is_empty() {
335        return Err(LoadError::Resolve(
336            "bind DO_BIND without symbol name".into(),
337        ));
338    }
339    let seg_i = usize::from(state.seg_index);
340    let seg_base = *seg_vmaddrs.get(seg_i).ok_or_else(|| {
341        LoadError::Resolve(format!(
342            "bind segment index {} out of range ({})",
343            state.seg_index,
344            seg_vmaddrs.len()
345        ))
346    })?;
347    let preferred_va = seg_base.wrapping_add(state.seg_offset);
348    out.push(BindSite {
349        name: state.symbol_name.clone(),
350        preferred_va,
351        addend: state.addend,
352        weak: state.is_weak(),
353        bind_type: state.bind_type,
354        lib_ordinal: state.lib_ordinal,
355        is_lazy,
356    });
357    Ok(())
358}
359
360fn read_uleb(data: &[u8], offset: &mut usize) -> Result<u64, LoadError> {
361    Uleb128::read(data, offset).map_err(|err| LoadError::Resolve(format!("bind uleb: {err}")))
362}
363
364fn read_sleb(data: &[u8], offset: &mut usize) -> Result<i64, LoadError> {
365    Sleb128::read(data, offset).map_err(|err| LoadError::Resolve(format!("bind sleb: {err}")))
366}
367
368fn read_cstring(data: &[u8], offset: &mut usize, end: usize) -> Result<String, LoadError> {
369    let start = *offset;
370    if start >= end {
371        return Err(LoadError::Resolve(
372            "bind symbol name past stream end".into(),
373        ));
374    }
375    let slice = data
376        .get(start..end)
377        .ok_or_else(|| LoadError::Resolve("bind symbol name OOB".into()))?;
378    let nul = slice
379        .iter()
380        .position(|&b| b == 0)
381        .ok_or_else(|| LoadError::Resolve("bind symbol name not NUL-terminated".into()))?;
382    let name_bytes = slice
383        .get(..nul)
384        .ok_or_else(|| LoadError::Resolve("bind symbol name slice OOB".into()))?;
385    let name = std::str::from_utf8(name_bytes)
386        .map_err(|err| LoadError::Resolve(format!("bind symbol utf8: {err}")))?
387        .to_owned();
388    *offset = start.saturating_add(nul).saturating_add(1);
389    Ok(name)
390}
391
392fn apply_bind_sites(
393    session: &mut LoadSession,
394    image_idx: usize,
395    sites: &[BindSite],
396) -> Result<(), LoadError> {
397    let slide = session.images.get(image_idx).map_or(0, ProcessImage::slide);
398
399    let mut updates: Vec<(u64, u64)> = Vec::with_capacity(sites.len());
400    for site in sites {
401        // Type 0: stream omitted SET_TYPE (unusual); treat as POINTER.
402        if site.bind_type != BIND_TYPE_POINTER && site.bind_type != 0 {
403            return Err(LoadError::NotImplemented(
404                "non-POINTER classic bind type (TEXT absolute/pcrel)",
405            ));
406        }
407        let resolved = resolve_bind_symbol(session.images(), image_idx, site)?;
408        let value = if site.addend == 0 {
409            resolved
410        } else {
411            resolved.wrapping_add(site.addend.cast_unsigned())
412        };
413        let slot = site.preferred_va.wrapping_add(slide);
414        tracing::debug!(
415            name = %site.name,
416            slot,
417            value,
418            ordinal = site.lib_ordinal,
419            lazy = site.is_lazy,
420            "bind opcode POINTER"
421        );
422        updates.push((slot, value));
423    }
424
425    write_pointer_slots(session, image_idx, &updates)
426}
427
428/// Resolve a two-level (or special/flat) import for bind / chained fixups.
429pub(crate) fn resolve_bind_symbol(
430    images: &[ProcessImage],
431    binder_idx: usize,
432    site: &BindSite,
433) -> Result<u64, LoadError> {
434    match resolve_bind_symbol_inner(images, binder_idx, site) {
435        Ok(va) => Ok(va),
436        Err(LoadError::UnresolvedSymbol { name }) if !site.weak => {
437            // Large guests (curl) import more libc surface than freestanding
438            // libSystem implements. Point each strong miss at a per-name
439            // trampoline → `_kh_missing_symbol_named` so the first *call*
440            // prints which import we still need (G1).
441            resolve_missing_stub(images, &name)
442        }
443        Err(err) => Err(err),
444    }
445}
446
447fn resolve_bind_symbol_inner(
448    images: &[ProcessImage],
449    binder_idx: usize,
450    site: &BindSite,
451) -> Result<u64, LoadError> {
452    // Specials from SET_DYLIB_SPECIAL_IMM / chained import ordinals are
453    // sign-extended to negative i16 (SELF=0, MAIN=-1, FLAT=-2, WEAK=-3).
454    // Positive ordinals are 1-based LC_LOAD_* order.
455    match site.lib_ordinal {
456        o if o == i16::from(BIND_SPECIAL_DYLIB_SELF) => {
457            lookup_in_image(images.get(binder_idx), &site.name, site.weak)
458        }
459        -1 => {
460            // BIND_SPECIAL_DYLIB_MAIN_EXECUTABLE
461            debug_assert_eq!(BIND_SPECIAL_DYLIB_MAIN_EXECUTABLE, 0xf);
462            lookup_in_image(images.first(), &site.name, site.weak)
463        }
464        -2 => {
465            // BIND_SPECIAL_DYLIB_FLAT_LOOKUP
466            debug_assert_eq!(BIND_SPECIAL_DYLIB_FLAT_LOOKUP, 0xe);
467            lookup_flat(images, &site.name, site.weak)
468        }
469        -3 => {
470            // BIND_SPECIAL_DYLIB_WEAK_LOOKUP (object/macho: -3; not in goblin yet).
471            // Search all loaded images for a definition (weak coalescing). Same
472            // map walk as flat lookup for our micro loader.
473            lookup_flat(images, &site.name, site.weak)
474        }
475        n if n > 0 => {
476            let binder = images.get(binder_idx).ok_or(LoadError::NotImplemented(
477                "binder image missing for bind resolve",
478            ))?;
479            let ordinal_u32 = u32::try_from(n)
480                .map_err(|_| LoadError::Resolve(format!("bind ordinal out of u32 range: {n}")))?;
481            let dep_name = nth_dependent_dylib(binder, ordinal_u32)?;
482            if let Some(img) = find_mapped_by_install_name(images, &dep_name) {
483                lookup_in_image(Some(img), &site.name, site.weak)
484            } else if site.weak {
485                Ok(0)
486            } else if let Ok(va) = lookup_flat(images, &site.name, false) {
487                // Framework skipped (e.g. CoreFoundation) but freestanding
488                // libSystem may still export a stub for G1 probes (curl).
489                tracing::debug!(
490                    name = %site.name,
491                    missing = %dep_name,
492                    "two-level target missing; flat stub resolve"
493                );
494                Ok(va)
495            } else {
496                // Two-level target not mapped and no flat definition.
497                Err(LoadError::UnresolvedSymbol {
498                    name: site.name.clone(),
499                })
500            }
501        }
502        other => Err(LoadError::Resolve(format!(
503            "unsupported bind library ordinal {other}"
504        ))),
505    }
506}
507
508fn nth_dependent_dylib(binder: &ProcessImage, ordinal: u32) -> Result<String, LoadError> {
509    let image = binder
510        .image
511        .as_ref()
512        .ok_or(LoadError::NotImplemented("binder has no Mach-O image"))?;
513    let deps = dependent_dylib_names(image);
514    let idx = ordinal
515        .checked_sub(1)
516        .and_then(|i| usize::try_from(i).ok())
517        .ok_or_else(|| LoadError::Resolve(format!("invalid dylib ordinal {ordinal}")))?;
518    deps.get(idx).cloned().ok_or_else(|| {
519        LoadError::Resolve(format!(
520            "dylib ordinal {ordinal} out of range ({} deps)",
521            deps.len()
522        ))
523    })
524}
525
526fn dependent_dylib_names(image: &MachOImage) -> Vec<String> {
527    image
528        .dylibs
529        .iter()
530        .filter(|d| d.kind != DylibKind::Id)
531        .map(|d| d.name.clone())
532        .collect()
533}
534
535fn find_mapped_by_install_name<'a>(
536    images: &'a [ProcessImage],
537    install_name: &str,
538) -> Option<&'a ProcessImage> {
539    if let Some(img) = images.iter().find(|img| {
540        matches!(img.status, ImageLoadStatus::Mapped)
541            && (img.install_name == install_name
542                || img
543                    .path
544                    .file_name()
545                    .and_then(|n| n.to_str())
546                    .is_some_and(|n| install_name.ends_with(n)))
547    }) {
548        return Some(img);
549    }
550
551    // Bottle alias: `libc++.1.dylib` → same real path as already-mapped
552    // `libSystem.B.dylib` is recorded as `skipped:duplicate`. Reuse the mapped
553    // image so two-level binds against the alias ordinal still resolve.
554    //
555    // Use the load-time cached `real_path` (no per-bind `canonicalize` /
556    // readlinkat storm — roadmap A4).
557    let alias = images.iter().find(|img| {
558        matches!(
559            img.status,
560            ImageLoadStatus::Skipped(crate::session::SkipReason::Duplicate)
561        ) && img.install_name == install_name
562    })?;
563    let alias_key = &alias.real_path;
564    if alias_key.as_os_str().is_empty() {
565        return None;
566    }
567    images
568        .iter()
569        .find(|img| matches!(img.status, ImageLoadStatus::Mapped) && img.real_path == *alias_key)
570}
571
572fn lookup_in_image(img: Option<&ProcessImage>, name: &str, weak: bool) -> Result<u64, LoadError> {
573    let Some(img) = img else {
574        return if weak {
575            Ok(0)
576        } else {
577            Err(LoadError::UnresolvedSymbol {
578                name: name.to_owned(),
579            })
580        };
581    };
582    if !matches!(img.status, ImageLoadStatus::Mapped) {
583        return if weak {
584            Ok(0)
585        } else {
586            Err(LoadError::UnresolvedSymbol {
587                name: name.to_owned(),
588            })
589        };
590    }
591    let slide = img.slide();
592    if let Some(exp) = img.exports.iter().find(|e| e.name == name) {
593        return Ok(exp.value.wrapping_add(slide));
594    }
595    // curl imports unadorned `dyld_stub_binder`; freestanding libSystem exports
596    // the C nlist `_dyld_stub_binder` (see `build_export_map` alias).
597    if name == "dyld_stub_binder"
598        && let Some(exp) = img.exports.iter().find(|e| e.name == "_dyld_stub_binder")
599    {
600        return Ok(exp.value.wrapping_add(slide));
601    }
602    if weak {
603        Ok(0)
604    } else {
605        Err(LoadError::UnresolvedSymbol {
606            name: name.to_owned(),
607        })
608    }
609}
610
611fn lookup_flat(images: &[ProcessImage], name: &str, weak: bool) -> Result<u64, LoadError> {
612    let map = build_export_map(images);
613    match map.get(name) {
614        Some(&va) => Ok(va),
615        None if weak => Ok(0),
616        None => Err(LoadError::UnresolvedSymbol {
617            name: name.to_owned(),
618        }),
619    }
620}
621
622/// Write absolute pointers into a mapped image.
623///
624/// Batches by region and skips host `mprotect` when the region is already
625/// Darwin-writable (typical `__DATA` binds). Per-slot RW↔restore used to cost
626/// ~2×N `mprotect` syscalls on large guests (roadmap A5).
627pub(crate) fn write_pointer_slots(
628    session: &mut LoadSession,
629    image_idx: usize,
630    updates: &[(u64, u64)],
631) -> Result<(), LoadError> {
632    if updates.is_empty() {
633        return Ok(());
634    }
635    let img = session
636        .images
637        .get_mut(image_idx)
638        .ok_or(LoadError::NotImplemented("image missing for bind write"))?;
639    let memory = img
640        .memory
641        .as_mut()
642        .ok_or(LoadError::NotImplemented("memory missing for bind write"))?;
643    write_slots_batched(memory, updates)
644}
645
646/// Apply `(slot_va, value)` writes with at most one mprotect pair per region.
647pub(crate) fn write_slots_batched(
648    memory: &mut GuestMemory,
649    updates: &[(u64, u64)],
650) -> Result<(), LoadError> {
651    if updates.is_empty() {
652        return Ok(());
653    }
654
655    // Group slot → value by region index (stable order for deterministic errors).
656    let mut by_region: BTreeMap<usize, Vec<(u64, u64)>> = BTreeMap::new();
657    for &(slot, value) in updates {
658        let region_idx = memory
659            .regions()
660            .iter()
661            .position(|r| {
662                let start = r.guest_addr;
663                let end = start.saturating_add(r.vmsize);
664                slot >= start && slot < end
665            })
666            .ok_or_else(|| {
667                LoadError::Resolve(format!("bind slot {slot:#x} outside mapped regions"))
668            })?;
669        by_region.entry(region_idx).or_default().push((slot, value));
670    }
671
672    for (region_idx, slots) in by_region {
673        let restore = memory
674            .regions()
675            .get(region_idx)
676            .ok_or_else(|| LoadError::Resolve(format!("bind region missing idx {region_idx}")))?
677            .prot;
678        // DATA/BSS already RW after map: do not thrash mprotect (A5).
679        let need_flip = restore & VM_PROT_WRITE == 0;
680        if need_flip {
681            let region = memory.regions_mut().get_mut(region_idx).ok_or_else(|| {
682                LoadError::Resolve(format!("bind region missing idx {region_idx}"))
683            })?;
684            mprotect_rw(region).map_err(LoadError::Map)?;
685        }
686
687        for (slot, value) in slots {
688            if memory.write_u64_le(slot, value).is_none() {
689                return Err(LoadError::Resolve(format!(
690                    "bind write failed at {slot:#x}"
691                )));
692            }
693        }
694
695        if need_flip {
696            let region = memory
697                .regions()
698                .get(region_idx)
699                .ok_or_else(|| LoadError::Resolve(format!("bind region lost idx {region_idx}")))?;
700            mprotect_darwin(region, restore).map_err(LoadError::Map)?;
701        }
702    }
703    Ok(())
704}
705
706/// Encode a minimal non-lazy POINTER bind sequence for fixtures / tests.
707#[must_use]
708pub fn encode_pointer_bind(
709    dylib_ordinal: u8,
710    symbol: &str,
711    seg_index: u8,
712    seg_offset: u64,
713) -> Vec<u8> {
714    let mut out = Vec::with_capacity(32);
715    out.push(BIND_OPCODE_SET_DYLIB_ORDINAL_IMM | (dylib_ordinal & BIND_IMMEDIATE_MASK));
716    out.push(BIND_OPCODE_SET_TYPE_IMM | BIND_TYPE_POINTER);
717    out.push(BIND_OPCODE_SET_SYMBOL_TRAILING_FLAGS_IMM);
718    out.extend_from_slice(symbol.as_bytes());
719    out.push(0);
720    out.push(BIND_OPCODE_SET_SEGMENT_AND_OFFSET_ULEB | (seg_index & BIND_IMMEDIATE_MASK));
721    push_uleb(&mut out, seg_offset);
722    out.push(BIND_OPCODE_DO_BIND);
723    out.push(BIND_OPCODE_DONE);
724    out
725}
726
727fn push_uleb(out: &mut Vec<u8>, mut value: u64) {
728    loop {
729        let mut byte = u8::try_from(value & 0x7f).unwrap_or(0);
730        value >>= 7;
731        if value != 0 {
732            byte |= 0x80;
733        }
734        out.push(byte);
735        if value == 0 {
736            break;
737        }
738    }
739}
740
741#[cfg(test)]
742#[allow(clippy::expect_used, clippy::unwrap_used)]
743mod tests {
744    use super::*;
745    use crate::fixture::{CALL_DYLIB_GOT_VA, KH_ADD_SYMBOL, arm64_dylib_add, call_dylib_exit};
746    use crate::session::{ImageRole, LoadSession};
747    use crate::test_util::map_test_lock;
748    use std::io::Write;
749    use std::sync::atomic::{AtomicU64, Ordering};
750
751    #[test]
752    fn encode_and_collect_one_site() {
753        let stream = encode_pointer_bind(1, KH_ADD_SYMBOL, 2, 0);
754        // Minimal fake: only stream interpretation via a tiny Mach-O is heavy;
755        // unit-test the encoder shape and DO_BIND fields via interpret_stream.
756        let seg = [0_u64, 0x1_0000_0000, CALL_DYLIB_GOT_VA];
757        let mut sites = Vec::new();
758        interpret_stream(&stream, 0..stream.len(), false, &seg, &mut sites).expect("interp");
759        assert_eq!(sites.len(), 1);
760        let s = sites.first().expect("one");
761        assert_eq!(s.name, KH_ADD_SYMBOL);
762        assert_eq!(s.preferred_va, CALL_DYLIB_GOT_VA);
763        assert_eq!(s.lib_ordinal, 1);
764        assert_eq!(s.bind_type, BIND_TYPE_POINTER);
765        assert!(!s.weak);
766        assert!(!s.is_lazy);
767    }
768
769    #[test]
770    fn call_dylib_fixture_has_bind_opcodes() {
771        let bytes = call_dylib_exit();
772        let sites = collect_bind_sites(&bytes).expect("sites");
773        assert_eq!(sites.len(), 1, "{sites:?}");
774        let s = sites.first().expect("one");
775        assert_eq!(s.name, KH_ADD_SYMBOL);
776        assert_eq!(s.preferred_va, CALL_DYLIB_GOT_VA);
777        assert_eq!(s.lib_ordinal, 1);
778    }
779
780    #[test]
781    fn opcode_bind_writes_got() {
782        static N: AtomicU64 = AtomicU64::new(0);
783        let _guard = map_test_lock();
784        let n = N.fetch_add(1, Ordering::Relaxed);
785        let dir = std::env::temp_dir().join(format!("kh-bind-op-{}-{n}", std::process::id()));
786        std::fs::create_dir_all(&dir).expect("mkdir");
787        let main_path = dir.join("call_dylib.macho");
788        let dylib_path = dir.join("libkh_add.dylib");
789        {
790            let mut f = std::fs::File::create(&main_path).expect("create main");
791            f.write_all(&call_dylib_exit()).expect("write main");
792        }
793        {
794            let mut f = std::fs::File::create(&dylib_path).expect("create dylib");
795            f.write_all(&arm64_dylib_add()).expect("write dylib");
796        }
797
798        let mut session = LoadSession::open(&main_path, None).expect("open");
799        let _ = session.map_process().expect("map_process");
800        let main = session.images().first().expect("main");
801        assert_eq!(main.role, ImageRole::Main);
802        let main_slide = main.slide();
803
804        let export_va = session
805            .images()
806            .iter()
807            .find(|i| i.role == ImageRole::Dylib && matches!(i.status, ImageLoadStatus::Mapped))
808            .and_then(|dylib| {
809                dylib
810                    .exports
811                    .iter()
812                    .find(|e| e.name == KH_ADD_SYMBOL)
813                    .map(|e| e.value.wrapping_add(dylib.slide()))
814            })
815            .expect("dylib export");
816
817        let got_va = CALL_DYLIB_GOT_VA.wrapping_add(main_slide);
818        let main_mem = session
819            .images()
820            .first()
821            .and_then(|i| i.memory.as_ref())
822            .expect("main mem");
823        let region = main_mem
824            .regions()
825            .iter()
826            .find(|r| got_va >= r.guest_addr && got_va < r.guest_addr.saturating_add(r.vmsize))
827            .expect("DATA region");
828        let off = usize::try_from(got_va.saturating_sub(region.guest_addr)).unwrap();
829        let end = off.saturating_add(8);
830        let bytes = region.host_bytes().get(off..end).expect("got bytes");
831        let mut le = [0_u8; 8];
832        le.copy_from_slice(bytes);
833        assert_eq!(u64::from_le_bytes(le), export_va);
834
835        drop(session);
836        drop(std::fs::remove_dir_all(dir));
837    }
838
839    #[test]
840    fn do_bind_times_skipping() {
841        // SET_ORD 1, SET_TYPE PTR, SET_SYM "x", SET_SEG 0 off 0,
842        // DO_BIND_ULEB_TIMES_SKIPPING count=2 skip=8 → slots 0 and 16
843        let mut stream = Vec::new();
844        stream.push(BIND_OPCODE_SET_DYLIB_ORDINAL_IMM | 1);
845        stream.push(BIND_OPCODE_SET_TYPE_IMM | BIND_TYPE_POINTER);
846        stream.push(BIND_OPCODE_SET_SYMBOL_TRAILING_FLAGS_IMM);
847        stream.extend_from_slice(b"x\0");
848        stream.push(BIND_OPCODE_SET_SEGMENT_AND_OFFSET_ULEB);
849        push_uleb(&mut stream, 0);
850        stream.push(BIND_OPCODE_DO_BIND_ULEB_TIMES_SKIPPING_ULEB);
851        push_uleb(&mut stream, 2);
852        push_uleb(&mut stream, 8);
853        stream.push(BIND_OPCODE_DONE);
854
855        let seg = [0x1000_u64];
856        let mut sites = Vec::new();
857        interpret_stream(&stream, 0..stream.len(), false, &seg, &mut sites).expect("interp");
858        assert_eq!(sites.len(), 2);
859        assert_eq!(sites.first().expect("0").preferred_va, 0x1000);
860        assert_eq!(sites.get(1).expect("1").preferred_va, 0x1000 + 16);
861    }
862}