X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=lib%2Fvirt_mem_types.mli;h=ff4f147d199dc6cf51f9775cf811376c425926d3;hb=4b90a4d2fc09e7aabc40909aba93e06938aeec27;hp=24ce3e747ed93192da5fa8501efe4dc02d79d3db;hpb=e7fad361d3dbf1689a22fdd1ae5f5579d6ef5fb0;p=virt-mem.git

diff --git a/lib/virt_mem_types.mli b/lib/virt_mem_types.mli
index 24ce3e7..ff4f147 100644
--- a/lib/virt_mem_types.mli
+++ b/lib/virt_mem_types.mli
@@ -20,6 +20,8 @@
    Common types.
  *)
 
+(** {2 Kernel symbols} *)
+
 type ksym = string
   (** A kernel symbol. *)
 
@@ -39,34 +41,129 @@ module Ksymmap : sig
   val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
   val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
 end
-  (** A map of kernel symbols to addresses. *)
+  (** Functions available in the map of kernel symbols to addresses. *)
 
-type utsname = {
-  kernel_name : string;
-  nodename : string;
-  kernel_release : string;
-  kernel_version : string;
-  machine : string;
-  domainname : string;
-}
-  (** Kernel version, from utsname structure in the kernel. *)
+type ksymmap = Virt_mem_mmap.addr Ksymmap.t
+  (** Kernel symbol table (map of kernel symbols to addresses). *)
+
+(** {2 Kernel memory images and associated metadata} *)
 
-type image0 = {
+type image = {
   dom : Libvirt.ro Libvirt.Domain.t option; (** Domain, if known. *)
   domname : string;			(** Domain name. *)
   arch : Virt_mem_utils.architecture;	(** Architecture, eg. i386. *)
   mem : ([`Wordsize], [`Endian], [`HasMapping]) Virt_mem_mmap.t;
                                         (** Memory map. *)
+  kernel_min : Virt_mem_mmap.addr;	(** Minimum addr of kernel pointers. *)
+  kernel_max : Virt_mem_mmap.addr;	(** Maximum addr of kernel pointers. *)
 }
   (** A basic kernel image. *)
 
-type image1 =
-    image0
-    * Virt_mem_mmap.addr Ksymmap.t	(* Kernel symbol map. *)
-  (** A kernel image, after finding kernel symbols. *)
+(** {2 Kernel structures internal format}
+
+    So that we don't need to reiterate over certain important
+    kernel structures in each tool, we convert them into a more
+    convenient internal format.
+
+    See {!Virt_mem_tasks}, {!Virt_mem_net_devices}.
+*)
+
+type utsname = {
+  uts_kernel_name : string;
+  uts_nodename : string;
+  uts_kernel_release : string;
+  uts_kernel_version : string;
+  uts_machine : string;
+  uts_domainname : string;
+}
+  (** Kernel version, from utsname structure in the kernel. *)
+
+type task = {
+  task_state : int64;
+  task_prio : int64;
+  task_normal_prio : int64;
+  task_static_prio : int64;
+  task_comm : string;			(** Short command name. *)
+  task_pid : int64;			(** Process ID. *)
+}
+  (** Internal version of the kernel [task_struct]. *)
+
+type net_device = {
+  netdev_name : string;			(** Device name. *)
+  netdev_flags : int64;
+  netdev_operstate : int64;
+  netdev_mtu : int64;
+  netdev_perm_addr : string;
+  netdev_addr_len : int64;
+}
+  (** Internal version of the kernel [net_device] (network device struct). *)
+
+type kdata = {
+  ksyms : ksymmap option;	 (** Kernel symbol lookup function. *)
+  utsname : utsname option;	 (** Kernel version. *)
+  tasks : task list option;	 (** List of tasks (processes). *)
+  net_devices : net_device list option; (** List of net devices. *)
+}
+  (** Optional data derived from the raw kernel image by the main
+      program and passed to the tools' [~run] functions.
+
+      What fields get filled in is controlled by the [~needs_*]
+      options passed when tools register themselves, and also of
+      course by what we are able to find out about the memory image
+      (see {!Virt_mem.register}).
+
+      Note there is significant cost to filling in some of these
+      fields.
+*)
+
+(** {2 Helper declarations for kernel structure parsers}
+
+    The kernel structure parsers (in {!Kernel_task_struct} et al (see
+    [lib/kernel_*])) share a few common types declared here.
+
+    Note that the parsers themselves are generated automatically.
+*)
+
+exception ParseError of string * string * string
+  (** Parsing exception raised by [Kernel_*] parser functions.
+
+      The fields are: structure name, function which raised the error,
+      error message. *)
+
+type fieldsig = {
+  field_available : bool; (** Field available in this kernel version? *)
+  field_offset : int;	 (** Offset of field in this kernel version. *)
+}
+  (** Returned by [Kernel_*.field_signature_of_*] functions. *)
+
+(** {2 Functions to load kernel memory} *)
+
+type load_memory_error =
+  | AddressOutOfRange          (** Address not in [kernel_min..kernel_max] *)
+  | DomIsNull                  (** image.dom = None *)
+
+exception LoadMemoryError of load_memory_error * string
+
+val load_memory : image -> Virt_mem_mmap.addr -> int -> image
+  (** [load_memory img start size] tries to load [size] bytes from
+      the start address into the memory map.  If the memory was loaded
+      previously, then it is not requested again.
+
+      Note that the memory map may be updated by this, so a modified
+      image structure is returned.
+
+      This function can raise many different sorts of exceptions and
+      the caller is advised to catch any exceptions and deal with them
+      appropriately. *)
+
+val load_static_memory : dom:Libvirt.ro Libvirt.Domain.t ->
+  domname:string ->
+  arch:Virt_mem_utils.architecture ->
+  wordsize:Virt_mem_utils.wordsize -> endian:Bitstring.endian ->
+  kernel_min:Virt_mem_mmap.addr -> kernel_max:Virt_mem_mmap.addr ->
+  Virt_mem_mmap.addr -> int -> image
+  (** [load_static_memory ~dom (*...*) start size] creates an [image0]
+      object, and initializes it with static kernel memory loaded
+      from the [start] address and [size] of [dom].
 
-type image2 =
-    image0
-    * Virt_mem_mmap.addr Ksymmap.t	(* Kernel symbol map. *)
-    * utsname option			(* Kernel version, etc., if found. *)
-  (** A kernel image, after finding kernel version (like 'uname'). *)
+      See also {!load_memory} for exceptions this can raise. *)