Use page tracking for snapshot and restore

docs/signal-handlers-development-notes.md

@@ -1,11 +1,12 @@
 # Signal Handling in Hyperlight
 
-Hyperlight registers custom signal handlers to intercept and manage specific signals, primarily `SIGSYS` and `SIGRTMIN`. Here's an overview of the registration process:
-- **Preserving Old Handlers**: When registering a new signal handler, Hyperlight first retrieves and stores the existing handler using `OnceCell`. This allows Hyperlight to delegate signals to the original handler if necessary.
--  **Custom Handlers**:
-  - **`SIGSYS` Handler**: Captures disallowed syscalls enforced by seccomp. If the signal originates from a hyperlight thread, Hyperlight logs the syscall details. Otherwise, it delegates the signal to the previously registered handler. 
-  - **`SIGRTMIN` Handler**: Utilized for inter-thread signaling, such as execution cancellation. Similar to SIGSYS, it distinguishes between application and non-hyperlight threads to determine how to handle the signal.
-- **Thread Differentiation**: Hyperlight uses thread-local storage (IS_HYPERLIGHT_THREAD) to identify whether the current thread is a hyperlight thread. This distinction ensures that signals are handled appropriately based on the thread's role.
+Hyperlight registers custom signal handlers to intercept and manage specific signals, primarily `SIGSYS` , `SIGRTMIN` and `SIGSEGV` Here's an overview of the registration process:
+
+- **Preserving Old Handlers**: When registering a new signal handler, Hyperlight first retrieves and stores the existing handler using either `OnceCell` or a `static AtomicPtr` This allows Hyperlight to delegate signals to the original handler if necessary.
+- **Custom Handlers**:
+- **`SIGSYS` Handler**: Captures disallowed syscalls enforced by seccomp. If the signal originates from a hyperlight thread, Hyperlight logs the syscall details. Otherwise, it delegates the signal to the previously registered handler. 
+- **`SIGRTMIN` Handler**: Utilized for inter-thread signaling, such as execution cancellation. Similar to SIGSYS, it distinguishes between application and non-hyperlight threads to determine how to handle the signal.
+- **`SIGSEGV` Handler**: Handles segmentation faults for dirty page tracking of host memory mapped into a VM. If the signal applies to an address that is mapped to a VM, it is processed by Hyperlight; otherwise, it is passed to the original handler.
 
 ## Potential Issues and Considerations
 
@@ -15,3 +16,14 @@ Hyperlight registers custom signal handlers to intercept and manage specific sig
     - **Invalidation of `old_handler`**: The stored old_handler reference may no longer point to a valid handler, causing undefined behavior when Hyperlight attempts to delegate signals.
     - **Loss of Custom Handling**: Hyperlight's custom handler might not be invoked as expected, disrupting its ability to enforce syscall restrictions or manage inter-thread signals.
 
+### Debugging and Signal Handling
+
+By default when debugging a host application/test/example with GDB or LLDB the debugger will handle the `SIGSEGV` signal by breaking when it is raised, to prevent this and let hyperlight handle the signal enter the following in the debug console:
+
+#### LLDB
+
+```process handle SIGSEGV -n true -p true -s false```
+
+#### GDB
+
+```handle SIGSEGV nostop noprint pass```

src/hyperlight_common/src/mem.rs

@@ -17,6 +17,8 @@ limitations under the License.
 pub const PAGE_SHIFT: u64 = 12;
 pub const PAGE_SIZE: u64 = 1 << 12;
 pub const PAGE_SIZE_USIZE: usize = 1 << 12;
+// The number of pages in 1 "block". A single u64 can be used as bitmap to keep track of all dirty pages in a block.
+pub const PAGES_IN_BLOCK: usize = 64;
 
 /// A memory region in the guest address space
 #[derive(Debug, Clone, Copy)]

src/hyperlight_host/Cargo.toml

@@ -44,6 +44,7 @@ anyhow = "1.0"
 metrics = "0.24.2"
 serde_json = "1.0"
 elfcore = "2.0"
+lockfree ="0.5"
 
 [target.'cfg(windows)'.dependencies]
 windows = { version = "0.61", features = [

src/hyperlight_host/benches/benchmarks.rs

@@ -79,37 +79,65 @@ fn guest_call_benchmark(c: &mut Criterion) {
     group.finish();
 }
 
-fn guest_call_benchmark_large_param(c: &mut Criterion) {
+fn guest_call_benchmark_large_params(c: &mut Criterion) {
     let mut group = c.benchmark_group("guest_functions_with_large_parameters");
     #[cfg(target_os = "windows")]
     group.sample_size(10); // This benchmark is very slow on Windows, so we reduce the sample size to avoid long test runs.
 
-    // This benchmark includes time to first clone a vector and string, so it is not a "pure' benchmark of the guest call, but it's still useful
-    group.bench_function("guest_call_with_large_parameters", |b| {
-        const SIZE: usize = 50 * 1024 * 1024; // 50 MB
-        let large_vec = vec![0u8; SIZE];
-        let large_string = unsafe { String::from_utf8_unchecked(large_vec.clone()) }; // Safety: indeed above vec is valid utf8
+    // Helper function to create a benchmark for a specific size
+    let create_benchmark = |group: &mut criterion::BenchmarkGroup<_>, size_mb: usize| {
+        let benchmark_name = format!("guest_call_with_2_large_parameters_{}mb each", size_mb);
+        group.bench_function(&benchmark_name, |b| {
+            let size = size_mb * 1024 * 1024; // Convert MB to bytes
+            let large_vec = vec![0u8; size];
+            let large_string = unsafe { String::from_utf8_unchecked(large_vec.clone()) }; // Safety: indeed above vec is valid utf8
 
-        let mut config = SandboxConfiguration::default();
-        config.set_input_data_size(2 * SIZE + (1024 * 1024)); // 2 * SIZE + 1 MB, to allow 1MB for the rest of the serialized function call
-        config.set_heap_size(SIZE as u64 * 15);
+            let mut config = SandboxConfiguration::default();
+            config.set_input_data_size(2 * size + (1024 * 1024));
 
-        let sandbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(simple_guest_as_string().unwrap()),
-            Some(config),
-        )
-        .unwrap();
-        let mut sandbox = sandbox.evolve(Noop::default()).unwrap();
+            if size < 50 * 1024 * 1024 {
+                config.set_heap_size(size as u64 * 16);
+            } else {
+                config.set_heap_size(size as u64 * 11); // Set to 1GB for larger sizes
+            }
 
-        b.iter(|| {
-            sandbox
-                .call_guest_function_by_name::<()>(
-                    "LargeParameters",
-                    (large_vec.clone(), large_string.clone()),
-                )
-                .unwrap()
+            let sandbox = UninitializedSandbox::new(
+                GuestBinary::FilePath(simple_guest_as_string().unwrap()),
+                Some(config),
+            )
+            .unwrap();
+            let mut sandbox = sandbox.evolve(Noop::default()).unwrap();
+
+            b.iter_custom(|iters| {
+                let mut total_duration = std::time::Duration::new(0, 0);
+
+                for _ in 0..iters {
+                    // Clone the data (not measured)
+                    let vec_clone = large_vec.clone();
+                    let string_clone = large_string.clone();
+
+                    // Measure only the guest function call
+                    let start = std::time::Instant::now();
+                    sandbox
+                        .call_guest_function_by_name::<()>(
+                            "LargeParameters",
+                            (vec_clone, string_clone),
+                        )
+                        .unwrap();
+                    total_duration += start.elapsed();
+                }
+
+                total_duration
+            });
         });
-    });
+    };
+
+    // Create benchmarks for different sizes
+    create_benchmark(&mut group, 5); // 5MB
+    create_benchmark(&mut group, 10); // 10MB
+    create_benchmark(&mut group, 20); // 20MB
+    create_benchmark(&mut group, 40); // 40MB
+    create_benchmark(&mut group, 60); // 60MB
 
     group.finish();
 }
@@ -153,9 +181,143 @@ fn sandbox_benchmark(c: &mut Criterion) {
     group.finish();
 }
 
+fn sandbox_heap_size_benchmark(c: &mut Criterion) {
+    let mut group = c.benchmark_group("sandbox_heap_sizes");
+
+    // Helper function to create sandbox with specific heap size
+    let create_sandbox_with_heap_size = |heap_size_mb: Option<u64>| {
+        let path = simple_guest_as_string().unwrap();
+        let config = if let Some(size_mb) = heap_size_mb {
+            let mut config = SandboxConfiguration::default();
+            config.set_heap_size(size_mb * 1024 * 1024); // Convert MB to bytes
+            Some(config)
+        } else {
+            None
+        };
+
+        let uninit_sandbox =
+            UninitializedSandbox::new(GuestBinary::FilePath(path), config).unwrap();
+        uninit_sandbox.evolve(Noop::default()).unwrap()
+    };
+
+    // Benchmark sandbox creation with default heap size
+    group.bench_function("create_sandbox_default_heap", |b| {
+        b.iter_with_large_drop(|| create_sandbox_with_heap_size(None));
+    });
+
+    // Benchmark sandbox creation with 50MB heap
+    group.bench_function("create_sandbox_50mb_heap", |b| {
+        b.iter_with_large_drop(|| create_sandbox_with_heap_size(Some(50)));
+    });
+
+    // Benchmark sandbox creation with 100MB heap
+    group.bench_function("create_sandbox_100mb_heap", |b| {
+        b.iter_with_large_drop(|| create_sandbox_with_heap_size(Some(100)));
+    });
+
+    // Benchmark sandbox creation with 250MB heap
+    group.bench_function("create_sandbox_250mb_heap", |b| {
+        b.iter_with_large_drop(|| create_sandbox_with_heap_size(Some(250)));
+    });
+
+    // Benchmark sandbox creation with 500MB heap
+    group.bench_function("create_sandbox_500mb_heap", |b| {
+        b.iter_with_large_drop(|| create_sandbox_with_heap_size(Some(500)));
+    });
+
+    // Benchmark sandbox creation with 995MB heap (close to the limit of 1GB for a Sandbox )
+    group.bench_function("create_sandbox_995mb_heap", |b| {
+        b.iter_with_large_drop(|| create_sandbox_with_heap_size(Some(995)));
+    });
+
+    group.finish();
+}
+
+fn guest_call_heap_size_benchmark(c: &mut Criterion) {
+    let mut group = c.benchmark_group("guest_call_heap_sizes");
+
+    // Helper function to create sandbox with specific heap size
+    let create_sandbox_with_heap_size = |heap_size_mb: Option<u64>| {
+        let path = simple_guest_as_string().unwrap();
+        let config = if let Some(size_mb) = heap_size_mb {
+            let mut config = SandboxConfiguration::default();
+            config.set_heap_size(size_mb * 1024 * 1024); // Convert MB to bytes
+            Some(config)
+        } else {
+            None
+        };
+
+        let uninit_sandbox =
+            UninitializedSandbox::new(GuestBinary::FilePath(path), config).unwrap();
+        uninit_sandbox.evolve(Noop::default()).unwrap()
+    };
+
+    // Benchmark guest function call with default heap size
+    group.bench_function("guest_call_default_heap", |b| {
+        let mut sandbox = create_sandbox_with_heap_size(None);
+        b.iter(|| {
+            sandbox
+                .call_guest_function_by_name::<String>("Echo", "hello\n".to_string())
+                .unwrap()
+        });
+    });
+
+    // Benchmark guest function call with 50MB heap
+    group.bench_function("guest_call_50mb_heap", |b| {
+        let mut sandbox = create_sandbox_with_heap_size(Some(50));
+        b.iter(|| {
+            sandbox
+                .call_guest_function_by_name::<String>("Echo", "hello\n".to_string())
+                .unwrap()
+        });
+    });
+
+    // Benchmark guest function call with 100MB heap
+    group.bench_function("guest_call_100mb_heap", |b| {
+        let mut sandbox = create_sandbox_with_heap_size(Some(100));
+        b.iter(|| {
+            sandbox
+                .call_guest_function_by_name::<String>("Echo", "hello\n".to_string())
+                .unwrap()
+        });
+    });
+
+    // Benchmark guest function call with 250MB heap
+    group.bench_function("guest_call_250mb_heap", |b| {
+        let mut sandbox = create_sandbox_with_heap_size(Some(250));
+        b.iter(|| {
+            sandbox
+                .call_guest_function_by_name::<String>("Echo", "hello\n".to_string())
+                .unwrap()
+        });
+    });
+
+    // Benchmark guest function call with 500MB heap
+    group.bench_function("guest_call_500mb_heap", |b| {
+        let mut sandbox = create_sandbox_with_heap_size(Some(500));
+        b.iter(|| {
+            sandbox
+                .call_guest_function_by_name::<String>("Echo", "hello\n".to_string())
+                .unwrap()
+        });
+    });
+
+    // Benchmark guest function call with 995MB heap
+    group.bench_function("guest_call_995mb_heap", |b| {
+        let mut sandbox = create_sandbox_with_heap_size(Some(995));
+        b.iter(|| {
+            sandbox
+                .call_guest_function_by_name::<String>("Echo", "hello\n".to_string())
+                .unwrap()
+        });
+    });
+
+    group.finish();
+}
+
 criterion_group! {
     name = benches;
     config = Criterion::default();
-    targets = guest_call_benchmark, sandbox_benchmark, guest_call_benchmark_large_param
+    targets = guest_call_benchmark, sandbox_benchmark, sandbox_heap_size_benchmark, guest_call_benchmark_large_params, guest_call_heap_size_benchmark
 }
 criterion_main!(benches);