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