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 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 (** {2 Kernel structures internal format}
  63
  64     So that we don't need to reiterate over certain important
  65     kernel structures in each tool, we convert them into a more
  66     convenient internal format.
  67
  68     See {!Virt_mem_tasks}, {!Virt_mem_net_devices}.
  69 *)
  70
  71 type utsname = {
  72   uts_kernel_name : string;
  73   uts_nodename : string;
  74   uts_kernel_release : string;
  75   uts_kernel_version : string;
  76   uts_machine : string;
  77   uts_domainname : string;
  78 }
  79   (** Kernel version, from utsname structure in the kernel. *)
  80
  81 type task = {
  82   task_state : int64;
  83   task_prio : int64;
  84   task_normal_prio : int64;
  85   task_static_prio : int64;
  86   task_comm : string;                   (** Short command name. *)
  87   task_pid : int64;                     (** Process ID. *)
  88 }
  89   (** Internal version of the kernel [task_struct]. *)
  90
  91 type net_device = {
  92   netdev_name : string;                 (** Device name. *)
  93   netdev_flags : int64;
  94   netdev_operstate : int64;
  95   netdev_mtu : int64;
  96   netdev_perm_addr : string;
  97   netdev_addr_len : int64;
  98 }
  99   (** Internal version of the kernel [net_device] (network device struct). *)
 100
 101 type kdata = {
 102   ksyms : ksymmap option;        (** Kernel symbol lookup function. *)
 103   utsname : utsname option;      (** Kernel version. *)
 104   tasks : task list option;      (** List of tasks (processes). *)
 105   net_devices : net_device list option; (** List of net devices. *)
 106 }
 107   (** Optional data derived from the raw kernel image by the main
 108       program and passed to the tools' [~run] functions.
 109
 110       What fields get filled in is controlled by the [~needs_*]
 111       options passed when tools register themselves, and also of
 112       course by what we are able to find out about the memory image
 113       (see {!Virt_mem.register}).
 114
 115       Note there is significant cost to filling in some of these
 116       fields.
 117 *)
 118
 119 (** {2 Helper declarations for kernel structure parsers}
 120
 121     The kernel structure parsers (in {!Kernel_task_struct} et al (see
 122     [lib/kernel_*])) share a few common types declared here.
 123
 124     Note that the parsers themselves are generated automatically.
 125 *)
 126
 127 exception ParseError of string * string * string
 128   (** Parsing exception raised by [Kernel_*] parser functions.
 129
 130       The fields are: structure name, function which raised the error,
 131       error message. *)
 132
 133 type fieldsig = {
 134   field_available : bool; (** Field available in this kernel version? *)
 135   field_offset : int;    (** Offset of field in this kernel version. *)
 136 }
 137   (** Returned by [Kernel_*.field_signature_of_*] functions. *)
 138
 139 (** {2 Functions to load kernel memory} *)
 140
 141 type load_memory_error =
 142   | AddressOutOfRange          (** Address not in [kernel_min..kernel_max] *)
 143   | DomIsNull                  (** image.dom = None *)
 144
 145 exception LoadMemoryError of load_memory_error * string
 146
 147 val load_memory : image -> Virt_mem_mmap.addr -> int -> image
 148   (** [load_memory img start size] tries to load [size] bytes from
 149       the start address into the memory map.  If the memory was loaded
 150       previously, then it is not requested again.
 151
 152       Note that the memory map may be updated by this, so a modified
 153       image structure is returned.
 154
 155       This function can raise many different sorts of exceptions and
 156       the caller is advised to catch any exceptions and deal with them
 157       appropriately. *)
 158
 159 val load_static_memory : dom:Libvirt.ro Libvirt.Domain.t ->
 160   domname:string ->
 161   arch:Virt_mem_utils.architecture ->
 162   wordsize:Virt_mem_utils.wordsize -> endian:Bitstring.endian ->
 163   kernel_min:Virt_mem_mmap.addr -> kernel_max:Virt_mem_mmap.addr ->
 164   Virt_mem_mmap.addr -> int -> image
 165   (** [load_static_memory ~dom (*...*) start size] creates an [image0]
 166       object, and initializes it with static kernel memory loaded
 167       from the [start] address and [size] of [dom].
 168
 169       See also {!load_memory} for exceptions this can raise. *)