A foreign domain must explicitly "grant" us memory and send us the "reference". The pair of (foreign domain id, reference) uniquely identifies the block of memory. This pair ("grant") is transmitted to us out-of-band, usually either via xenstore during device setup or via a shared memory ring structure.

map_exn grant ~writable creates a single mapping from grant that will be writable if writable is true.

Like the above but wraps the result in a result type instead of raising an exception.

mapv_exn grants ~writable creates a single contiguous mapping from a list of grants that will be writable if writable is true. Note the grant list can involve grants from multiple domains. If the mapping fails (because at least one grant fails to be mapped), then all grants are unmapped.

Like the above but wraps the result in a result type instead of raising an exception.

with_mapping grant ~writable f maps grant, calls f on the result, and then unmaps it. Returns Error _ if the map operation fails.