lib/virt_mem_types.mli

   1 (** Common types. *)
   2 (* Memory info command for virtual domains.
   3    (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
   4    http://libvirt.org/
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 2 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software
  18    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  19
  20    Common types.
  21  *)
  22
  23 (** {2 Kernel symbols} *)
  24
  25 type ksym = string
  26   (** A kernel symbol. *)
  27
  28 module Ksymmap : sig
  29   type key = String.t
  30   type 'a t = 'a Map.Make(String).t
  31   val empty : 'a t
  32   val is_empty : 'a t -> bool
  33   val add : key -> 'a -> 'a t -> 'a t
  34   val find : key -> 'a t -> 'a
  35   val remove : key -> 'a t -> 'a t
  36   val mem : key -> 'a t -> bool
  37   val iter : (key -> 'a -> unit) -> 'a t -> unit
  38   val map : ('a -> 'b) -> 'a t -> 'b t
  39   val mapi : (key -> 'a -> 'b) -> 'a t -> 'b t
  40   val fold : (key -> 'a -> 'b -> 'b) -> 'a t -> 'b -> 'b
  41   val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
  42   val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
  43 end
  44   (** A map of kernel symbols to addresses. *)
  45
  46 (** {2 Kernel images and associated data} *)
  47
  48 type utsname = {
  49   kernel_name : string;
  50   nodename : string;
  51   kernel_release : string;
  52   kernel_version : string;
  53   machine : string;
  54   domainname : string;
  55 }
  56   (** Kernel version, from utsname structure in the kernel. *)
  57
  58 type image0 = {
  59   dom : Libvirt.ro Libvirt.Domain.t option; (** Domain, if known. *)
  60   domname : string;                     (** Domain name. *)
  61   arch : Virt_mem_utils.architecture;   (** Architecture, eg. i386. *)
  62   mem : ([`Wordsize], [`Endian], [`HasMapping]) Virt_mem_mmap.t;
  63                                         (** Memory map. *)
  64   kernel_min : Virt_mem_mmap.addr;      (** Minimum addr of kernel pointers. *)
  65   kernel_max : Virt_mem_mmap.addr;      (** Maximum addr of kernel pointers. *)
  66 }
  67   (** A basic kernel image. *)
  68
  69 type image1 =
  70     image0
  71     * Virt_mem_mmap.addr Ksymmap.t      (* Kernel symbol map. *)
  72   (** A kernel image, after finding kernel symbols. *)
  73
  74 type image2 =
  75     image0
  76     * Virt_mem_mmap.addr Ksymmap.t      (* Kernel symbol map. *)
  77     * utsname option                    (* Kernel version, etc., if found. *)
  78   (** A kernel image, after finding kernel version (like 'uname'). *)
  79
  80 (** {2 Load kernel memory} *)
  81
  82 type load_memory_error =
  83   | AddressOutOfRange           (** Address not in [kernel_min..kernel_max] *)
  84   | DomIsNull                   (** image.dom = None *)
  85
  86 exception LoadMemoryError of load_memory_error * string
  87
  88 val load_static_memory : dom:Libvirt.ro Libvirt.Domain.t ->
  89   domname:string ->
  90   arch:Virt_mem_utils.architecture ->
  91   wordsize:Virt_mem_utils.wordsize -> endian:Bitstring.endian ->
  92   kernel_min:Virt_mem_mmap.addr -> kernel_max:Virt_mem_mmap.addr ->
  93   Virt_mem_mmap.addr -> int -> image0
  94   (** [load_static_memory ~dom (*...*) start size] creates an [image0]
  95       object, and initializes it with static kernel memory loaded
  96       from the [start] address and [size] of [dom].
  97
  98       See also {!load_memory} for exceptions this can raise. *)
  99
 100 val load_memory : image0 -> Virt_mem_mmap.addr -> int -> image0
 101   (** [load_memory img start size] tries to load [size] bytes from
 102       the start address into the memory map.  If the memory was loaded
 103       previously, then it is not requested again.
 104
 105       Note that the memory map may be updated by this, so a modified
 106       image structure is returned.
 107
 108       This function can raise many different sorts of exceptions and
 109       the caller is advised to catch any exceptions and deal with them
 110       appropriately. *)