1use std::collections::HashMap;
9use std::ops::Range;
10
11use goblin::mach::Mach;
12use goblin::mach::load_command::CommandVariant;
13use goblin::mach::symbols::{N_EXT, N_SECT, N_TYPE, N_UNDF, N_WEAK_REF, Symbols};
14
15use kh_runtime::{mprotect_darwin, mprotect_rw};
16
17use crate::error::LoadError;
18use crate::image::MachOImage;
19use crate::parse::{read_thin_arm64, thin_arm64_bytes};
20use crate::session::{ImageLoadStatus, LoadSession, ProcessImage};
21
22#[derive(Debug, Clone, PartialEq, Eq)]
24pub struct DefinedSymbol {
25 pub name: String,
27 pub value: u64,
29 pub sect: u8,
31}
32
33#[derive(Debug, Clone, PartialEq, Eq)]
35pub struct UndefinedSymbol {
36 pub name: String,
38 pub weak_ref: bool,
40}
41
42pub fn defined_exports(bytes: &[u8]) -> Result<Vec<DefinedSymbol>, LoadError> {
52 let thin = thin_arm64_bytes(bytes)?;
53 let macho = parse_macho_binary(thin)?;
54 let Some(symbols) = macho.symbols.as_ref() else {
55 return Ok(Vec::new());
56 };
57 let mut out = Vec::new();
58 match dysym_extdef_range(&macho) {
59 Some(r) if r.is_empty() => return Ok(out),
60 Some(r) => {
61 out.reserve(r.len().min(4096));
62 for_each_nlist_index(symbols, r, |name, nlist| {
63 push_defined_export(&mut out, name, &nlist);
64 })?;
65 }
66 None => {
67 for entry in symbols {
69 match entry {
70 Ok((name, nlist)) => push_defined_export(&mut out, name, &nlist),
71 Err(err) => return Err(LoadError::NotMachO(format!("nlist: {err}"))),
72 }
73 }
74 }
75 }
76 Ok(out)
77}
78
79fn push_defined_export(
80 out: &mut Vec<DefinedSymbol>,
81 name: &str,
82 nlist: &goblin::mach::symbols::Nlist,
83) {
84 if nlist.is_stab() || (nlist.n_type & N_EXT) == 0 {
85 return;
86 }
87 if nlist.n_type & N_TYPE != N_SECT {
88 return;
89 }
90 out.push(DefinedSymbol {
91 name: name.to_owned(),
92 value: nlist.n_value,
93 sect: u8::try_from(nlist.n_sect).unwrap_or(u8::MAX),
94 });
95}
96
97pub fn undefined_imports(bytes: &[u8]) -> Result<Vec<UndefinedSymbol>, LoadError> {
103 let thin = thin_arm64_bytes(bytes)?;
104 let macho = parse_macho_binary(thin)?;
105 let Some(symbols) = macho.symbols.as_ref() else {
106 return Ok(Vec::new());
107 };
108 let mut out = Vec::new();
109 match dysym_undef_range(&macho) {
110 Some(r) if r.is_empty() => return Ok(out),
111 Some(r) => {
112 out.reserve(r.len().min(1024));
113 for_each_nlist_index(symbols, r, |name, nlist| {
114 push_undefined_import(&mut out, name, &nlist);
115 })?;
116 }
117 None => {
118 for entry in symbols {
119 match entry {
120 Ok((name, nlist)) => push_undefined_import(&mut out, name, &nlist),
121 Err(err) => return Err(LoadError::NotMachO(format!("nlist: {err}"))),
122 }
123 }
124 }
125 }
126 Ok(out)
127}
128
129fn push_undefined_import(
130 out: &mut Vec<UndefinedSymbol>,
131 name: &str,
132 nlist: &goblin::mach::symbols::Nlist,
133) {
134 if nlist.is_stab() || (nlist.n_type & N_EXT) == 0 {
135 return;
136 }
137 if nlist.n_type & N_TYPE != N_UNDF {
139 return;
140 }
141 if nlist.n_sect != 0 {
142 return;
143 }
144 out.push(UndefinedSymbol {
145 name: name.to_owned(),
146 weak_ref: nlist.n_desc & N_WEAK_REF != 0,
147 });
148}
149
150pub(crate) fn bind_main_got_nlist(session: &mut LoadSession) -> Result<(), LoadError> {
155 let main_path = session
156 .images
157 .first()
158 .map(|i| i.path.clone())
159 .ok_or(LoadError::NotImplemented("main missing before bind"))?;
160 let main_bytes = read_thin_arm64(&main_path)?;
161 let undefs = undefined_imports(&main_bytes)?;
162 if undefs.is_empty() {
163 return Ok(());
164 }
165
166 let main = session
167 .images
168 .first()
169 .ok_or(LoadError::NotImplemented("main missing before bind"))?;
170 let main_slide = main.slide();
174
175 let export_map = build_export_map(session.images());
176 let (got_pref, got_size) =
177 find_got_section(main.image.as_ref()).ok_or(LoadError::MissingGot {
178 count: undefs.len(),
179 })?;
180 let need = undefs.len().checked_mul(8).ok_or(LoadError::MissingGot {
181 count: undefs.len(),
182 })?;
183 let need_u64 = u64::try_from(need).unwrap_or(u64::MAX);
184 if got_size < need_u64 {
185 return Err(LoadError::MissingGot {
186 count: undefs.len(),
187 });
188 }
189 let got_va = got_pref.wrapping_add(main_slide);
190
191 let named_handler = export_map.get("_kh_missing_symbol_named").copied();
192 let missing_stub = export_map.get("_kh_missing_symbol").copied();
193 let mut values = Vec::with_capacity(undefs.len());
194 for u in &undefs {
195 match export_map.get(&u.name) {
196 Some(&va) => {
197 tracing::debug!(name = %u.name, va, "bind GOT nlist");
198 values.push(va);
199 }
200 None if u.weak_ref => {
201 tracing::debug!(name = %u.name, "weak undef → GOT 0");
202 values.push(0);
203 }
204 None => {
205 if let Some(handler) = named_handler {
206 match crate::missing_stub::trampoline_for(&u.name, handler) {
207 Ok(va) => {
208 tracing::warn!(
209 name = %u.name,
210 stub = format_args!("{va:#x}"),
211 "unresolved strong nlist; bound to named missing trampoline"
212 );
213 values.push(va);
214 continue;
215 }
216 Err(err) => {
217 tracing::warn!(
218 name = %u.name,
219 error = %err,
220 "missing trampoline emit failed; falling back"
221 );
222 }
223 }
224 }
225 if let Some(stub) = missing_stub {
226 tracing::warn!(
227 name = %u.name,
228 "unresolved strong nlist; bound to _kh_missing_symbol"
229 );
230 values.push(stub);
231 } else if let Some(handler) = named_handler {
232 values.push(handler);
233 } else {
234 return Err(LoadError::UnresolvedSymbol {
235 name: u.name.clone(),
236 });
237 }
238 }
239 }
240 }
241
242 write_got_slots(session, got_va, &values)?;
243 Ok(())
244}
245
246pub(crate) fn fill_exports(session: &mut LoadSession) -> Result<(), LoadError> {
247 for img in &mut session.images {
248 if !matches!(img.status, ImageLoadStatus::Mapped) {
249 img.exports.clear();
250 img.export_by_name.clear();
251 continue;
252 }
253 if img.path.as_os_str().is_empty() {
254 img.exports.clear();
255 img.export_by_name.clear();
256 continue;
257 }
258 img.exports = if let Some(container) = img.file_bytes.as_ref() {
260 let thin = thin_arm64_bytes(container.as_slice())?;
261 defined_exports(thin)?
262 } else {
263 let bytes = read_thin_arm64(&img.path)?;
264 defined_exports(&bytes)?
265 };
266 img.export_by_name.clear();
268 img.export_by_name.reserve(img.exports.len().saturating_add(1));
269 for exp in &img.exports {
270 img.export_by_name
271 .entry(exp.name.clone())
272 .or_insert(exp.value);
273 }
274 if let Some(v) = img.export_by_name.get("_dyld_stub_binder").copied() {
277 img.export_by_name
278 .entry("dyld_stub_binder".into())
279 .or_insert(v);
280 }
281 }
282 Ok(())
283}
284
285pub(crate) fn build_export_map(images: &[ProcessImage]) -> HashMap<String, u64> {
290 let mut map = HashMap::new();
291 for img in images {
292 if !matches!(img.status, ImageLoadStatus::Mapped) {
293 continue;
294 }
295 let slide = img.slide();
296 if img.export_by_name.is_empty() {
297 for exp in &img.exports {
298 map.entry(exp.name.clone())
299 .or_insert_with(|| exp.value.wrapping_add(slide));
300 }
301 } else {
302 for (name, &pref) in &img.export_by_name {
303 map.entry(name.clone())
304 .or_insert_with(|| pref.wrapping_add(slide));
305 }
306 }
307 }
308 map
309}
310
311fn find_got_section(image: Option<&MachOImage>) -> Option<(u64, u64)> {
312 let image = image?;
313 for seg in &image.segments {
314 for sect in &seg.sections {
315 if sect.name == "__got" {
316 return Some((sect.addr, sect.size));
317 }
318 }
319 }
320 None
321}
322
323fn write_got_slots(
324 session: &mut LoadSession,
325 got_va: u64,
326 values: &[u64],
327) -> Result<(), LoadError> {
328 let main = session
329 .images
330 .first_mut()
331 .ok_or(LoadError::NotImplemented("main missing for GOT write"))?;
332 let memory = main.memory.as_mut().ok_or(LoadError::NotImplemented(
333 "main memory missing for GOT write",
334 ))?;
335
336 let region_idx = memory
338 .regions()
339 .iter()
340 .position(|r| {
341 let start = r.guest_addr;
342 let end = start.saturating_add(r.vmsize);
343 got_va >= start && got_va < end
344 })
345 .ok_or(LoadError::MissingGot {
346 count: values.len(),
347 })?;
348
349 let region = memory
350 .regions_mut()
351 .get_mut(region_idx)
352 .ok_or(LoadError::MissingGot {
353 count: values.len(),
354 })?;
355 let region_base = region.guest_addr;
356 let restore = region.prot;
357 mprotect_rw(region).map_err(LoadError::Map)?;
358
359 for (i, &va) in values.iter().enumerate() {
360 let slot = got_va.saturating_add(u64::try_from(i).unwrap_or(0).saturating_mul(8));
361 let offset = usize::try_from(slot.saturating_sub(region_base)).map_err(|_| {
362 LoadError::MissingGot {
363 count: values.len(),
364 }
365 })?;
366 let end = offset.saturating_add(8);
367 let host = region.host_bytes_mut();
368 let Some(slot_bytes) = host.get_mut(offset..end) else {
369 return Err(LoadError::MissingGot {
370 count: values.len(),
371 });
372 };
373 slot_bytes.copy_from_slice(&va.to_le_bytes());
374 }
375
376 mprotect_darwin(region, restore).map_err(LoadError::Map)?;
377 Ok(())
378}
379
380fn parse_macho_binary(thin: &[u8]) -> Result<goblin::mach::MachO<'_>, LoadError> {
381 match Mach::parse(thin) {
382 Ok(Mach::Binary(m)) => Ok(m),
383 Ok(Mach::Fat(_)) => Err(LoadError::NotMachO(
384 "nested fat image inside arm64 slice".into(),
385 )),
386 Err(err) => Err(LoadError::NotMachO(err.to_string())),
387 }
388}
389
390fn dysym_extdef_range(macho: &goblin::mach::MachO<'_>) -> Option<Range<usize>> {
397 for lc in &macho.load_commands {
398 if let CommandVariant::Dysymtab(d) = &lc.command {
399 if dysymtab_is_vacuous(d) {
400 return None;
401 }
402 let start = usize::try_from(d.iextdefsym).ok()?;
403 let count = usize::try_from(d.nextdefsym).ok()?;
404 return Some(start..start.saturating_add(count));
405 }
406 }
407 None
408}
409
410fn dysym_undef_range(macho: &goblin::mach::MachO<'_>) -> Option<Range<usize>> {
412 for lc in &macho.load_commands {
413 if let CommandVariant::Dysymtab(d) = &lc.command {
414 if dysymtab_is_vacuous(d) {
415 return None;
416 }
417 let start = usize::try_from(d.iundefsym).ok()?;
418 let count = usize::try_from(d.nundefsym).ok()?;
419 return Some(start..start.saturating_add(count));
420 }
421 }
422 None
423}
424
425fn dysymtab_is_vacuous(d: &goblin::mach::load_command::DysymtabCommand) -> bool {
427 d.nlocalsym == 0 && d.nextdefsym == 0 && d.nundefsym == 0
428}
429
430fn for_each_nlist_index<F>(
431 symbols: &Symbols<'_>,
432 range: Range<usize>,
433 mut f: F,
434) -> Result<(), LoadError>
435where
436 F: FnMut(&str, goblin::mach::symbols::Nlist),
437{
438 for i in range {
439 match symbols.get(i) {
440 Ok((name, nlist)) => f(name, nlist),
441 Err(err) => {
442 return Err(LoadError::NotMachO(format!("nlist[{i}]: {err}")));
443 }
444 }
445 }
446 Ok(())
447}
448
449#[cfg(test)]
450#[allow(clippy::expect_used, clippy::unwrap_used)]
451mod tests {
452 use super::*;
453 use crate::fixture::{
454 KH_BOTTLE_MARK_SYMBOL, arm64_dylib_add, arm64_libsystem_stub, call_dylib_exit,
455 call_libsystem_exit, minimal_arm64_execute,
456 };
457 use crate::session::{ImageLoadStatus, ImageRole, LoadSession};
458 use crate::test_util::map_test_lock;
459 use std::io::Write;
460 use std::sync::atomic::{AtomicU64, Ordering};
461
462 #[test]
463 fn no_symtab_means_zero_undefs() {
464 let bytes = minimal_arm64_execute();
465 let undefs = undefined_imports(&bytes).expect("undefs");
466 assert!(undefs.is_empty());
467 let exports = defined_exports(&bytes).expect("exports");
468 assert!(exports.is_empty());
469 }
470
471 #[test]
472 fn fixture_export_and_import_names() {
473 let dylib = arm64_dylib_add();
474 let exports = defined_exports(&dylib).expect("exports");
475 assert_eq!(exports.len(), 1);
476 let exp = exports.first().expect("one export");
477 assert_eq!(exp.name, "_kh_add");
478 assert!(
479 exp.value >= crate::fixture::LIBKH_ADD_TEXT_VA
480 && exp.value < crate::fixture::LIBKH_ADD_TEXT_VA + 0x4000,
481 "export VA in dylib TEXT: {:#x}",
482 exp.value
483 );
484
485 let main = call_dylib_exit();
486 let undefs = undefined_imports(&main).expect("undefs");
487 assert_eq!(undefs.len(), 1);
488 let und = undefs.first().expect("one undef");
489 assert_eq!(und.name, "_kh_add");
490 assert!(!und.weak_ref);
491 }
492
493 #[test]
494 fn bind_one_got_slot() {
495 static N: AtomicU64 = AtomicU64::new(0);
496 let _guard = map_test_lock();
497 let n = N.fetch_add(1, Ordering::Relaxed);
498 let dir = std::env::temp_dir().join(format!("kh-bind-{}-{n}", std::process::id()));
499 std::fs::create_dir_all(&dir).expect("mkdir");
500 let main_path = dir.join("call_dylib.macho");
501 let dylib_path = dir.join("libkh_add.dylib");
502 {
503 let mut f = std::fs::File::create(&main_path).expect("create main");
504 f.write_all(&call_dylib_exit()).expect("write main");
505 }
506 {
507 let mut f = std::fs::File::create(&dylib_path).expect("create dylib");
508 f.write_all(&arm64_dylib_add()).expect("write dylib");
509 }
510
511 let mut session = LoadSession::open(&main_path, None).expect("open");
512 let _ = session.map_process().expect("map_process");
513 let mapped_count = session
514 .images()
515 .iter()
516 .filter(|i| matches!(i.status, ImageLoadStatus::Mapped))
517 .count();
518 assert!(
519 mapped_count >= 2,
520 "main + dylib should map: {:?}",
521 session
522 .images()
523 .iter()
524 .map(|i| (i.role, i.status.as_str(), i.install_name.as_str()))
525 .collect::<Vec<_>>()
526 );
527 let main = session.images().first().expect("main");
528 assert_eq!(main.role, ImageRole::Main);
529 let main_slide = main.slide();
530
531 let export_va = session
532 .images()
533 .iter()
534 .find(|i| i.role == ImageRole::Dylib && matches!(i.status, ImageLoadStatus::Mapped))
535 .and_then(|dylib| {
536 dylib
537 .exports
538 .iter()
539 .find(|e| e.name == "_kh_add")
540 .map(|e| e.value.wrapping_add(dylib.slide()))
541 })
542 .expect("dylib export");
543
544 let got_va = crate::fixture::CALL_DYLIB_GOT_VA.wrapping_add(main_slide);
545 let main_mem = session
546 .images()
547 .first()
548 .and_then(|i| i.memory.as_ref())
549 .expect("main mem");
550 let region = main_mem
551 .regions()
552 .iter()
553 .find(|r| got_va >= r.guest_addr && got_va < r.guest_addr.saturating_add(r.vmsize))
554 .expect("DATA region");
555 let off = usize::try_from(got_va.saturating_sub(region.guest_addr)).unwrap();
556 let end = off.saturating_add(8);
557 let bytes = region.host_bytes().get(off..end).expect("got bytes");
558 let mut le = [0_u8; 8];
559 le.copy_from_slice(bytes);
560 assert_eq!(u64::from_le_bytes(le), export_va);
561
562 drop(session);
563 drop(std::fs::remove_dir_all(dir));
564 }
565
566 #[test]
567 fn libsystem_stub_export_name() {
568 use crate::fixture::{
569 LIBSYSTEM_EXIT_SYMBOL, LIBSYSTEM_PRINTF_SYMBOL, LIBSYSTEM_PUTS_SYMBOL,
570 LIBSYSTEM_WRITE_SYMBOL,
571 };
572
573 let exports = defined_exports(&arm64_libsystem_stub()).expect("exports");
574 assert_eq!(exports.len(), 5);
575 let names: Vec<&str> = exports.iter().map(|e| e.name.as_str()).collect();
576 assert!(names.contains(&LIBSYSTEM_WRITE_SYMBOL));
577 assert!(names.contains(&LIBSYSTEM_EXIT_SYMBOL));
578 assert!(names.contains(&LIBSYSTEM_PUTS_SYMBOL));
579 assert!(names.contains(&LIBSYSTEM_PRINTF_SYMBOL));
580 assert!(names.contains(&KH_BOTTLE_MARK_SYMBOL));
581 for exp in &exports {
582 assert!(
583 exp.value >= crate::fixture::LIBSYSTEM_TEXT_VA
584 && exp.value < crate::fixture::LIBSYSTEM_TEXT_VA + 0x4000,
585 "export VA in stub TEXT: {} @ {:#x}",
586 exp.name,
587 exp.value
588 );
589 }
590
591 let undefs = undefined_imports(&call_libsystem_exit()).expect("undefs");
592 assert_eq!(undefs.len(), 1);
593 assert_eq!(undefs.first().expect("one").name, KH_BOTTLE_MARK_SYMBOL);
594 }
595}