+(** {2 Memory maps}
+
+ Memory maps represent the virtual memory of a virtual machine.
+
+ We are mostly interested in the kernel memory and kernel data
+ structures. In Linux this stays at the same virtual memory
+ address whichever task is actually running (eg. on i386 machines,
+ the kernel is often found at virtual address 0xC0100000). Kernel
+ memory is spread out over several ranges of addresses, with gaps
+ of uninteresting or non-existant virtual addresses in between, and
+ this structure captures that.
+
+ A memory map is a range of 64 bit addresses from [0] to [2^64-1].
+ (Note that 64 bit addresses are used even for 32 bit virtual
+ machines - just ignore everything above 0xFFFFFFFF).
+
+ A memory map consists of zero or more {b mappings} of data. A
+ mapping starts at some address and has some size, and the data for
+ a mapping can come from some source such as a file or OCaml
+ string. Use {!of_file}, {!of_string}, {!add_file}, {!add_string}
+ to create a memory map from mappings.
+
+ {3 Overlapping mappings and holes}
+
+ If mappings overlap, then the mapping which was added later
+ overrides/overwrites earlier mappings at any addresses which
+ coincide.
+
+ Where there is no mapping for a particular address, the memory map
+ is said to have a hole. (Typically almost all of a memory map is
+ holes). In general, the searching functions such as {!find} skip
+ over holes, while the accessor functions such as {!get_bytes}
+ raise an error if you try to read a hole, but read the individual
+ function documentation.
+
+ {3 Word size and endianness}
+
+ Memory maps may (or may not) have an associated word size and
+ endianness for the whole map. These are used when we look at
+ integers and pointers in the memory. See {!get_endian},
+ {!set_endian}, {!get_wordsize} and {!set_wordsize}, and accessor
+ functions such as {!get_int32} and {!follow_pointer}.
+
+ {3 Efficiency}
+
+ Mappings' data are stored in 1D Bigarrays. The advantages of
+ using a Bigarray are: (a) hidden from the garbage collector, (b)
+ easily accessible from C, (c) uses mmap(2) where possible.
+
+ Some low level functions are written in C for speed.
+
+ Mappings are stored in a segment tree for efficient access, but
+ the segment tree has to be rebuilt from scratch each time you add
+ a new mapping (it is not known if there is a more efficient way to
+ incrementally update a segment tree).
+*)
+
+(** {2 Types} *)
+
+type ('ws,'e,'hm) t
+(** Memory map.
+
+ The ['ws], ['e] and ['hm] type parameters are phantom types
+ designed to ensure you don't try illegal operations before
+ initializing certain parts of the memory map. If you are not
+ familiar with phantom types, you can just ignore them.
+
+ See also:
+ [http://camltastic.blogspot.com/2008/05/phantom-types.html] *)
git.annexia.org / virt-mem.git / commitdiff