Attribute Macro simics::simics_exception

#[simics_exception]

Marks a function as being a SIMICS API that can throw exceptions in called FFI APIs.

A SIMICS exception can be generated by most APIs. This macro makes the function private, wraps it, and adds the requisite code to check for and report exceptions. clear_exception should not be called inside the wrapped function. last_error may be called, however, as any exceptions will be cleared after the wrapped function returns.

Examples

Add the #[simics_exception] attribute to a function which calls a SIMICS API that can throw exceptions. The function will be wrapped and the requisite code to check for and report exceptions will be added.

#[simics_exception]
pub fn write_byte(physical_memory: *mut ConfObject, physical_addr: u64, byte: u8) {
    unsafe { SIM_write_byte(physical_memory, physical_addr, byte) };
}

This expands to:

fn _write_byte(physical_memory: *mut ConfObject, physical_addr: u64, byte: u8) {
    unsafe { SIM_write_byte(physical_memory, physical_addr, byte) };
}

pub fn write_byte(physical_memory: *mut ConfObject, physical_addr: u64, byte: u8) -> Result<()> {
    let res = _write_byte(physical_memory, physical_addr, byte);

    match simics::get_pending_exception() {
        SimException::SimExc_No_Exception => Ok(()),
        exception => {
            clear_exception();
            Err(Error::from(exception))
        }
    }
}