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