Crate axvisor_api

Source
Expand description

axvisor_api is a library that provides:

  • a set of Rust API for all components of the axvisor Hypervisor, including:

    • memory management,
    • time and timer management,
    • interrupt management,

    these APIs are defined here, should be implemented by the axvisor Hypervisor, and can be use by all components.

  • a standard way to define and implement APIs, including the api_mod and the api_mod_impl attributes, which the components can utilize to define and implement their own APIs.

§How to define and implement APIs

§Define APIs

To define APIs, you can use the api_mod attribute to define a module containing the API functions. An API function is defined with the extern fn syntax. Note that Vanilla Rust does not support defining extern functions in such a way, so the definition of the API functions can easily be distinguished from the regular functions.

#[api_mod]
/// Memory-related API
pub mod memory_demo {
    pub use memory_addr::PhysAddr;

    /// Allocate a frame
    extern fn alloc_frame() -> Option<PhysAddr>;
    /// Deallocate a frame
    extern fn dealloc_frame(addr: PhysAddr);
}

Defined APIs can be invoked by other components:

struct SomeComponent;

impl SomeComponent {
    fn some_method() {
        let frame = memory_demo::alloc_frame().unwrap();
        // Do something with the frame
        memory_demo::dealloc_frame(frame);
    }
}

§Implement APIs

Defined APIs should be implemented by the Hypervisor, or other components that are able and responsible to do so. To implement APIs, you can use the api_mod_impl attribute, with the path of the module defining the APIs as the argument, on a module containing the implementation of the API functions. The implementations of the API functions are also defined with the extern fn syntax.

#[api_mod_impl(memory_demo)]
mod memory_impl {
    use memory_addr::PhysAddr;

    extern fn alloc_frame() -> Option<PhysAddr> {
        // Implementation of the `alloc_frame` API
        todo!()
    }

    extern fn dealloc_frame(addr: PhysAddr) {
        // Implementation of the `dealloc_frame` API
        todo!()
    }
}

§Tricks behind the macros

api_mod and api_mod_impl are wrappers around the great crate_interface crate, with some macro tricks to make the usage more convenient.

Modules§

arch
This module contains 5 API functions to be implemented:
host
This module contains 1 API function to be implemented:
memory
Memory-related API.
time
Time-and-timer-related API.
vmm
Virtual machine management API.

Attribute Macros§

api_mod
Define a module containing API functions.
api_mod_impl
Implement the API functions defined in another module.