2 (* Memory info command for virtual domains.
3 (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
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.
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.
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.
23 (** {2 Kernel symbols} *)
26 (** A kernel symbol. *)
30 type 'a t = 'a Map.Make(String).t
32 val is_empty : 'a t -> bool
33 val add : key -> 'a -> 'a t -> 'a t
34 val find : key -> 'a t -> 'a
35 val remove : key -> 'a t -> 'a t
36 val mem : key -> 'a t -> bool
37 val iter : (key -> 'a -> unit) -> 'a t -> unit
38 val map : ('a -> 'b) -> 'a t -> 'b t
39 val mapi : (key -> 'a -> 'b) -> 'a t -> 'b t
40 val fold : (key -> 'a -> 'b -> 'b) -> 'a t -> 'b -> 'b
41 val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
42 val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
44 (** Functions available in the map of kernel symbols to addresses. *)
46 type ksymmap = Virt_mem_mmap.addr Ksymmap.t
47 (** Kernel symbol table (map of kernel symbols to addresses). *)
49 (** {2 Kernel memory images and associated metadata} *)
52 dom : Libvirt.ro Libvirt.Domain.t option; (** Domain, if known. *)
53 domname : string; (** Domain name. *)
54 arch : Virt_mem_utils.architecture; (** Architecture, eg. i386. *)
55 mem : ([`Wordsize], [`Endian], [`HasMapping]) Virt_mem_mmap.t;
57 kernel_min : Virt_mem_mmap.addr; (** Minimum addr of kernel pointers. *)
58 kernel_max : Virt_mem_mmap.addr; (** Maximum addr of kernel pointers. *)
60 (** A basic kernel image. *)
62 (** {2 Kernel structures internal format}
64 So that we don't need to reiterate over certain important
65 kernel structures in each tool, we convert them into a more
66 convenient internal format.
68 See {!Virt_mem_tasks}, {!Virt_mem_net_devices}.
72 uts_kernel_name : string;
73 uts_nodename : string;
74 uts_kernel_release : string;
75 uts_kernel_version : string;
77 uts_domainname : string;
79 (** Kernel version, from utsname structure in the kernel. *)
84 task_normal_prio : int64;
85 task_static_prio : int64;
86 task_comm : string; (** Short command name. *)
87 task_pid : int64; (** Process ID. *)
89 (** Internal version of the kernel [task_struct]. *)
92 netdev_name : string; (** Device name. *)
94 netdev_operstate : int64;
96 netdev_perm_addr : string;
97 netdev_addr_len : int64;
99 (** Internal version of the kernel [net_device] (network device struct). *)
102 ksyms : ksymmap option; (** Kernel symbol lookup function. *)
103 utsname : utsname option; (** Kernel version. *)
104 tasks : task list option; (** List of tasks (processes). *)
105 net_devices : net_device list option; (** List of net devices. *)
107 (** Optional data derived from the raw kernel image by the main
108 program and passed to the tools' [~run] functions.
110 What fields get filled in is controlled by the [~needs_*]
111 options passed when tools register themselves, and also of
112 course by what we are able to find out about the memory image
113 (see {!Virt_mem.register}).
115 Note there is significant cost to filling in some of these
119 (** {2 Helper declarations for kernel structure parsers}
121 The kernel structure parsers (in {!Kernel_task_struct} et al (see
122 [lib/kernel_*])) share a few common types declared here.
124 Note that the parsers themselves are generated automatically.
127 exception ParseError of string * string * string
128 (** Parsing exception raised by [Kernel_*] parser functions.
130 The fields are: structure name, function which raised the error,
133 (** {2 Functions to load kernel memory} *)
135 type load_memory_error =
136 | AddressOutOfRange (** Address not in [kernel_min..kernel_max] *)
137 | DomIsNull (** image.dom = None *)
139 exception LoadMemoryError of load_memory_error * string
141 val load_memory : image -> Virt_mem_mmap.addr -> int -> image
142 (** [load_memory img start size] tries to load [size] bytes from
143 the start address into the memory map. If the memory was loaded
144 previously, then it is not requested again.
146 Note that the memory map may be updated by this, so a modified
147 image structure is returned.
149 This function can raise many different sorts of exceptions and
150 the caller is advised to catch any exceptions and deal with them
153 val load_static_memory : dom:Libvirt.ro Libvirt.Domain.t ->
155 arch:Virt_mem_utils.architecture ->
156 wordsize:Virt_mem_utils.wordsize -> endian:Bitstring.endian ->
157 kernel_min:Virt_mem_mmap.addr -> kernel_max:Virt_mem_mmap.addr ->
158 Virt_mem_mmap.addr -> int -> image
159 (** [load_static_memory ~dom (*...*) start size] creates an [image0]
160 object, and initializes it with static kernel memory loaded
161 from the [start] address and [size] of [dom].
163 See also {!load_memory} for exceptions this can raise. *)