Skip to main content

shadow_rs/host/
host.rs

1//! An emulated Linux system.
2
3use std::cell::{Cell, Ref, RefCell, RefMut, UnsafeCell};
4use std::collections::BTreeMap;
5use std::ffi::{CStr, CString, OsString};
6use std::net::{Ipv4Addr, SocketAddrV4};
7use std::ops::{Deref, DerefMut};
8use std::os::unix::prelude::OsStringExt;
9use std::path::{Path, PathBuf};
10use std::sync::{Arc, Mutex};
11
12use asm_util::tsc::Tsc;
13use atomic_refcell::AtomicRefCell;
14use linux_api::signal::{Signal, siginfo_t};
15use log::{debug, trace};
16use logger::LogLevel;
17use once_cell::unsync::OnceCell;
18use rand::SeedableRng;
19use rand_xoshiro::Xoshiro256PlusPlus;
20use shadow_shim_helper_rs::HostId;
21use shadow_shim_helper_rs::emulated_time::EmulatedTime;
22use shadow_shim_helper_rs::explicit_drop::ExplicitDropper;
23use shadow_shim_helper_rs::rootedcell::Root;
24use shadow_shim_helper_rs::rootedcell::cell::RootedCell;
25use shadow_shim_helper_rs::rootedcell::rc::RootedRc;
26use shadow_shim_helper_rs::rootedcell::refcell::RootedRefCell;
27use shadow_shim_helper_rs::shim_shmem::{HostShmem, HostShmemProtected, ManagerShmem};
28use shadow_shim_helper_rs::simulation_time::SimulationTime;
29use shadow_shmem::allocator::ShMemBlock;
30use vasi_sync::scmutex::SelfContainedMutexGuard;
31
32use crate::core::configuration::{ProcessFinalState, QDiscMode};
33use crate::core::sim_config::PcapConfig;
34use crate::core::work::event::{Event, EventData};
35use crate::core::work::event_queue::EventQueue;
36use crate::core::work::task::TaskRef;
37use crate::core::worker::Worker;
38use crate::cshadow;
39use crate::host::descriptor::socket::abstract_unix_ns::AbstractUnixNamespace;
40use crate::host::descriptor::socket::inet::InetSocket;
41use crate::host::fcntl_lock_table::FcntlLockTable;
42use crate::host::futex_table::FutexTable;
43use crate::host::network::interface::{FifoPacketPriority, NetworkInterface, PcapOptions};
44use crate::host::network::namespace::NetworkNamespace;
45use crate::host::process::Process;
46use crate::host::thread::{Thread, ThreadId};
47use crate::network::router::{Router, RouterContext, RouterEvent};
48use crate::network::{PacketDevice, RateLimit};
49use crate::utility;
50#[cfg(feature = "perf_timers")]
51use crate::utility::perf_timer::PerfTimer;
52
53pub struct HostParameters {
54    pub id: HostId,
55    pub node_seed: u64,
56    // TODO: Remove when we don't need C compatibility.
57    // Already storing as a String in HostInfo.
58    pub hostname: CString,
59    pub node_id: u32,
60    pub ip_addr: libc::in_addr_t,
61    pub sim_end_time: EmulatedTime,
62    pub requested_bw_down_bits: u64,
63    pub requested_bw_up_bits: u64,
64    pub cpu_frequency: u64,
65    pub cpu_threshold: Option<SimulationTime>,
66    pub cpu_precision: Option<SimulationTime>,
67    pub log_level: LogLevel,
68    pub pcap_config: Option<PcapConfig>,
69    pub qdisc: QDiscMode,
70    pub init_sock_recv_buf_size: u64,
71    pub autotune_recv_buf: bool,
72    pub init_sock_send_buf_size: u64,
73    pub autotune_send_buf: bool,
74    pub native_tsc_frequency: u64,
75    pub model_unblocked_syscall_latency: bool,
76    pub max_unapplied_cpu_latency: SimulationTime,
77    pub unblocked_syscall_latency: SimulationTime,
78    pub unblocked_vdso_latency: SimulationTime,
79    pub strace_logging_options: Option<FmtOptions>,
80    pub shim_log_level: LogLevel,
81    pub use_new_tcp: bool,
82    pub use_syscall_counters: bool,
83}
84
85use super::cpu::Cpu;
86use super::process::ProcessId;
87use super::syscall::formatter::FmtOptions;
88
89/// Immutable information about the Host.
90#[derive(Debug, Clone)]
91pub struct HostInfo {
92    pub id: HostId,
93    pub name: String,
94    pub default_ip: Ipv4Addr,
95    pub log_level: Option<log::LevelFilter>,
96}
97
98/// A simulated Host.
99pub struct Host {
100    // Store immutable info in an Arc, that we can safely clone into the
101    // ShadowLogger. We can't use a RootedRc here since this needs to be cloned
102    // into the logger thread, which doesn't have access to the Host's Root.
103    //
104    // TODO: Get rid of the enclosing OnceCell and initialize at the point where
105    // the necessary data is available.
106    info: OnceCell<Arc<HostInfo>>,
107
108    // Inside the Host "object graph", we use the Host's Root for RootedRc and RootedRefCells,
109    // giving us atomic-free refcounting and checked borrowing.
110    //
111    // This makes the Host !Sync.
112    root: Root,
113
114    event_queue: Arc<Mutex<EventQueue>>,
115
116    random: RefCell<Xoshiro256PlusPlus>,
117
118    // The router is our subsystem for actively sending, receiving, and routing
119    // packets across our devices and other network hosts while conforming to
120    // the host's configured uplink/downlink bandwidth rates. This is owned
121    // by the host and responsible for moving packets around between the host
122    // and its upstream provider, it is not a physically separate machine in
123    // the traditional sense.
124    router: Arc<Router>,
125
126    // map address to futex objects
127    futex_table: RefCell<FutexTable>,
128
129    // track fcntl locks
130    fcntl_lock_table: RefCell<FcntlLockTable>,
131
132    #[cfg(feature = "perf_timers")]
133    execution_timer: RefCell<PerfTimer>,
134
135    pub params: HostParameters,
136
137    cpu: RefCell<Cpu>,
138
139    net_ns: NetworkNamespace,
140
141    // Store as a CString so that we can return a borrowed pointer to C code
142    // instead of having to allocate a new string.
143    //
144    // TODO: Remove `data_dir_path_cstring` once we can remove `host_getDataPath`. (Or maybe don't
145    // store it at all)
146    data_dir_path: PathBuf,
147    data_dir_path_cstring: CString,
148
149    // virtual process and event id counter
150    thread_id_counter: Cell<libc::pid_t>,
151    event_id_counter: Cell<u64>,
152    packet_id_counter: Cell<u64>,
153
154    // Enables us to sort objects deterministically based on their creation order.
155    determinism_sequence_counter: Cell<u64>,
156
157    // track the order in which the application sent us application data
158    packet_priority_counter: Cell<FifoPacketPriority>,
159
160    // Owned pointers to processes.
161    processes: RefCell<BTreeMap<ProcessId, RootedRc<RootedRefCell<Process>>>>,
162
163    tsc: Tsc,
164    // Cached lock for shim_shmem. `[Host::shmem_lock]` uses unsafe code to give it
165    // a 'static lifetime.
166    // SAFETY:
167    // * This field must not outlive `shim_shmem`. We achieve this by:
168    //   * Declaring this field before `shim_shmem` so that it's dropped before
169    //   it.
170    //   * We never expose the guard itself via non-unsafe interfaces. e.g.  our
171    //   safe interfaces don't allow access to the guard itself, nor to the
172    //   internal data with a lifetime that could outlive `self` (and thereby
173    //   `shim_shmem`).
174    shim_shmem_lock:
175        RefCell<Option<UnsafeCell<SelfContainedMutexGuard<'static, HostShmemProtected>>>>,
176    // Shared memory with the shim.
177    //
178    // SAFETY: The data inside HostShmem::protected aliases shim_shmem_lock when
179    // the latter is held.  Even when holding `&mut self` or `self`, if
180    // `shim_shmem_lock` is held we must avoid invalidating it, e.g. by
181    // `std::mem::replace`.
182    //
183    // Note though that we're already prevented from creating another reference
184    // to the data inside `HostShmem::protected` through this field, since
185    // `self.shim_shmem...protected.lock()` will fail if the lock is already
186    // held.
187    shim_shmem: UnsafeCell<ShMemBlock<'static, HostShmem>>,
188
189    in_notify_socket_has_packets: RootedCell<bool>,
190
191    /// Paths to be added to LD_PRELOAD of managed processes.
192    preload_paths: Arc<Vec<PathBuf>>,
193}
194
195/// Host must be `Send`.
196impl crate::utility::IsSend for Host {}
197
198// TODO: use derive(Debug) if/when all fields implement Debug.
199impl std::fmt::Debug for Host {
200    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
201        f.debug_struct("Host")
202            .field("info", &self.info)
203            .finish_non_exhaustive()
204    }
205}
206
207impl Host {
208    pub fn new(
209        params: HostParameters,
210        host_root_path: &Path,
211        raw_cpu_freq_khz: u64,
212        manager_shmem: &ShMemBlock<ManagerShmem>,
213        preload_paths: Arc<Vec<PathBuf>>,
214    ) -> Self {
215        #[cfg(feature = "perf_timers")]
216        let execution_timer = RefCell::new(PerfTimer::new_started());
217
218        let root = Root::new();
219        let random = RefCell::new(Xoshiro256PlusPlus::seed_from_u64(params.node_seed));
220        let cpu = RefCell::new(Cpu::new(
221            params.cpu_frequency,
222            raw_cpu_freq_khz,
223            params.cpu_threshold,
224            params.cpu_precision,
225        ));
226        let data_dir_path = Self::make_data_dir_path(&params.hostname, host_root_path);
227        let data_dir_path_cstring = utility::pathbuf_to_nul_term_cstring(data_dir_path.clone());
228
229        let host_shmem = HostShmem::new(
230            params.id,
231            params.model_unblocked_syscall_latency,
232            params.max_unapplied_cpu_latency,
233            params.unblocked_syscall_latency,
234            params.unblocked_vdso_latency,
235            nix::unistd::getpid().as_raw(),
236            params.native_tsc_frequency,
237            params.shim_log_level,
238            manager_shmem,
239        );
240        let shim_shmem = UnsafeCell::new(shadow_shmem::allocator::shmalloc(host_shmem));
241
242        // Process IDs start at 1000
243        let thread_id_counter = Cell::new(1000);
244        let event_id_counter = Cell::new(0);
245        let packet_id_counter = Cell::new(0);
246        let determinism_sequence_counter = Cell::new(0);
247        // Packet priorities start at 1. "0" is used for control packets.
248        let packet_priority_counter = Cell::new(1);
249        let tsc = Tsc::new(params.native_tsc_frequency);
250
251        std::fs::create_dir_all(&data_dir_path).unwrap();
252
253        // Register using the param hints.
254        // We already checked that the addresses are available, so fail if they are not.
255
256        let public_ip: Ipv4Addr = u32::from_be(params.ip_addr).into();
257
258        let pcap_options = params.pcap_config.as_ref().map(|x| PcapOptions {
259            path: data_dir_path.clone(),
260            capture_size_bytes: x.capture_size.try_into().unwrap(),
261        });
262
263        let net_ns = NetworkNamespace::new(public_ip, pcap_options, params.qdisc);
264
265        let inet_tx_rate = RateLimit::BytesPerSecond(params.requested_bw_up_bits / 8);
266        let inet_rx_rate = RateLimit::BytesPerSecond(params.requested_bw_down_bits / 8);
267
268        // Note: our rate limit configs below are meant to match the previous
269        // router/relay design where we popped packets from the netif according
270        // to the upstream rate limit, and we popped packets from the CoDel
271        // queue according to the downstream rate limit. For now, we mimic that
272        // same behavior within the new router design, but a future commit will
273        // change this behavior to model device rates separate from
274        // up/downstream rates.
275        let mut router = Router::new(RateLimit::Unlimited, inet_rx_rate);
276
277        // Now install routes and rate limits for our packet devices.
278        // TODO: add new shadow config options if we want to allow users to
279        // restrict the rate of these device independent of the global
280        // upstream and downstream rates we configure in Router::new().
281
282        // The localhost/loopback interface.
283        router.attach_packet_device(
284            net_ns.localhost.borrow().get_address(),
285            RateLimit::Unlimited,
286            RateLimit::Unlimited,
287        );
288        // The default network-facing interface.
289        router.attach_packet_device(
290            net_ns.internet.borrow().get_address(),
291            inet_tx_rate, // See note above
292            RateLimit::Unlimited,
293        );
294
295        let in_notify_socket_has_packets = RootedCell::new(&root, false);
296
297        let res = Self {
298            info: OnceCell::new(),
299            root,
300            event_queue: Arc::new(Mutex::new(EventQueue::new())),
301            params,
302            router: Arc::new(router),
303            futex_table: RefCell::new(FutexTable::new()),
304            fcntl_lock_table: RefCell::new(FcntlLockTable::new()),
305            random,
306            shim_shmem,
307            shim_shmem_lock: RefCell::new(None),
308            cpu,
309            net_ns,
310            data_dir_path,
311            data_dir_path_cstring,
312            thread_id_counter,
313            event_id_counter,
314            packet_id_counter,
315            packet_priority_counter,
316            determinism_sequence_counter,
317            tsc,
318            processes: RefCell::new(BTreeMap::new()),
319            #[cfg(feature = "perf_timers")]
320            execution_timer,
321            in_notify_socket_has_packets,
322            preload_paths,
323        };
324
325        res.stop_execution_timer();
326
327        debug!(
328            concat!(
329                "Setup host id '{:?}'",
330                " name '{name}'",
331                " with seed {seed},",
332                " {bw_up_kiBps} bwUpKiBps,",
333                " {bw_down_kiBps} bwDownKiBps,",
334                " {init_sock_send_buf_size} initSockSendBufSize,",
335                " {init_sock_recv_buf_size} initSockRecvBufSize, ",
336                " {cpu_frequency:?} cpuFrequency, ",
337                " {cpu_threshold:?} cpuThreshold, ",
338                " {cpu_precision:?} cpuPrecision"
339            ),
340            res.id(),
341            name = res.info().name,
342            seed = res.params.node_seed,
343            bw_up_kiBps = res.bw_up_kiBps(),
344            bw_down_kiBps = res.bw_down_kiBps(),
345            init_sock_send_buf_size = res.params.init_sock_send_buf_size,
346            init_sock_recv_buf_size = res.params.init_sock_recv_buf_size,
347            cpu_frequency = res.params.cpu_frequency,
348            cpu_threshold = res.params.cpu_threshold,
349            cpu_precision = res.params.cpu_precision,
350        );
351
352        res
353    }
354
355    pub fn root(&self) -> &Root {
356        &self.root
357    }
358
359    fn make_data_dir_path(hostname: &CStr, host_root_path: &Path) -> PathBuf {
360        let hostname: OsString = { OsString::from_vec(hostname.to_bytes().to_vec()) };
361
362        let mut data_dir_path = PathBuf::new();
363        data_dir_path.push(host_root_path);
364        data_dir_path.push(&hostname);
365        data_dir_path
366    }
367
368    pub fn data_dir_path(&self) -> &Path {
369        &self.data_dir_path
370    }
371
372    pub fn add_application(
373        &self,
374        start_time: SimulationTime,
375        shutdown_time: Option<SimulationTime>,
376        shutdown_signal: nix::sys::signal::Signal,
377        plugin_name: CString,
378        plugin_path: CString,
379        argv: Vec<CString>,
380        envv: Vec<CString>,
381        pause_for_debugging: bool,
382        expected_final_state: ProcessFinalState,
383    ) {
384        debug_assert!(shutdown_time.is_none() || shutdown_time.unwrap() > start_time);
385
386        // Schedule spawning the process.
387        let task = TaskRef::new(move |host| {
388            // We can't move out of these captured variables, since TaskRef takes
389            // a Fn, not a FnOnce.
390            // TODO: Add support for FnOnce?
391            let envv = envv.clone();
392            let argv = argv.clone();
393
394            let process = Process::spawn(
395                host,
396                plugin_name.clone(),
397                &plugin_path,
398                argv,
399                envv,
400                pause_for_debugging,
401                host.params.strace_logging_options,
402                expected_final_state,
403            )
404            .unwrap_or_else(|e| panic!("Failed to initialize application {plugin_name:?}: {e:?}"));
405            let (process_id, thread_id) = {
406                let process = process.borrow(host.root());
407                (process.id(), process.thread_group_leader_id())
408            };
409            host.processes.borrow_mut().insert(process_id, process);
410
411            if let Some(shutdown_time) = shutdown_time {
412                let task = TaskRef::new(move |host| {
413                    let Some(process) = host.process_borrow(process_id) else {
414                        debug!(
415                            "Can't send shutdown signal to process {process_id}; it no longer exists"
416                        );
417                        return;
418                    };
419                    let process = process.borrow(host.root());
420                    let siginfo = siginfo_t::new_for_kill(
421                        Signal::try_from(shutdown_signal as i32).unwrap(),
422                        1,
423                        0,
424                    );
425                    process.signal(host, None, &siginfo);
426                });
427                host.schedule_task_at_emulated_time(
428                    task,
429                    EmulatedTime::SIMULATION_START + shutdown_time,
430                );
431            }
432
433            host.resume(process_id, thread_id);
434        });
435        self.schedule_task_at_emulated_time(task, EmulatedTime::SIMULATION_START + start_time);
436    }
437
438    pub fn add_and_schedule_forked_process(
439        &self,
440        host: &Host,
441        process: RootedRc<RootedRefCell<Process>>,
442    ) {
443        let (process_id, thread_id) = {
444            let process = process.borrow(&self.root);
445            (process.id(), process.thread_group_leader_id())
446        };
447        host.processes.borrow_mut().insert(process_id, process);
448        // Schedule process to run.
449        let task = TaskRef::new(move |host| {
450            host.resume(process_id, thread_id);
451        });
452        self.schedule_task_with_delay(task, SimulationTime::ZERO);
453    }
454
455    pub fn resume(&self, pid: ProcessId, tid: ThreadId) {
456        let Some(processrc) = self
457            .process_borrow(pid)
458            .map(|p| RootedRc::clone(&p, &self.root))
459        else {
460            trace!("{pid:?} doesn't exist");
461            return;
462        };
463        let processrc = ExplicitDropper::new(processrc, |p| {
464            p.explicit_drop_recursive(&self.root, self);
465        });
466        let died;
467        let is_orphan;
468        {
469            Worker::set_active_process(&processrc);
470            let process = processrc.borrow(self.root());
471            process.resume(self, tid);
472            Worker::clear_active_process();
473            let zombie_state = process.borrow_as_zombie();
474            if let Some(zombie) = zombie_state {
475                died = true;
476                is_orphan = zombie.reaper(self).is_none();
477            } else {
478                died = false;
479                is_orphan = false;
480            }
481        };
482
483        if !died {
484            return;
485        }
486
487        let child_pids: Vec<_> = self
488            .processes
489            .borrow()
490            .iter()
491            .filter_map(|(other_pid, processrc)| {
492                let process = processrc.borrow(&self.root);
493                if process.parent_id() != pid {
494                    // Not a child of the current process
495                    return None;
496                }
497                Some(*other_pid)
498            })
499            .collect();
500
501        // Reparent children, and collect IDs of children that are dead. Deliver
502        // parent-death signals before reparenting so the old parent PID is still
503        // reported in the siginfo payload. Since Shadow tracks parentage at the
504        // process level, this models parent-process death rather than the more
505        // specific parent-thread behavior Linux implements.
506        let mut orphaned_zombie_pids: Vec<ProcessId> = Vec::new();
507        for child_pid in child_pids {
508            let parent_death_signal = {
509                let Some(processrc) = self.process_borrow(child_pid) else {
510                    continue;
511                };
512                let process = processrc.borrow(&self.root);
513                process.parent_death_signal()
514            };
515
516            if let Some(signal) = parent_death_signal {
517                let siginfo = siginfo_t::new_for_kill(signal, pid.into(), 0);
518                let Some(processrc) = self.process_borrow(child_pid) else {
519                    continue;
520                };
521                let process = processrc.borrow(&self.root);
522                process.signal(self, None, &siginfo);
523            }
524
525            let is_zombie = {
526                let Some(processrc) = self.process_borrow(child_pid) else {
527                    continue;
528                };
529                let process = processrc.borrow(&self.root);
530                process.set_parent_id(ProcessId::INIT);
531                process.borrow_as_zombie().is_some()
532            };
533            if is_zombie {
534                orphaned_zombie_pids.push(child_pid);
535            }
536        }
537
538        // Process we ran is a zombie; is it also an orphan?
539        debug_assert!(died);
540        if is_orphan {
541            orphaned_zombie_pids.push(pid);
542        }
543
544        // Free orphaned zombies.
545        let mut processes = self.processes.borrow_mut();
546        for pid in orphaned_zombie_pids {
547            trace!("Dropping orphan zombie process {pid:?}");
548            let processrc = processes.remove(&pid).unwrap();
549            RootedRc::explicit_drop_recursive(processrc, &self.root, self);
550        }
551    }
552
553    #[track_caller]
554    pub fn process_borrow(
555        &self,
556        id: ProcessId,
557    ) -> Option<impl Deref<Target = RootedRc<RootedRefCell<Process>>> + '_> {
558        Ref::filter_map(self.processes.borrow(), |processes| processes.get(&id)).ok()
559    }
560
561    /// Remove the given process from the Host, if it exists.
562    #[track_caller]
563    pub fn process_remove(&self, id: ProcessId) -> Option<RootedRc<RootedRefCell<Process>>> {
564        self.processes.borrow_mut().remove(&id)
565    }
566
567    /// Borrow the set of processes. Generally this should only be used to
568    /// iterate over the set of processes. e.g. fetching a specific process
569    /// should be done via via `process_borrow`.
570    // TODO: It would be preferable to return an iterator instead of the
571    // collection itself. There has to be an intermediate object though since we
572    // need both the borrowed map of processes, and an iterator that borrows
573    // from that. I suppose we could create an abstract "Iterator factory" and
574    // return that here instead of exposing BTreeMap type.
575    #[track_caller]
576    pub fn processes_borrow(
577        &self,
578    ) -> impl Deref<Target = BTreeMap<ProcessId, RootedRc<RootedRefCell<Process>>>> + '_ {
579        self.processes.borrow()
580    }
581
582    pub fn cpu_borrow(&self) -> impl Deref<Target = Cpu> + '_ {
583        self.cpu.borrow()
584    }
585
586    pub fn cpu_borrow_mut(&self) -> impl DerefMut<Target = Cpu> + '_ {
587        self.cpu.borrow_mut()
588    }
589
590    /// Information about the Host. Made available as an Arc for cheap cloning
591    /// into, e.g. Worker and ShadowLogger. When there's no need to clone the
592    /// Arc, generally prefer the top-level `Host` methods for accessing this
593    /// information, which are likely to be more stable.
594    pub fn info(&self) -> &Arc<HostInfo> {
595        self.info.get_or_init(|| {
596            Arc::new(HostInfo {
597                id: self.id(),
598                name: self.params.hostname.to_str().unwrap().to_owned(),
599                default_ip: self.default_ip(),
600                log_level: self.log_level(),
601            })
602        })
603    }
604
605    pub fn id(&self) -> HostId {
606        self.params.id
607    }
608
609    pub fn name(&self) -> &str {
610        &self.info().name
611    }
612
613    pub fn default_ip(&self) -> Ipv4Addr {
614        self.net_ns.default_ip
615    }
616
617    pub fn abstract_unix_namespace(
618        &self,
619    ) -> impl Deref<Target = Arc<AtomicRefCell<AbstractUnixNamespace>>> + '_ {
620        &self.net_ns.unix
621    }
622
623    pub fn log_level(&self) -> Option<log::LevelFilter> {
624        let level = self.params.log_level;
625        log_c2rust::c_to_rust_log_level(level).map(|l| l.to_level_filter())
626    }
627
628    #[track_caller]
629    pub fn network_namespace_borrow(&self) -> impl Deref<Target = NetworkNamespace> + '_ {
630        &self.net_ns
631    }
632
633    #[track_caller]
634    pub fn futextable_borrow(&self) -> impl Deref<Target = FutexTable> + '_ {
635        self.futex_table.borrow()
636    }
637
638    #[track_caller]
639    pub fn futextable_borrow_mut(&self) -> impl DerefMut<Target = FutexTable> + '_ {
640        self.futex_table.borrow_mut()
641    }
642
643    #[track_caller]
644    pub fn fcntl_lock_table_borrow(&self) -> impl Deref<Target = FcntlLockTable> + '_ {
645        self.fcntl_lock_table.borrow()
646    }
647
648    #[track_caller]
649    pub fn fcntl_lock_table_borrow_mut(&self) -> impl DerefMut<Target = FcntlLockTable> + '_ {
650        self.fcntl_lock_table.borrow_mut()
651    }
652
653    #[allow(non_snake_case)]
654    pub fn bw_up_kiBps(&self) -> u64 {
655        self.params.requested_bw_up_bits / (8 * 1024)
656    }
657
658    #[allow(non_snake_case)]
659    pub fn bw_down_kiBps(&self) -> u64 {
660        self.params.requested_bw_down_bits / (8 * 1024)
661    }
662
663    /// Returns `None` if there is no such interface.
664    ///
665    /// Panics if we have shut down.
666    pub fn interface_borrow_mut(
667        &self,
668        addr: Ipv4Addr,
669    ) -> Option<impl DerefMut<Target = NetworkInterface> + '_> {
670        self.net_ns.interface_borrow_mut(addr)
671    }
672
673    /// Returns `None` if there is no such interface.
674    ///
675    /// Panics if we have shut down.
676    pub fn interface_borrow(
677        &self,
678        addr: Ipv4Addr,
679    ) -> Option<impl Deref<Target = NetworkInterface> + '_> {
680        self.net_ns.interface_borrow(addr)
681    }
682
683    /// Get the packet device that handles packets for the given address. This
684    /// could be the source device from which we forward packets, or the device
685    /// that will receive and process packets with a given destination address.
686    ///
687    /// Returns [`None`] if the host does not have a device for the address.
688    ///
689    /// Panics if we have shut down.
690    fn interface_borrow_as_packet_device(
691        &self,
692        addr: Ipv4Addr,
693    ) -> Option<Ref<'_, dyn PacketDevice>> {
694        self.net_ns.interface_borrow_as_packet_device(addr)
695    }
696
697    /// Run the router to handle the given router event that has occurred.
698    fn run_router(&self, event: RouterEvent) {
699        // Construct the router runtime context.
700        let ctx = RouterContext {
701            now: Worker::current_time().unwrap(),
702            is_bootstrapping: Worker::is_bootstrapping(),
703            send_packet_fn: Worker::send_packet,
704            get_packet_device_fn: Host::interface_borrow_as_packet_device,
705            fn_arg: self,
706        };
707
708        // Run the router to handle the event. If it wants to run again, it will
709        // return the time that we should wake it up.
710        if let Some(next_run_time) = self.router.run(&ctx, event) {
711            let task = TaskRef::new(move |host| {
712                host.run_router(RouterEvent::Wakeup);
713            });
714            self.schedule_task_at_emulated_time(task, next_run_time);
715        }
716    }
717
718    /// Call to trigger the forwarding of packets from the network interface to
719    /// the next hop (either back to the network interface for loopback, or to
720    /// another host for internet-bound packets).
721    ///
722    /// WARNING: This is not reentrant. Do not allow this to be called
723    /// recursively. Nothing in `add_data_source()` can call back into this
724    /// method, including socket code called in any indirect way from here.
725    pub fn notify_socket_has_packets(&self, addr: Ipv4Addr, socket: &InetSocket) {
726        if self.in_notify_socket_has_packets.replace(&self.root, true) {
727            panic!("Recursively calling host.notify_socket_has_packets()");
728        }
729
730        // Notice we carefully drop the borrow before running the router.
731        let iface_addr: Option<Ipv4Addr> = self.interface_borrow(addr).map(|iface| {
732            iface.add_data_source(socket);
733            iface.get_address()
734        });
735
736        if let Some(iface_addr) = iface_addr {
737            // Routing action is required on the interface.
738            self.run_router(RouterEvent::DeviceInterrupt(iface_addr));
739        } else {
740            log::warn!("Interface not found for socket addr {addr}");
741        }
742
743        self.in_notify_socket_has_packets.set(&self.root, false);
744    }
745
746    #[track_caller]
747    pub fn random_mut(&self) -> impl DerefMut<Target = Xoshiro256PlusPlus> + '_ {
748        self.random.borrow_mut()
749    }
750
751    pub fn get_new_event_id(&self) -> u64 {
752        let res = self.event_id_counter.get();
753        self.event_id_counter.set(res + 1);
754        res
755    }
756
757    pub fn get_new_thread_id(&self) -> ThreadId {
758        let res = self.thread_id_counter.get();
759        self.thread_id_counter.set(res + 1);
760        res.try_into().unwrap()
761    }
762
763    pub fn get_new_packet_id(&self) -> u64 {
764        let res = self.packet_id_counter.get();
765        self.packet_id_counter.set(res + 1);
766        res
767    }
768
769    pub fn get_next_deterministic_sequence_value(&self) -> u64 {
770        let res = self.determinism_sequence_counter.get();
771        self.determinism_sequence_counter.set(res + 1);
772        res
773    }
774
775    pub fn get_next_packet_priority(&self) -> FifoPacketPriority {
776        let res = self.packet_priority_counter.get();
777        self.packet_priority_counter
778            .set(res.checked_add(1).unwrap());
779        res
780    }
781
782    pub fn continue_execution_timer(&self) {
783        #[cfg(feature = "perf_timers")]
784        self.execution_timer.borrow_mut().start();
785    }
786
787    pub fn stop_execution_timer(&self) {
788        #[cfg(feature = "perf_timers")]
789        self.execution_timer.borrow_mut().stop();
790    }
791
792    pub fn schedule_task_at_emulated_time(&self, task: TaskRef, t: EmulatedTime) -> bool {
793        let event = Event::new_local(task, t, self);
794        self.push_local_event(event)
795    }
796
797    pub fn schedule_task_with_delay(&self, task: TaskRef, t: SimulationTime) -> bool {
798        self.schedule_task_at_emulated_time(task, Worker::current_time().unwrap() + t)
799    }
800
801    pub fn event_queue(&self) -> &Arc<Mutex<EventQueue>> {
802        &self.event_queue
803    }
804
805    pub fn push_local_event(&self, event: Event) -> bool {
806        if event.time() >= self.params.sim_end_time {
807            return false;
808        }
809        self.event_queue.lock().unwrap().push(event);
810        true
811    }
812
813    /// Shut down the host. This should be called while `Worker` has the active host set.
814    pub fn shutdown(&self) {
815        self.continue_execution_timer();
816
817        debug!("shutting down host {}", self.name());
818
819        // the network namespace object needs to be cleaned up before it's dropped
820        self.net_ns.cleanup();
821
822        assert!(self.processes.borrow().is_empty());
823
824        self.stop_execution_timer();
825        #[cfg(feature = "perf_timers")]
826        debug!(
827            "host '{}' has been shut down, total execution time was {:?}",
828            self.name(),
829            self.execution_timer.borrow().elapsed()
830        );
831    }
832
833    pub fn free_all_applications(&self) {
834        trace!("start freeing applications for host '{}'", self.name());
835        let processes = std::mem::take(&mut *self.processes.borrow_mut());
836        for (_id, processrc) in processes.into_iter() {
837            let processrc = ExplicitDropper::new(processrc, |p| {
838                p.explicit_drop_recursive(self.root(), self);
839            });
840            Worker::set_active_process(&processrc);
841            let process = processrc.borrow(self.root());
842            process.stop(self);
843            Worker::clear_active_process();
844            // Reparent to Shadow/INIT, since the original parent is or is
845            // about to be dead.
846            process.set_parent_id(ProcessId::INIT);
847        }
848        trace!("done freeing application for host '{}'", self.name());
849    }
850
851    pub fn execute(&self, until: EmulatedTime) {
852        loop {
853            let mut event = {
854                let mut event_queue = self.event_queue.lock().unwrap();
855                match event_queue.next_event_time() {
856                    Some(t) if t < until => {}
857                    _ => break,
858                };
859                event_queue.pop().unwrap()
860            };
861
862            {
863                let mut cpu = self.cpu.borrow_mut();
864                cpu.update_time(event.time());
865                let cpu_delay = cpu.delay();
866                if cpu_delay > SimulationTime::ZERO {
867                    trace!("event blocked on CPU, rescheduled for {cpu_delay:?} from now");
868
869                    // reschedule the event after the CPU delay time
870                    event.set_time(event.time() + cpu_delay);
871                    self.push_local_event(event);
872
873                    // want to continue pushing back events until we reach the delay time
874                    continue;
875                }
876            }
877
878            // run the event
879            Worker::set_current_time(event.time());
880            self.continue_execution_timer();
881            match event.data() {
882                EventData::Packet(data) => self.run_router(RouterEvent::PacketArrival(data.into())),
883                EventData::Local(data) => TaskRef::from(data).execute(self),
884            }
885            self.stop_execution_timer();
886            Worker::clear_current_time();
887        }
888    }
889
890    pub fn next_event_time(&self) -> Option<EmulatedTime> {
891        self.event_queue.lock().unwrap().next_event_time()
892    }
893
894    /// The unprotected part of the Host's shared memory.
895    ///
896    /// Do not try to take the lock of [`HostShmem::protected`] directly.
897    /// Instead use [`Host::lock_shmem`], [`Host::shim_shmem_lock_borrow`], and
898    /// [`Host::shim_shmem_lock_borrow_mut`].
899    pub fn shim_shmem(&self) -> &ShMemBlock<'static, HostShmem> {
900        unsafe { &*self.shim_shmem.get() }
901    }
902
903    /// Returns the specified thread if it exists. If you already have the thread's process,
904    /// [`Process::thread_borrow`] may be more efficient.
905    pub fn thread_cloned_rc(
906        &self,
907        virtual_tid: ThreadId,
908    ) -> Option<RootedRc<RootedRefCell<Thread>>> {
909        for process in self.processes.borrow().values() {
910            let process = process.borrow(self.root());
911            if let Some(thread) = process.thread_borrow(virtual_tid) {
912                return Some(RootedRc::clone(&*thread, self.root()));
913            };
914        }
915
916        None
917    }
918
919    /// Returns `true` if the host has a process that contains the specified thread.
920    pub fn has_thread(&self, virtual_tid: ThreadId) -> bool {
921        for process in self.processes.borrow().values() {
922            let process = process.borrow(self.root());
923            if process.thread_borrow(virtual_tid).is_some() {
924                return true;
925            }
926        }
927
928        false
929    }
930
931    /// Locks the Host's shared memory, caching the lock internally.
932    ///
933    /// Dropping the Host before calling [`Host::unlock_shmem`] will panic.
934    ///
935    /// TODO: Consider removing this API once we don't need to cache the lock for the C API.
936    pub fn lock_shmem(&self) {
937        // We're extending this lifetime to extend the lifetime of `lock`, below, without
938        // having to `transmute` the type itself.
939        //
940        // SAFETY:
941        // * We ensure that `self.shim_shmem_lock` doesn't outlive `self.shim_shmem`.
942        //   See SAFETY requirements on Self::shim_shmem_lock itself.
943        // * We never mutate `self.shim_shmem` nor borrow the internals of
944        //   `self.shim_shmem.protected` while the lock is held, since that would
945        //   conflict with the cached guard's mutable reference.
946        // * `ShMemBlock` guarantees that its data doesn't move even if the block does.
947        //    So moving `shim_shmem` (e.g. by moving `self`) doesn't invalidate the lock.
948        let shim_shmem: &'static ShMemBlock<HostShmem> =
949            unsafe { self.shim_shmem.get().as_ref().unwrap() };
950        let lock = shim_shmem.protected().lock();
951        let prev = self
952            .shim_shmem_lock
953            .borrow_mut()
954            .replace(UnsafeCell::new(lock));
955        assert!(prev.is_none());
956    }
957
958    /// Panics if there is still an outstanding reference returned by
959    /// `shim_shmem_lock_borrow` or `shim_shmem_lock_borrow_mut`.
960    pub fn unlock_shmem(&self) {
961        let prev = self.shim_shmem_lock.borrow_mut().take();
962        assert!(prev.is_some());
963    }
964
965    pub fn shim_shmem_lock_borrow(&self) -> Option<impl Deref<Target = HostShmemProtected> + '_> {
966        Ref::filter_map(self.shim_shmem_lock.borrow(), |l| {
967            l.as_ref().map(|l| {
968                // SAFETY: Returned object holds a checked borrow of the lock;
969                // trying to release the lock before the returned object is
970                // dropped will result in a panic.
971                let guard = unsafe { &*l.get() };
972                guard.deref()
973            })
974        })
975        .ok()
976    }
977
978    pub fn shim_shmem_lock_borrow_mut(
979        &self,
980    ) -> Option<impl DerefMut<Target = HostShmemProtected> + '_> {
981        RefMut::filter_map(self.shim_shmem_lock.borrow_mut(), |l| {
982            l.as_ref().map(|l| {
983                // SAFETY: Returned object holds a checked borrow of the lock;
984                // trying to release the lock before the returned object is
985                // dropped will result in a panic.
986                let guard = unsafe { &mut *l.get() };
987                guard.deref_mut()
988            })
989        })
990        .ok()
991    }
992
993    /// Timestamp Counter emulation for this Host. It ticks at the same rate as
994    /// the native Timestamp Counter, if we were able to find it.
995    pub fn tsc(&self) -> &Tsc {
996        &self.tsc
997    }
998
999    /// Returns the Session ID for the given process group ID, if it exists.
1000    pub fn process_session_id_of_group_id(&self, group_id: ProcessId) -> Option<ProcessId> {
1001        let processes = self.processes.borrow();
1002        for processrc in processes.values() {
1003            let process = processrc.borrow(&self.root);
1004            if process.group_id() == group_id {
1005                return Some(process.session_id());
1006            }
1007        }
1008        None
1009    }
1010
1011    /// Paths of libraries that should be preloaded into managed processes.
1012    pub fn preload_paths(&self) -> &[PathBuf] {
1013        &self.preload_paths
1014    }
1015}
1016
1017impl Drop for Host {
1018    fn drop(&mut self) {
1019        // Validate that the shmem lock isn't held, which would potentially
1020        // violate the SAFETY argument in `lock_shmem`. (AFAIK Rust makes no formal
1021        // guarantee about the order in which fields are dropped)
1022        assert!(self.shim_shmem_lock.borrow().is_none());
1023    }
1024}
1025
1026mod export {
1027    use std::{os::raw::c_char, time::Duration};
1028
1029    use libc::{in_addr_t, in_port_t};
1030    use rand::{Rng, RngExt};
1031    use shadow_shim_helper_rs::shim_shmem;
1032
1033    use super::*;
1034    use crate::cshadow::{CEmulatedTime, CSimulationTime};
1035    use crate::network::packet::IanaProtocol;
1036
1037    #[unsafe(no_mangle)]
1038    pub unsafe extern "C-unwind" fn host_execute(hostrc: *const Host, until: CEmulatedTime) {
1039        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1040        let until = EmulatedTime::from_c_emutime(until).unwrap();
1041        hostrc.execute(until)
1042    }
1043
1044    #[unsafe(no_mangle)]
1045    pub unsafe extern "C-unwind" fn host_nextEventTime(hostrc: *const Host) -> CEmulatedTime {
1046        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1047        EmulatedTime::to_c_emutime(hostrc.next_event_time())
1048    }
1049
1050    #[unsafe(no_mangle)]
1051    pub unsafe extern "C-unwind" fn host_getNewPacketID(hostrc: *const Host) -> u64 {
1052        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1053        hostrc.get_new_packet_id()
1054    }
1055
1056    #[unsafe(no_mangle)]
1057    pub unsafe extern "C-unwind" fn host_freeAllApplications(hostrc: *const Host) {
1058        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1059        hostrc.free_all_applications()
1060    }
1061
1062    #[unsafe(no_mangle)]
1063    pub unsafe extern "C-unwind" fn host_getID(hostrc: *const Host) -> HostId {
1064        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1065        hostrc.id()
1066    }
1067
1068    /// SAFETY: The returned pointer belongs to Host, and is invalidated when
1069    /// `host` is moved or freed.
1070    #[unsafe(no_mangle)]
1071    pub unsafe extern "C-unwind" fn host_getTsc(host: *const Host) -> *const Tsc {
1072        let hostrc = unsafe { host.as_ref().unwrap() };
1073        hostrc.tsc()
1074    }
1075
1076    #[unsafe(no_mangle)]
1077    pub unsafe extern "C-unwind" fn host_getName(hostrc: *const Host) -> *const c_char {
1078        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1079        hostrc.params.hostname.as_ptr()
1080    }
1081
1082    #[unsafe(no_mangle)]
1083    pub unsafe extern "C-unwind" fn host_getDefaultIP(hostrc: *const Host) -> in_addr_t {
1084        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1085        let ip = hostrc.default_ip();
1086        u32::from(ip).to_be()
1087    }
1088
1089    #[unsafe(no_mangle)]
1090    pub unsafe extern "C-unwind" fn host_getNextPacketPriority(
1091        hostrc: *const Host,
1092    ) -> FifoPacketPriority {
1093        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1094        hostrc.get_next_packet_priority()
1095    }
1096
1097    #[unsafe(no_mangle)]
1098    pub unsafe extern "C-unwind" fn host_autotuneReceiveBuffer(hostrc: *const Host) -> bool {
1099        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1100        hostrc.params.autotune_recv_buf
1101    }
1102
1103    #[unsafe(no_mangle)]
1104    pub unsafe extern "C-unwind" fn host_autotuneSendBuffer(hostrc: *const Host) -> bool {
1105        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1106        hostrc.params.autotune_send_buf
1107    }
1108
1109    #[unsafe(no_mangle)]
1110    pub unsafe extern "C-unwind" fn host_getConfiguredRecvBufSize(hostrc: *const Host) -> u64 {
1111        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1112        hostrc.params.init_sock_recv_buf_size
1113    }
1114
1115    #[unsafe(no_mangle)]
1116    pub unsafe extern "C-unwind" fn host_getConfiguredSendBufSize(hostrc: *const Host) -> u64 {
1117        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1118        hostrc.params.init_sock_send_buf_size
1119    }
1120
1121    #[unsafe(no_mangle)]
1122    pub unsafe extern "C-unwind" fn host_get_bw_down_kiBps(hostrc: *const Host) -> u64 {
1123        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1124        hostrc.bw_down_kiBps()
1125    }
1126
1127    #[unsafe(no_mangle)]
1128    pub unsafe extern "C-unwind" fn host_get_bw_up_kiBps(hostrc: *const Host) -> u64 {
1129        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1130        hostrc.bw_up_kiBps()
1131    }
1132
1133    /// SAFETY: The returned pointer is owned by the Host, and will be invalidated when
1134    /// the Host is destroyed, and possibly when it is otherwise moved or mutated.
1135    #[unsafe(no_mangle)]
1136    pub unsafe extern "C-unwind" fn host_getDataPath(hostrc: *const Host) -> *const c_char {
1137        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1138        hostrc.data_dir_path_cstring.as_ptr()
1139    }
1140
1141    #[unsafe(no_mangle)]
1142    pub unsafe extern "C-unwind" fn host_disassociateInterface(
1143        hostrc: *const Host,
1144        c_protocol: cshadow::ProtocolType,
1145        bind_ip: in_addr_t,
1146        bind_port: in_port_t,
1147        peer_ip: in_addr_t,
1148        peer_port: in_port_t,
1149    ) {
1150        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1151
1152        let bind_ip = Ipv4Addr::from(u32::from_be(bind_ip));
1153        let peer_ip = Ipv4Addr::from(u32::from_be(peer_ip));
1154        let bind_port = u16::from_be(bind_port);
1155        let peer_port = u16::from_be(peer_port);
1156
1157        let bind_addr = SocketAddrV4::new(bind_ip, bind_port);
1158        let peer_addr = SocketAddrV4::new(peer_ip, peer_port);
1159
1160        let protocol = IanaProtocol::from(c_protocol);
1161
1162        // associate the interfaces corresponding to bind_addr with socket
1163        hostrc
1164            .net_ns
1165            .disassociate_interface(protocol, bind_addr, peer_addr);
1166    }
1167
1168    #[unsafe(no_mangle)]
1169    pub unsafe extern "C-unwind" fn host_getRandomFreePort(
1170        hostrc: *const Host,
1171        c_protocol: cshadow::ProtocolType,
1172        interface_ip: in_addr_t,
1173        peer_ip: in_addr_t,
1174        peer_port: in_port_t,
1175    ) -> in_port_t {
1176        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1177
1178        let interface_ip = Ipv4Addr::from(u32::from_be(interface_ip));
1179        let peer_addr = SocketAddrV4::new(
1180            Ipv4Addr::from(u32::from_be(peer_ip)),
1181            u16::from_be(peer_port),
1182        );
1183
1184        let protocol = IanaProtocol::from(c_protocol);
1185
1186        hostrc
1187            .net_ns
1188            .get_random_free_port(
1189                protocol,
1190                interface_ip,
1191                peer_addr,
1192                hostrc.random.borrow_mut().deref_mut(),
1193            )
1194            .unwrap_or(0)
1195            .to_be()
1196    }
1197
1198    /// Returns a pointer to the Host's FutexTable.
1199    ///
1200    /// SAFETY: The returned pointer belongs to and is synchronized by the Host,
1201    /// and is invalidated when the Host is no longer accessible to the current
1202    /// thread, or something else accesses its FutexTable.
1203    #[unsafe(no_mangle)]
1204    pub unsafe extern "C-unwind" fn host_getFutexTable(hostrc: *const Host) -> *mut FutexTable {
1205        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1206        &mut *hostrc.futextable_borrow_mut()
1207    }
1208
1209    /// Returns the specified process, or NULL if it doesn't exist.
1210    #[unsafe(no_mangle)]
1211    pub unsafe extern "C-unwind" fn host_getProcess(
1212        host: *const Host,
1213        virtual_pid: libc::pid_t,
1214    ) -> *const Process {
1215        let host = unsafe { host.as_ref().unwrap() };
1216        let virtual_pid = ProcessId::try_from(virtual_pid).unwrap();
1217        host.process_borrow(virtual_pid)
1218            .map(|x| std::ptr::from_ref(&*x.borrow(host.root())))
1219            .unwrap_or(std::ptr::null_mut())
1220    }
1221
1222    /// Returns the specified thread, or NULL if it doesn't exist.
1223    /// If you already have the thread's Process*, `process_getThread` may be more
1224    /// efficient.
1225    ///
1226    /// # Safety
1227    ///
1228    /// The pointer should not be accessed from threads other than the calling thread,
1229    /// or after `host` is no longer active on the current thread.
1230    #[unsafe(no_mangle)]
1231    pub unsafe extern "C-unwind" fn host_getThread(
1232        host: *const Host,
1233        virtual_tid: libc::pid_t,
1234    ) -> *const Thread {
1235        let host = unsafe { host.as_ref().unwrap() };
1236        let tid = ThreadId::try_from(virtual_tid).unwrap();
1237        for process in host.processes.borrow().values() {
1238            let process = process.borrow(host.root());
1239            if let Some(thread) = process.thread_borrow(tid) {
1240                // We're returning a pointer to the Thread itself after having
1241                // dropped the borrow. In addition to the requirements noted for the calling code,
1242                // this could cause soundness issues if we were to ever take mutable borrows of
1243                // the RootedRefCell, since it'd be difficult to ensure we didn't have any simultaneous
1244                // additional references from dereferencing a C pointer.
1245                //
1246                // TODO: Add a variant of RootedRefCell that doesn't allow
1247                // mutable borrows, use it for Thread, and name that type
1248                // explicitly here to ensure a compilation error if the type is
1249                // changed again to one that would allow mutable references.
1250                let thread = thread.borrow(host.root());
1251                return std::ptr::from_ref(&*thread);
1252            };
1253        }
1254        std::ptr::null_mut()
1255    }
1256
1257    /// Returns the lock, or panics if the lock isn't held by Shadow.
1258    ///
1259    /// Generally the lock can and should be held when Shadow is running, and *not*
1260    /// held when any of the host's managed threads are running (leaving it available
1261    /// to be taken by the shim). While this can be a little fragile to ensure
1262    /// properly, debug builds detect if we get it wrong (e.g. we try accessing
1263    /// protected data without holding the lock, or the shim tries to take the lock
1264    /// but can't).
1265    ///
1266    /// SAFETY: The returned pointer is invalidated when the memory is unlocked, e.g.
1267    /// via `host_unlockShimShmemLock`.
1268    #[unsafe(no_mangle)]
1269    pub unsafe extern "C-unwind" fn host_getShimShmemLock(
1270        hostrc: *const Host,
1271    ) -> *mut shim_shmem::export::ShimShmemHostLock {
1272        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1273        let mut opt_lock = hostrc.shim_shmem_lock.borrow_mut();
1274        let lock = opt_lock.as_mut().unwrap();
1275        // SAFETY: The caller is responsible for not accessing the returned pointer
1276        // after the lock has been released.
1277        unsafe { lock.get().as_mut().unwrap().deref_mut() }
1278    }
1279
1280    /// Take the host's shared memory lock. See `host_getShimShmemLock`.
1281    #[unsafe(no_mangle)]
1282    pub unsafe extern "C-unwind" fn host_lockShimShmemLock(hostrc: *const Host) {
1283        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1284        hostrc.lock_shmem()
1285    }
1286
1287    /// Release the host's shared memory lock. See `host_getShimShmemLock`.
1288    #[unsafe(no_mangle)]
1289    pub unsafe extern "C-unwind" fn host_unlockShimShmemLock(hostrc: *const Host) {
1290        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1291        hostrc.unlock_shmem()
1292    }
1293
1294    /// Returns the next value and increments our monotonically increasing
1295    /// determinism sequence counter. The resulting values can be sorted to
1296    /// established a deterministic ordering, which can be useful when iterating
1297    /// items that are otherwise inconsistently ordered (e.g. hash table iterators).
1298    #[unsafe(no_mangle)]
1299    pub unsafe extern "C-unwind" fn host_getNextDeterministicSequenceValue(
1300        hostrc: *const Host,
1301    ) -> u64 {
1302        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1303        hostrc.get_next_deterministic_sequence_value()
1304    }
1305
1306    /// Schedule a task for this host at time 'time'.
1307    #[unsafe(no_mangle)]
1308    pub unsafe extern "C-unwind" fn host_scheduleTaskAtEmulatedTime(
1309        hostrc: *const Host,
1310        task: *mut TaskRef,
1311        time: CEmulatedTime,
1312    ) -> bool {
1313        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1314        let task = unsafe { task.as_ref().unwrap().clone() };
1315        let time = EmulatedTime::from_c_emutime(time).unwrap();
1316        hostrc.schedule_task_at_emulated_time(task, time)
1317    }
1318
1319    /// Schedule a task for this host at a time 'nanoDelay' from now,.
1320    #[unsafe(no_mangle)]
1321    pub unsafe extern "C-unwind" fn host_scheduleTaskWithDelay(
1322        hostrc: *const Host,
1323        task: *mut TaskRef,
1324        delay: CSimulationTime,
1325    ) -> bool {
1326        let hostrc = unsafe { hostrc.as_ref().unwrap() };
1327        let task = unsafe { task.as_ref().unwrap().clone() };
1328        let delay = SimulationTime::from_c_simtime(delay).unwrap();
1329        hostrc.schedule_task_with_delay(task, delay)
1330    }
1331
1332    #[unsafe(no_mangle)]
1333    pub unsafe extern "C-unwind" fn host_rngDouble(host: *const Host) -> f64 {
1334        let host = unsafe { host.as_ref().unwrap() };
1335        host.random_mut().random()
1336    }
1337
1338    /// Fills the buffer with pseudo-random bytes.
1339    #[unsafe(no_mangle)]
1340    pub extern "C-unwind" fn host_rngNextNBytes(host: *const Host, buf: *mut u8, len: usize) {
1341        let host = unsafe { host.as_ref().unwrap() };
1342        let buf = unsafe { std::slice::from_raw_parts_mut(buf, len) };
1343        host.random_mut().fill_bytes(buf);
1344    }
1345
1346    #[unsafe(no_mangle)]
1347    pub extern "C-unwind" fn host_paramsCpuFrequencyHz(host: *const Host) -> u64 {
1348        let host = unsafe { host.as_ref().unwrap() };
1349        host.params.cpu_frequency
1350    }
1351
1352    #[unsafe(no_mangle)]
1353    pub extern "C-unwind" fn host_addDelayNanos(host: *const Host, delay_nanos: u64) {
1354        let host = unsafe { host.as_ref().unwrap() };
1355        let delay = Duration::from_nanos(delay_nanos);
1356        host.cpu.borrow_mut().add_delay(delay);
1357    }
1358
1359    #[unsafe(no_mangle)]
1360    pub unsafe extern "C-unwind" fn host_socketWantsToSend(
1361        hostrc: *const Host,
1362        socket: *const InetSocket,
1363        addr: in_addr_t,
1364    ) {
1365        let host = unsafe { hostrc.as_ref().unwrap() };
1366        let socket = unsafe { socket.as_ref().unwrap() };
1367        let addr = u32::from_be(addr).into();
1368        host.notify_socket_has_packets(addr, socket);
1369    }
1370
1371    #[unsafe(no_mangle)]
1372    pub unsafe extern "C-unwind" fn host_continue(
1373        host: *const Host,
1374        pid: libc::pid_t,
1375        tid: libc::pid_t,
1376    ) {
1377        let host = unsafe { host.as_ref().unwrap() };
1378        host.resume(pid.try_into().unwrap(), tid.try_into().unwrap())
1379    }
1380}