package mirage-xen

When sharing a number of pages with another domain, we receive back both the list of grant references shared and actually mapped page(s). The foreign domain can map the same shared memory, after being notified (e.g. via xenstore) of our domid and list of references.

The grant references that have been shared with the foreign domain.

Mapping of the shared memory.

share_pages ~domid ~count ~writable shares count pages with foreign domain domid. writable determines whether or not the foreign domain can write to the shared memory. You must not allow the returned share to be GC'd before successfully calling unshare on it (if you do, the memory and grant ref will be leaked).

try_unshare ~release_refs t unshares a single mapping (which may involve multiple grants). If release_refs = true then it also calls put on each grant. If it encounters a grant that is still in use then it stops and returns Error `Busy, with t containing the remaining grants. In this case, you must call try_unshare again later to retry.

Like try_unshare, but keeps trying until all pages have been unshared.

Allocate a single grant table index

Allocate a block of n grant table indices

Deallocate a grant table index.

get_nonblock () is Some idx if the grant table is not full, or None otherwise.

get_n_nonblock count is a list of grant table indices of length count, or [] if there if the table is too full to accomodate count new grant references.

num_free_grants () returns the number of instantaneously free grant table indices

with_ref f allocates a grant with get, passes it to f, and then puts it.

grant_access ~domid ~writable gntref page adds a grant table entry at index gntref to the grant table, granting access to domid to read page, and write to is as well if writable is true. You must call end_access later to unshare the page.

try_end_access gntref removes entry index gntref from the grant table. If release_ref = true then it also calls put gntref on success. If the remote domain is still using the grant then it returns Error `Busy instead.

Like try_end_access, but if the remote domain is still using the grant then it sleeps for 10 seconds and tries again, until it succeeds.

with_grant ~domid ~writable gntref page f shares access to page with domid, calls f () and then unshares the page.