"Fossies" - the Fresh Open Source Software Archive

Member "virt-dmesg-0.3.0/src/kernel.mli" (25 May 2011, 5203 Bytes) of package /linux/privat/old/virt-dmesg-0.3.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Objective Caml source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

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