Interface guest_ram.h
The libsel4vm RAM interface provides us with a set of methods to manage a guest VM’s RAM. This involves functions to register, allocate and copy to and from RAM regions.
Brief content:
Functions:
vm_guest_ram_read_callback(vm, guest_addr, vaddr, size, offset, buf)
vm_guest_ram_write_callback(vm, guest_addr, vaddr, size, offset, buf)
Functions
The interface guest_ram.h
defines the following functions.
Function vm_guest_ram_read_callback(vm, guest_addr, vaddr, size, offset, buf)
Common guest ram touch callback for reading from a guest address into a user supplied buffer
Parameters:
vm {vm_t *}
: A handle to the VMguest_addr {uintptr_t}
: Guest physical address to read fromvmm_vaddr {void *}
: Virtual address in hosts (vmm) vspace corresponding with the ‘guest_addr’size {size_t}
: Size of region being currently accessedoffset {size_t}
: Current offset from the base guest physical address supplied to ‘vm_ram_touch’cookie {void *}
: User supplied buffer to store read data into
Returns:
- 0 on success, -1 on error
Back to interface description.
Function vm_guest_ram_write_callback(vm, guest_addr, vaddr, size, offset, buf)
Common guest ram touch callback for writing a user supplied buffer into a guest address
Parameters:
vm {vm_t *}
: A handle to the VMguest_addr {uintptr_t}
: Guest physical address to write tovmm_vaddr {void *}
: Virtual address in hosts (vmm) vspace corresponding with the ‘guest_addr’size {size_t}
: Size of region being currently accessedoffset {size_t}
: Current offset from the base guest physical address supplied to ‘vm_ram_touch’cookie {void *}
: User supplied buffer to write data from
Returns:
- 0 on success, -1 on error
Back to interface description.
Function vm_ram_touch(vm, addr, size, touch_callback, cookie)
Touch a series of pages in the guest vm and invoke a callback for each page accessed
Parameters:
vm {vm_t *}
: A handle to the VMaddr {uintptr_t}
: Address to access in the guest vmsize {size_t}
: Size of memory region to accesscallback {ram_touch_callback_fn}
: Callback to invoke on each page accesscookie {void *}
: User data to pass onto callback
Returns:
- 0 on success, -1 on error
Back to interface description.
Function vm_ram_find_largest_free_region(vm, addr, size)
Find the largest free ram region
Parameters:
vm {vm_t *}
: A handle to the VMaddr {uintptr_t *}
: Pointer to be set with largest region addresssize {size_t *}
: Pointer to be set with largest region size
Returns:
- -1 on failure, otherwise 0 for success
Back to interface description.
Function vm_ram_register(vm, bytes)
Reserve a region of memory for RAM in the guest VM
Parameters:
vm {vm_t *}
: A handle to the VMbytes {size_t}
: Size of RAM region to allocate
Returns:
- Starting address of registered ram region
Back to interface description.
Function vm_ram_register_at(vm, start, bytes, untyped)
Reserve a region of memory for RAM in the guest VM at a starting guest physical address
Parameters:
vm {vm_t *}
: A handle to the VM that ram needs to be allocated forstart {uintptr_t}
: Starting guest physical address of the ram region being allocatedsize {size_t}
: The size of the RAM region to be allocateduntyped {bool}
: Allocate RAM frames such that it uses untyped memory
Returns:
- 0 on success, -1 on error
Back to interface description.
Function vm_ram_mark_allocated(vm, start, bytes)
Mark a registered region of RAM as allocated
Parameters:
vm {vm_t *}
: A handle to the VMstart {uintptr_t}
: Starting address of guest ram regionbytes {size_t}
: Size of RAM region
Returns:
No return
Back to interface description.
Function vm_ram_allocate(vm, bytes)
Allocate a region of registered ram
Parameters:
vm {vm_t *}
: A handle to the VMbytes {size_t}
: Size of allocation
Returns:
- Starting address of allocated ram region
Back to interface description.
Function vm_ram_free(vm, start, bytes)
Free a RAM a previously allocated RAM region
Parameters:
vm {vm_t *}
: A handle to the VM that ram needs to be free’d forstart {uintptr_t}
: Starting guest physical address of the ram region being free’dsize {size_t}
: The size of the RAM region to be free’d
Returns:
No return
Back to interface description.
Back to top.