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