claim_pages

Note

This API is deprecated; Use XEN_DOMCTL_claim_memory for new code.

XENMEM_claim_pages

Hypercall command for installing legacy claims.

Legacy claim installation describes the API for installing legacy claims via this hypercall command.

It passes a single claim entry to the hypervisor via a xen_memory_reservation structure with the page count in the xen_memory_reservation.nr_extents field and the domain ID xen_memory_reservation.domid field. The claim entry’s target is implicitly global, and the legacy claim path is invoked in the hypervisor to process the claim:

Data structure for the hypercall command for installing legacy claims:

struct xen_memory_reservation

Structure for passing claim requests to the hypervisor via XENMEM_claim_pages and other memory hypercalls.

struct xen_memory_reservation {
    xen_pfn_t  * extent_start; // not used for XENMEM_claim_pages
    xen_ulong_t  nr_extents;   // pass page counts to claim
    unsigned int extent_order; // must be 0
    unsigned int mem_flags;    // XENMEMF flags.
    domid_t      domid;        // domain to apply the claim to
};
typedef struct xen_memory_reservation xen_memory_reservation_t;

xen_ulong_t nr_extents

For XENMEM_claim_pages, the page count to claim.

domid_t domid

Domain ID for the claim.

unsigned int mem_flags

Not used for XENMEM_claim_pages (must be 0)

In principle, it supports all the XENMEMF_* flags, including the possibility of passing a single NUMA node ID, but using it to pass a NUMA node ID is not currently supported by the legacy claim path.

During review of the NUMA extension of the legacy claim path, it was used, but the request was made to instead create a new hypercall which is now XEN_DOMCTL_claim_memory with support for claim sets.

unsigned int extent_order

xen_pfn_t *extent_start

Both are not used for XENMEM_claim_pages, but are used for other memory hypercalls.

See Legacy claim installation for details.

API example using libxenctrl

The example below claims pages, populates the domain, and then clears the claim.

#include <xenctrl.h>

int build_with_claims(xc_interface *xch, uint32_t domid,
                      unsigned long nr_pages)
{
    int ret;

    /* Claim pages for the domain build. */
    ret = xc_domain_claim_pages(xch, domid, nr_pages);
    if ( ret < 0 )
        return ret;

    /* Populate the domain's physmap. */
    ret = xc_domain_populate_physmap(xch, domid, /* ... */);
    if ( ret < 0 )
        return ret;

    /* Release any remaining claim after populating the domain memory. */
    ret = xc_domain_claim_pages(xch, domid, 0);
    if ( ret < 0 )
        return ret;

    /* Unpause the domain to allow it to run. */
    return xc_unpause_domain(xch, domid);
}