(* virt-dmesg
 * (C) Copyright 2008-2011 Red Hat Inc.
 *
 * 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.
 *)

(** Functions for downloading, accessing kernel memory from guests. *)

type t = {
  data : string;             (** Contents of kernel memory. *)
  base_addr : int64;         (** Base virtual address of [data.(0)] *)

  endian : endian;                      (** Endianness. *)
  wordsize : wordsize;                  (** Word size. *)
}
    (** A kernel. *)

and endian = BigEndian | LittleEndian

and wordsize = Word32 | Word64

val bytes_of_wordsize : t -> int
  (** Returns [4] or [8] depending on number of bytes in a word. *)

val succ_word : t -> int64 -> int64
val pred_word : t -> int64 -> int64
  (** Increment or decrement a pointer by one word.  Depending on the
      current kernel word size, these increment or decrement the
      address passed by 4 or 8. *)

val succ_align : t -> int64 -> int64
  (** [succ_align k addr] increments [addr] to the next aligned word.
      However if [addr] is already aligned to a word boundary, then
      {i [addr] is returned unchanged}. *)

val string_of_endian : endian -> string
val string_of_wordsize : wordsize -> string
  (** Convert endian and wordsize values into English printable
      strings, useful for debugging. *)

external addr_compare : int64 -> int64 -> int = "virt_dmesg_addr_compare" "noalloc"
  (** Lack of unsigned int64 type is a major annoyance.  Instead of
      importing the external uint64 library (not available on Fedora)
      use this function to compare addresses as unsigned numbers
      without wrap-around.

      [addr_compare a1 a2] returns:
      [1] if [a1 > a2],
      zero if [a1 = a2], and
      [-1] if [a1 < a2]. *)

val create : int64 -> (int64 -> string) -> t
  (** [create base_addr f] creates a kernel object.  [f] should read
      data on request from a specific virtual address in the guest.

      Endianness and wordsize are determined heuristically from the
      image.  If the data coming back during this step doesn't look
      like it's from a kernel, then this function raises [Not_found]. *)

val find_first : t -> string -> int64
val find_all : t -> string -> int64 list
  (** [find_first t str] looks for the string [str] in the kernel memory,
      returning the virtual address of the first match.  If no string is
      found it raises [Not_found].

      [find_all] is the same but it returns all matches.  This function
      returns an empty list if no string is found. *)

val find_all_pointers : t -> int64 -> int64 list
  (** [find_all_pointers t ptr] locates all addresses in the kernel memory
      which contain a pointer [ptr].  This function adjusts the search
      depending on the endianness and word size of the kernel, so callers
      don't have to worry about it.  Only aligned pointers are matched,
      since some coincidental unaligned value is unlikely to be a pointer. *)

val follow_pointer : t -> int64 -> int64
  (** In [follow_pointer t addr], [addr] is assumed to be an address
      in the kernel image containing a pointer.  This dereferences the
      pointer and returns that.  Endianness and word size are taken
      into account automatically. *)

val is_mapped : t -> int64 -> bool
  (** [is_mapped k addr] returns true iff [addr] is a plausible kernel
      pointer. *)

val get_memory : t -> int64 -> int -> string
  (** [get_memory k addr len] returns a copy of the memory at address
      [addr], length [len] bytes. *)

val get_string : t -> int64 -> string
  (** Return the NUL-terminated string that starts at the given
      address.  Note this may be zero length or very very long, so be
      careful. *)

val get_byte : t -> int64 -> int
  (** [get_byte k addr] returns the single byte at address [addr]. *)

val get_int32 : t -> int64 -> int64
  (** [get_int32 k addr] returns the signed 32 bit int at [addr].  The
      correct adjustment is made for endianness. *)

val get_int64 : t -> int64 -> int64
  (** [get_int64 k addr] returns the signed 64 bit int at [addr].  The
      correct adjustment is made for endianness. *)

val is_C_identifier : t -> int64 -> bool
  (** [is_C_identifier t addr] returns true iff [addr] of the memory
      image contains something which could plausibly be a NUL-terminated
      C programming language identifier.

      Unlike other functions in this file, calling this with a bogus
      pointer returns [false].  This is so you can dereference a
      pointer and call this function directly without needing an extra
      check. *)