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 images and associated data} *)
  50
  51 type image = {
  52   dom : Libvirt.ro Libvirt.Domain.t option; (** Domain, if known. *)
  53   domname : string;                     (** Domain name. *)
  54   arch : Virt_mem_utils.architecture;   (** Architecture, eg. i386. *)
  55   mem : ([`Wordsize], [`Endian], [`HasMapping]) Virt_mem_mmap.t;
  56                                         (** Memory map. *)
  57   kernel_min : Virt_mem_mmap.addr;      (** Minimum addr of kernel pointers. *)
  58   kernel_max : Virt_mem_mmap.addr;      (** Maximum addr of kernel pointers. *)
  59 }
  60   (** A basic kernel image. *)
  61
  62 type utsname = {
  63   kernel_name : string;
  64   nodename : string;
  65   kernel_release : string;
  66   kernel_version : string;
  67   machine : string;
  68   domainname : string;
  69 }
  70   (** Kernel version, from utsname structure in the kernel. *)
  71
  72 type kdata = {
  73   ksyms : ksymmap option;               (** Kernel symbol lookup function. *)
  74   utsname : utsname option;             (** Kernel version. *)
  75   tasks : Virt_mem_mmap.addr option;    (** Linked list of tasks (processes)
  76                                             starting at the address of
  77                                             init_task (swapper). *)
  78   net_devices : Virt_mem_mmap.addr option; (** Linked list of net devices
  79                                                starting at the address of
  80                                                dev_base_head. *)
  81 }
  82   (** Optional data derived from the raw kernel image by the main
  83       program and passed to the tools' [~run] functions.
  84
  85       What fields get filled in is controlled by the [~needs_*]
  86       options passed when tools register themselves, and also of
  87       course by what we are able to find out about the memory image.
  88
  89       Note there is significant cost to filling in some of these
  90       fields.
  91 *)
  92
  93 (** {2 Kernel structure parsers} *)
  94
  95 exception ParseError of string * string * string
  96   (** Parsing exception raised by [Kernel_*] parser functions.
  97
  98       The fields are: structure name, function which raised the error,
  99       error message. *)
 100
 101 type fieldsig = {
 102   field_available : bool; (** Field available in this kernel version? *)
 103   field_offset : int;    (** Offset of field in this kernel version. *)
 104 }
 105   (** Returned by [Kernel_*.field_signature_of_*] functions. *)
 106
 107 (** {2 Load kernel memory} *)
 108
 109 type load_memory_error =
 110   | AddressOutOfRange          (** Address not in [kernel_min..kernel_max] *)
 111   | DomIsNull                  (** image.dom = None *)
 112
 113 exception LoadMemoryError of load_memory_error * string
 114
 115 val load_memory : image -> Virt_mem_mmap.addr -> int -> image
 116   (** [load_memory img start size] tries to load [size] bytes from
 117       the start address into the memory map.  If the memory was loaded
 118       previously, then it is not requested again.
 119
 120       Note that the memory map may be updated by this, so a modified
 121       image structure is returned.
 122
 123       This function can raise many different sorts of exceptions and
 124       the caller is advised to catch any exceptions and deal with them
 125       appropriately. *)
 126
 127 val load_static_memory : dom:Libvirt.ro Libvirt.Domain.t ->
 128   domname:string ->
 129   arch:Virt_mem_utils.architecture ->
 130   wordsize:Virt_mem_utils.wordsize -> endian:Bitstring.endian ->
 131   kernel_min:Virt_mem_mmap.addr -> kernel_max:Virt_mem_mmap.addr ->
 132   Virt_mem_mmap.addr -> int -> image
 133   (** [load_static_memory ~dom (*...*) start size] creates an [image0]
 134       object, and initializes it with static kernel memory loaded
 135       from the [start] address and [size] of [dom].
 136
 137       See also {!load_memory} for exceptions this can raise. *)