libvirt/libvirt.mli

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