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