mirage-xen 8.0.2 · OCaml Package

type t

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 refs : t -> Gntref.t list

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

val mapping : t -> Io_page.t

Mapping of the shared memory.

val share_pages : 
  domid:int ->
  count:int ->
  writable:bool ->
  (t, [> `Grant_table_full ]) Stdlib.result

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).

val share_pages_exn : domid:int -> count:int -> writable:bool -> t

val try_unshare : release_refs:bool -> t -> (unit, [> `Busy ]) Stdlib.result

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.

val unshare : release_refs:bool -> t -> unit Lwt.t

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

Low-level interface

val get : unit -> Gntref.t Lwt.t

Allocate a single grant table index

val get_n : int -> Gntref.t list Lwt.t

Allocate a block of n grant table indices

val put : Gntref.t -> unit

Deallocate a grant table index.

val get_nonblock : unit -> Gntref.t option

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

val get_n_nonblock : int -> Gntref.t 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.t -> 'a Lwt.t) -> 'a Lwt.t

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

val with_refs : int -> (Gntref.t list -> 'a Lwt.t) -> 'a Lwt.t

val grant_access : domid:int -> writable:bool -> Gntref.t -> 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. You must call end_access later to unshare the page.

val try_end_access : 
  release_ref:bool ->
  Gntref.t ->
  (unit, [> `Busy ]) Stdlib.result

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.

val end_access : release_ref:bool -> Gntref.t -> unit Lwt.t

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.

val with_grant : 
  domid:int ->
  writable:bool ->
  Gntref.t ->
  Io_page.t ->
  (unit -> 'a Lwt.t) ->
  'a Lwt.t

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

val with_grants : 
  domid:int ->
  writable:bool ->
  Gntref.t list ->
  Io_page.t list ->
  (unit -> 'a Lwt.t) ->
  'a Lwt.t

package mirage-xen

Low-level interface