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 of_string : string -> addr -> ([`NoWordsize], [`NoEndian]) t
56 (** Create a new memory map, mapping string at address [addr]. *)
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. *)
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. *)
67 val find_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr option
68 (** Find a string aligned to the wordsize in the memory map. *)
70 val find_all : ('a, 'b) t -> ?start:addr -> string -> addr list
71 (** Find all occurrences of a string in a memory map. *)
73 val find_all_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr list
74 (** Find all occurrences of a string in a memory map. *)
76 val find_pointer : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
78 (** Find a pointer (address) in the memory map.
79 The pointer must be aligned to a word. *)
81 val find_pointer_all : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
83 (** Find all occurrences of a pointer in the memory map. *)
85 val get_byte : ('a, 'b) t -> addr -> int
86 (** Return the byte at the given address.
88 This may raise [Invalid_argument "get_byte"] if the address is
91 val get_bytes : ('a, 'b) t -> addr -> int -> string
92 (** Return the sequence of bytes starting at the given address.
94 This may raise [Invalid_argument "get_bytes"] if the address range
95 is not fully mapped. *)
97 val get_int32 : ('a, [`Endian]) t -> addr -> int32
98 (** Return the 32-bit int at [addr]. *)
100 val get_int64 : ('a, [`Endian]) t -> addr -> int64
101 (** Return the 64-bit int at [addr]. *)
103 val get_C_int : ([`Wordsize], [`Endian]) t -> addr -> int32
104 (** Return the C 32-bit int at [addr]. *)
106 val get_C_long : ([`Wordsize], [`Endian]) t -> addr -> int64
107 (** Return the C 32 or 64-bit long at [addr]. *)
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.
114 This may raise [Invalid_argument "get_string"] if we reach an
115 unmapped address before finding the end of the string.
117 See also {!is_string} and {!is_C_identifier}. *)
119 val is_string : ('a, 'b) t -> addr -> bool
120 (** Return true or false if the address contains an ASCII NUL-terminated
123 val is_C_identifier : ('a, 'b) t -> addr -> bool
124 (** Return true or false if the address contains a NUL-terminated
127 val is_mapped : ('a, 'b) t -> addr -> bool
128 (** Return true if the single address [addr] is mapped. *)
130 val follow_pointer : ([`Wordsize], [`Endian]) t -> addr -> addr
131 (** Follow (dereference) the pointer at [addr] and return
132 the address pointed to. *)
134 val succ_long : ([`Wordsize], 'b) t -> addr -> addr
135 (** Add wordsize bytes to [addr] and return it. *)
137 val pred_long : ([`Wordsize], 'b) t -> addr -> addr
138 (** Subtract wordsize bytes from [addr] and return it. *)
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]. *)