gasp_map_firmware()

Map a guest-physical address range into the qvm process address space for virtual firmware access

Synopsis:

#include <qvm/gasp.h>
errno_t gasp_map_firmware(uint64_t guest_paddr,
                          size_t length,
                          gasp_map_flags_t prot,
                          gasp_map_handle_t *h)

Arguments:

guest_paddr
The starting guest-physical address to be mapped in.
length
The number of bytes to be mapped in.
prot
A bitfield of GMF_* constants specifying the access protection bits for the mapping, including possibly GMF_MAP_ANY.
h
A pointer to a gasp_map_handle_t object that is initialized upon a successful return.

Description:

Use the gasp_map_firmware() function to emulate a vCPU accessing memory. This function attempts to map length bytes from guest-physical memory beginning at guest_paddr to provide access to virtual firmware in the VM.

When deciding whether to use gasp_map_firmware() or gasp_map(), consider the following:
  • If you have allocated the guest-physical address, use gasp_map_firmware() unless you know it makes sense to allow the guest to decide if the mapping is permitted.
  • If the guest has provided the guest-physical address you want to map, use gasp_map() because with this function the mapping goes through the guest-controlled simulated IOMMU.

The above are guidelines, and your design may require that you use the function not recommended here. In this case, be sure that you can justify your decision and you understand the implications of not following these guidelines.

If successful, the function fills in the object pointed to by h with a handle for this new mapping. You can then use this handle to obtain the virtual address for the mapped address range by calling gasp_get_vaddr().

When you're done using the address range, call gasp_unmap_handle() to unmap it.

Returns:

EOK on success, an error code on failure.

Errors:

ENXIO
One of the following is true:
  • The guest-physical address is invalid
  • The prot flag combination is invalid
  • There's no contiguous guest-physical address range that can accommodate the requested mapping

In addition to the errors listed above, this function may return any error returned by mmap(). For more information, refer to the mmap() entry in the C Library Reference.

Page updated: