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 node_get_free_memory : [> `R] t -> int64
 109     (**
 110        [node_get_free_memory conn]
 111        returns the amount of free memory (not allocated to any guest)
 112        in the machine.
 113     *)
 114
 115   val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
 116     (**
 117        [node_get_cells_free_memory conn start max]
 118        returns the amount of free memory on each NUMA cell in kilobytes.
 119        [start] is the first cell for which we return free memory.
 120        [max] is the maximum number of cells for which we return free memory.
 121        Returns an array of up to [max] entries in length.
 122     *)
 123
 124   val maxcpus_of_node_info : node_info -> int
 125     (** Calculate the total number of CPUs supported (but not necessarily
 126         active) in the host.
 127     *)
 128
 129   val cpumaplen : int -> int
 130     (** Calculate the length (in bytes) required to store the complete
 131         CPU map between a single virtual and all physical CPUs of a domain.
 132     *)
 133
 134   val use_cpu : string -> int -> unit
 135     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 136   val unuse_cpu : string -> int -> unit
 137     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 138   val cpu_usable : string -> int -> int -> int -> bool
 139     (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
 140         [cpu] is usable by [vcpu]. *)
 141
 142   external const : [>`R] t -> ro t = "%identity"
 143     (** [const conn] turns a read/write connection into a read-only
 144         connection.  Note that the opposite operation is impossible.
 145       *)
 146 end
 147   (** Module dealing with connections.  [Connect.t] is the
 148       connection object.
 149   *)
 150
 151 module Domain :
 152 sig
 153   type 'rw t
 154     (** Domain handle.  Read-only handles have type [ro Domain.t] and
 155         read-write handles have type [rw Domain.t].
 156     *)
 157
 158   type state =
 159     | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
 160     | InfoShutdown | InfoShutoff | InfoCrashed
 161
 162   type info = {
 163     state : state;                      (** running state *)
 164     max_mem : int64;                    (** maximum memory in kilobytes *)
 165     memory : int64;                     (** memory used in kilobytes *)
 166     nr_virt_cpu : int;                  (** number of virtual CPUs *)
 167     cpu_time : int64;                   (** CPU time used in nanoseconds *)
 168   }
 169
 170   type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
 171
 172   type vcpu_info = {
 173     number : int;                       (** virtual CPU number *)
 174     vcpu_state : vcpu_state;            (** state *)
 175     vcpu_time : int64;                  (** CPU time used in nanoseconds *)
 176     cpu : int;                          (** real CPU number, -1 if offline *)
 177   }
 178
 179   type sched_param = string * sched_param_value
 180   and sched_param_value =
 181     | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
 182     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
 183     | SchedFieldFloat of float | SchedFieldBool of bool
 184
 185   type migrate_flag = Live
 186
 187   type block_stats = {
 188     rd_req : int64;
 189     rd_bytes : int64;
 190     wr_req : int64;
 191     wr_bytes : int64;
 192     errs : int64;
 193   }
 194
 195   type interface_stats = {
 196     rx_bytes : int64;
 197     rx_packets : int64;
 198     rx_errs : int64;
 199     rx_drop : int64;
 200     tx_bytes : int64;
 201     tx_packets : int64;
 202     tx_errs : int64;
 203     tx_drop : int64;
 204   }
 205
 206   val create_linux : [>`W] Connect.t -> xml -> rw t
 207   val lookup_by_id : 'a Connect.t -> int -> 'a t
 208   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 209   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 210   val lookup_by_name : 'a Connect.t -> string -> 'a t
 211   val destroy : [>`W] t -> unit
 212   val free : [>`R] t -> unit
 213     (** [free domain] frees the domain object in memory.
 214
 215         The domain object is automatically freed if it is garbage
 216         collected.  This function just forces it to be freed right
 217         away.
 218     *)
 219
 220   val suspend : [>`W] t -> unit
 221   val resume : [>`W] t -> unit
 222   val save : [>`W] t -> string -> unit
 223   val restore : [>`W] Connect.t -> string -> unit
 224   val core_dump : [>`W] t -> string -> unit
 225   val shutdown : [>`W] t -> unit
 226   val reboot : [>`W] t -> unit
 227   val get_name : [>`R] t -> string
 228   val get_uuid : [>`R] t -> uuid
 229   val get_uuid_string : [>`R] t -> string
 230   val get_id : [>`R] t -> int
 231     (** [getid dom] returns the ID of the domain.
 232
 233         Do not call this on a defined but not running domain.  Those
 234         domains don't have IDs, and you'll get an error here.
 235     *)
 236
 237   val get_os_type : [>`R] t -> string
 238   val get_max_memory : [>`R] t -> int64
 239   val set_max_memory : [>`W] t -> int64 -> unit
 240   val set_memory : [>`W] t -> int64 -> unit
 241   val get_info : [>`R] t -> info
 242   val get_xml_desc : [>`R] t -> xml
 243   val get_scheduler_type : [>`R] t -> string * int
 244   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 245   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 246   val define_xml : [>`W] Connect.t -> xml -> rw t
 247   val undefine : [>`W] t -> unit
 248   val create : [>`W] t -> unit
 249   val get_autostart : [>`R] t -> bool
 250   val set_autostart : [>`W] t -> bool -> unit
 251   val set_vcpus : [>`W] t -> int -> unit
 252   val pin_vcpu : [>`W] t -> int -> string -> unit
 253   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 254   val get_max_vcpus : [>`R] t -> int
 255   val attach_device : [>`W] t -> xml -> unit
 256   val detach_device : [>`W] t -> xml -> unit
 257
 258   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 259     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 260
 261   val block_stats : [>`R] t -> string -> block_stats
 262   val interface_stats : [>`R] t -> string -> interface_stats
 263
 264   external const : [>`R] t -> ro t = "%identity"
 265     (** [const dom] turns a read/write domain handle into a read-only
 266         domain handle.  Note that the opposite operation is impossible.
 267       *)
 268 end
 269   (** Module dealing with domains.  [Domain.t] is the
 270       domain object.
 271   *)
 272
 273 module Network :
 274 sig
 275   type 'rw t
 276     (** Network handle.  Read-only handles have type [ro Network.t] and
 277         read-write handles have type [rw Network.t].
 278     *)
 279
 280   val lookup_by_name : 'a Connect.t -> string -> 'a t
 281   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 282   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 283   val create_xml : [>`W] Connect.t -> xml -> rw t
 284   val define_xml : [>`W] Connect.t -> xml -> rw t
 285   val undefine : [>`W] t -> unit
 286   val create : [>`W] t -> unit
 287   val destroy : [>`W] t -> unit
 288   val free : [>`R] t -> unit
 289     (** [free network] frees the network object in memory.
 290
 291         The network object is automatically freed if it is garbage
 292         collected.  This function just forces it to be freed right
 293         away.
 294     *)
 295
 296   val get_name : [>`R] t -> string
 297   val get_uuid : [>`R] t -> uuid
 298   val get_uuid_string : [>`R] t -> string
 299   val get_xml_desc : [>`R] t -> xml
 300   val get_bridge_name : [>`R] t -> string
 301   val get_autostart : [>`R] t -> bool
 302   val set_autostart : [>`W] t -> bool -> unit
 303
 304   external const : [>`R] t -> ro t = "%identity"
 305     (** [const network] turns a read/write network handle into a read-only
 306         network handle.  Note that the opposite operation is impossible.
 307       *)
 308 end
 309   (** Module dealing with networks.  [Network.t] is the
 310       network object.
 311   *)
 312
 313 module Virterror :
 314 sig
 315   type code =
 316     | VIR_ERR_OK
 317     | VIR_ERR_INTERNAL_ERROR
 318     | VIR_ERR_NO_MEMORY
 319     | VIR_ERR_NO_SUPPORT
 320     | VIR_ERR_UNKNOWN_HOST
 321     | VIR_ERR_NO_CONNECT
 322     | VIR_ERR_INVALID_CONN
 323     | VIR_ERR_INVALID_DOMAIN
 324     | VIR_ERR_INVALID_ARG
 325     | VIR_ERR_OPERATION_FAILED
 326     | VIR_ERR_GET_FAILED
 327     | VIR_ERR_POST_FAILED
 328     | VIR_ERR_HTTP_ERROR
 329     | VIR_ERR_SEXPR_SERIAL
 330     | VIR_ERR_NO_XEN
 331     | VIR_ERR_XEN_CALL
 332     | VIR_ERR_OS_TYPE
 333     | VIR_ERR_NO_KERNEL
 334     | VIR_ERR_NO_ROOT
 335     | VIR_ERR_NO_SOURCE
 336     | VIR_ERR_NO_TARGET
 337     | VIR_ERR_NO_NAME
 338     | VIR_ERR_NO_OS
 339     | VIR_ERR_NO_DEVICE
 340     | VIR_ERR_NO_XENSTORE
 341     | VIR_ERR_DRIVER_FULL
 342     | VIR_ERR_CALL_FAILED
 343     | VIR_ERR_XML_ERROR
 344     | VIR_ERR_DOM_EXIST
 345     | VIR_ERR_OPERATION_DENIED
 346     | VIR_ERR_OPEN_FAILED
 347     | VIR_ERR_READ_FAILED
 348     | VIR_ERR_PARSE_FAILED
 349     | VIR_ERR_CONF_SYNTAX
 350     | VIR_ERR_WRITE_FAILED
 351     | VIR_ERR_XML_DETAIL
 352     | VIR_ERR_INVALID_NETWORK
 353     | VIR_ERR_NETWORK_EXIST
 354     | VIR_ERR_SYSTEM_ERROR
 355     | VIR_ERR_RPC
 356     | VIR_ERR_GNUTLS_ERROR
 357     | VIR_WAR_NO_NETWORK
 358     | VIR_ERR_NO_DOMAIN
 359     | VIR_ERR_NO_NETWORK
 360         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
 361
 362   val string_of_code : code -> string
 363
 364   type level =
 365     | VIR_ERR_NONE
 366     | VIR_ERR_WARNING
 367     | VIR_ERR_ERROR
 368         (** No error, a warning or an error. *)
 369
 370   val string_of_level : level -> string
 371
 372   type domain =
 373     | VIR_FROM_NONE
 374     | VIR_FROM_XEN
 375     | VIR_FROM_XEND
 376     | VIR_FROM_XENSTORE
 377     | VIR_FROM_SEXPR
 378     | VIR_FROM_XML
 379     | VIR_FROM_DOM
 380     | VIR_FROM_RPC
 381     | VIR_FROM_PROXY
 382     | VIR_FROM_CONF
 383     | VIR_FROM_QEMU
 384     | VIR_FROM_NET
 385     | VIR_FROM_TEST
 386     | VIR_FROM_REMOTE
 387         (** Subsystem / driver which produced the error. *)
 388
 389   val string_of_domain : domain -> string
 390
 391   type t = {
 392     code : code;                        (** Error code. *)
 393     domain : domain;                    (** Origin of the error. *)
 394     message : string option;            (** Human-readable message. *)
 395     level : level;                      (** Error or warning. *)
 396     conn : ro Connect.t option;         (** Associated connection. *)
 397     dom : ro Domain.t option;           (** Associated domain. *)
 398     str1 : string option;               (** Informational string. *)
 399     str2 : string option;               (** Informational string. *)
 400     str3 : string option;               (** Informational string. *)
 401     int1 : int32;                       (** Informational integer. *)
 402     int2 : int32;                       (** Informational integer. *)
 403     net : ro Network.t option;          (** Associated network. *)
 404   }
 405     (** An error object. *)
 406
 407   val to_string : t -> string
 408     (** Turn the exception into a printable string. *)
 409
 410   val get_last_error : unit -> t option
 411   val get_last_conn_error : [>`R] Connect.t -> t option
 412     (** Get the last error at a global or connection level.
 413
 414         Normally you do not need to use these functions because
 415         the library automatically turns errors into exceptions.
 416     *)
 417
 418   val reset_last_error : unit -> unit
 419   val reset_last_conn_error : [>`R] Connect.t -> unit
 420     (** Reset the error at a global or connection level.
 421
 422         Normally you do not need to use these functions.
 423     *)
 424
 425   val no_error : unit -> t
 426     (** Creates an empty error message.
 427
 428         Normally you do not need to use this function.
 429     *)
 430 end
 431   (** Module dealing with errors. *)
 432
 433 exception Virterror of Virterror.t
 434 (** This exception can be raised by any library function that detects
 435     an error.  To get a printable error message, call
 436     {!Virterror.to_string} on the content of this exception.
 437
 438     Note that functions may also raise
 439     [Invalid_argument "virFoo not supported"]
 440     (where virFoo is the libvirt function name) if a function is
 441     not supported at either compile or runtime.  This applies to
 442     any libvirt function added after version 0.2.1.
 443     See also [http://libvirt.org/hvsupport.html]
 444 *)
 445