(** Common types. *)
(* Memory info command for virtual domains.
   (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
   http://libvirt.org/

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

   Common types.
 *)

(** {2 Kernel symbols} *)

type ksym = string
  (** A kernel symbol. *)

module Ksymmap : sig
  type key = String.t
  type 'a t = 'a Map.Make(String).t
  val empty : 'a t
  val is_empty : 'a t -> bool
  val add : key -> 'a -> 'a t -> 'a t
  val find : key -> 'a t -> 'a
  val remove : key -> 'a t -> 'a t
  val mem : key -> 'a t -> bool
  val iter : (key -> 'a -> unit) -> 'a t -> unit
  val map : ('a -> 'b) -> 'a t -> 'b t
  val mapi : (key -> 'a -> 'b) -> 'a t -> 'b t
  val fold : (key -> 'a -> 'b -> 'b) -> 'a t -> 'b -> 'b
  val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
  val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
end
  (** Functions available in the map of kernel symbols to addresses. *)

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 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. *)

(** {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_dev_addr : string;	        (** Interface network address. *)
}
  (** 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].

      See also {!load_memory} for exceptions this can raise. *)