Xen Internal - grant tables

Xen's grant tables provide a generic mechanism to memory sharing between domains. This shared memory interface underpins the split device drivers for block and network IO.

Each domain has its own grant table. This is a data structure that is shared with Xen; it allows the domain to tell Xen what kind of permissions other domains have on its pages. Entries in the grant table are identified by grant references. A grant reference is an integer, which indexes into the grant table. It acts as a capability which the grantee can use to perform operations on the granter's memory.

This capability-based system allows shared-memory communications between unprivileged domains. A grant reference also encapsulates the details of a shared page, removing the need for a domain to know the real machine address of a page it is sharing. This makes it possible to share memory correctly with domains running in fully virtualised memory.

6.1.1 Grant table manipulation

Creating and destroying grant references is done by direct access to the grant table. This removes the need to involve Xen when creating grant references, modifying access permissions, etc. The grantee domain will invoke hypercalls to use the grant references. Four main operations can be accomplished by directly manipulating the table:

Grant foreign access

allocate a new entry in the grant table and fill out the access permissions accordingly. The access permissions will be looked up by Xen when the grantee attempts to use the reference to map the granted frame.

End foreign access

check that the grant reference is not currently in use, then remove the mapping permissions for the frame. This prevents further mappings from taking place but does not allow forced revocations of existing mappings.

Grant foreign transfer

allocate a new entry in the table specifying transfer permissions for the grantee. Xen will look up this entry when the grantee attempts to transfer a frame to the granter.

End foreign transfer

remove permissions to prevent a transfer occurring in future. If the transfer is already committed, modifying the grant table cannot prevent it from completing.

Use of grant references is accomplished via a hypercall. The grant table op hypercall takes three arguments:

grant_table_op(unsigned int cmd, void *uop, unsigned int count)

cmd indicates the grant table operation of interest. uop is a pointer to a structure (or an array of structures) describing the operation to be performed. The count field describes how many grant table operations are being batched together.

The core logic is situated in xen/common/grant_table.c. The grant table operation hypercall can be used to perform the following actions:

GNTTABOP_map_grant_ref

Given a grant reference from another domain, map the referred page into the caller's address space.

GNTTABOP_unmap_grant_ref

Remove a mapping to a granted frame from the caller's address space. This is used to voluntarily relinquish a mapping to a granted page.

GNTTABOP_setup_table

Setup grant table for caller domain.

GNTTABOP_dump_table

Debugging operation.

GNTTABOP_transfer

Given a transfer reference from another domain, transfer ownership of a page frame to that domain.