src/kernel.mli

   1 (* virt-dmesg
   2  * (C) Copyright 2008-2011 Red Hat Inc.
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *)
  18
  19 (** Functions for downloading, accessing kernel memory from guests. *)
  20
  21 type t = {
  22   data : string;             (** Contents of kernel memory. *)
  23   base_addr : int64;         (** Base virtual address of [data.(0)] *)
  24
  25   endian : endian;                      (** Endianness. *)
  26   wordsize : wordsize;                  (** Word size. *)
  27 }
  28     (** A kernel. *)
  29
  30 and endian = BigEndian | LittleEndian
  31
  32 and wordsize = Word32 | Word64
  33
  34 val bytes_of_wordsize : t -> int
  35   (** Returns [4] or [8] depending on number of bytes in a word. *)
  36
  37 val succ_word : t -> int64 -> int64
  38 val pred_word : t -> int64 -> int64
  39   (** Increment or decrement a pointer by one word.  Depending on the
  40       current kernel word size, these increment or decrement the
  41       address passed by 4 or 8. *)
  42
  43 val succ_align : t -> int64 -> int64
  44   (** [succ_align k addr] increments [addr] to the next aligned word.
  45       However if [addr] is already aligned to a word boundary, then
  46       {i [addr] is returned unchanged}. *)
  47
  48 val string_of_endian : endian -> string
  49 val string_of_wordsize : wordsize -> string
  50   (** Convert endian and wordsize values into English printable
  51       strings, useful for debugging. *)
  52
  53 external addr_compare : int64 -> int64 -> int = "virt_dmesg_addr_compare" "noalloc"
  54   (** Lack of unsigned int64 type is a major annoyance.  Instead of
  55       importing the external uint64 library (not available on Fedora)
  56       use this function to compare addresses as unsigned numbers
  57       without wrap-around.
  58
  59       [addr_compare a1 a2] returns:
  60       [1] if [a1 > a2],
  61       zero if [a1 = a2], and
  62       [-1] if [a1 < a2]. *)
  63
  64 val create : int64 -> (int64 -> string) -> t
  65   (** [create base_addr f] creates a kernel object.  [f] should read
  66       data on request from a specific virtual address in the guest.
  67
  68       Endianness and wordsize are determined heuristically from the
  69       image.  If the data coming back during this step doesn't look
  70       like it's from a kernel, then this function raises [Not_found]. *)
  71
  72 val find_first : t -> string -> int64
  73 val find_all : t -> string -> int64 list
  74   (** [find_first t str] looks for the string [str] in the kernel memory,
  75       returning the virtual address of the first match.  If no string is
  76       found it raises [Not_found].
  77
  78       [find_all] is the same but it returns all matches.  This function
  79       returns an empty list if no string is found. *)
  80
  81 val find_all_pointers : t -> int64 -> int64 list
  82   (** [find_all_pointers t ptr] locates all addresses in the kernel memory
  83       which contain a pointer [ptr].  This function adjusts the search
  84       depending on the endianness and word size of the kernel, so callers
  85       don't have to worry about it.  Only aligned pointers are matched,
  86       since some coincidental unaligned value is unlikely to be a pointer. *)
  87
  88 val follow_pointer : t -> int64 -> int64
  89   (** In [follow_pointer t addr], [addr] is assumed to be an address
  90       in the kernel image containing a pointer.  This dereferences the
  91       pointer and returns that.  Endianness and word size are taken
  92       into account automatically. *)
  93
  94 val is_mapped : t -> int64 -> bool
  95   (** [is_mapped k addr] returns true iff [addr] is a plausible kernel
  96       pointer. *)
  97
  98 val get_memory : t -> int64 -> int -> string
  99   (** [get_memory k addr len] returns a copy of the memory at address
 100       [addr], length [len] bytes. *)
 101
 102 val get_string : t -> int64 -> string
 103   (** Return the NUL-terminated string that starts at the given
 104       address.  Note this may be zero length or very very long, so be
 105       careful. *)
 106
 107 val get_byte : t -> int64 -> int
 108   (** [get_byte k addr] returns the single byte at address [addr]. *)
 109
 110 val get_int32 : t -> int64 -> int64
 111   (** [get_int32 k addr] returns the signed 32 bit int at [addr].  The
 112       correct adjustment is made for endianness. *)
 113
 114 val get_int64 : t -> int64 -> int64
 115   (** [get_int64 k addr] returns the signed 64 bit int at [addr].  The
 116       correct adjustment is made for endianness. *)
 117
 118 val is_C_identifier : t -> int64 -> bool
 119   (** [is_C_identifier t addr] returns true iff [addr] of the memory
 120       image contains something which could plausibly be a NUL-terminated
 121       C programming language identifier.
 122
 123       Unlike other functions in this file, calling this with a bogus
 124       pointer returns [false].  This is so you can dereference a
 125       pointer and call this function directly without needing an extra
 126       check. *)