1 (* Memory info command for virtual domains.
2 (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
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.
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.
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.
19 Functions for making a memory map of a virtual machine from
20 various sources. The memory map will most certainly have holes.
27 (** Virtual memory addresses (even on 32 bit machines). *)
29 val create : unit -> ([`NoWordsize], [`NoEndian]) t
30 (** Create a new, empty memory map. *)
32 val set_wordsize : ([`NoWordsize], 'b) t -> Virt_mem_utils.wordsize ->
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. *)
37 val set_endian : ('a, [`NoEndian]) t -> Bitmatch.endian ->
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. *)
42 val get_wordsize : ([`Wordsize], 'b) t -> Virt_mem_utils.wordsize
43 (** Return the wordsize previously set for this memory map. *)
45 val get_endian : ('a, [`Endian]) t -> Bitmatch.endian
46 (** Return the endianness previously set for this memory map. *)
48 val of_file : Unix.file_descr -> addr -> ([`NoWordsize], [`NoEndian]) t
49 (** Create a new memory map, mapping file [fd] at address [addr]. *)
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. *)
55 val find : ('a, 'b) t -> ?start:addr -> string -> addr option
56 (** Find string in a memory map and return its address (if found).
57 You can pass an optional starting address. Any holes in
58 the memory map are skipped automatically. *)
60 val find_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr option
61 (** Find a string aligned to the wordsize in the memory map. *)
63 val find_all : ('a, 'b) t -> ?start:addr -> string -> addr list
64 (** Find all occurrences of a string in a memory map. *)
66 val find_all_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr list
67 (** Find all occurrences of a string in a memory map. *)
69 val find_pointer : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
71 (** Find a pointer (address) in the memory map.
72 The pointer must be aligned to a word. *)
74 val find_pointer_all : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
76 (** Find all occurrences of a pointer in the memory map. *)
78 val get_byte : ('a, 'b) t -> addr -> int
79 (** Return the byte at the given address.
81 This may raise [Invalid_argument "get_byte"] if the address is
84 val get_bytes : ('a, 'b) t -> addr -> int -> string
85 (** Return the sequence of bytes starting at the given address.
87 This may raise [Invalid_argument "get_bytes"] if the address range
88 is not fully mapped. *)
90 val get_int32 : ('a, [`Endian]) t -> addr -> int32
91 (** Return the 32-bit int at [addr]. *)
93 val get_int64 : ('a, [`Endian]) t -> addr -> int64
94 (** Return the 64-bit int at [addr]. *)
96 val get_C_int : ([`Wordsize], [`Endian]) t -> addr -> int32
97 (** Return the C 32-bit int at [addr]. *)
99 val get_C_long : ([`Wordsize], [`Endian]) t -> addr -> int64
100 (** Return the C 32 or 64-bit long at [addr]. *)
102 val get_string : ('a, 'b) t -> addr -> string
103 (** Return the sequence of bytes starting at [addr] up to (but not
104 including) the first ASCII NUL character. In other words, this
105 returns a C-style string.
107 This may raise [Invalid_argument "get_string"] if we reach an
108 unmapped address before finding the end of the string.
110 See also {!is_string} and {!is_C_identifier}. *)
112 val is_string : ('a, 'b) t -> addr -> bool
113 (** Return true or false if the address contains an ASCII NUL-terminated
116 val is_C_identifier : ('a, 'b) t -> addr -> bool
117 (** Return true or false if the address contains a NUL-terminated
120 val is_mapped : ('a, 'b) t -> addr -> bool
121 (** Return true if the single address [addr] is mapped. *)
123 val follow_pointer : ([`Wordsize], [`Endian]) t -> addr -> addr
124 (** Follow (dereference) the pointer at [addr] and return
125 the address pointed to. *)
127 val succ_long : ([`Wordsize], 'b) t -> addr -> addr
128 (** Add wordsize bytes to [addr] and return it. *)
130 val pred_long : ([`Wordsize], 'b) t -> addr -> addr
131 (** Subtract wordsize bytes from [addr] and return it. *)
133 val align : ([`Wordsize], 'b) t -> addr -> addr
134 (** Align the [addr] to the next wordsize boundary. If it already
135 aligned, this just returns [addr]. *)