README.md

ahv

Bindings for Apple Silicon Hypervisor.

Usage

To use ahv, add this to your Cargo.toml:

[dependencies]
ahv = "0.3.0"

Example

The following example execute a move of the immediate value 2 to register x0 at EL1 and then call HVC 0.

use ahv::*;

fn main() -> Result<()> {
    let el1_user_payload = [
        0x40, 0x00, 0x80, 0xD2, // mov x0, #2
        0x02, 0x00, 0x00, 0xD4, // hvc #0
    ];

    const EL1_USER_PAYLOAD_ADDRESS: hv_ipa_t = 0x20000;
    let mut virtual_machine: VirtualMachine = VirtualMachine::new(None)?;
    let el1_user_payload_allocation_handle = virtual_machine.allocate_from(&el1_user_payload)?;
    virtual_machine.map(el1_user_payload_allocation_handle,
                        EL1_USER_PAYLOAD_ADDRESS,
                        MemoryPermission::READ_WRITE_EXECUTE)?;

    {
        // vCPU scope
        let mut vcpu = virtual_machine.create_vcpu(None)?;

        vcpu.set_register(Register::CPSR, 0x3c4)?;
        vcpu.set_register(Register::PC, EL1_USER_PAYLOAD_ADDRESS)?;
        vcpu.set_trap_debug_exceptions(true)?;
    
        loop {
            let result = vcpu.run()?;
    
            match result {
                VirtualCpuExitReason::Exception { exception } => {
                    let ec = (exception.syndrome >> 26) & 0x3f;
    
                    if ec == 0x16 {
                        println!("HVC executed! x0 is {}", vcpu.get_register(Register::X0)?);
                        break;
                    } else {
                        println!("Unknown exception class 0x{:x}", ec);
                        break;
                    }
                }
                reason => {
                    println!("Unexpected exit! Reason: {:?}", reason);
                    break;
                }
            }
        }
    }

    // VirtualMachine will unmap and deallocate on drop.

    Ok(())
}

To run this example make sure to give the built binary the com.apple.security.hypervisor entitlement.

MSRV

Current MSRV is 1.65.0.

License

ahv is distributed under the terms of either the MIT license or the Apache License (Version 2.0), at the user's choice.

See LICENSE-APACHE and LICENSE-MIT.