Updated PO files.
[virt-mem.git] / lib / virt_mem_mmap.mli
1 (** Memory map. *)
2 (* Memory info command for virtual domains.
3    (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
4    http://libvirt.org/
5
6    This program is free software; you can redistribute it and/or modify
7    it under the terms of the GNU General Public License as published by
8    the Free Software Foundation; either version 2 of the License, or
9    (at your option) any later version.
10
11    This program is distributed in the hope that it will be useful,
12    but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14    GNU General Public License for more details.
15
16    You should have received a copy of the GNU General Public License
17    along with this program; if not, write to the Free Software
18    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
19  *)
20
21 (** {2 Memory maps}
22
23     Memory maps represent the virtual memory of a virtual machine.
24
25     We are mostly interested in the kernel memory and kernel data
26     structures.  In Linux this stays at the same virtual memory
27     address whichever task is actually running (eg. on i386 machines,
28     the kernel is often found at virtual address 0xC0100000).  Kernel
29     memory is spread out over several ranges of addresses, with gaps
30     of uninteresting or non-existant virtual addresses in between, and
31     this structure captures that.
32
33     A memory map is a range of 64 bit addresses from [0] to [2^64-1].
34     (Note that 64 bit addresses are used even for 32 bit virtual
35     machines - just ignore everything above 0xFFFFFFFF).
36
37     A memory map consists of zero or more {b mappings} of data.  A
38     mapping starts at some address and has some size, and the data for
39     a mapping can come from some source such as a file or OCaml
40     string.  Use {!of_file}, {!of_string}, {!add_file}, {!add_string}
41     to create a memory map from mappings.
42
43     {3 Overlapping mappings and holes}
44
45     If mappings overlap, then the mapping which was added later
46     overrides/overwrites earlier mappings at any addresses which
47     coincide.
48
49     Where there is no mapping for a particular address, the memory map
50     is said to have a hole.  (Typically almost all of a memory map is
51     holes).  In general, the searching functions such as {!find} skip
52     over holes, while the accessor functions such as {!get_bytes}
53     raise an error if you try to read a hole, but read the individual
54     function documentation.
55
56     {3 Word size and endianness}
57
58     Memory maps may (or may not) have an associated word size and
59     endianness for the whole map.  These are used when we look at
60     integers and pointers in the memory.  See {!get_endian},
61     {!set_endian}, {!get_wordsize} and {!set_wordsize}, and accessor
62     functions such as {!get_int32} and {!follow_pointer}.
63
64     {3 Efficiency}
65
66     Mappings' data are stored in 1D Bigarrays.  The advantages of
67     using a Bigarray are: (a) hidden from the garbage collector, (b)
68     easily accessible from C, (c) uses mmap(2) where possible.
69
70     Some low level functions are written in C for speed.
71
72     Mappings are stored in a segment tree for efficient access, but
73     the segment tree has to be rebuilt from scratch each time you add
74     a new mapping (it is not known if there is a more efficient way to
75     incrementally update a segment tree).
76 *)
77
78 (** {2 Types} *)
79
80 type ('ws,'e,'hm) t
81 (** Memory map.
82
83     The ['ws], ['e] and ['hm] type parameters are phantom types
84     designed to ensure you don't try illegal operations before
85     initializing certain parts of the memory map.  If you are not
86     familiar with phantom types, you can just ignore them.
87
88     See also:
89     [http://camltastic.blogspot.com/2008/05/phantom-types.html] *)
90
91 type addr = int64
92 (** Virtual memory addresses (even on 32 bit machines). *)
93
94 (** {2 Create a memory map, add mappings} *)
95
96 val create : unit -> ([`NoWordsize], [`NoEndian], [`NoMappings]) t
97 (** Create a new, empty memory map. *)
98
99 val of_file : Unix.file_descr -> addr ->
100   ([`NoWordsize], [`NoEndian], [`HasMapping]) t
101 (** Create a new memory map, mapping file [fd] at address [addr]. *)
102
103 val add_file : ('ws, 'e, 'hm) t -> Unix.file_descr -> addr ->
104   ('ws, 'e, [`HasMapping]) t
105 (** Add file [fd] at address [addr] to an existing memory map.
106     The new mapping can overwrite all or part of an existing mapping. *)
107
108 val of_string : string -> addr -> ([`NoWordsize], [`NoEndian], [`HasMapping]) t
109 (** Create a new memory map, mapping string at address [addr]. *)
110
111 val add_string : ('ws, 'e, 'hm) t -> string -> addr ->
112   ('ws, 'e, [`HasMapping]) t
113 (** Add string at address [addr] to an existing memory map.
114     The new mapping can overwrite all or part of an existing mapping. *)
115
116 val set_wordsize : ([`NoWordsize], 'e, 'hm) t -> Virt_mem_utils.wordsize ->
117   ([`Wordsize], 'e, 'hm) t
118 (** Set the natural wordsize of the memory map.  This is used
119     for matching integers and pointers within the map and can be
120     set only once. *)
121
122 val set_endian : ('ws, [`NoEndian], 'hm) t -> Bitstring.endian ->
123   ('ws, [`Endian], 'hm) t
124 (** Set the natural endianness of the memory map.  This is used
125     for matching integers and pointers within the map and can be
126     set only once. *)
127
128 val get_wordsize : ([`Wordsize], 'e, 'hm) t -> Virt_mem_utils.wordsize
129 (** Return the wordsize previously set for this memory map. *)
130
131 val get_endian : ('ws, [`Endian], 'hm) t -> Bitstring.endian
132 (** Return the endianness previously set for this memory map. *)
133
134 (*
135 (** {2 Searching} *)
136
137 val find : ('ws, 'e, [`HasMapping]) t -> ?start:addr -> string -> addr option
138 (** Find string in a memory map and return its address (if found)
139     or [None] (if not found).  You can pass an optional starting
140     address.  If no start address is given, we begin searching at
141     the beginning of the first mapping.
142
143     Any holes in the memory map are skipped automatically.
144
145     Note that this doesn't find strings which straddle the
146     boundary of two adjacent or overlapping mappings.
147
148     Note that because the string being matched is an OCaml
149     string it may contain NULs (zero bytes) and those are matched
150     properly. *)
151
152 val find_align : ([`Wordsize], 'e, [`HasMapping]) t -> ?start:addr -> string ->
153   addr option
154 (** Same as {!find}, but the string must be aligned to the word size of
155     the memory map. *)
156
157 val find_all : ('ws, 'e, [`HasMapping]) t -> ?start:addr -> string -> addr list
158 (** Same as {!find}, but returns all occurrences of a string in a memory map. *)
159
160 val find_all_align : ([`Wordsize], 'e, [`HasMapping]) t -> ?start:addr ->
161   string -> addr list
162 (** Same as {!find_all}, but the strings must be aligned to the word size. *)
163
164 val find_pointer : ([`Wordsize], [`Endian], [`HasMapping]) t -> ?start:addr ->
165   addr -> addr option
166 (** Find a pointer (address) in the memory map.
167     The pointer must be aligned to a word. *)
168
169 val find_pointer_all : ([`Wordsize], [`Endian], [`HasMapping]) t ->
170   ?start:addr -> addr -> addr list
171 (** Find all occurrences of a pointer in the memory map. *)
172
173 (** {2 Get bytes and ranges of bytes} *)
174 *)
175
176 val get_byte : ('ws, 'e, [`HasMapping]) t -> addr -> int
177 (** Return the byte at the given address.
178
179     This will raise [Invalid_argument "get_byte"] if the address is
180     a hole (not mapped). *)
181
182 (*
183 val get_bytes : ('ws, 'e, [`HasMapping]) t -> addr -> int -> string
184 (** Return the sequence of bytes starting at the given address.
185
186     This will raise [Invalid_argument "get_bytes"] if the address range
187     contains holes. *)
188
189 val get_int32 : ('ws, [`Endian], [`HasMapping]) t -> addr -> int32
190 (** Return the 32-bit int at [addr]. *)
191
192 val get_int64 : ('ws, [`Endian], [`HasMapping]) t -> addr -> int64
193 (** Return the 64-bit int at [addr]. *)
194
195 val get_C_int : ([`Wordsize], [`Endian], [`HasMapping]) t -> addr -> int32
196 (** Return the C 32-bit int at [addr]. *)
197
198 val get_C_long : ([`Wordsize], [`Endian], [`HasMapping]) t -> addr -> int64
199 (** Return the C 32 or 64-bit long at [addr]. *)
200
201 val get_string : ('ws, 'e, [`HasMapping]) t -> addr -> string
202 (** Return the sequence of bytes starting at [addr] up to (but not
203     including) the first ASCII NUL character.  In other words, this
204     returns a C-style string.
205
206     This may raise [Invalid_argument "get_string"] if we reach a
207     hole (unmapped address) before finding the end of the string.
208
209     See also {!get_bytes}, {!is_string} and {!is_C_identifier}. *)
210
211 val is_string : ('ws, 'e, [`HasMapping]) t -> addr -> bool
212 (** Return true or false if the address contains an ASCII NUL-terminated
213     string. *)
214
215 val is_C_identifier : ('ws, 'e, [`HasMapping]) t -> addr -> bool
216 (** Return true or false if the address contains a NUL-terminated
217     C identifier. *)
218
219 val is_mapped : ('ws, 'e, [`HasMapping]) t -> addr -> bool
220 (** Return true if the single address [addr] is mapped. *)
221
222 val follow_pointer : ([`Wordsize], [`Endian], [`HasMapping]) t -> addr -> addr
223 (** Follow (dereference) the pointer at [addr] and return
224     the address pointed to. *)
225
226 val succ_long : ([`Wordsize], 'e, [`HasMapping]) t -> addr -> addr
227 (** Add wordsize bytes to [addr] and return it. *)
228
229 val pred_long : ([`Wordsize], 'e, [`HasMapping]) t -> addr -> addr
230 (** Subtract wordsize bytes from [addr] and return it. *)
231
232 val align : ([`Wordsize], 'e, [`HasMapping]) t -> addr -> addr
233 (** Align the [addr] to the next wordsize boundary.  If it already
234     aligned, this just returns [addr]. *)
235
236 (** {2 Save and load memory maps} *)
237
238 (*val to_channel : ('ws, 'e, [`HasMapping]) t -> out_channel -> unit*)
239 (** Write the memory map and data to the given output channel in
240     a reasonably efficient and stable binary format. *)
241
242 (*val from_channel : in_channel -> ('?, '?, [`HasMapping]) t*)
243 (** Read a previously saved memory map.  If the input channel does
244     not contain a memory map, this raises [Invalid_argument]. *)
245 *)