Interface guest_vm.h
The guest vm interface is central to libsel4vm, providing definitions of the guest vm datastructure and primitives to run the VM instance and start its vcpus.
Brief content:
Functions:
vm_register_unhandled_mem_fault_callback(vm, fault_handler, cookie)
vm_register_notification_callback(vm, notification_callback, cookie)
Structs:
Functions
The interface guest_vm.h
defines the following functions.
Function vm_run(vm_t *vm)
Enter the VM event runtime loop. This funtion is a blocking call, returning on the event of an unhandled VM exit or error
Parameters:
vm {vm_t *}
: A handle to the VM to run
Returns:
- 0 on success, -1 on error
Back to interface description.
Function vcpu_start(vcpu)
Start an initialised vcpu thread
Parameters:
vcpu {vm_vcpu_t *}
: A handle to vcpu to start
Returns:
- 0 on success, -1 on error
Back to interface description.
Function vm_register_unhandled_mem_fault_callback(vm, fault_handler, cookie)
Register a callback for processing unhandled memory faults (memory regions not previously registered or reserved)
Parameters:
vm {vm_t *}
: A handle to the VMfault_handler {unhandled_mem_fault_callback_fn}
: A user supplied callback to process unhandled memory faultscookie {void *}
: A cookie to supply to the memory fault handler
Returns:
- 0 on success, -1 on error
Back to interface description.
Function vm_register_notification_callback(vm, notification_callback, cookie)
Register a callback for processing unhandled notifications (events unknown to libsel4vm)
Parameters:
vm {vm_t *}
: A handle to the VMnotification_callback {notification_callback_fn}
: A user supplied callback to process unhandled notificationscookie {void *}
: A cookie to supply to the callback
Returns:
- 0 on success, -1 on error
Back to interface description.
Structs
The interface guest_vm.h
defines the following structs.
Struct vm_ram_region
Structure representing individual RAM region. A VM can have multiple regions to represent its total RAM
Elements:
start {uintptr_t}
: Guest physical start address of regionsize {size_t}
: Size of region in bytesallocated {int}
: Whether or not this region has been ‘allocated’
Back to interface description.
Struct vm_mem
Structure representing VM memory managment
Elements:
vm_vspace {vspace_t}
: Guest VM’s vspacevm_vspace_root {vka_object_t}
: VKA allocated guest VM root vspacevmm_vspace {vspace_t}
: Hosts/VMMs vspacenum_ram_regions {int}
: Total number of registeredvm_ram_regions
Set {struct vm_ram_region *}
: of registeredvm_ram_regions
Initialised {vm_memory_reservation_cookie_t *}
: instance of vm memory interfaceunhandled_mem_fault_handler {unhandled_mem_fault_callback_fn}
: Registered callback for unhandled memory faultsunhandled_mem_fault_cookie {void *}
: User data passed onto unhandled mem fault callback
Back to interface description.
Struct vm_tcb
Structure used for TCB management within a VCPU
Elements:
tcb {vka_object_t}
: VKA allocated TCB objectsc {vka_object_t}
: VKA allocated scheduling contextpriority {int}
: VCPU scheduling priority
Back to interface description.
Struct vm_vcpu
Structure used to represent a VCPU
Elements:
vm {struct vm *}
: Parent VMvcpu {vka_object_t}
: VKA allocated vcpu objecttcb {struct vm_tcb}
: VCPUs TCB management structurevcpu_id {unsigned int}
: VCPU Identifiertarget_cpu {int}
: The target core the vcpu is assigned tovcpu_online {bool}
: Flag representing if the vcpu has been startedvcpu_arch {struct vm_vcpu_arch}
: Architecture specific vcpu properties
Back to interface description.
Struct vm_run
VM Runtime management structure
Elements:
exit_reason {int}
: Records last vm exit reasonnotification_callback {notification_callback_fn}
: Callback for processing unhandled notificationsnotification_callback_cookie {void *}
: A cookie to supply to the notification callback
Back to interface description.
Struct vm_cspace
VM cspace management structure
Elements:
cspace_obj {vka_object_t}
: VKA allocated cspace objectcspace_root_data {seL4_Word}
: cspace root data capability
Back to interface description.
Struct vm
Structure representing a VM instance
Elements:
arch {struct vm_arch}
: Architecture specfic vm structurenum_vcpus {unsigned int}
: Number of vcpus created for the VMvcpus {struct vm_vcpu*}
: vcpu’s belonging to the VMmem {struct vm_mem}
: Memory management structurerun {struct vm_run}
: VM Runtime management structurecspace {struct vm_cspace}
: VM CSpace management structurehost_endpoint {seL4_CPtr}
: Host/VMM endpoint.vm_run
waits on this enpointvka {vka_t *}
: Handle to virtual kernel allocator for seL4 kernel object allocationio_ops {ps_io_ops_t *}
: Handle to platforms io opssimple {simple_t *}
: Handle to hosts simple environmentvm_name {char *}
: String used to describe VM. Useful for debuggingvm_id {unsigned int}
: Identifier for VM. Useful for debuggingvm_initialised {bool}
: Boolean flagging whether VM is intialised or not
Back to interface description.
Back to top.