lib/virt_mem_mmap.mli

   1 (* Memory info command for virtual domains.
   2    (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
   3    http://libvirt.org/
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 2 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software
  17    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18
  19    Functions for making a memory map of a virtual machine from
  20    various sources.  The memory map will most certainly have holes.
  21  *)
  22
  23 type ('a,'b) t
  24 (** Memory map. *)
  25
  26 type addr = int64
  27 (** Virtual memory addresses (even on 32 bit machines). *)
  28
  29 val create : unit -> ([`NoWordsize], [`NoEndian]) t
  30 (** Create a new, empty memory map. *)
  31
  32 val set_wordsize : ([`NoWordsize], 'b) t -> Virt_mem_utils.wordsize ->
  33   ([`Wordsize], 'b) t
  34 (** Set the natural wordsize of the memory map.  This is used
  35     for matching pointers within the map and can be set only once. *)
  36
  37 val set_endian : ('a, [`NoEndian]) t -> Bitmatch.endian ->
  38   ('a, [`Endian]) t
  39 (** Set the natural endianness of the memory map.  This is used
  40     for matching pointers within the map and can be set only once. *)
  41
  42 val get_wordsize : ([`Wordsize], 'b) t -> Virt_mem_utils.wordsize
  43 (** Return the wordsize previously set for this memory map. *)
  44
  45 val get_endian : ('a, [`Endian]) t -> Bitmatch.endian
  46 (** Return the endianness previously set for this memory map. *)
  47
  48 val of_file : Unix.file_descr -> addr -> ([`NoWordsize], [`NoEndian]) t
  49 (** Create a new memory map, mapping file [fd] at address [addr]. *)
  50
  51 val add_file : ('a, 'b) t -> Unix.file_descr -> addr -> ('a, 'b) t
  52 (** Add file [fd] at address [addr] to an existing memory map.
  53     Behaviour is undefined if memory mappings overlap. *)
  54
  55 val of_string : string -> addr -> ([`NoWordsize], [`NoEndian]) t
  56 (** Create a new memory map, mapping string at address [addr]. *)
  57
  58 val add_string : ('a, 'b) t -> string -> addr -> ('a, 'b) t
  59 (** Add string at address [addr] to an existing memory map.
  60     Behaviour is undefined if memory mappings overlap. *)
  61
  62 val find : ('a, 'b) t -> ?start:addr -> string -> addr option
  63 (** Find string in a memory map and return its address (if found).
  64     You can pass an optional starting address.  Any holes in
  65     the memory map are skipped automatically. *)
  66
  67 val find_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr option
  68 (** Find a string aligned to the wordsize in the memory map. *)
  69
  70 val find_all : ('a, 'b) t -> ?start:addr -> string -> addr list
  71 (** Find all occurrences of a string in a memory map. *)
  72
  73 val find_all_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr list
  74 (** Find all occurrences of a string in a memory map. *)
  75
  76 val find_pointer : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
  77   addr option
  78 (** Find a pointer (address) in the memory map.
  79     The pointer must be aligned to a word. *)
  80
  81 val find_pointer_all : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
  82   addr list
  83 (** Find all occurrences of a pointer in the memory map. *)
  84
  85 val get_byte : ('a, 'b) t -> addr -> int
  86 (** Return the byte at the given address.
  87
  88     This may raise [Invalid_argument "get_byte"] if the address is
  89     not mapped. *)
  90
  91 val get_bytes : ('a, 'b) t -> addr -> int -> string
  92 (** Return the sequence of bytes starting at the given address.
  93
  94     This may raise [Invalid_argument "get_bytes"] if the address range
  95     is not fully mapped. *)
  96
  97 val get_int32 : ('a, [`Endian]) t -> addr -> int32
  98 (** Return the 32-bit int at [addr]. *)
  99
 100 val get_int64 : ('a, [`Endian]) t -> addr -> int64
 101 (** Return the 64-bit int at [addr]. *)
 102
 103 val get_C_int : ([`Wordsize], [`Endian]) t -> addr -> int32
 104 (** Return the C 32-bit int at [addr]. *)
 105
 106 val get_C_long : ([`Wordsize], [`Endian]) t -> addr -> int64
 107 (** Return the C 32 or 64-bit long at [addr]. *)
 108
 109 val get_string : ('a, 'b) t -> addr -> string
 110 (** Return the sequence of bytes starting at [addr] up to (but not
 111     including) the first ASCII NUL character.  In other words, this
 112     returns a C-style string.
 113
 114     This may raise [Invalid_argument "get_string"] if we reach an
 115     unmapped address before finding the end of the string.
 116
 117     See also {!is_string} and {!is_C_identifier}. *)
 118
 119 val is_string : ('a, 'b) t -> addr -> bool
 120 (** Return true or false if the address contains an ASCII NUL-terminated
 121     string. *)
 122
 123 val is_C_identifier : ('a, 'b) t -> addr -> bool
 124 (** Return true or false if the address contains a NUL-terminated
 125     C identifier. *)
 126
 127 val is_mapped : ('a, 'b) t -> addr -> bool
 128 (** Return true if the single address [addr] is mapped. *)
 129
 130 val follow_pointer : ([`Wordsize], [`Endian]) t -> addr -> addr
 131 (** Follow (dereference) the pointer at [addr] and return
 132     the address pointed to. *)
 133
 134 val succ_long : ([`Wordsize], 'b) t -> addr -> addr
 135 (** Add wordsize bytes to [addr] and return it. *)
 136
 137 val pred_long : ([`Wordsize], 'b) t -> addr -> addr
 138 (** Subtract wordsize bytes from [addr] and return it. *)
 139
 140 val align : ([`Wordsize], 'b) t -> addr -> addr
 141 (** Align the [addr] to the next wordsize boundary.  If it already
 142     aligned, this just returns [addr]. *)