Adding New Hook Types¶

#[test]
#[cfg_attr(miri, ignore)]
#[cfg_attr(asan, ignore)]
fn test_unmapped_read_hooks() {
    // tests that the hook gets called when we read from an unmapped address

    // (1) test fixture will attempt to read from address `0x9999`
    let machine = TestMachine::with_code("movw r1, #0x9999;ldr r4, [r1];");

    // create the callback variant without userdata
    let cb = |cpu: &CpuBackend, addr: u64, size: u32, fault_data: MemFaultData| {
        println!(
            "unmapped fault: 0x{:x} of size: {}, type: {:?}",
            addr, size, fault_data
        );

        cpu.write_register(ArmRegister::R2, 1u32).unwrap();


        false
    };

    // create the callback variant with userdata
    let cb_data = |cpu: &CpuBackend,
                   addr: u64,
                   size: u32,
                   fault_data: MemFaultData,
                   userdata: HookUserData| {
        let value = userdata.downcast_ref::<String>().unwrap();

        println!(
            "unmapped fault: 0x{:x} of size: {}, type: {:?}",
            addr, size, fault_data
        );
        println!("\twith userdata: {:?}", value);

        cpu.write_register(ArmRegister::R3, 1u32).unwrap();

        false
    };

    // (2) insert hooks and collect tokens for removal later
    let token1 = machine
        .proc
        .unmapped_fault_hook(0, u64::MAX, Box::new(cb))
        .unwrap();
    let token2 = machine
        .proc
        .unmapped_fault_hook_data(
            0,
            u64::MAX,
            Box::new(cb_data),
            Arc::new(String::from("userdata!")),
        )
        .unwrap();

    // (3) run the code, and assert that the exit condition is our unmapped read
    machine.run_and_assert_exit_reason(TargetExitReason::UnmappedMemoryRead);

    let end_pc = machine.proc.pc().unwrap();

    // (4) basic assertions are correct
    assert_eq!(
        0x4004u64, end_pc,
        "Stopped at incorrect instruction: {:#x}",
        end_pc,
    );
    assert_eq!(
        0x9999,
        machine.proc.read_register::<u32>(ArmRegister::R1).unwrap(),
        "r1 is incorrect immediate value",
    );

    // (5) assertions to test that the hooks we successfully called
    assert_eq!(
        1,
        machine.proc.read_register::<u32>(ArmRegister::R2).unwrap(),
        "normal hook failed"
    );
    assert_eq!(
        1,
        machine.proc.read_register::<u32>(ArmRegister::R3).unwrap(),
        "userdata hook failed"
    );

    // removal of hooks is correct
    machine.proc.delete_hook(token1).unwrap();
    machine.proc.delete_hook(token2).unwrap();

fn protection_fault_hook(
    &self,
    start: u64,
    end: u64,
    callback: ProtectionFaultHookCBType,
) -> Result<HookToken, StyxCpuBackendError> {
    // create the entire `CallbackBody`
    let mut callback_meta = Box::new(StyxHookDescriptor {
        func: callback.into(),
        backend: self.weak_ref.clone(),
        userdata: None, // (1) userdata
        start,
        end,
    });

    // make ptr for output token
    let mut hook_token = HookToken::default();

    // call the unicorn ffi to add the hook
    let err = unsafe {
        ffi::uc_hook_add(
            self.inner().get_handle(),
            hook_token.inner(),
            // we use MEM_PROT which technically is three different types:
            // - MEM_READ_PROT
            // - MEM_WRITE_PROT
            // - MEM_FETCH_PROT
            //
            // but in the proxy we map the fetch to the read error
            unicorn_engine::unicorn_const::HookType::MEM_PROT, // (2) hook type
            protection_fault_hook_proxy as _, // (3) proxy method
            callback_meta.as_mut() as *mut _ as _,
            start,
            end,
        )
    };

    if hook_token.inner().is_null() {
        return Err(StyxCpuBackendError::FFIFailure(String::from(
            "Unicorn failed to write hook pointer",
        )));
    }

    if err == unicorn_const::uc_error::OK {
        // pass ownership to the inner struct
        // add the callback to UnicornInner
        self.hook_map.add_hook(hook_token, callback_meta)?;

        // return the index item
        Ok(hook_token)
    } else {
        Err(err.into())
    }
}

// Used in `protection_fault_hook_proxy` to ensure that the received
// hook type is correct (1)
const PROT_MEM_TYPE: [unicorn_const::MemType; 3] = [
    unicorn_const::MemType::READ_PROT,
    unicorn_const::MemType::WRITE_PROT,
    unicorn_const::MemType::FETCH_PROT,
];

pub fn protection_fault_hook_proxy(
    _uc: unicorn_engine::ffi::uc_handle,
    mem_type: unicorn_const::MemType,
    address: u64,
    size: usize,
    value: i64, // always 0 when `mem_type` is a `READ_PROT`
    hook: *mut StyxHookDescriptor,
) -> bool {
    let hook = unsafe { &mut *hook };

    // match on the signature of the callback to avoid
    // ugly generic's everywhere (2)
    let callback = match &mut hook.func {
        HookCallback::ProtectionFaultCB(cb) => cb,
        _ => panic!(
            "Invalid hook type called on protection_fault_hook_proxy, got: {:?}",
            hook
        ),
    };

    // validate
    debug_assert!(
        PROT_MEM_TYPE.contains(&mem_type), // (3) make sure the event is correct
        "Invalid MemType provided to protection_fault_hook_proxy"
    );
    debug_assert!(
        address >= hook.start,
        "Trigger address: 0x{:x} is not >= hook.start(0x{:x})",
        address,
        hook.start
    );
    debug_assert!(
        address <= hook.end,
        "Trigger address: 0x{:x} is not <= hook.end(0x{:x})",
        address,
        hook.end
    );

    // (4) get the fault data for the callback
    let fault_bytes = value.to_le_bytes();
    let fault_data = match mem_type {
        unicorn_const::MemType::WRITE_PROT => MemFaultData::Write { data: &fault_bytes },
        // we map both the fetch and the read variant into `READ`
        _ => MemFaultData::Read,
    };

    let backend = hook.backend.upgrade().unwrap();

    // (5) get the permissions of the underlying memory region
    let perms = backend
        .memory_manager()
        .unwrap()
        .containing_region_perms(address, size as u64)
        .unwrap();

    // (6) call callback
    callback(&backend, address, size as u32, perms, fault_data)
}