Module Gnt.Gnttab

type interface

A connection to the grant device, needed for mapping/unmapping

val interface_open : unit -> interface

Open a connection to the grant device. This must be done before any calls to map or unmap.

val interface_close : interface -> unit

Close a connection to the grant device. Any future calls to map or unmap will fail.

type grant = {
  1. domid : int;
    (*

    foreign domain who is exporting memory

    *)
  2. ref : gntref;
    (*

    id which identifies the specific export in the foreign domain

    *)
}

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.

module Local_mapping : sig ... end
val map_exn : interface -> grant -> bool -> Local_mapping.t

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

val map : interface -> grant -> bool -> Local_mapping.t option

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

val mapv_exn : interface -> grant list -> bool -> Local_mapping.t

mapv_exn if 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.

val mapv : interface -> grant list -> bool -> Local_mapping.t option

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

val unmap_exn : interface -> Local_mapping.t -> unit

Unmap a single mapping (which may involve multiple grants). Throws a Failure if unsuccessful.

val with_gnttab : (interface -> 'a) -> 'a

with_gnttab f opens an interface to gnttab, passes it to f, then returns the result of f (or re-raises any exceptions) ensuring that the gnttab interface is closed before returning.

val with_mapping : interface -> grant -> bool -> (Local_mapping.t option -> 'a Lwt.t) -> 'a Lwt.t

with_mapping if grant writable f maps grant and calls f on the result.