2 * (C) Copyright 2008-2011 Red Hat Inc.
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
19 (** Functions for downloading, accessing kernel memory from guests. *)
22 data : string; (** Contents of kernel memory. *)
23 base_addr : int64; (** Base virtual address of [data.(0)] *)
25 endian : endian; (** Endianness. *)
26 wordsize : wordsize; (** Word size. *)
30 and endian = BigEndian | LittleEndian
32 and wordsize = Word32 | Word64
34 val bytes_of_wordsize : t -> int
35 (** Returns [4] or [8] depending on number of bytes in a word. *)
37 val succ_word : t -> int64 -> int64
38 val pred_word : t -> int64 -> int64
39 (** Increment or decrement a pointer by one word. Depending on the
40 current kernel word size, these increment or decrement the
41 address passed by 4 or 8. *)
43 val succ_align : t -> int64 -> int64
44 (** [succ_align k addr] increments [addr] to the next aligned word.
45 However if [addr] is already aligned to a word boundary, then
46 {i [addr] is returned unchanged}. *)
48 val string_of_endian : endian -> string
49 val string_of_wordsize : wordsize -> string
50 (** Convert endian and wordsize values into English printable
51 strings, useful for debugging. *)
53 external addr_compare : int64 -> int64 -> int = "virt_dmesg_addr_compare" "noalloc"
54 (** Lack of unsigned int64 type is a major annoyance. Instead of
55 importing the external uint64 library (not available on Fedora)
56 use this function to compare addresses as unsigned numbers
59 [addr_compare a1 a2] returns:
61 zero if [a1 = a2], and
64 val create : int64 -> (int64 -> string) -> t
65 (** [create base_addr f] creates a kernel object. [f] should read
66 data on request from a specific virtual address in the guest.
68 Endianness and wordsize are determined heuristically from the
69 image. If the data coming back during this step doesn't look
70 like it's from a kernel, then this function raises [Not_found]. *)
72 val find_first : t -> string -> int64
73 val find_all : t -> string -> int64 list
74 (** [find_first t str] looks for the string [str] in the kernel memory,
75 returning the virtual address of the first match. If no string is
76 found it raises [Not_found].
78 [find_all] is the same but it returns all matches. This function
79 returns an empty list if no string is found. *)
81 val find_all_pointers : t -> int64 -> int64 list
82 (** [find_all_pointers t ptr] locates all addresses in the kernel memory
83 which contain a pointer [ptr]. This function adjusts the search
84 depending on the endianness and word size of the kernel, so callers
85 don't have to worry about it. Only aligned pointers are matched,
86 since some coincidental unaligned value is unlikely to be a pointer. *)
88 val follow_pointer : t -> int64 -> int64
89 (** In [follow_pointer t addr], [addr] is assumed to be an address
90 in the kernel image containing a pointer. This dereferences the
91 pointer and returns that. Endianness and word size are taken
92 into account automatically. *)
94 val is_mapped : t -> int64 -> bool
95 (** [is_mapped k addr] returns true iff [addr] is a plausible kernel
98 val get_memory : t -> int64 -> int -> string
99 (** [get_memory k addr len] returns a copy of the memory at address
100 [addr], length [len] bytes. *)
102 val get_string : t -> int64 -> string
103 (** Return the NUL-terminated string that starts at the given
104 address. Note this may be zero length or very very long, so be
107 val get_byte : t -> int64 -> int
108 (** [get_byte k addr] returns the single byte at address [addr]. *)
110 val get_int32 : t -> int64 -> int64
111 (** [get_int32 k addr] returns the signed 32 bit int at [addr]. The
112 correct adjustment is made for endianness. *)
114 val get_int64 : t -> int64 -> int64
115 (** [get_int64 k addr] returns the signed 64 bit int at [addr]. The
116 correct adjustment is made for endianness. *)
118 val is_C_identifier : t -> int64 -> bool
119 (** [is_C_identifier t addr] returns true iff [addr] of the memory
120 image contains something which could plausibly be a NUL-terminated
121 C programming language identifier.
123 Unlike other functions in this file, calling this with a bogus
124 pointer returns [false]. This is so you can dereference a
125 pointer and call this function directly without needing an extra