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   (** Functions available in the map of kernel symbols to addresses. *)
  45
  46 type ksymmap = Virt_mem_mmap.addr Ksymmap.t
  47   (** Kernel symbol table (map of kernel symbols to addresses). *)
  48
  49 (** {2 Kernel memory images and associated metadata}
  50
  51     The kimage structure captures everything known about a kernel
  52     image, including the source domain details, kernel address, kernel
  53     symbols, kernel memory map, and all the kernel structures parsed
  54     out of the memory map.
  55 *)
  56
  57 type utsname = {
  58   uts_kernel_name : string;
  59   uts_nodename : string;
  60   uts_kernel_release : string;
  61   uts_kernel_version : string;
  62   uts_machine : string;
  63   uts_domainname : string;
  64 }
  65   (** Kernel version, from utsname structure in the kernel. *)
  66
  67 type kimage = {
  68   dom : Libvirt.ro Libvirt.Domain.t option; (** Domain, if known. *)
  69   domname : string;                     (** Domain name. *)
  70   arch : Virt_mem_utils.architecture;   (** Architecture, eg. i386. *)
  71
  72   kernel_min : Virt_mem_mmap.addr;      (** Minimum addr of kernel pointers. *)
  73   kernel_max : Virt_mem_mmap.addr;      (** Maximum addr of kernel pointers. *)
  74
  75   mem : ([`Wordsize], [`Endian], [`HasMapping]) Virt_mem_mmap.t;
  76                                         (** Memory map. *)
  77
  78   addrmap : Kernel.addrmap;             (** Parsed kernel structures. *)
  79
  80   ksyms : ksymmap;                      (** Kernel symbol table *)
  81
  82   have_ksyms : bool;                    (** True if we were able to load
  83                                             the kernel symbols. *)
  84   have_kallsyms : bool;                 (** True if we were able to load
  85                                             the kallsyms from the kernel. *)
  86
  87   utsname : utsname option;             (** Kernel version, if we were able
  88                                             to find it. *)
  89
  90   have_tasks : bool;                    (** True if we were able to load
  91                                             the kernel task_struct list. *)
  92   have_net_devices : bool;              (** True if we were able to load
  93                                             the kernel net_device structures.*)
  94 }
  95   (** A basic kernel image. *)
  96
  97 (** {2 Functions to load kernel memory} *)
  98
  99 type load_memory_error =
 100   | AddressOutOfRange          (** Address not in [kernel_min..kernel_max] *)
 101   | DomIsNull                  (** kimage.dom = None *)
 102
 103 exception LoadMemoryError of load_memory_error * string
 104
 105 val load_memory : kimage -> Virt_mem_mmap.addr -> int -> kimage
 106   (** [load_memory img start size] tries to load [size] bytes from
 107       the start address into the memory map.  If the memory was loaded
 108       previously, then it is not requested again.
 109
 110       Note that the memory map may be updated by this, so a modified
 111       image structure is returned.
 112
 113       This function can raise many different sorts of exceptions and
 114       the caller is advised to catch any exceptions and deal with them
 115       appropriately. *)
 116
 117 val load_static_memory : dom:Libvirt.ro Libvirt.Domain.t ->
 118   domname:string ->
 119   arch:Virt_mem_utils.architecture ->
 120   wordsize:Virt_mem_utils.wordsize -> endian:Bitstring.endian ->
 121   kernel_min:Virt_mem_mmap.addr -> kernel_max:Virt_mem_mmap.addr ->
 122   Virt_mem_mmap.addr -> int -> kimage
 123   (** [load_static_memory ~dom (*...*) start size] creates a [kimage]
 124       object, and initializes it with static kernel memory loaded
 125       from the [start] address and [size] of [dom].
 126
 127       See also {!load_memory} for exceptions this can raise. *)