gasp_region

Synopsis:

#include <qvm/gasp.h>

void gasp_region_set(struct guest_system *gsp,
                     unsigned num_regions,
                     const struct gasp_region *rgn)

Arguments:

gsp: A pointer to the guest system.
num_regions: The number of region structures passed by the rgn argument.
rgn: A pointer to an array of gasp_region structures. For information about how the field settings in each structure determine whether the corresponding region gets added, modified, or deleted, see gasp_region_set_soft().

Description:

This function serves the same purpose as gasp_region_set_soft() but implicitly calls gasp_lock() and gasp_unlock() to ensure that another vdev cannot interfere while you are manipulating the guest address space. Another difference is that a fatal error causes it to terminate the running process (i.e., the qvm process instance with the vdev that called gasp_region_set()). To not terminate the running process on a fatal error, use gasp_region_set_soft() instead.

Example:

Regardless of how memory is laid out at configuration time, qvm splits memory into regions as necessary to ensure that the underlying host-physical memory is contiguous and to allow for different flag settings (including those changed at runtime by a vdev). The following example shows how to account for this when deleting memory regions:

/*
 * Before deleting memory regions, check if the memory has been split.
 * Here, blk points to a qvm_state_block struct, which sets the information for
 * the region being deleted. And rgn points to a gasp_region struct, which will
 * store the results from the function call that retrieves guest region
 * information, which includes the qvm_state_block struct inside.
 */

// blk.location is set first
remaining_length = blk.length;

while (remaining_length > 0) {
    if (gasp_region_info(gsp, &blk, &rgn) != EOK) {
        // error handling goes here
    }
    blk.length = rgn.guest.length;
    
    gasp_region_set(gsp, 1, &rgn);
    
    blk.location += blk.length;     // update to the next location
    remaining_length -= blk.length; // subtract length of region that was deleted
    blk.length = remaining_length;  // used for nexy gasp_region_info() query
}