Module Gnt.Gntshr

type interface

A connection to the gntshr device, needed for sharing/unmapping

val interface_open : unit -> interface

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

val interface_close : interface -> unit

Close a connection to the gntshr device. Any future calls to share or unmap will fail.

type share = {
refs : gntref list;

List of grant references which have been shared with a foreign domain.

mapping : Io_page.t;

Mapping of the shared memory.

}

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.

val share_pages_exn : interface -> int -> int -> bool -> share

share_pages_exn if domid count writable shares count pages with foreign domain domid. writable determines whether or not the foreign domain can write to the shared memory.

val share_pages : interface -> int -> int -> bool -> share option

share_pages if domid count writable shares count pages with foreign domain domid. writable determines whether or not the foreign domain can write to the shared memory. On error this function returns None. Diagnostic details will be logged.

val munmap_exn : interface -> share -> unit

Unmap a single mapping (which may involve multiple grants)

Low-level interface

exception Interface_unavailable

Raised when the low-level grant table interface is not available

val get : unit -> gntref Lwt.t

Allocate a single grant table index

val get_n : int -> gntref list Lwt.t

Allocate a block of n grant table indices

val put : gntref -> unit

Deallocate a grant table index

val get_nonblock : unit -> gntref option

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

val get_n_nonblock : int -> gntref list

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.

val num_free_grants : unit -> int

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

val with_ref : (gntref -> 'a Lwt.t) -> 'a Lwt.t
val with_refs : int -> (gntref list -> 'a Lwt.t) -> 'a Lwt.t
val grant_access : domid:int -> writable:bool -> gntref -> Io_page.t -> unit

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.

val end_access : gntref -> unit

end_access gntref removes entry index gntref from the grant table.

val with_grant : domid:int -> writable:bool -> gntref -> Io_page.t -> (unit -> 'a Lwt.t) -> 'a Lwt.t
val with_grants : domid:int -> writable:bool -> gntref list -> Io_page.t list -> (unit -> 'a Lwt.t) -> 'a Lwt.t
val with_gntshr : (interface -> 'a) -> 'a

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