libvirt/libvirt.mli

   1 (** OCaml bindings for libvirt.
   2     (C) Copyright 2007 Richard W.M. Jones, Red Hat Inc.
   3     http://libvirt.org/
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2 of the License, or (at your option) any later version.
   9
  10    This library 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 GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with this library; if not, write to the Free Software
  17    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  18 *)
  19
  20 type uuid = string
  21 (** This is a "raw" UUID, ie. a packed string of bytes. *)
  22
  23 type xml = string
  24 (** Type of XML (an uninterpreted string of bytes).  Use PXP, expat,
  25     xml-light, etc. if you want to do anything useful with the XML.
  26 *)
  27
  28 val get_version : ?driver:string -> unit -> int * int
  29   (** [get_version ()] returns the library version in the first part
  30       of the tuple, and [0] in the second part.
  31
  32       [get_version ~driver ()] returns the library version in the first
  33       part of the tuple, and the version of the driver called [driver]
  34       in the second part.
  35
  36       The version numbers are encoded as
  37       1,000,000 * major + 1,000 * minor + release.
  38   *)
  39
  40 val uuid_length : int
  41   (** Length of packed UUIDs. *)
  42
  43 val uuid_string_length : int
  44   (** Length of UUID strings. *)
  45
  46 (* These phantom types are used to ensure the type-safety of read-only
  47  * versus read-write connections.  For more information see:
  48  * http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html
  49  *)
  50 type rw = [`R|`W]
  51 type ro = [`R]
  52
  53 module Connect :
  54 sig
  55   type 'rw t
  56     (** Connection.  Read-only connections have type [ro Connect.t] and
  57         read-write connections have type [rw Connect.t].
  58       *)
  59
  60   type node_info = {
  61     model : string;                     (** CPU model *)
  62     memory : int64;                     (** memory size in kilobytes *)
  63     cpus : int;                         (** number of active CPUs *)
  64     mhz : int;                          (** expected CPU frequency *)
  65     nodes : int;                        (** number of NUMA nodes (1 = UMA) *)
  66     sockets : int;                      (** number of CPU sockets per node *)
  67     cores : int;                        (** number of cores per socket *)
  68     threads : int;                      (** number of threads per core *)
  69   }
  70
  71   val connect : ?name:string -> unit -> rw t
  72   val connect_readonly : ?name:string -> unit -> ro t
  73     (** [connect ~name ()] connects to the hypervisor with URI [name].
  74
  75         [connect ()] connects to the default hypervisor.
  76
  77         [connect_readonly] is the same but connects in read-only mode.
  78     *)
  79
  80   val close : [>`R] t -> unit
  81     (** [close conn] closes and frees the connection object in memory.
  82
  83         The connection is automatically closed if it is garbage
  84         collected.  This function just forces it to be closed
  85         and freed right away.
  86     *)
  87
  88   val get_type : [>`R] t -> string
  89   val get_version : [>`R] t -> int
  90   val get_hostname : [>`R] t -> string
  91   val get_uri : [>`R] t -> string
  92   val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
  93   val list_domains : [>`R] t -> int -> int array
  94   val num_of_domains : [>`R] t -> int
  95   val get_capabilities : [>`R] t -> string
  96   val num_of_defined_domains : [>`R] t -> int
  97   val list_defined_domains : [>`R] t -> int -> string array
  98   val num_of_networks : [>`R] t -> int
  99   val list_networks : [>`R] t -> int -> string array
 100   val num_of_defined_networks : [>`R] t -> int
 101   val list_defined_networks : [>`R] t -> int -> string array
 102
 103     (* The name of this function is inconsistent, but the inconsistency
 104      * is really in libvirt itself.
 105      *)
 106   val get_node_info : [>`R] t -> node_info
 107
 108   val maxcpus_of_node_info : node_info -> int
 109     (** Calculate the total number of CPUs supported (but not necessarily
 110         active) in the host.
 111     *)
 112
 113   val cpumaplen : int -> int
 114     (** Calculate the length (in bytes) required to store the complete
 115         CPU map between a single virtual and all physical CPUs of a domain.
 116     *)
 117
 118   val use_cpu : string -> int -> unit
 119     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 120   val unuse_cpu : string -> int -> unit
 121     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 122   val cpu_usable : string -> int -> int -> int -> bool
 123     (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
 124         [cpu] is usable by [vcpu]. *)
 125
 126   external const : [>`R] t -> ro t = "%identity"
 127     (** [const conn] turns a read/write connection into a read-only
 128         connection.  Note that the opposite operation is impossible.
 129       *)
 130 end
 131   (** Module dealing with connections.  [Connect.t] is the
 132       connection object.
 133   *)
 134
 135 module Domain :
 136 sig
 137   type 'rw t
 138     (** Domain handle.  Read-only handles have type [ro Domain.t] and
 139         read-write handles have type [rw Domain.t].
 140     *)
 141
 142   type state =
 143     | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
 144     | InfoShutdown | InfoShutoff | InfoCrashed
 145
 146   type info = {
 147     state : state;                      (** running state *)
 148     max_mem : int64;                    (** maximum memory in kilobytes *)
 149     memory : int64;                     (** memory used in kilobytes *)
 150     nr_virt_cpu : int;                  (** number of virtual CPUs *)
 151     cpu_time : int64;                   (** CPU time used in nanoseconds *)
 152   }
 153
 154   type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
 155
 156   type vcpu_info = {
 157     number : int;                       (** virtual CPU number *)
 158     vcpu_state : vcpu_state;            (** state *)
 159     vcpu_time : int64;                  (** CPU time used in nanoseconds *)
 160     cpu : int;                          (** real CPU number, -1 if offline *)
 161   }
 162
 163   type sched_param = string * sched_param_value
 164   and sched_param_value =
 165     | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
 166     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
 167     | SchedFieldFloat of float | SchedFieldBool of bool
 168
 169   type migrate_flag = Live
 170
 171   type block_stats = {
 172     rd_req : int64;
 173     rd_bytes : int64;
 174     wr_req : int64;
 175     wr_bytes : int64;
 176     errs : int64;
 177   }
 178
 179   type interface_stats = {
 180     rx_bytes : int64;
 181     rx_packets : int64;
 182     rx_errs : int64;
 183     rx_drop : int64;
 184     tx_bytes : int64;
 185     tx_packets : int64;
 186     tx_errs : int64;
 187     tx_drop : int64;
 188   }
 189
 190   val create_linux : [>`W] Connect.t -> xml -> rw t
 191   val lookup_by_id : 'a Connect.t -> int -> 'a t
 192   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 193   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 194   val lookup_by_name : 'a Connect.t -> string -> 'a t
 195   val destroy : [>`W] t -> unit
 196   val free : [>`R] t -> unit
 197     (** [free domain] frees the domain object in memory.
 198
 199         The domain object is automatically freed if it is garbage
 200         collected.  This function just forces it to be freed right
 201         away.
 202     *)
 203
 204   val suspend : [>`W] t -> unit
 205   val resume : [>`W] t -> unit
 206   val save : [>`W] t -> string -> unit
 207   val restore : [>`W] Connect.t -> string -> unit
 208   val core_dump : [>`W] t -> string -> unit
 209   val shutdown : [>`W] t -> unit
 210   val reboot : [>`W] t -> unit
 211   val get_name : [>`R] t -> string
 212   val get_uuid : [>`R] t -> uuid
 213   val get_uuid_string : [>`R] t -> string
 214   val get_id : [>`R] t -> int
 215     (** [getid dom] returns the ID of the domain.
 216
 217         Do not call this on a defined but not running domain.  Those
 218         domains don't have IDs, and you'll get an error here.
 219     *)
 220
 221   val get_os_type : [>`R] t -> string
 222   val get_max_memory : [>`R] t -> int64
 223   val set_max_memory : [>`W] t -> int64 -> unit
 224   val set_memory : [>`W] t -> int64 -> unit
 225   val get_info : [>`R] t -> info
 226   val get_xml_desc : [>`R] t -> xml
 227   val get_scheduler_type : [>`R] t -> string * int
 228   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 229   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 230   val define_xml : [>`W] Connect.t -> xml -> rw t
 231   val undefine : [>`W] t -> unit
 232   val create : [>`W] t -> unit
 233   val get_autostart : [>`R] t -> bool
 234   val set_autostart : [>`W] t -> bool -> unit
 235   val set_vcpus : [>`W] t -> int -> unit
 236   val pin_vcpu : [>`W] t -> int -> string -> unit
 237   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 238   val get_max_vcpus : [>`R] t -> int
 239   val attach_device : [>`W] t -> xml -> unit
 240   val detach_device : [>`W] t -> xml -> unit
 241
 242   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 243     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 244
 245   val block_stats : [>`R] t -> string -> block_stats
 246   val interface_stats : [>`R] t -> string -> interface_stats
 247
 248   external const : [>`R] t -> ro t = "%identity"
 249     (** [const dom] turns a read/write domain handle into a read-only
 250         domain handle.  Note that the opposite operation is impossible.
 251       *)
 252 end
 253   (** Module dealing with domains.  [Domain.t] is the
 254       domain object.
 255   *)
 256
 257 module Network :
 258 sig
 259   type 'rw t
 260     (** Network handle.  Read-only handles have type [ro Network.t] and
 261         read-write handles have type [rw Network.t].
 262     *)
 263
 264   val lookup_by_name : 'a Connect.t -> string -> 'a t
 265   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 266   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 267   val create_xml : [>`W] Connect.t -> xml -> rw t
 268   val define_xml : [>`W] Connect.t -> xml -> rw t
 269   val undefine : [>`W] t -> unit
 270   val create : [>`W] t -> unit
 271   val destroy : [>`W] t -> unit
 272   val free : [>`R] t -> unit
 273     (** [free network] frees the network object in memory.
 274
 275         The network object is automatically freed if it is garbage
 276         collected.  This function just forces it to be freed right
 277         away.
 278     *)
 279
 280   val get_name : [>`R] t -> string
 281   val get_uuid : [>`R] t -> uuid
 282   val get_uuid_string : [>`R] t -> string
 283   val get_xml_desc : [>`R] t -> xml
 284   val get_bridge_name : [>`R] t -> string
 285   val get_autostart : [>`R] t -> bool
 286   val set_autostart : [>`W] t -> bool -> unit
 287
 288   external const : [>`R] t -> ro t = "%identity"
 289     (** [const network] turns a read/write network handle into a read-only
 290         network handle.  Note that the opposite operation is impossible.
 291       *)
 292 end
 293   (** Module dealing with networks.  [Network.t] is the
 294       network object.
 295   *)
 296
 297 module Virterror :
 298 sig
 299   type code =
 300     | VIR_ERR_OK
 301     | VIR_ERR_INTERNAL_ERROR
 302     | VIR_ERR_NO_MEMORY
 303     | VIR_ERR_NO_SUPPORT
 304     | VIR_ERR_UNKNOWN_HOST
 305     | VIR_ERR_NO_CONNECT
 306     | VIR_ERR_INVALID_CONN
 307     | VIR_ERR_INVALID_DOMAIN
 308     | VIR_ERR_INVALID_ARG
 309     | VIR_ERR_OPERATION_FAILED
 310     | VIR_ERR_GET_FAILED
 311     | VIR_ERR_POST_FAILED
 312     | VIR_ERR_HTTP_ERROR
 313     | VIR_ERR_SEXPR_SERIAL
 314     | VIR_ERR_NO_XEN
 315     | VIR_ERR_XEN_CALL
 316     | VIR_ERR_OS_TYPE
 317     | VIR_ERR_NO_KERNEL
 318     | VIR_ERR_NO_ROOT
 319     | VIR_ERR_NO_SOURCE
 320     | VIR_ERR_NO_TARGET
 321     | VIR_ERR_NO_NAME
 322     | VIR_ERR_NO_OS
 323     | VIR_ERR_NO_DEVICE
 324     | VIR_ERR_NO_XENSTORE
 325     | VIR_ERR_DRIVER_FULL
 326     | VIR_ERR_CALL_FAILED
 327     | VIR_ERR_XML_ERROR
 328     | VIR_ERR_DOM_EXIST
 329     | VIR_ERR_OPERATION_DENIED
 330     | VIR_ERR_OPEN_FAILED
 331     | VIR_ERR_READ_FAILED
 332     | VIR_ERR_PARSE_FAILED
 333     | VIR_ERR_CONF_SYNTAX
 334     | VIR_ERR_WRITE_FAILED
 335     | VIR_ERR_XML_DETAIL
 336     | VIR_ERR_INVALID_NETWORK
 337     | VIR_ERR_NETWORK_EXIST
 338     | VIR_ERR_SYSTEM_ERROR
 339     | VIR_ERR_RPC
 340     | VIR_ERR_GNUTLS_ERROR
 341     | VIR_WAR_NO_NETWORK
 342     | VIR_ERR_NO_DOMAIN
 343     | VIR_ERR_NO_NETWORK
 344         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
 345
 346   val string_of_code : code -> string
 347
 348   type level =
 349     | VIR_ERR_NONE
 350     | VIR_ERR_WARNING
 351     | VIR_ERR_ERROR
 352         (** No error, a warning or an error. *)
 353
 354   val string_of_level : level -> string
 355
 356   type domain =
 357     | VIR_FROM_NONE
 358     | VIR_FROM_XEN
 359     | VIR_FROM_XEND
 360     | VIR_FROM_XENSTORE
 361     | VIR_FROM_SEXPR
 362     | VIR_FROM_XML
 363     | VIR_FROM_DOM
 364     | VIR_FROM_RPC
 365     | VIR_FROM_PROXY
 366     | VIR_FROM_CONF
 367     | VIR_FROM_QEMU
 368     | VIR_FROM_NET
 369     | VIR_FROM_TEST
 370     | VIR_FROM_REMOTE
 371         (** Subsystem / driver which produced the error. *)
 372
 373   val string_of_domain : domain -> string
 374
 375   type t = {
 376     code : code;                        (** Error code. *)
 377     domain : domain;                    (** Origin of the error. *)
 378     message : string option;            (** Human-readable message. *)
 379     level : level;                      (** Error or warning. *)
 380     conn : ro Connect.t option;         (** Associated connection. *)
 381     dom : ro Domain.t option;           (** Associated domain. *)
 382     str1 : string option;               (** Informational string. *)
 383     str2 : string option;               (** Informational string. *)
 384     str3 : string option;               (** Informational string. *)
 385     int1 : int32;                       (** Informational integer. *)
 386     int2 : int32;                       (** Informational integer. *)
 387     net : ro Network.t option;          (** Associated network. *)
 388   }
 389     (** An error object. *)
 390
 391   val to_string : t -> string
 392     (** Turn the exception into a printable string. *)
 393
 394   val get_last_error : unit -> t option
 395   val get_last_conn_error : [>`R] Connect.t -> t option
 396     (** Get the last error at a global or connection level.
 397
 398         Normally you do not need to use these functions because
 399         the library automatically turns errors into exceptions.
 400     *)
 401
 402   val reset_last_error : unit -> unit
 403   val reset_last_conn_error : [>`R] Connect.t -> unit
 404     (** Reset the error at a global or connection level.
 405
 406         Normally you do not need to use these functions.
 407     *)
 408
 409   val no_error : unit -> t
 410     (** Creates an empty error message.
 411
 412         Normally you do not need to use this function.
 413     *)
 414 end
 415   (** Module dealing with errors. *)
 416
 417 exception Virterror of Virterror.t
 418 (** This exception can be raised by any library function that detects
 419     an error.  To get a printable error message, call
 420     {!Virterror.to_string} on the content of this exception.
 421
 422     Note that functions may also raise
 423     [Invalid_argument "virFoo not supported"]
 424     (where virFoo is the libvirt function name) if a function is
 425     not supported at either compile or runtime.  This applies to
 426     any libvirt function added after version 0.2.1.
 427     See also [http://libvirt.org/hvsupport.html]
 428 *)
 429