### Running Hyperlight Guest Debugging Example

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

This command starts the Hyperlight guest debugging example with the 'gdb' feature enabled. This prepares the sandbox to listen for a GDB client connection.

```bash
# Terminal 1
$ cargo run --example guest-debugging --features gdb
```

--------------------------------

### Install cargo-hyperlight and create new project

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Installs the cargo-hyperlight tool and creates a new Hyperlight project. This is the recommended way to start a new Hyperlight application.

```bash
cargo install --locked cargo-hyperlight
cargo hyperlight new my-project
```

--------------------------------

### C Guest Example Reference

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-build-a-hyperlight-guest-binary.md

Reference to a complete example of a C guest binary, located in `src/tests/c_guests/c_simpleguest/main.c`.

```c
See [src/tests/c_guests/c_simpleguest/main.c](../src/tests/c_guests/c_simpleguest/main.c)
for a complete example.

```

--------------------------------

### Install cargo-hyperlight

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-build-a-hyperlight-guest-binary.md

Install the `cargo-hyperlight` tool using cargo.

```sh
cargo install --locked cargo-hyperlight
```

--------------------------------

### Run Hyperlight Example with Guest Tracing

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

Execute a Hyperlight example with tracing enabled for both host and guest. Trace data is exported as OpenTelemetry spans and events.

```bash
RUST_LOG="info,hyperlight_host::sandbox=info,hyperlight_guest=trace,hyperlight_guest_bin=trace" cargo run --example tracing-otlp --features trace_guest
```

--------------------------------

### Install Clang/LLVM on Windows

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Installs the Clang/LLVM component using the Visual Studio installer. This is necessary for building guest binaries on Windows.

```powershell
$vsPath = & "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe" -property installationPath
& "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vs_installer.exe" modify \
    --installPath $vsPath \
    --add Microsoft.VisualStudio.Component.VC.Llvm.Clang \
    --quiet --norestart
```

--------------------------------

### Install LLVM/Clang on Ubuntu/Debian

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Installs LLVM and Clang on Ubuntu/Debian systems using a provided script. This is required for building guest binaries.

```bash
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 18
```

--------------------------------

### Benchmark Results Example

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/benchmarking-hyperlight.md

Example output from a daily benchmark run, showing execution time and percentage change compared to the previous run.

```text
sandboxes/create_sandbox
                        time:   [33.803 ms 34.740 ms 35.763 ms]
                        change: [+0.7173% +3.7017% +7.1346%] (p = 0.03 < 0.05)
                        Change within noise threshold.*
   
```

--------------------------------

### Example of Inspecting Guest Memory Trace Files

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

An example command to inspect a guest trace file using `trace_dump`, specifying paths to the guest binary and the trace file.

```bash
cargo run -p trace_dump ./src/tests/rust_guests/bin/debug/simpleguest ./trace/<UUID>.trace list_frames
```

--------------------------------

### Run CI Coverage with KVM

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-run-coverage.md

Example of running the CI coverage recipe specifically for the KVM hypervisor.

```sh
just coverage-ci kvm
```

--------------------------------

### Install pango Development Files

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

Installs pango development files on Fedora/RHEL/CentOS systems. These are dependencies for Rust crates like pango-sys.

```bash
sudo dnf install pango-devel
```

--------------------------------

### Example POSIX 'write' Stub Implementation

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/src/hyperlight_libc/README.md

This example shows how to implement the POSIX 'write' stub, which delegates to a host function for printing. It handles input validation and supports writing to stdout and stderr.

```rust
use alloc::string::String;
use core::ffi::{c_int, c_void};
use hyperlight_guest_bin::host_function;
use hyperlight_guest_bin::libc::{errno, EINVAL, EBADF, EIO};

#[host_function("HostPrint")]
fn host_print(message: String) -> i32;

#[unsafe(no_mangle)]
extern "C" fn write(fd: c_int, buf: *const c_void, count: usize) -> isize {
    // Validate input buffer
    if buf.is_null() && count > 0 {
        unsafe { errno = EINVAL as _ };
        return -1;
    }

    // Only support stdout (1) and stderr (2)
    if fd != 1 && fd != 2 {
        unsafe { errno = EBADF as _ };
        return -1;
    }

    // Read the buffer and convert to a String
    let buf = unsafe { core::slice::from_raw_parts(buf as *const u8, count) };
    let text = String::from_utf8_lossy(buf).into_owned();

    // Delegate to the host function
    host_print(text);

    count as isize
}
```

--------------------------------

### Install cairo and cairo-gobject Development Files

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

Installs cairo and cairo-gobject development files on Fedora/RHEL/CentOS systems. These are necessary for Rust crates such as cairo-sys-rs.

```bash
sudo dnf install cairo-devel cairo-gobject-devel
```

--------------------------------

### Install Build Tools on Ubuntu/Debian

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Installs essential build tools on Ubuntu or Debian systems. These tools are required for compiling software, including Hyperlight components.

```bash
sudo apt install build-essential
```

--------------------------------

### Install clang on Azure Linux

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Installs the clang compiler on Azure Linux systems. This is required for building guest binaries.

```bash
sudo dnf install clang
```

--------------------------------

### Install glib-2.0 Development Files

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

Installs glib-2.0 development files and pkgconf-pkg-config on Fedora/RHEL/CentOS systems. These are required by Rust crates like glib-sys.

```bash
sudo dnf install glib2-devel pkgconf-pkg-config
```

--------------------------------

### Benchmark Comparison Output

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/benchmarking-hyperlight.md

Example output displayed on stdout after a subsequent benchmark run, comparing new results against the 'my_baseline'.

```text
                        time:   [40.434 ms 40.777 ms 41.166 ms]
                        change: [+0.0506% +1.1399% +2.2775%] (p = 0.06 > 0.05)
                        No change in performance detected.
Found 1 outliers among 100 measurements (1.00%)

```

--------------------------------

### Install Build Tools on Azure Linux

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Installs essential build tools on Azure Linux systems using dnf. These tools are required for compiling software.

```bash
sudo dnf install build-essential
```

--------------------------------

### Run Tests with Coverage Instrumentation

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-run-coverage.md

Collects profiling data by running all tests and examples under coverage instrumentation. This only needs to be run once.

```sh
just coverage-run
```

--------------------------------

### Run Jaeger All-in-One Collector

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

Start the Jaeger all-in-one container to collect and view OTLP trace data. Ports 16686, 4317, and 4318 are exposed for the UI and OTLP.

```docker
docker run -p 16686:16686 -p 4317:4317 -p 4318:4318 -e COLLECTOR_OTLP_ENABLED=true jaegertracing/all-in-one:latest
```

--------------------------------

### VirtualCPU::run() Loop - Clear Cancel

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/cancellation.md

At the start of a cancellable window, before calling `VirtualCPU::run()`, the cancellation state is cleared.

```rust
Caller->>IH: clear_cancel()
Note right of Caller: Start of cancellable window
```

--------------------------------

### Build and run Hyperlight guest and host

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Builds the Hyperlight guest binary and then runs the host application. This is the typical workflow after creating a new project.

```bash
cd my-project/guest && cargo hyperlight build
cd ../host && cargo run
```

--------------------------------

### GDB Client Configuration and Connection

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

This sequence shows how to configure the GDB client using a `.gdbinit` file and then launch GDB to connect to the Hyperlight guest. The `.gdbinit` file specifies the symbol file and the remote debug port.

```bash
# Terminal 2
$ cat .gdbinit
file src/tests/rust_guests/bin/debug/simpleguest
target remote :8080
set disassembly-flavor intel
set disassemble-next-line on
enable pretty-printer
layout src

$ gdb
```

--------------------------------

### Basic GDB Initialization Configuration

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

This `.gdbinit` file provides a basic configuration for GDB startup, including setting the symbol file path and the remote target port. It also configures disassembly flavor and enables source layout.

```gdb
# Path to symbols
file path/to/symbols.elf
# The port on which Hyperlight listens for a connection
target remote :8080
set disassembly-flavor intel
set disassemble-next-line on
enable pretty-printer
layout src
```

--------------------------------

### Build and Test Picolibc Integration

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/picolibc.md

Commands to build guest binaries and run tests after updating picolibc.

```bash
just guests
just test
```

--------------------------------

### Host: Create Sandbox, Register Host Function, and Call Guest

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/README.md

This snippet demonstrates how to set up a Hyperlight sandbox on the host. It includes creating an uninitialized sandbox, registering a host-callable function, and then evolving the sandbox to a usable state before making a call into the guest.

```rust
// Create an uninitialized sandbox by giving it the path to a guest binary.
// Allocates memory but does not yet run a VM.
let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(guest_path), None)?;

// Register a host function that the guest can call. In a real app this
// might query a database, read a config, or call an external API.
// By default, guests can only print to the host.
sandbox.register("GetWeekday", || Ok("Monday".to_string()))?;

// Initialize the sandbox. Starts the VM and runs guest setup code.
let mut sandbox: MultiUseSandbox = sandbox.evolve()?;

// Call a function inside the VM
let greeting: String = sandbox.call("SayHello", "World".to_string())?;
println!("{greeting}"); // "Hello, World! Today is Monday."
```

--------------------------------

### Build Guest Binaries

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-run-coverage.md

Build guest binaries before running coverage. This is a prerequisite step.

```sh
just guests
```

--------------------------------

### Build Guest with Release-Debug Profile

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

Compile your guest binary using the custom 'release-with-debug' profile to include debug information.

```bash
cargo build --profile release-with-debug
```

--------------------------------

### Run Benchmarks Locally

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/benchmarking-hyperlight.md

Command to run release build benchmarks locally. Use 'just bench-download' to fetch GitHub release benchmarks for comparison.

```bash
just bench

```

--------------------------------

### Build Rust Guest Binary

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-build-a-hyperlight-guest-binary.md

Build the Rust guest binary using `cargo hyperlight build`.

```sh
cargo hyperlight build
```

--------------------------------

### Compare to Previous Release Benchmarks

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/benchmarking-hyperlight.md

Command to compare local benchmarks against (and overwrite) the previous release benchmarks stored in GitHub. Assumes benchmarks have been downloaded.

```bash
just bench-ci main

```

--------------------------------

### Build Rust Guest with Tracing Support

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

Build Rust guest binaries with the 'trace_guest' feature enabled and move them to the host's location.

```bash
just build-rust-guests debug trace_guest
```

```bash
just move-rust-guests debug
```

--------------------------------

### Compare Local Benchmarks to GitHub Release

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/benchmarking-hyperlight.md

Command to download and extract GitHub release benchmarks for local comparison. 'main' refers to the baseline name stored on GitHub.

```bash
just bench-download os hypervisor [tag] 

```

--------------------------------

### Minimal Rust Guest main.rs

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-build-a-hyperlight-guest-binary.md

A minimal Rust guest implementation using `hyperlight-guest-bin` macros to register guest functions and declare host functions.

```rust
#![no_std]
#![no_main]
extern crate alloc;

use alloc::string::String;

use hyperlight_guest_bin::error::Result;
use hyperlight_guest_bin::{guest_function, host_function};

// Declare a host function the guest can call. The string is the name the
// host registered it under. If omitted, the Rust function name is used.
#[host_function("GetWeekday")]
fn get_weekday() -> Result<String>;

// Register a guest function the host can call.
#[guest_function("SayHello")]
fn say_hello(name: String) -> Result<String> {
    let weekday = get_weekday()?;
    Ok(alloc::format!("Hello, {name}! Today is {weekday}."))
}

```

--------------------------------

### Inspect Guest Memory Trace Files

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

Use the `trace_dump` crate to list stack frames and tracing information from a guest trace file. Requires paths to guest symbols and the trace file.

```bash
cargo run -p trace_dump <path_to_guest_symbols> <trace_file_path> list_frames
```

--------------------------------

### Run CI Coverage Recipe

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-run-coverage.md

The CI recipe runs tests and generates HTML, LCOV, and text summary reports in a single command. It requires the hypervisor type as an argument.

```sh
just coverage-ci <hypervisor>
```

--------------------------------

### Scaffold a new Hyperlight project

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-build-a-hyperlight-guest-binary.md

Create a new Hyperlight project with a host and guest component, or optionally only a guest or host.

```sh
cargo hyperlight new my-project
```

--------------------------------

### Load Core Dump with LLDB (Basic)

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

Use this command for basic analysis of a core dump with LLDB, focusing on function names and stack traces.

```bash
lldb ${BINARY} -c /path/to/core.dump
```

--------------------------------

### VSCode Launch Configurations for Hyperlight Debugging

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

This JSON configuration file is used by VSCode to set up debugging sessions for Hyperlight guests. It includes configurations for both LLDB and GDB, specifying how to connect to the guest process running on a remote port.

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "LLDB",
            "type": "lldb",
            "request": "launch",
            "targetCreateCommands": ["target create ${workspaceFolder}/src/tests/rust_guests/bin/debug/simpleguest"],
            "processCreateCommands": ["gdb-remote localhost:8080"]
        },
        {
            "name": "GDB",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/src/tests/rust_guests/bin/debug/simpleguest",
            "args": [],
            "stopAtEntry": true,
            "hardwareBreakpoints": {"require": false, "limit": 4},
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "miDebuggerPath": "/usr/bin/gdb",
            "miDebuggerServerAddress": "localhost:8080",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                },
                {
                    "description": "Set Disassembly Flavor to Intel",
                    "text": "-gdb-set disassembly-flavor intel",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}
```

--------------------------------

### Hyperlight Guest Execution Flow

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

This diagram illustrates the typical execution flow of a Hyperlight guest, including states like continuing execution, VCPU halting, and communication channel disconnection. It helps in understanding when and why a guest might stop responding.

```text
     │ │◄──────────────────────┬─────────│ │                                         │ │                                |      │
     │ │    continue until end │         │ │                                         │ │                                |      │
     │ │───────────────────────┼────────►│ │            continue                     │ │         resume vcpu            |      │
     │ │                       │         │ │────────────────────────────────────────►│ │──────────────────────────────►┌─┐     │
     │ │                       │         │ │                                         │ │                               │ │     │
     │ │                       │         │ │        comm channel disconnected        │ │         vcpu halted           │ │     │
     │ │   target finished exec│         │ │◄────────────────────────────────────────┤ │◄──────────────────────────────┴─┘     │
     │ │◄──────────────────────┼─────────┴─┘          target finished exec           └─┘                                |      │
     │ │                       │          |                                           |                                 |      │
     └─┘                       │          |                                           |                                 |      │
      |                        └───────────────────────────────────────────────────────────────────────────────────────────────┘
```

--------------------------------

### Load Core Dump with GDB

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

Inspect a generated core dump file by loading it alongside the guest binary in GDB. This allows for post-mortem analysis of the guest's state at the time of the crash.

```bash
gdb <guest-binary> -c <core-dump-file>

```

```bash
gdb src/tests/rust_guests/bin/debug/simpleguest -c /tmp/hl_dumps/hl_core_20260225_T165358.517.elf

```

--------------------------------

### VirtualCPU::run() Loop - Guest Entry

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/cancellation.md

The vCPU enters guest execution. If a `kill()` operation occurs during this phase, signals will interrupt the guest.

```rust
vCPU->>vCPU: run_vcpu() (Enter Guest)
activate vCPU
```

--------------------------------

### Create Git Tag and Push

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-make-releases.md

Create a Git tag for the new version and push it to the remote repository. Ensure you have pulled the latest main branch changes before tagging.

```bash
git tag -a v0.4.0 -m "A brief description of the release"
git push origin v0.4.0 # if you've named your git remote for the hyperlight-dev/hyperlight repo differently, change 'origin' to your remote name
```

--------------------------------

### Importing libc Bindings in hyperlight-guest-bin

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/src/hyperlight_libc/README.md

When the 'libc' feature is enabled in hyperlight-guest-bin, these libc bindings are re-exported and can be imported directly.

```rust
use hyperlight_guest_bin::libc::{errno, timespec, EINVAL, CLOCK_REALTIME};
```

--------------------------------

### Load Core Dump with LLDB (Full Debugging)

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

This command enables full source-level debugging with LLDB by creating a target and specifying the binary and core dump.

```bash
lldb -o "target create -c /path/to/core.dump ${BINARY}" -o "add-dsym ${DEBUG_FILE_FULL}"
```

--------------------------------

### Check Hypervisor Features on Windows

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Lists the status of Hyper-V related features on Windows. This is a troubleshooting step for 'NoHypervisorFound' errors.

```powershell
Get-WindowsOptionalFeature -Online | Where-Object {$_.FeatureName -match 'Hyper-V|HypervisorPlatform|VirtualMachinePlatform'} | Format-Table
```

--------------------------------

### Update Picolibc Submodule

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/picolibc.md

Commands to fetch, checkout, and add the updated picolibc submodule.

```bash
cd src/hyperlight_libc/third_party/picolibc
git fetch origin
git checkout <new-fork-tag>
cd ../../../..
git add src/hyperlight_libc/third_party/picolibc
```

--------------------------------

### Generate Guest Core Dump On Demand using GDB

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

Manually trigger a core dump of the guest's current state using GDB. This is useful for debugging issues that do not cause a crash, such as infinite loops or non-responsive functions.

```shell
sudo gdb -p <pid_of_your_process>
(gdb) info threads
# find the thread that is running the guest function you want to debug
(gdb) thread <thread_number>
# switch to the frame where you have access to your MultiUseSandbox instance
(gdb) backtrace
(gdb) frame <frame_number>
# get the pointer to your MultiUseSandbox instance
# Get the sandbox pointer
(gdb) print sandbox
# Call the crashdump function with the pointer
    # Call the crashdump function 
call sandbox.generate_crashdump()

```

--------------------------------

### Criterion Artifacts Structure (Initial Run)

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/benchmarking-hyperlight.md

Illustrates the directory structure created by Criterion after the first 'cargo bench -- --save-baseline my_baseline' command in a clean project.

```text
target/criterion/
|-- report
`-- sandboxes
    |-- create_sandbox
    |   |-- my_baseline
    |   |-- new
    |   `-- report
    |-- create_sandbox_and_call_context
    |   |-- my_baseline
    |   |-- new
    |   `-- report
    `-- report

```

--------------------------------

### Configure Git for GPG Signing

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/CONTRIBUTING.md

Set your GPG signing key and enable GPG signing for all commits globally in your Git configuration.

```sh
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true
```

--------------------------------

### Minimal Rust Guest Cargo.toml

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-build-a-hyperlight-guest-binary.md

Defines a minimal Rust guest crate, depending on `hyperlight-guest-bin`.

```toml
[package]
name = "my-guest"
version = "0.1.0"
edition = "2024"

[dependencies]
hyperlight-guest-bin = "*"  # use the latest version from crates.io

```

--------------------------------

### Run Jaeger All-in-One (Windows)

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/hyperlight-metrics-logs-and-traces.md

Execute the Jaeger all-in-one executable on Windows to collect and view OTLP trace data.

```powershell
.\jaeger-all-in-one.exe
```

--------------------------------

### Memory Ordering Guarantees Graph

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/cancellation.md

Visualizes the synchronization between vCPU and Interrupt threads using Release-Acquire semantics for various operations.

```mermaid
graph TB
    subgraph "vCPU Thread"
        A[set_tid<br/>Store tid with Release]
        B[set_running<br/>fetch_update RUNNING_BIT<br/>with Release]
        C[is_cancelled<br/>Load with Acquire]
        D[clear_running<br/>fetch_and with Release]
        J[is_debug_interrupted<br/>Load with Acquire]
    end
    
    subgraph "Interrupt Thread"
        E[kill<br/>fetch_or CANCEL_BIT<br/>with Release]
        F[send_signal<br/>Load running with Acquire]
        G[Load tid with Acquire]
        H[pthread_kill]
        I[kill_from_debugger<br/>fetch_or DEBUG_INTERRUPT_BIT<br/>with Release]
    end
    
    B -->|Synchronizes-with| F
    A -->|Happens-before via B→F| G
    E -->|Synchronizes-with| C
    D -->|Synchronizes-with| F
    I -->|Synchronizes-with| J
```

--------------------------------

### Generate HTML Coverage Report

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-run-coverage.md

Generates a browsable HTML report in 'target/coverage/html/'. Requires 'coverage-run' to have been executed first.

```sh
just coverage-html
```

--------------------------------

### Generate Text Coverage Summary

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-run-coverage.md

Prints a coverage summary to the terminal. Requires 'coverage-run' to have been executed first.

```sh
just coverage
```

--------------------------------

### Generate FlatBuffers Rust Code

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-use-flatbuffers.md

Use this command to generate all FlatBuffers Rust code from schema files. Ensure you have built `flatc` from source.

```console
just gen-all-fbs-rust-code
```

--------------------------------

### VirtualCPU::run() Loop - Set Tid and Running

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/cancellation.md

At the beginning of each run loop iteration, the thread ID is set, and the running status is enabled to allow signal delivery.

```rust
vCPU->>IH: set_tid()
vCPU->>IH: set_running()
Note right of vCPU: Enable signal delivery
```

--------------------------------

### Enable Windows Hypervisor Platform

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Enables the Windows Hypervisor Platform feature on Windows systems. This feature is required for Hyperlight to run on Windows.

```powershell
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -NoRestart
```

--------------------------------

### Analyze Core Dump with GDB (Basic)

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/how-to-debug-a-hyperlight-guest.md

Use GDB to analyze a core dump with basic function names for stack traces. This requires the stripped binary.

```bash
gdb ${BINARY} -c /path/to/core.dump
```

--------------------------------

### Check /dev/kvm and /dev/mshv on Linux

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/getting-started.md

Checks for the existence of the KVM or MSHV hypervisor devices on Linux systems. This is a troubleshooting step for 'NoHypervisorFound' errors.

```bash
ls -l /dev/kvm
ls -l /dev/mshv
```

--------------------------------

### VirtualCPU::run() Loop - Guest Exit Handling

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/cancellation.md

Upon guest exit, signal delivery is disabled by clearing the running status. The cancellation status is then captured to determine if a cancellation exit was genuine or stale.

```rust
Note over vCPU: === TIMING POINT 4 ===
vCPU->>IH: clear_running()
Note right of vCPU: Disable signal delivery

Note over vCPU: === TIMING POINT 5 ===
vCPU->>IH: is_cancelled()
IH-->>vCPU: cancel_requested (bool)
Note right of vCPU: Check if we should exit
```

--------------------------------

### Run Benchmarks with Debug Symbols

Source: https://github.com/hyperlight-dev/hyperlight/blob/main/docs/benchmarking-hyperlight.md

Command to compile and run benchmarks directly with 'cargo bench' to include debug symbols, useful for profiling.

```bash
cargo bench

```