From 92b683260beb687d331562ff95c40adf08bb259a Mon Sep 17 00:00:00 2001 From: Andrii Sultanov Date: Fri, 20 Sep 2024 08:22:30 +0100 Subject: [PATCH 1/8] idl: Make in_product_since default value explicit and unnecessary with lifecycle provided in_product_since was always given a 'Some value' for fields, meaning that the exception for a not provided lifecycle parameter would never be triggered. Force to specify either a lifecycle (for newer fields), or in_product_since (older ones), but not both. No functional change, and all parameters have been made explicit since otherwise this commit would fail to build. Signed-off-by: Andrii Sultanov --- ocaml/idl/datamodel.ml | 556 +++++++++++++++++++--------------- ocaml/idl/datamodel_common.ml | 29 +- ocaml/idl/datamodel_host.ml | 82 ++--- ocaml/idl/datamodel_pool.ml | 30 +- ocaml/idl/datamodel_vm.ml | 124 ++++---- ocaml/idl/datamodel_vtpm.ml | 3 +- 6 files changed, 473 insertions(+), 351 deletions(-) diff --git a/ocaml/idl/datamodel.ml b/ocaml/idl/datamodel.ml index 737ecc53b0f..d2471e720f2 100644 --- a/ocaml/idl/datamodel.ml +++ b/ocaml/idl/datamodel.ml @@ -195,13 +195,14 @@ module Session = struct ~contents: [ uid _session - ; field ~qualifier:DynamicRO ~ty:(Ref _host) "this_host" - "Currently connected host" - ; field ~qualifier:DynamicRO ~ty:(Ref _user) "this_user" - "Currently connected user" - ; field ~qualifier:DynamicRO ~ty:DateTime "last_active" - "Timestamp for last time session was active" - ; field ~qualifier:DynamicRO ~ty:Bool ~in_oss_since:None "pool" + ; field ~qualifier:DynamicRO ~ty:(Ref _host) ~in_product_since:rel_rio + "this_host" "Currently connected host" + ; field ~qualifier:DynamicRO ~ty:(Ref _user) ~in_product_since:rel_rio + "this_user" "Currently connected user" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "last_active" "Timestamp for last time session was active" + ; field ~qualifier:DynamicRO ~ty:Bool ~in_oss_since:None + ~in_product_since:rel_rio "pool" "True if this session relates to a intra-pool login, false \ otherwise" ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) @@ -384,46 +385,53 @@ module Task = struct ] @ allowed_and_current_operations task_allowed_operations @ [ - field ~qualifier:DynamicRO ~ty:DateTime "created" - "Time task was created" - ; field ~qualifier:DynamicRO ~ty:DateTime "finished" + field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "created" "Time task was created" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "finished" "Time task finished (i.e. succeeded or failed). If task-status \ is pending, then the value of this field has no meaning" - ; field ~qualifier:DynamicRO ~ty:status_type "status" - "current status of the task" - ; field ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:(Ref _session) "session" "the session that created the task" - ; field ~qualifier:DynamicRO ~ty:(Ref _host) "resident_on" - "the host on which the task is running" - ; field ~qualifier:DynamicRO ~ty:Float "progress" + ; field ~qualifier:DynamicRO ~ty:status_type ~in_product_since:rel_rio + "status" "current status of the task" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~internal_only:true ~qualifier:DynamicRO ~ty:(Ref _session) + "session" "the session that created the task" + ; field ~qualifier:DynamicRO ~ty:(Ref _host) ~in_product_since:rel_rio + "resident_on" "the host on which the task is running" + ; field ~qualifier:DynamicRO ~ty:Float ~in_product_since:rel_rio + "progress" "This field contains the estimated fraction of the task which is \ complete. This field should not be used to determine whether \ the task is complete - for this the status field of the task \ should be used." - ; field ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:Int "externalpid" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~internal_only:true ~qualifier:DynamicRO ~ty:Int "externalpid" "If the task has spawned a program, the field record the PID of \ the process that the task is waiting on. (-1 if no waiting \ completion of an external program )" - ; field ~in_oss_since:None ~internal_deprecated_since:rel_boston - ~internal_only:true ~qualifier:DynamicRO ~ty:Int "stunnelpid" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~internal_deprecated_since:rel_boston ~internal_only:true + ~qualifier:DynamicRO ~ty:Int "stunnelpid" "If the task has been forwarded, this field records the pid of \ the stunnel process spawned to manage the forwarding connection" - ; field ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:Bool "forwarded" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~internal_only:true ~qualifier:DynamicRO ~ty:Bool "forwarded" "True if this task has been forwarded to a slave" - ; field ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:(Ref _host) "forwarded_to" - "The host to which the task has been forwarded" - ; field ~qualifier:DynamicRO ~ty:String "type" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~internal_only:true ~qualifier:DynamicRO ~ty:(Ref _host) + "forwarded_to" "The host to which the task has been forwarded" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "type" "if the task has completed successfully, this field contains the \ type of the encoded result (i.e. name of the class whose \ reference is in the result field). Undefined otherwise." - ; field ~qualifier:DynamicRO ~ty:String "result" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "result" "if the task has completed successfully, this field contains the \ result value (either Void or an object reference). Undefined \ otherwise." - ; field ~qualifier:DynamicRO ~ty:(Set String) "error_info" + ; field ~qualifier:DynamicRO ~ty:(Set String) + ~in_product_since:rel_rio "error_info" "if the task has failed, this field contains the set of \ associated error strings. Undefined otherwise." ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) @@ -492,8 +500,9 @@ module User = struct ~contents: [ uid _user - ; field ~qualifier:StaticRO "short_name" "short name (e.g. userid)" - ; field "fullname" "full name" + ; field ~qualifier:StaticRO ~in_product_since:rel_rio "short_name" + "short name (e.g. userid)" + ; field ~in_product_since:rel_rio "fullname" "full name" ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -535,14 +544,16 @@ module Host_crashdump = struct ~contents: [ uid ~in_oss_since:None _host_crashdump - ; field ~in_oss_since:None ~qualifier:StaticRO ~ty:(Ref _host) "host" - "Host the crashdump relates to" - ; field ~in_oss_since:None ~qualifier:DynamicRO ~ty:DateTime "timestamp" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO + ~ty:(Ref _host) "host" "Host the crashdump relates to" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:DateTime "timestamp" "Time the crash happened" - ; field ~in_oss_since:None ~qualifier:DynamicRO ~ty:Int "size" - "Size of the crashdump" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:Int "size" "Size of the crashdump" ; field ~qualifier:StaticRO ~ty:String ~in_oss_since:None - ~internal_only:true "filename" "filename of crash dir" + ~in_product_since:rel_rio ~internal_only:true "filename" + "filename of crash dir" ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -711,8 +722,8 @@ module Pool_update = struct ~in_oss_since:None ~qualifier:StaticRO ~ty:(Set after_apply_guidance) "after_apply_guidance" "What the client should do after this update has been applied." - ; field ~in_oss_since:None ~qualifier:StaticRO ~ty:(Ref _vdi) "vdi" - "VDI the update was uploaded to" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO + ~ty:(Ref _vdi) "vdi" "VDI the update was uploaded to" ; field ~in_product_since:rel_ely ~in_oss_since:None ~qualifier:DynamicRO ~ty:(Set (Ref _host)) "hosts" "The hosts that have applied this update." @@ -892,18 +903,20 @@ module Host_patch = struct [ uid ~in_oss_since:None _host_patch ; namespace ~name:"name" ~contents:(names None StaticRO) () - ; field ~in_oss_since:None ~qualifier:StaticRO ~ty:String "version" - "Patch version number" - ; field ~in_oss_since:None ~qualifier:StaticRO ~ty:(Ref _host) "host" - "Host the patch relates to" - ; field ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:String "filename" "Filename of the patch" - ; field ~in_oss_since:None ~qualifier:DynamicRO ~ty:Bool "applied" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO + ~ty:String "version" "Patch version number" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO + ~ty:(Ref _host) "host" "Host the patch relates to" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~internal_only:true + ~qualifier:DynamicRO ~ty:String "filename" "Filename of the patch" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:Bool "applied" "True if the patch has been applied" - ; field ~in_oss_since:None ~qualifier:DynamicRO ~ty:DateTime - "timestamp_applied" "Time the patch was applied" - ; field ~in_oss_since:None ~qualifier:DynamicRO ~ty:Int "size" - "Size of the patch" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:DateTime "timestamp_applied" + "Time the patch was applied" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:Int "size" "Size of the patch" ; field ~in_product_since:rel_miami ~in_oss_since:None ~qualifier:StaticRO ~ty:(Ref _pool_patch) ~default_value:(Some (VRef "")) "pool_patch" "The patch applied" @@ -919,8 +932,8 @@ module Host_metrics = struct let host_metrics_memory = let field = field ~ty:Int in [ - field ~qualifier:DynamicRO "total" "Total host memory (bytes)" - ~doc_tags:[Memory] + field ~qualifier:DynamicRO ~in_product_since:rel_rio "total" + "Total host memory (bytes)" ~doc_tags:[Memory] ; field "free" "Free host memory (bytes)" ~default_value:(Some (VInt 0L)) ~lifecycle: [ @@ -942,9 +955,9 @@ module Host_metrics = struct uid _host_metrics ; namespace ~name:"memory" ~contents:host_metrics_memory () ; field ~qualifier:DynamicRO ~ty:Bool ~in_oss_since:None "live" - "Pool master thinks this host is live" - ; field ~qualifier:DynamicRO ~ty:DateTime "last_updated" - "Time at which this information was last updated" + ~in_product_since:rel_rio "Pool master thinks this host is live" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "last_updated" "Time at which this information was last updated" ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -971,28 +984,30 @@ module Host_cpu = struct ~contents: [ uid _hostcpu - ; field ~qualifier:DynamicRO ~ty:(Ref _host) "host" - "the host the CPU is in" - ; field ~qualifier:DynamicRO ~ty:Int "number" + ; field ~qualifier:DynamicRO ~ty:(Ref _host) ~in_product_since:rel_rio + "host" "the host the CPU is in" + ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "number" "the number of the physical CPU within the host" - ; field ~qualifier:DynamicRO ~ty:String "vendor" - "the vendor of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:Int "speed" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "vendor" "the vendor of the physical CPU" + ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "speed" "the speed of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:String "modelname" - "the model name of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:Int "family" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "modelname" "the model name of the physical CPU" + ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "family" "the family (number) of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:Int "model" + ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "model" "the model number of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:String "stepping" - "the stepping of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:String "flags" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "stepping" "the stepping of the physical CPU" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "flags" "the flags of the physical CPU (a decoded version of the features \ field)" - ; field ~qualifier:DynamicRO ~ty:String "features" - "the physical CPU feature bitmap" - ; field ~qualifier:DynamicRO ~persist:false ~ty:Float "utilisation" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "features" "the physical CPU feature bitmap" + ; field ~qualifier:DynamicRO ~persist:false ~ty:Float + ~in_product_since:rel_rio "utilisation" "the current CPU utilisation" ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) @@ -1004,11 +1019,13 @@ end (** Disk and network interfaces are associated with QoS parameters: *) let qos devtype = [ - field "algorithm_type" "QoS algorithm to use" + field ~in_product_since:rel_rio "algorithm_type" "QoS algorithm to use" ; field ~ty:(Map (String, String)) - "algorithm_params" "parameters for chosen QoS algorithm" - ; field ~qualifier:DynamicRO ~ty:(Set String) "supported_algorithms" + ~in_product_since:rel_rio "algorithm_params" + "parameters for chosen QoS algorithm" + ; field ~qualifier:DynamicRO ~ty:(Set String) ~in_product_since:rel_rio + "supported_algorithms" ("supported QoS algorithms for this " ^ devtype) ] @@ -1255,10 +1272,10 @@ module Network = struct ] @ allowed_and_current_operations ~writer_roles:_R_POOL_OP operations @ [ - field ~qualifier:DynamicRO ~ty:(Set (Ref _vif)) "VIFs" - "list of connected vifs" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pif)) "PIFs" - "list of connected pifs" + field ~qualifier:DynamicRO ~ty:(Set (Ref _vif)) + ~in_product_since:rel_rio "VIFs" "list of connected vifs" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pif)) + ~in_product_since:rel_rio "PIFs" "list of connected pifs" ; field ~qualifier:RW ~ty:Int ~default_value:(Some (VInt 1500L)) ~in_product_since:rel_midnight_ride "MTU" "MTU in octets" ; field ~writer_roles:_R_POOL_OP @@ -1270,6 +1287,7 @@ module Network = struct ; ("XenCenter.CustomFields.*", _R_VM_OP) ; ("XenCenterCreateInProgress", _R_VM_OP) ] + ~in_product_since:rel_rio ; field ~lifecycle: [ @@ -1786,23 +1804,25 @@ module PIF = struct [ uid _pif ; (* qualifier changed RW -> StaticRO in Miami *) - field ~qualifier:StaticRO "device" + field ~qualifier:StaticRO ~in_product_since:rel_rio "device" "machine-readable name of the interface (e.g. eth0)" - ; field ~qualifier:StaticRO ~ty:(Ref _network) "network" - "virtual network to which this pif is connected" - ; field ~qualifier:StaticRO ~ty:(Ref _host) "host" - "physical machine to which this pif is connected" + ; field ~qualifier:StaticRO ~ty:(Ref _network) ~in_product_since:rel_rio + "network" "virtual network to which this pif is connected" + ; field ~qualifier:StaticRO ~ty:(Ref _host) ~in_product_since:rel_rio + "host" "physical machine to which this pif is connected" ; (* qualifier changed RW -> StaticRO in Miami *) - field ~qualifier:StaticRO "MAC" + field ~qualifier:StaticRO ~in_product_since:rel_rio "MAC" "ethernet MAC address of physical interface" ; (* qualifier changed RW -> StaticRO in Miami *) - field ~qualifier:StaticRO ~ty:Int "MTU" "MTU in octets" + field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio "MTU" + "MTU in octets" ; (* qualifier changed RW -> StaticRO in Miami *) - field ~qualifier:StaticRO ~ty:Int "VLAN" + field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio "VLAN" "VLAN tag for all traffic passing through this interface" - ; field ~in_oss_since:None ~internal_only:true "device_name" - "actual dom0 device name" - ; field ~qualifier:DynamicRO ~ty:(Ref _pif_metrics) "metrics" + ; field ~in_oss_since:None ~internal_only:true ~in_product_since:rel_rio + "device_name" "actual dom0 device name" + ; field ~qualifier:DynamicRO ~ty:(Ref _pif_metrics) + ~in_product_since:rel_rio "metrics" "metrics associated with this PIF" ; field ~in_oss_since:None ~ty:Bool ~in_product_since:rel_miami ~qualifier:DynamicRO "physical" @@ -1948,22 +1968,24 @@ module PIF_metrics = struct [ uid _pif_metrics ; namespace ~name:"io" ~contents:iobandwidth () - ; field ~qualifier:DynamicRO ~ty:Bool "carrier" - "Report if the PIF got a carrier or not" - ; field ~qualifier:DynamicRO ~ty:String "vendor_id" "Report vendor ID" - ; field ~qualifier:DynamicRO ~ty:String "vendor_name" - "Report vendor name" - ; field ~qualifier:DynamicRO ~ty:String "device_id" "Report device ID" - ; field ~qualifier:DynamicRO ~ty:String "device_name" - "Report device name" - ; field ~qualifier:DynamicRO ~ty:Int "speed" + ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + "carrier" "Report if the PIF got a carrier or not" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "vendor_id" "Report vendor ID" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "vendor_name" "Report vendor name" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "device_id" "Report device ID" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "device_name" "Report device name" + ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "speed" "Speed of the link in Mbit/s (if available)" - ; field ~qualifier:DynamicRO ~ty:Bool "duplex" + ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio "duplex" "Full duplex capability of the link (if available)" - ; field ~qualifier:DynamicRO ~ty:String "pci_bus_path" - "PCI bus path of the pif (if available)" - ; field ~qualifier:DynamicRO ~ty:DateTime "last_updated" - "Time at which this information was last updated" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "pci_bus_path" "PCI bus path of the pif (if available)" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "last_updated" "Time at which this information was last updated" ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -2321,17 +2343,17 @@ module PBD = struct ~contents: [ uid _pbd - ; field ~qualifier:StaticRO ~ty:(Ref _host) "host" - "physical machine on which the pbd is available" - ; field ~qualifier:StaticRO ~ty:(Ref _sr) "SR" + ; field ~qualifier:StaticRO ~ty:(Ref _host) ~in_product_since:rel_rio + "host" "physical machine on which the pbd is available" + ; field ~qualifier:StaticRO ~ty:(Ref _sr) ~in_product_since:rel_rio "SR" "the storage repository that the pbd realises" ; field ~ty:(Map (String, String)) - ~qualifier:StaticRO "device_config" + ~qualifier:StaticRO "device_config" ~in_product_since:rel_rio "a config string to string map that is provided to the host's \ SR-backend-driver" - ; field ~ty:Bool ~qualifier:DynamicRO "currently_attached" - "is the SR currently attached on this host?" + ; field ~ty:Bool ~qualifier:DynamicRO ~in_product_since:rel_rio + "currently_attached" "is the SR currently attached on this host?" ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -2353,15 +2375,17 @@ let device_status_fields = ) ] "currently_attached" "is the device currently attached (erased on reboot)" - ; field ~ty:Int ~qualifier:DynamicRO "status_code" + ; field ~ty:Int ~qualifier:DynamicRO ~in_product_since:rel_rio "status_code" "error/success code associated with last attach-operation (erased on \ reboot)" - ; field ~ty:String ~qualifier:DynamicRO "status_detail" + ; field ~ty:String ~qualifier:DynamicRO ~in_product_since:rel_rio + "status_detail" "error/success information associated with last attach-operation status \ (erased on reboot)" ; field ~ty:(Map (String, String)) - ~qualifier:DynamicRO "runtime_properties" "Device runtime properties" + ~qualifier:DynamicRO ~in_product_since:rel_rio "runtime_properties" + "Device runtime properties" ] module VIF = struct @@ -2652,21 +2676,24 @@ module VIF = struct ([uid _vif] @ allowed_and_current_operations operations @ [ - field ~qualifier:StaticRO "device" + field ~qualifier:StaticRO ~in_product_since:rel_rio "device" "order in which VIF backends are created by xapi" - ; field ~qualifier:StaticRO ~ty:(Ref _network) "network" + ; field ~qualifier:StaticRO ~ty:(Ref _network) + ~in_product_since:rel_rio "network" "virtual network to which this vif is connected" - ; field ~qualifier:StaticRO ~ty:(Ref _vm) "VM" - "virtual machine to which this vif is connected" - ; field ~qualifier:StaticRO ~ty:String "MAC" + ; field ~qualifier:StaticRO ~ty:(Ref _vm) ~in_product_since:rel_rio + "VM" "virtual machine to which this vif is connected" + ; field ~qualifier:StaticRO ~ty:String ~in_product_since:rel_rio "MAC" "ethernet MAC address of virtual interface, as exposed to guest" - ; field ~qualifier:StaticRO ~ty:Int "MTU" "MTU in octets" - ; field ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:Bool "reserved" + ; field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio "MTU" + "MTU in octets" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~internal_only:true ~qualifier:DynamicRO ~ty:Bool "reserved" "true if the VIF is reserved pending a reboot/migrate" ; field ~ty:(Map (String, String)) - "other_config" "additional configuration" + ~in_product_since:rel_rio "other_config" + "additional configuration" ] @ device_status_fields @ [namespace ~name:"qos" ~contents:(qos "VIF") ()] @@ -2748,8 +2775,8 @@ module VIF_metrics = struct [ uid _vif_metrics ; namespace ~name:"io" ~contents:iobandwidth () - ; field ~qualifier:DynamicRO ~ty:DateTime "last_updated" - "Time at which this information was last updated" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "last_updated" "Time at which this information was last updated" ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -2767,17 +2794,19 @@ module Data_source = struct ~contents: [ namespace ~name:"name" ~contents:(names oss_since_303 DynamicRO) () - ; field ~qualifier:DynamicRO ~ty:Bool "enabled" - "true if the data source is being logged" - ; field ~qualifier:DynamicRO ~ty:Bool "standard" + ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + "enabled" "true if the data source is being logged" + ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + "standard" "true if the data source is enabled by default. Non-default data \ sources cannot be disabled" - ; field ~qualifier:DynamicRO ~ty:String "units" "the units of the value" - ; field ~qualifier:DynamicRO ~ty:Float "min" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "units" "the units of the value" + ; field ~qualifier:DynamicRO ~ty:Float ~in_product_since:rel_rio "min" "the minimum value of the data source" - ; field ~qualifier:DynamicRO ~ty:Float "max" + ; field ~qualifier:DynamicRO ~ty:Float ~in_product_since:rel_rio "max" "the maximum value of the data source" - ; field ~qualifier:DynamicRO ~ty:Float "value" + ; field ~qualifier:DynamicRO ~ty:Float ~in_product_since:rel_rio "value" "current value of the data source" ] () @@ -3371,23 +3400,29 @@ module SR = struct ] @ allowed_and_current_operations operations @ [ - field ~ty:(Set (Ref _vdi)) ~qualifier:DynamicRO "VDIs" + field ~ty:(Set (Ref _vdi)) ~qualifier:DynamicRO + ~in_product_since:rel_rio "VDIs" "all virtual disks known to this storage repository" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pbd)) "PBDs" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pbd)) + ~in_product_since:rel_rio "PBDs" "describes how particular hosts can see this storage repository" - ; field ~ty:Int ~qualifier:DynamicRO "virtual_allocation" + ; field ~ty:Int ~qualifier:DynamicRO ~in_product_since:rel_rio + "virtual_allocation" "sum of virtual_sizes of all VDIs in this storage repository (in \ bytes)" - ; field ~ty:Int ~qualifier:DynamicRO "physical_utilisation" + ; field ~ty:Int ~qualifier:DynamicRO ~in_product_since:rel_rio + "physical_utilisation" "physical space currently utilised on this storage repository \ (in bytes). Note that for sparse disk formats, \ physical_utilisation may be less than virtual_allocation" - ; field ~ty:Int ~qualifier:StaticRO "physical_size" - "total physical size of the repository (in bytes)" - ; field ~qualifier:StaticRO "type" "type of the storage repository" - ; field ~qualifier:StaticRO "content_type" + ; field ~ty:Int ~qualifier:StaticRO ~in_product_since:rel_rio + "physical_size" "total physical size of the repository (in bytes)" + ; field ~qualifier:StaticRO ~in_product_since:rel_rio "type" + "type of the storage repository" + ; field ~qualifier:StaticRO ~in_product_since:rel_rio "content_type" "the type of the SR's content, if required (e.g. ISOs)" ; field ~qualifier:DynamicRO "shared" ~ty:Bool + ~in_product_since:rel_rio "true if this SR is (capable of being) shared between multiple \ hosts" ; field @@ -3395,11 +3430,13 @@ module SR = struct "other_config" "additional configuration" ~map_keys_roles: [("folder", _R_VM_OP); ("XenCenter.CustomFields.*", _R_VM_OP)] + ~in_product_since:rel_rio ; field ~writer_roles:_R_VM_OP ~in_product_since:rel_orlando ~default_value:(Some (VSet [])) ~ty:(Set String) "tags" "user-specified tags for categorization purposes" ; field ~ty:Bool ~qualifier:DynamicRO ~in_oss_since:None - ~internal_only:true "default_vdi_visibility" "" + ~in_product_since:rel_rio ~internal_only:true + "default_vdi_visibility" "" ; field ~in_oss_since:None ~ty:(Map (String, String)) ~in_product_since:rel_miami ~qualifier:RW "sm_config" @@ -3446,16 +3483,20 @@ module SM = struct [ uid _sm ; namespace ~name:"name" ~contents:(names None DynamicRO) () - ; field ~in_oss_since:None ~qualifier:DynamicRO "type" "SR.type" - ; field ~in_oss_since:None ~qualifier:DynamicRO "vendor" - "Vendor who created this plugin" - ; field ~in_oss_since:None ~qualifier:DynamicRO "copyright" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO "type" "SR.type" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO "vendor" "Vendor who created this plugin" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO "copyright" "Entity which owns the copyright of this plugin" - ; field ~in_oss_since:None ~qualifier:DynamicRO "version" - "Version of the plugin" - ; field ~in_oss_since:None ~qualifier:DynamicRO "required_api_version" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO "version" "Version of the plugin" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO "required_api_version" "Minimum SM API version required on the server" - ; field ~in_oss_since:None ~qualifier:DynamicRO + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:(Map (String, String)) "configuration" "names and descriptions of device config keys" ; field ~in_oss_since:None ~qualifier:DynamicRO @@ -4410,37 +4451,46 @@ module VDI = struct ] @ allowed_and_current_operations operations @ [ - field ~qualifier:StaticRO ~ty:(Ref _sr) "SR" - "storage repository in which the VDI resides" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vbd)) "VBDs" + field ~qualifier:StaticRO ~ty:(Ref _sr) ~in_product_since:rel_rio + "SR" "storage repository in which the VDI resides" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vbd)) + ~in_product_since:rel_rio "VBDs" "list of vbds that refer to this disk" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _crashdump)) "crash_dumps" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _crashdump)) + ~in_product_since:rel_rio "crash_dumps" "list of crash dumps that refer to this disk" - ; field ~qualifier:StaticRO ~ty:Int "virtual_size" + ; field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio + "virtual_size" "size of disk as presented to the guest (in bytes). Note that, \ depending on storage backend type, requested size may not be \ respected exactly" - ; field ~qualifier:DynamicRO ~ty:Int "physical_utilisation" + ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio + "physical_utilisation" "amount of physical space that the disk image is currently \ taking up on the storage repository (in bytes)" - ; field ~qualifier:StaticRO ~ty:type' "type" "type of the VDI" - ; field ~qualifier:StaticRO ~ty:Bool "sharable" - "true if this disk may be shared" - ; field ~qualifier:StaticRO ~ty:Bool "read_only" - "true if this disk may ONLY be mounted read-only" + ; field ~qualifier:StaticRO ~ty:type' ~in_product_since:rel_rio "type" + "type of the VDI" + ; field ~qualifier:StaticRO ~ty:Bool ~in_product_since:rel_rio + "sharable" "true if this disk may be shared" + ; field ~qualifier:StaticRO ~ty:Bool ~in_product_since:rel_rio + "read_only" "true if this disk may ONLY be mounted read-only" ; field ~ty:(Map (String, String)) - "other_config" "additional configuration" + ~in_product_since:rel_rio "other_config" + "additional configuration" ~map_keys_roles: [("folder", _R_VM_OP); ("XenCenter.CustomFields.*", _R_VM_OP)] ; field ~qualifier:DynamicRO ~ty:Bool "storage_lock" + ~in_product_since:rel_rio "true if this disk is locked at the storage level" ; (* XXX: location field was in the database in rio, now API in miami *) field ~in_oss_since:None ~in_product_since:rel_miami ~ty:String ~qualifier:DynamicRO ~default_value:(Some (VString "")) "location" "location information" - ; field ~in_oss_since:None ~ty:Bool ~qualifier:DynamicRO "managed" "" - ; field ~in_oss_since:None ~ty:Bool ~qualifier:DynamicRO "missing" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~ty:Bool + ~qualifier:DynamicRO "managed" "" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~ty:Bool + ~qualifier:DynamicRO "missing" "true if SR scan operation reported this VDI as not present on \ disk" ; field ~in_oss_since:None ~ty:(Ref _vdi) ~qualifier:DynamicRO @@ -4684,8 +4734,10 @@ module VBD = struct ([uid _vbd] @ allowed_and_current_operations operations @ [ - field ~qualifier:StaticRO ~ty:(Ref _vm) "VM" "the virtual machine" - ; field ~qualifier:StaticRO ~ty:(Ref _vdi) "VDI" "the virtual disk" + field ~qualifier:StaticRO ~ty:(Ref _vm) ~in_product_since:rel_rio + "VM" "the virtual machine" + ; field ~qualifier:StaticRO ~ty:(Ref _vdi) ~in_product_since:rel_rio + "VDI" "the virtual disk" ; field ~qualifier:StaticRO ~ty:String ~default_value:(Some (VString "")) ~lifecycle: @@ -4698,25 +4750,29 @@ module VBD = struct ) ] "device" "device seen by the guest e.g. hda1" - ; field "userdevice" "user-friendly device name e.g. 0,1,2,etc." - ; field ~ty:Bool "bootable" "true if this VBD is bootable" - ; field ~qualifier:StaticRO ~ty:mode "mode" + ; field ~in_product_since:rel_rio "userdevice" + "user-friendly device name e.g. 0,1,2,etc." + ; field ~ty:Bool ~in_product_since:rel_rio "bootable" + "true if this VBD is bootable" + ; field ~qualifier:StaticRO ~ty:mode ~in_product_since:rel_rio "mode" "the mode the VBD should be mounted with" - ; field ~ty:type' "type" + ; field ~ty:type' ~in_product_since:rel_rio "type" "how the VBD will appear to the guest (e.g. disk or CD)" ; field ~in_oss_since:None ~in_product_since:rel_miami ~ty:Bool ~default_value:(Some (VBool true)) "unpluggable" "true if this VBD will support hot-unplug" - ; field ~qualifier:DynamicRO ~ty:Bool "storage_lock" - "true if a storage level lock was acquired" - ; field ~qualifier:StaticRO ~ty:Bool "empty" + ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + "storage_lock" "true if a storage level lock was acquired" + ; field ~qualifier:StaticRO ~ty:Bool ~in_product_since:rel_rio "empty" "if true this represents an empty drive" - ; field ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:Bool ~default_value:(Some (VBool false)) "reserved" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~internal_only:true ~qualifier:DynamicRO ~ty:Bool + ~default_value:(Some (VBool false)) "reserved" "true if the VBD is reserved pending a reboot/migrate" ; field ~ty:(Map (String, String)) - "other_config" "additional configuration" + ~in_product_since:rel_rio "other_config" + "additional configuration" ] @ device_status_fields @ [namespace ~name:"qos" ~contents:(qos "VBD") ()] @@ -4765,7 +4821,7 @@ module VBD_metrics = struct ; (Removed, rel_tampa, "Disabled in favour of RRD") ] "last_updated" "Time at which this information was last updated" - ; field ~in_product_since:rel_orlando + ; field ~lifecycle: [ (Published, rel_orlando, "") @@ -4796,8 +4852,10 @@ module Crashdump = struct ~contents: [ uid _crashdump - ; field ~qualifier:StaticRO ~ty:(Ref _vm) "VM" "the virtual machine" - ; field ~qualifier:StaticRO ~ty:(Ref _vdi) "VDI" "the virtual disk" + ; field ~qualifier:StaticRO ~ty:(Ref _vm) ~in_product_since:rel_rio "VM" + "the virtual machine" + ; field ~qualifier:StaticRO ~ty:(Ref _vdi) ~in_product_since:rel_rio + "VDI" "the virtual disk" ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -5061,16 +5119,17 @@ module Console = struct ~contents: [ uid _console - ; field ~qualifier:DynamicRO ~ty:protocol "protocol" - "the protocol used by this console" - ; field ~qualifier:DynamicRO ~ty:String "location" - "URI for the console service" - ; field ~qualifier:DynamicRO ~ty:(Ref _vm) "VM" - "VM to which this console is attached" + ; field ~qualifier:DynamicRO ~ty:protocol ~in_product_since:rel_rio + "protocol" "the protocol used by this console" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "location" "URI for the console service" + ; field ~qualifier:DynamicRO ~ty:(Ref _vm) ~in_product_since:rel_rio + "VM" "VM to which this console is attached" ; field ~ty:(Map (String, String)) - "other_config" "additional configuration" - ; field ~in_oss_since:None ~internal_only:true ~ty:Int "port" + ~in_product_since:rel_rio "other_config" "additional configuration" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~internal_only:true + ~ty:Int "port" "port in dom0 on which the console server is listening" ] () @@ -5079,14 +5138,14 @@ end module VM_metrics = struct let vm_memory_metrics = [ - field ~qualifier:DynamicRO ~ty:Int "actual" + field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "actual" "Guest's actual memory (bytes)" ~persist:false ] let vm_vcpu_metrics = [ - field ~qualifier:DynamicRO ~ty:Int "number" "Current number of VCPUs" - ~persist:true + field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "number" + "Current number of VCPUs" ~persist:true ; field ~qualifier:DynamicRO ~ty:(Map (Int, Float)) ~persist:false "utilisation" @@ -5100,13 +5159,15 @@ module VM_metrics = struct ] ; field ~qualifier:DynamicRO ~ty:(Map (Int, Int)) - "CPU" "VCPU to PCPU map" ~persist:false + ~in_product_since:rel_rio "CPU" "VCPU to PCPU map" ~persist:false ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - "params" "The live equivalent to VM.VCPUs_params" ~persist:false + ~in_product_since:rel_rio "params" + "The live equivalent to VM.VCPUs_params" ~persist:false ; field ~qualifier:DynamicRO ~ty:(Map (Int, Set String)) - "flags" "CPU flags (blocked,online,running)" ~persist:false + ~in_product_since:rel_rio "flags" "CPU flags (blocked,online,running)" + ~persist:false ] let t = @@ -5120,14 +5181,17 @@ module VM_metrics = struct uid _vm_metrics ; namespace ~name:"memory" ~contents:vm_memory_metrics () ; namespace ~name:"VCPUs" ~contents:vm_vcpu_metrics () - ; field ~qualifier:DynamicRO ~ty:(Set String) "state" - "The state of the guest, eg blocked, dying etc" ~persist:false - ; field ~qualifier:DynamicRO ~ty:DateTime "start_time" - "Time at which this VM was last booted" + ; field ~qualifier:DynamicRO ~ty:(Set String) ~in_product_since:rel_rio + "state" "The state of the guest, eg blocked, dying etc" + ~persist:false + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "start_time" "Time at which this VM was last booted" ; field ~in_oss_since:None ~qualifier:DynamicRO ~ty:DateTime - "install_time" "Time at which the VM was installed" - ; field ~qualifier:DynamicRO ~ty:DateTime "last_updated" - "Time at which this information was last updated" ~persist:false + ~in_product_since:rel_rio "install_time" + "Time at which the VM was installed" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "last_updated" "Time at which this information was last updated" + ~persist:false ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ~persist:false @@ -5182,14 +5246,15 @@ module VM_guest_metrics = struct uid _vm_guest_metrics ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - "os_version" "version of the OS" + ~in_product_since:rel_rio "os_version" "version of the OS" ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) ~lifecycle:[] "netbios_name" "The NETBIOS name of the machine" ~default_value:(Some (VMap [])) ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - "PV_drivers_version" "version of the PV drivers" + ~in_product_since:rel_rio "PV_drivers_version" + "version of the PV drivers" ; field ~qualifier:DynamicRO ~ty:Bool ~in_oss_since:None ~lifecycle: [ @@ -5232,12 +5297,12 @@ module VM_guest_metrics = struct "disks" "This field exists but has no data." ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - "networks" "network configuration" + ~in_product_since:rel_rio "networks" "network configuration" ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - "other" "anything else" - ; field ~qualifier:DynamicRO ~ty:DateTime "last_updated" - "Time at which this information was last updated" + ~in_product_since:rel_rio "other" "anything else" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "last_updated" "Time at which this information was last updated" ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -5855,26 +5920,28 @@ module VMSS = struct [ uid _vmss ; namespace ~name:"name" ~contents:(names None RW) () - ; field ~qualifier:RW ~ty:Bool "enabled" + ; field ~qualifier:RW ~ty:Bool ~in_product_since:rel_rio "enabled" "enable or disable this snapshot schedule" ~default_value:(Some (VBool true)) - ; field ~qualifier:StaticRO ~ty:type' "type" + ; field ~qualifier:StaticRO ~ty:type' ~in_product_since:rel_rio "type" "type of the snapshot schedule" - ; field ~qualifier:StaticRO ~ty:Int "retained_snapshots" + ; field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio + "retained_snapshots" "maximum number of snapshots that should be stored at any time" ~default_value:(Some (VInt 7L)) - ; field ~qualifier:StaticRO ~ty:frequency "frequency" - "frequency of taking snapshot from snapshot schedule" + ; field ~qualifier:StaticRO ~ty:frequency ~in_product_since:rel_rio + "frequency" "frequency of taking snapshot from snapshot schedule" ; field ~qualifier:StaticRO ~ty:(Map (String, String)) - "schedule" + ~in_product_since:rel_rio "schedule" "schedule of the snapshot containing 'hour', 'min', 'days'. \ Date/time-related information is in Local Timezone" ~default_value:(Some (VMap [])) - ; field ~qualifier:DynamicRO ~ty:DateTime "last_run_time" - "time of the last snapshot" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "last_run_time" "time of the last snapshot" ~default_value:(Some (VDateTime Date.epoch)) - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) "VMs" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) + ~in_product_since:rel_rio "VMs" "all VMs attached to this snapshot schedule" ] () @@ -6003,8 +6070,8 @@ module VM_appliance = struct ] @ allowed_and_current_operations operations @ [ - field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) "VMs" - "all VMs in this appliance" + field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) + ~in_product_since:rel_rio "VMs" "all VMs in this appliance" ] ) () @@ -6045,7 +6112,8 @@ module DR_task = struct ~contents: [ uid _dr_task - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _sr)) "introduced_SRs" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _sr)) + ~in_product_since:rel_rio "introduced_SRs" "All SRs introduced by this appliance" ] () @@ -6187,20 +6255,24 @@ module Event = struct } ; contents= [ - field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:Int "id" + field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:Int + ~in_product_since:rel_rio "id" "An ID, monotonically increasing, and local to the current session" ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:DateTime - ~internal_deprecated_since:rel_boston "timestamp" - "The time at which the event occurred" - ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:String "class" + ~in_product_since:rel_rio ~internal_deprecated_since:rel_boston + "timestamp" "The time at which the event occurred" + ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:String + ~in_product_since:rel_rio "class" "The name of the class of the object that changed" ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:operation - "operation" "The operation that was performed" - ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:String "ref" + ~in_product_since:rel_rio "operation" + "The operation that was performed" + ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:String + ~in_product_since:rel_rio "ref" "A reference to the object that changed" ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:String - ~internal_deprecated_since:rel_boston "obj_uuid" - "The uuid of the object that changed" + ~in_product_since:rel_rio ~internal_deprecated_since:rel_boston + "obj_uuid" "The uuid of the object that changed" ] ; (* As of tampa, the event record has one more field, snapshot, which is the record of the object changed. Due to the difficulty of representing this in the datamodel, the doc is generated manually, @@ -6257,14 +6329,15 @@ module Blob = struct [ uid _blob ; namespace ~name:"name" ~contents:(names oss_since_303 RW) () - ; field ~qualifier:DynamicRO ~ty:Int "size" + ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "size" "Size of the binary data, in bytes" ; field ~writer_roles:_R_POOL_OP ~qualifier:RW ~in_product_since:rel_tampa ~default_value:(Some (VBool false)) ~ty:Bool "public" "True if the blob is publicly accessible" - ; field ~qualifier:StaticRO ~ty:DateTime "last_updated" - "Time at which the data in the blob was last updated" - ; field ~qualifier:StaticRO ~ty:String "mime_type" + ; field ~qualifier:StaticRO ~ty:DateTime ~in_product_since:rel_rio + "last_updated" "Time at which the data in the blob was last updated" + ; field ~qualifier:StaticRO ~ty:String ~in_product_since:rel_rio + "mime_type" "The mime type associated with this object. Defaults to \ 'application/octet-stream' if the empty string is supplied" ] @@ -6399,9 +6472,10 @@ module Message = struct ~contents: [ uid _message - ; field ~qualifier:DynamicRO ~ty:String "name" "The name of the message" - ; field ~qualifier:DynamicRO ~ty:Int "priority" - "The message priority, 0 being low priority" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio "name" + "The name of the message" + ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio + "priority" "The message priority, 0 being low priority" ; field ~qualifier:DynamicRO ~ty:cls ~lifecycle: [ @@ -6409,11 +6483,12 @@ module Message = struct ; (Extended, "1.313.0", "Added Certificate class") ] "cls" "The class of the object this message is associated with" - ; field ~qualifier:DynamicRO ~ty:String "obj_uuid" - "The uuid of the object this message is associated with" - ; field ~qualifier:DynamicRO ~ty:DateTime "timestamp" - "The time at which the message was created" - ; field ~qualifier:DynamicRO ~ty:String "body" "The body of the message" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "obj_uuid" "The uuid of the object this message is associated with" + ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + "timestamp" "The time at which the message was created" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio "body" + "The body of the message" ] () end @@ -6458,11 +6533,12 @@ module Secret = struct ~contents: [ uid ~reader_roles:_R_POOL_OP _secret - ; field ~reader_roles:_R_POOL_OP ~qualifier:RW ~ty:String "value" - "the secret" + ; field ~reader_roles:_R_POOL_OP ~qualifier:RW ~ty:String + ~in_product_since:rel_rio "value" "the secret" ; field ~qualifier:RW ~ty:(Map (String, String)) - "other_config" "other_config" ~default_value:(Some (VMap [])) + ~in_product_since:rel_rio "other_config" "other_config" + ~default_value:(Some (VMap [])) ] () end @@ -7816,8 +7892,8 @@ module VUSB = struct ~ty:(Map (String, String)) ~lifecycle "other_config" "Additional configuration" ~default_value:(Some (VMap [])) - ; field ~qualifier:DynamicRO ~ty:Bool "currently_attached" - "is the device currently attached" + ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + "currently_attached" "is the device currently attached" ~default_value:(Some (VBool false)) ] ) diff --git a/ocaml/idl/datamodel_common.ml b/ocaml/idl/datamodel_common.ml index 45b9d3068e6..8b34e41c8ec 100644 --- a/ocaml/idl/datamodel_common.ml +++ b/ocaml/idl/datamodel_common.ml @@ -678,11 +678,19 @@ let field ?(in_oss_since = Some "3.0.3") ?in_product_since lifecycle ?(doc_tags = []) name desc = (* in_product_since currently defaults to 'Some rel_rio', for backwards compatibility. * This should eventually become 'None'. *) - let in_product_since = - match in_product_since with None -> Some rel_rio | x -> x + let _ = + match (lifecycle, in_product_since) with + | None, None -> + failwith ("Lifecycle for field '" ^ name ^ "' not specified") + | Some _, Some _ -> + failwith + ("lifecycle is given, in_product_since should not be specified \ + explicitly in " + ^ name + ) + | _, _ -> + () in - if lifecycle = None && in_product_since = None then - failwith ("Lifecycle for field '" ^ name ^ "' not specified") ; let lifecycle = match lifecycle with | None -> @@ -739,7 +747,9 @@ let field ?(in_oss_since = Some "3.0.3") ?in_product_since let uid ?(in_oss_since = Some "3.0.3") ?(reader_roles = None) ?lifecycle _refname = - field ~in_oss_since ?lifecycle ~qualifier:DynamicRO ~ty:String + let in_product_since = if lifecycle = None then Some rel_rio else None in + field ~in_oss_since ?in_product_since ?lifecycle ~qualifier:DynamicRO + ~ty:String ~writer_roles:_R_POOL_ADMIN (* only the system should be able to create/modify uuids *) ~reader_roles "uuid" "Unique identifier/object reference" @@ -748,13 +758,13 @@ let allowed_and_current_operations ?(writer_roles = None) ?(reader_roles = None) operations_type = [ field ~writer_roles ~reader_roles ~persist:false ~in_oss_since:None - ~qualifier:DynamicRO ~ty:(Set operations_type) + ~in_product_since:rel_rio ~qualifier:DynamicRO ~ty:(Set operations_type) ~default_value:(Some (VSet [])) "allowed_operations" "list of the operations allowed in this state. This list is advisory \ only and the server state may have changed by the time this field is \ read by a client." ; field ~writer_roles ~reader_roles ~persist:false ~in_oss_since:None - ~qualifier:DynamicRO + ~in_product_since:rel_rio ~qualifier:DynamicRO ~ty:(Map (String, operations_type)) ~default_value:(Some (VMap [])) "current_operations" "links each of the running tasks using this object (by reference) to a \ @@ -782,9 +792,10 @@ let namespace ?(get_field_writer_roles = fun x -> x) (** Many of the objects have a set of names of various lengths: *) let names ?(writer_roles = None) ?(reader_roles = None) ?lifecycle in_oss_since qual = + let in_product_since = if lifecycle = None then Some rel_rio else None in let field x y = - field x y ~in_oss_since ~qualifier:qual ~writer_roles ~reader_roles - ~default_value:(Some (VString "")) ?lifecycle + field x y ~in_oss_since ?in_product_since ~qualifier:qual ~writer_roles + ~reader_roles ~default_value:(Some (VString "")) ?lifecycle in [ field "label" "a human-readable name" diff --git a/ocaml/idl/datamodel_host.ml b/ocaml/idl/datamodel_host.ml index d48470f3a71..5bb9887a046 100644 --- a/ocaml/idl/datamodel_host.ml +++ b/ocaml/idl/datamodel_host.ml @@ -7,7 +7,7 @@ open Datamodel_types let host_memory = let field = field ~ty:Int in [ - field ~qualifier:DynamicRO "overhead" + field ~qualifier:DynamicRO "overhead" ~in_product_since:rel_rio "Virtualization memory overhead (bytes)." ~default_value:(Some (VInt 0L)) ~doc_tags:[Memory] ] @@ -15,12 +15,14 @@ let host_memory = let api_version = let field' = field ~qualifier:DynamicRO in [ - field' ~ty:Int "major" "major version number" - ; field' ~ty:Int "minor" "minor version number" - ; field' ~ty:String "vendor" "identification of vendor" + field' ~ty:Int ~in_product_since:rel_rio "major" "major version number" + ; field' ~ty:Int ~in_product_since:rel_rio "minor" "minor version number" + ; field' ~ty:String ~in_product_since:rel_rio "vendor" + "identification of vendor" ; field' ~ty:(Map (String, String)) - "vendor_implementation" "details of vendor implementation" + ~in_product_since:rel_rio "vendor_implementation" + "details of vendor implementation" ] let migrate_receive = @@ -1985,68 +1987,76 @@ let t = @ [ namespace ~name:"API_version" ~contents:api_version () ; field ~qualifier:DynamicRO ~ty:Bool "enabled" - "True if the host is currently enabled" + ~in_product_since:rel_rio "True if the host is currently enabled" ; field ~qualifier:StaticRO ~ty:(Map (String, String)) - "software_version" "version strings" + ~in_product_since:rel_rio "software_version" "version strings" ; field ~ty:(Map (String, String)) - "other_config" "additional configuration" + ~in_product_since:rel_rio "other_config" "additional configuration" ~map_keys_roles: [("folder", _R_VM_OP); ("XenCenter.CustomFields.*", _R_VM_OP)] - ; field ~qualifier:StaticRO ~ty:(Set String) "capabilities" - "Xen capabilities" + ; field ~qualifier:StaticRO ~ty:(Set String) ~in_product_since:rel_rio + "capabilities" "Xen capabilities" ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - "cpu_configuration" + ~in_product_since:rel_rio "cpu_configuration" "The CPU configuration on this host. May contain keys such as \ \"nr_nodes\", \"sockets_per_node\", \"cores_per_socket\", or \ \"threads_per_core\"" - ; field ~qualifier:DynamicRO ~ty:String "sched_policy" - "Scheduler policy currently in force on this host" - ; field ~qualifier:DynamicRO ~ty:(Set String) "supported_bootloaders" + ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + "sched_policy" "Scheduler policy currently in force on this host" + ; field ~qualifier:DynamicRO ~ty:(Set String) ~in_product_since:rel_rio + "supported_bootloaders" "a list of the bootloaders installed on the machine" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) "resident_VMs" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) + ~in_product_since:rel_rio "resident_VMs" "list of VMs currently resident on host" ; field ~qualifier:RW ~ty:(Map (String, String)) - "logging" "logging configuration" + ~in_product_since:rel_rio "logging" "logging configuration" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pif)) ~doc_tags:[Networking] - "PIFs" "physical network interfaces" - ; field ~qualifier:RW ~ty:(Ref _sr) "suspend_image_sr" + ~in_product_since:rel_rio "PIFs" "physical network interfaces" + ; field ~qualifier:RW ~ty:(Ref _sr) ~in_product_since:rel_rio + "suspend_image_sr" "The SR in which VDIs for suspend images are created" - ; field ~qualifier:RW ~ty:(Ref _sr) "crash_dump_sr" - "The SR in which VDIs for crash dumps are created" - ; field ~in_oss_since:None ~qualifier:DynamicRO - ~ty:(Set (Ref _host_crashdump)) "crashdumps" + ; field ~qualifier:RW ~ty:(Ref _sr) ~in_product_since:rel_rio + "crash_dump_sr" "The SR in which VDIs for crash dumps are created" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:(Set (Ref _host_crashdump)) "crashdumps" "Set of host crash dumps" - ; field ~in_oss_since:None ~internal_deprecated_since:rel_ely - ~qualifier:DynamicRO ~ty:(Set (Ref _host_patch)) "patches" - "Set of host patches" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~internal_deprecated_since:rel_ely ~qualifier:DynamicRO + ~ty:(Set (Ref _host_patch)) "patches" "Set of host patches" ; field ~in_oss_since:None ~in_product_since:rel_ely ~qualifier:DynamicRO ~ty:(Set (Ref _pool_update)) "updates" "Set of updates" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pbd)) "PBDs" - "physical blockdevices" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _hostcpu)) "host_CPUs" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pbd)) + ~in_product_since:rel_rio "PBDs" "physical blockdevices" + ; field ~qualifier:DynamicRO ~ty:(Set (Ref _hostcpu)) + ~in_product_since:rel_rio "host_CPUs" "The physical CPUs on this host" ; field ~qualifier:DynamicRO ~in_product_since:rel_midnight_ride ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "cpu_info" "Details about the physical CPUs on this host" - ; field ~in_oss_since:None ~qualifier:RW ~ty:String - ~doc_tags:[Networking] "hostname" "The hostname of this host" - ; field ~in_oss_since:None ~qualifier:RW ~ty:String - ~doc_tags:[Networking] "address" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW + ~ty:String ~doc_tags:[Networking] "hostname" + "The hostname of this host" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW + ~ty:String ~doc_tags:[Networking] "address" "The address by which this host can be contacted from any other \ host in the pool" - ; field ~qualifier:DynamicRO ~ty:(Ref _host_metrics) "metrics" + ; field ~qualifier:DynamicRO ~ty:(Ref _host_metrics) + ~in_product_since:rel_rio "metrics" "metrics associated with this host" - ; field ~in_oss_since:None ~qualifier:DynamicRO + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:(Map (String, String)) "license_params" "State of the current license" - ; field ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:Int "boot_free_mem" "Free memory on host at boot time" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~internal_only:true + ~qualifier:DynamicRO ~ty:Int "boot_free_mem" + "Free memory on host at boot time" ; field ~in_oss_since:None ~qualifier:DynamicRO ~in_product_since:rel_orlando ~ty:(Set String) ~default_value:(Some (VSet [])) "ha_statefiles" diff --git a/ocaml/idl/datamodel_pool.ml b/ocaml/idl/datamodel_pool.ml index 198c8b5a83a..f55f98d47ac 100644 --- a/ocaml/idl/datamodel_pool.ml +++ b/ocaml/idl/datamodel_pool.ml @@ -1287,20 +1287,22 @@ let t = ~contents: ([uid ~in_oss_since:None _pool] @ [ - field ~in_oss_since:None ~qualifier:RW ~ty:String "name_label" - "Short name" - ; field ~in_oss_since:None ~qualifier:RW ~ty:String "name_description" - "Description" - ; field ~in_oss_since:None ~qualifier:DynamicRO ~ty:(Ref _host) "master" + field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW + ~ty:String "name_label" "Short name" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW + ~ty:String "name_description" "Description" + ; field ~in_oss_since:None ~in_product_since:rel_rio + ~qualifier:DynamicRO ~ty:(Ref _host) "master" "The host that is pool master" - ; field ~in_oss_since:None ~qualifier:RW ~ty:(Ref _sr) "default_SR" - "Default SR for VDIs" - ; field ~in_oss_since:None ~qualifier:RW ~ty:(Ref _sr) - "suspend_image_SR" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW + ~ty:(Ref _sr) "default_SR" "Default SR for VDIs" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW + ~ty:(Ref _sr) "suspend_image_SR" "The SR in which VDIs for suspend images are created" - ; field ~in_oss_since:None ~qualifier:RW ~ty:(Ref _sr) "crash_dump_SR" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW + ~ty:(Ref _sr) "crash_dump_SR" "The SR in which VDIs for crash dumps are created" - ; field ~in_oss_since:None + ; field ~in_oss_since:None ~in_product_since:rel_rio ~ty:(Map (String, String)) "other_config" "additional configuration" ~map_keys_roles: @@ -1372,8 +1374,8 @@ let t = ~in_product_since:rel_george ~qualifier:RW ~ty:Bool ~default_value:(Some (VBool false)) "wlb_enabled" "true if workload balancing is enabled on the pool, false otherwise" - ; field ~in_product_since:rel_george ~qualifier:RW ~ty:Bool - ~default_value:(Some (VBool false)) "wlb_verify_cert" + ; field ~qualifier:RW ~ty:Bool ~default_value:(Some (VBool false)) + "wlb_verify_cert" "true if communication with the WLB server should enforce TLS \ certificate verification." ~lifecycle: @@ -1516,7 +1518,7 @@ let t = "Default behaviour during migration, True if stream compression \ should be used" ; field ~qualifier:RW ~ty:Bool ~default_value:(Some (VBool true)) - "coordinator_bias" + ~in_product_since:rel_rio "coordinator_bias" "true if bias against pool master when scheduling vms is enabled, \ false otherwise" ; field ~qualifier:StaticRO ~ty:Int ~default_value:(Some (VInt 8L)) diff --git a/ocaml/idl/datamodel_vm.ml b/ocaml/idl/datamodel_vm.ml index af7aa27b270..377d4c0f667 100644 --- a/ocaml/idl/datamodel_vm.ml +++ b/ocaml/idl/datamodel_vm.ml @@ -21,12 +21,14 @@ let vmpp_deprecated = let pv = [ - field "bootloader" "name of or path to bootloader" - ; field "kernel" "path to the kernel" - ; field "ramdisk" "path to the initrd" - ; field "args" "kernel command-line arguments" - ; field "bootloader_args" "miscellaneous arguments for the bootloader" - ; field ~in_oss_since:None "legacy_args" "to make Zurich guests boot" + field ~in_product_since:rel_rio "bootloader" "name of or path to bootloader" + ; field ~in_product_since:rel_rio "kernel" "path to the kernel" + ; field ~in_product_since:rel_rio "ramdisk" "path to the initrd" + ; field ~in_product_since:rel_rio "args" "kernel command-line arguments" + ; field ~in_product_since:rel_rio "bootloader_args" + "miscellaneous arguments for the bootloader" + ; field ~in_oss_since:None ~in_product_since:rel_rio "legacy_args" + "to make Zurich guests boot" ] (** HVM domain booting *) @@ -39,7 +41,9 @@ let hvm = ; (Deprecated, rel_kolkata, "Replaced by VM.domain_type") ] "boot_policy" "HVM boot policy" - ; field ~ty:(Map (String, String)) "boot_params" "HVM boot params" + ; field ~in_product_since:rel_rio + ~ty:(Map (String, String)) + "boot_params" "HVM boot params" ; field ~writer_roles:_R_VM_POWER_ADMIN ~in_oss_since:None ~ty:Float ~in_product_since:rel_miami ~qualifier:StaticRO "shadow_multiplier" "multiplier applied to the amount of shadow that will be made available \ @@ -50,24 +54,29 @@ let hvm = let guest_memory = let field = field ~ty:Int in [ - field "overhead" ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - "Virtualization memory overhead (bytes)." ~default_value:(Some (VInt 0L)) - ~doc_tags:[Memory] - ; field "target" ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO + field "overhead" ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN + ~qualifier:DynamicRO "Virtualization memory overhead (bytes)." + ~default_value:(Some (VInt 0L)) ~doc_tags:[Memory] + ; field "target" ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN + ~qualifier:StaticRO "Dynamically-set memory target (bytes). The value of this field \ indicates the current target for memory available to this VM." ~default_value:(Some (VInt 0L)) ~internal_deprecated_since:rel_midnight_ride ~doc_tags:[Memory] - ; field "static_max" ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO + ; field "static_max" ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN + ~qualifier:StaticRO "Statically-set (i.e. absolute) maximum (bytes). The value of this field \ at VM start time acts as a hard limit of the amount of memory a guest \ can use. New values only take effect on reboot." ~doc_tags:[Memory] - ; field "dynamic_max" ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO + ; field "dynamic_max" ~in_product_since:rel_rio + ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO "Dynamic maximum (bytes)" ~doc_tags:[Memory] - ; field "dynamic_min" ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO + ; field "dynamic_min" ~in_product_since:rel_rio + ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO "Dynamic minimum (bytes)" ~doc_tags:[Memory] - ; field "static_min" ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO + ; field "static_min" ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN + ~qualifier:StaticRO "Statically-set (i.e. absolute) mininum (bytes). The value of this field \ indicates the least amount of memory this VM can boot with without \ crashing." @@ -118,17 +127,21 @@ let on_normal_exit_behaviour = (** Virtual CPUs *) let vcpus = [ - field + field ~in_product_since:rel_rio ~ty:(Map (String, String)) "params" "configuration parameters for the selected VCPU policy" - ; field ~qualifier:StaticRO ~ty:Int "max" "Max number of VCPUs" - ; field ~qualifier:StaticRO ~ty:Int "at_startup" "Boot number of VCPUs" + ; field ~in_product_since:rel_rio ~qualifier:StaticRO ~ty:Int "max" + "Max number of VCPUs" + ; field ~in_product_since:rel_rio ~qualifier:StaticRO ~ty:Int "at_startup" + "Boot number of VCPUs" ] (** Default actions *) let actions = - let crash = field ~qualifier:StaticRO ~ty:on_crash_behaviour in - let normal = field ~ty:on_normal_exit_behaviour in + let crash = + field ~in_product_since:rel_rio ~qualifier:StaticRO ~ty:on_crash_behaviour + in + let normal = field ~in_product_since:rel_rio ~ty:on_normal_exit_behaviour in let soft = field ~qualifier:RW ~lifecycle:[] ~ty:on_softreboot_behavior ~default_value:(Some (VEnum "soft_reboot")) @@ -1970,9 +1983,9 @@ let t = ) ] ~ty:power_state "power_state" "Current power state of the machine" - ; field ~ty:Int "user_version" + ; field ~ty:Int "user_version" ~in_product_since:rel_rio "Creators of VMs and templates may store version information here." - ; field ~effect:true ~ty:Bool "is_a_template" + ; field ~effect:true ~ty:Bool "is_a_template" ~in_product_since:rel_rio "true if this is a template. Template VMs can never be started, \ they are used only for cloning other VMs" ; field ~ty:Bool ~default_value:(Some (VBool false)) @@ -1994,40 +2007,44 @@ let t = ~ty:(Ref _vdi) "suspend_VDI" "The VDI that a suspend image is stored on. (Only has meaning if \ VM is currently suspended)" - ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~ty:(Ref _host) "resident_on" + ; field ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN + ~qualifier:DynamicRO ~ty:(Ref _host) "resident_on" "the host the VM is currently resident on" ; field ~writer_roles:_R_VM_POWER_ADMIN ~in_oss_since:None - ~qualifier:DynamicRO ~default_value:(Some (VRef null_ref)) - ~ty:(Ref _host) "scheduled_to_be_resident_on" + ~in_product_since:rel_rio ~qualifier:DynamicRO + ~default_value:(Some (VRef null_ref)) ~ty:(Ref _host) + "scheduled_to_be_resident_on" "the host on which the VM is due to be started/resumed/migrated. \ This acts as a memory reservation indicator" ; field ~writer_roles:_R_VM_POWER_ADMIN ~in_oss_since:None - ~ty:(Ref _host) "affinity" + ~in_product_since:rel_rio ~ty:(Ref _host) "affinity" "A host which the VM has some affinity for (or NULL). This is used \ as a hint to the start call when it decides where to run the VM. \ Resource constraints may cause the VM to be started elsewhere." ; namespace ~name:"memory" ~contents:guest_memory () ; namespace ~name:"VCPUs" ~contents:vcpus () ; namespace ~name:"actions" ~contents:actions () - ; field ~writer_roles:_R_POOL_ADMIN ~qualifier:DynamicRO - ~ty:(Set (Ref _console)) "consoles" "virtual console devices" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vif)) ~doc_tags:[Networking] - "VIFs" "virtual network interfaces" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vbd)) "VBDs" - "virtual block devices" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vusb)) "VUSBs" - "virtual usb devices" - ; field ~writer_roles:_R_POOL_ADMIN ~qualifier:DynamicRO - ~ty:(Set (Ref _crashdump)) "crash_dumps" + ; field ~in_product_since:rel_rio ~writer_roles:_R_POOL_ADMIN + ~qualifier:DynamicRO ~ty:(Set (Ref _console)) "consoles" + "virtual console devices" + ; field ~in_product_since:rel_rio ~qualifier:DynamicRO + ~ty:(Set (Ref _vif)) ~doc_tags:[Networking] "VIFs" + "virtual network interfaces" + ; field ~in_product_since:rel_rio ~qualifier:DynamicRO + ~ty:(Set (Ref _vbd)) "VBDs" "virtual block devices" + ; field ~in_product_since:rel_rio ~qualifier:DynamicRO + ~ty:(Set (Ref _vusb)) "VUSBs" "virtual usb devices" + ; field ~in_product_since:rel_rio ~writer_roles:_R_POOL_ADMIN + ~qualifier:DynamicRO ~ty:(Set (Ref _crashdump)) "crash_dumps" "crash dumps associated with this VM" - ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vtpm)) "VTPMs" - "virtual TPMs" + ; field ~in_product_since:rel_rio ~qualifier:DynamicRO + ~ty:(Set (Ref _vtpm)) "VTPMs" "virtual TPMs" ; namespace ~name:"PV" ~contents:pv () ; namespace ~name:"HVM" ~contents:hvm () ; field ~ty:(Map (String, String)) - "platform" "platform-specific configuration" + ~in_product_since:rel_rio "platform" + "platform-specific configuration" ; field ~lifecycle: [ @@ -2035,7 +2052,7 @@ let t = ; (Deprecated, rel_boston, "Field was never used") ] "PCI_bus" "PCI bus path for pass-through devices" - ; field + ; field ~in_product_since:rel_rio ~ty:(Map (String, String)) "other_config" "additional configuration" ~map_keys_roles: @@ -2044,19 +2061,22 @@ let t = ; ("folder", _R_VM_OP) ; ("XenCenter.CustomFields.*", _R_VM_OP) ] - ; field ~qualifier:DynamicRO ~ty:Int "domid" + ; field ~qualifier:DynamicRO ~ty:Int "domid" ~in_product_since:rel_rio "domain ID (if available, -1 otherwise)" - ; field ~qualifier:DynamicRO ~in_oss_since:None ~ty:String "domarch" + ; field ~qualifier:DynamicRO ~in_oss_since:None + ~in_product_since:rel_rio ~ty:String "domarch" "Domain architecture (if available, null string otherwise)" - ; field ~in_oss_since:None ~qualifier:StaticRO + ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO ~ty:(Map (String, String)) ~default_value:(Some (VMap [])) "last_boot_CPU_flags" "describes the CPU flags on which the VM was last booted" - ; field ~qualifier:DynamicRO ~ty:Bool "is_control_domain" + ; field ~in_product_since:rel_rio ~qualifier:DynamicRO ~ty:Bool + "is_control_domain" "true if this is a control domain (domain 0 or a driver domain)" - ; field ~qualifier:DynamicRO ~ty:(Ref _vm_metrics) "metrics" - "metrics associated with this VM" - ; field ~qualifier:DynamicRO ~ty:(Ref _vm_guest_metrics) "guest_metrics" + ; field ~in_product_since:rel_rio ~qualifier:DynamicRO + ~ty:(Ref _vm_metrics) "metrics" "metrics associated with this VM" + ; field ~in_product_since:rel_rio ~qualifier:DynamicRO + ~ty:(Ref _vm_guest_metrics) "guest_metrics" "metrics associated with the running guest" ; (* This was an internal field in Rio, Miami beta1, Miami beta2 but is now exposed so that it will be included automatically in Miami GA exports and can be restored, important if @@ -2078,7 +2098,8 @@ let t = ~qualifier:StaticRO ~ty:String "last_booted_record" "marshalled value containing VM record at time of last boot" ~default_value:(Some (VString "")) - ; field ~in_oss_since:None ~ty:String "recommendations" + ; field ~in_oss_since:None ~in_product_since:rel_rio ~ty:String + "recommendations" "An XML specification of recommended values and ranges for \ properties of this VM" ; field ~effect:true ~in_oss_since:None @@ -2171,8 +2192,9 @@ let t = ~ty:Bool "is_vmss_snapshot" "true if this snapshot was created by the snapshot schedule" ; field ~writer_roles:_R_POOL_OP ~qualifier:StaticRO - ~ty:(Ref _vm_appliance) ~default_value:(Some (VRef null_ref)) - "appliance" "the appliance to which this VM belongs" + ~in_product_since:rel_rio ~ty:(Ref _vm_appliance) + ~default_value:(Some (VRef null_ref)) "appliance" + "the appliance to which this VM belongs" ; field ~writer_roles:_R_POOL_OP ~qualifier:StaticRO ~in_product_since:rel_boston ~default_value:(Some (VInt 0L)) ~ty:Int "start_delay" diff --git a/ocaml/idl/datamodel_vtpm.ml b/ocaml/idl/datamodel_vtpm.ml index b5278fe5d4e..3c31614a9a1 100644 --- a/ocaml/idl/datamodel_vtpm.ml +++ b/ocaml/idl/datamodel_vtpm.ml @@ -77,9 +77,10 @@ let t = ; allowed_and_current_operations operations ; [ field ~qualifier:StaticRO ~ty:(Ref _vm) "VM" + ~in_product_since:rel_rio "The virtual machine the TPM is attached to" ; field ~qualifier:DynamicRO ~ty:(Ref _vm) "backend" - ~default_value:(Some (VRef null_ref)) + ~in_product_since:rel_rio ~default_value:(Some (VRef null_ref)) "The domain where the backend is located (unused)" ; field ~qualifier:DynamicRO ~ty:persistence_backend ~default_value:(Some (VEnum "xapi")) ~lifecycle:[] From 7f1fff6a23b2ba53f34c975ac3db3fa0be95e22d Mon Sep 17 00:00:00 2001 From: Andrii Sultanov Date: Mon, 23 Sep 2024 13:15:24 +0100 Subject: [PATCH 2/8] idl: Remove in_product_since and internal_deprecated_since parameters for call These were already being replaced with lifecycle equivalents in datamodel_common, search and replace them all and remove parameters as such. Signed-off-by: Andrii Sultanov --- ocaml/idl/datamodel.ml | 1421 +++++++++++++++++++++++----- ocaml/idl/datamodel_common.ml | 32 +- ocaml/idl/datamodel_diagnostics.ml | 28 +- ocaml/idl/datamodel_host.ml | 684 +++++++++++-- ocaml/idl/datamodel_pool.ml | 441 +++++++-- ocaml/idl/datamodel_vm.ml | 731 ++++++++++++-- 6 files changed, 2821 insertions(+), 516 deletions(-) diff --git a/ocaml/idl/datamodel.ml b/ocaml/idl/datamodel.ml index d2471e720f2..b72087fb432 100644 --- a/ocaml/idl/datamodel.ml +++ b/ocaml/idl/datamodel.ml @@ -30,7 +30,15 @@ let api_version_minor = Datamodel_common.api_version_minor module Session = struct let login = - call ~flags:[] ~name:"login_with_password" ~in_product_since:rel_rio + call ~flags:[] ~name:"login_with_password" + ~lifecycle: + [ + ( Published + , rel_rio + , "Attempt to authenticate the user, returning a session reference \ + if successful" + ) + ] ~doc: "Attempt to authenticate the user, returning a session reference if \ successful" @@ -84,12 +92,29 @@ module Session = struct (Ref _host, "host", "Host id of slave") ; (SecretString, "psecret", "Pool secret") ] - ~in_oss_since:None ~in_product_since:rel_rio ~secret:true - ~hide_from_docs:true ~allowed_roles:_R_POOL_ADMIN + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Attempt to authenticate to the pool master by presenting the \ + slave's host ref and pool secret" + ) + ] + ~secret:true ~hide_from_docs:true ~allowed_roles:_R_POOL_ADMIN (*system can create a slave session !!! *) () let slave_local_login = - call ~flags:[] ~in_product_since:rel_miami ~name:"slave_local_login" + call ~flags:[] + ~lifecycle: + [ + ( Published + , rel_miami + , "Authenticate locally against a slave in emergency mode. Note the \ + resulting sessions are only good for use on this host." + ) + ] + ~name:"slave_local_login" ~doc: "Authenticate locally against a slave in emergency mode. Note the \ resulting sessions are only good for use on this host." @@ -99,7 +124,15 @@ module Session = struct ~allowed_roles:_R_POOL_ADMIN (*system can create a slave session*) () let slave_local_login_with_password = - call ~flags:[] ~in_product_since:rel_miami + call ~flags:[] + ~lifecycle: + [ + ( Published + , rel_miami + , "Authenticate locally against a slave in emergency mode. Note the \ + resulting sessions are only good for use on this host." + ) + ] ~name:"slave_local_login_with_password" ~doc: "Authenticate locally against a slave in emergency mode. Note the \ @@ -123,14 +156,17 @@ module Session = struct ~in_oss_since:None ~allowed_roles:_R_LOCAL_ROOT_ONLY () let local_logout = - call ~flags:[`Session] ~in_product_since:rel_miami ~name:"local_logout" - ~doc:"Log out of local session." ~params:[] ~in_oss_since:None - ~allowed_roles:_R_POOL_ADMIN (*system can destroy a local session*) () + call ~flags:[`Session] + ~lifecycle:[(Published, rel_miami, "Log out of local session.")] + ~name:"local_logout" ~doc:"Log out of local session." ~params:[] + ~in_oss_since:None ~allowed_roles:_R_POOL_ADMIN + (*system can destroy a local session*) () let logout = - call ~flags:[`Session] ~in_product_since:rel_rio ~name:"logout" - ~doc:"Log out of a session" ~params:[] ~allowed_roles:_R_ALL - (*any role can destroy a known user session*) () + call ~flags:[`Session] + ~lifecycle:[(Published, rel_rio, "Log out of a session")] + ~name:"logout" ~doc:"Log out of a session" ~params:[] + ~allowed_roles:_R_ALL (*any role can destroy a known user session*) () let change_password = call ~flags:[`Session] ~name:"change_password" @@ -143,8 +179,16 @@ module Session = struct (String, "old_pwd", "Old password for account") ; (String, "new_pwd", "New password for account") ] - ~in_product_since:rel_rio ~in_oss_since:None - ~allowed_roles:_R_LOCAL_ROOT_ONLY + ~lifecycle: + [ + ( Published + , rel_rio + , "Change the account password; if your session is authenticated \ + with root privileges then the old_pwd is validated and the \ + new_pwd is set regardless" + ) + ] + ~in_oss_since:None ~allowed_roles:_R_LOCAL_ROOT_ONLY (*not even pool-admin can change passwords, only root*) () let get_all_subject_identifiers = @@ -156,8 +200,16 @@ module Session = struct ( Set String , "The list of user subject-identifiers of all existing sessions" ) - ~params:[] ~in_product_since:rel_george ~in_oss_since:None - ~allowed_roles:_R_ALL () + ~params:[] + ~lifecycle: + [ + ( Published + , rel_george + , "Return a list of all the user subject-identifiers of all existing \ + sessions" + ) + ] + ~in_oss_since:None ~allowed_roles:_R_ALL () let logout_subject_identifier = call ~name:"logout_subject_identifier" @@ -171,8 +223,16 @@ module Session = struct , "User subject-identifier of the sessions to be destroyed" ) ] - ~in_product_since:rel_george ~in_oss_since:None ~allowed_roles:_R_POOL_OP - () + ~lifecycle: + [ + ( Published + , rel_george + , "Log out all sessions associated to a user subject-identifier, \ + except the session associated with the context calling this \ + function" + ) + ] + ~in_oss_since:None ~allowed_roles:_R_POOL_OP () let t = create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 @@ -266,7 +326,17 @@ module Task = struct ) let cancel = - call ~name:"cancel" ~in_product_since:rel_rio + call ~name:"cancel" + ~lifecycle: + [ + ( Published + , rel_rio + , "Request that a task be cancelled. Note that a task may fail to be \ + cancelled and may complete or fail normally and note that, even \ + when a task does cancel, it might take an arbitrary amount of \ + time." + ) + ] ~doc: "Request that a task be cancelled. Note that a task may fail to be \ cancelled and may complete or fail normally and note that, even when \ @@ -278,7 +348,14 @@ module Task = struct () let create = - call ~flags:[`Session] ~in_oss_since:None ~in_product_since:rel_rio + call ~flags:[`Session] ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Create a new task object which must be manually destroyed." + ) + ] ~name:"create" ~doc:"Create a new task object which must be manually destroyed." ~params: @@ -290,7 +367,8 @@ module Task = struct ~allowed_roles:_R_READ_ONLY (* any subject can create tasks *) () let destroy = - call ~flags:[`Session] ~in_oss_since:None ~in_product_since:rel_rio + call ~flags:[`Session] ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Destroy the task object")] ~name:"destroy" ~doc:"Destroy the task object" ~params:[(Ref _task, "self", "Reference to the task object")] ~allowed_roles:_R_READ_ONLY @@ -298,7 +376,8 @@ module Task = struct () let set_status = - call ~flags:[`Session] ~in_oss_since:None ~in_product_since:rel_falcon + call ~flags:[`Session] ~in_oss_since:None + ~lifecycle:[(Published, rel_falcon, "Set the task status")] ~name:"set_status" ~doc:"Set the task status" ~params: [ @@ -310,7 +389,8 @@ module Task = struct () let set_progress = - call ~flags:[`Session] ~in_oss_since:None ~in_product_since:rel_stockholm + call ~flags:[`Session] ~in_oss_since:None + ~lifecycle:[(Published, rel_stockholm, "Set the task progress")] ~name:"set_progress" ~doc:"Set the task progress" ~params: [ @@ -322,7 +402,8 @@ module Task = struct () let set_result = - call ~flags:[`Session] ~in_oss_since:None ~in_product_since:"21.3.0" + call ~flags:[`Session] ~in_oss_since:None + ~lifecycle:[(Published, "21.3.0", "")] ~name:"set_result" ~doc:"Set the task result" ~params: [ @@ -334,7 +415,8 @@ module Task = struct () let set_error_info = - call ~flags:[`Session] ~in_oss_since:None ~in_product_since:"21.3.0" + call ~flags:[`Session] ~in_oss_since:None + ~lifecycle:[(Published, "21.3.0", "")] ~name:"set_error_info" ~doc:"Set the task error info" ~params: [ @@ -346,7 +428,8 @@ module Task = struct () let set_resident_on = - call ~flags:[`Session] ~in_oss_since:None ~in_product_since:"21.3.0" + call ~flags:[`Session] ~in_oss_since:None + ~lifecycle:[(Published, "21.3.0", "")] ~name:"set_resident_on" ~doc:"Set the resident on field" ~params: [ @@ -519,14 +602,28 @@ module Host_crashdump = struct let destroy = call ~name:"destroy" ~doc:"Destroy specified host crash dump, removing it from the disk." - ~in_oss_since:None ~in_product_since:rel_rio + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Destroy specified host crash dump, removing it from the disk." + ) + ] ~params:[(Ref _host_crashdump, "self", "The host crashdump to destroy")] ~allowed_roles:_R_POOL_OP () let upload = call ~name:"upload" ~doc:"Upload the specified host crash dump to a specified URL" - ~in_oss_since:None ~in_product_since:rel_rio + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Upload the specified host crash dump to a specified URL" + ) + ] ~params: [ (Ref _host_crashdump, "self", "The host crashdump to upload") @@ -598,7 +695,7 @@ module Pool_update = struct let introduce = call ~name:"introduce" ~doc:"Introduce update VDI" ~in_oss_since:None - ~in_product_since:rel_ely + ~lifecycle:[(Published, rel_ely, "Introduce update VDI")] ~params:[(Ref _vdi, "vdi", "The VDI which contains a software update.")] ~result:(Ref _pool_update, "the introduced pool update") ~allowed_roles:_R_POOL_OP () @@ -606,7 +703,14 @@ module Pool_update = struct let precheck = call ~name:"precheck" ~doc:"Execute the precheck stage of the selected update on a host" - ~in_oss_since:None ~in_product_since:rel_ely + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_ely + , "Execute the precheck stage of the selected update on a host" + ) + ] ~params: [ (Ref _pool_update, "self", "The update whose prechecks will be run") @@ -618,7 +722,8 @@ module Pool_update = struct let apply = call ~name:"apply" ~doc:"Apply the selected update to a host" - ~in_oss_since:None ~in_product_since:rel_ely + ~in_oss_since:None + ~lifecycle:[(Published, rel_ely, "Apply the selected update to a host")] ~params: [ (Ref _pool_update, "self", "The update to apply") @@ -630,7 +735,14 @@ module Pool_update = struct let pool_apply = call ~name:"pool_apply" ~doc:"Apply the selected update to all hosts in the pool" - ~in_oss_since:None ~in_product_since:rel_ely + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_ely + , "Apply the selected update to all hosts in the pool" + ) + ] ~params:[(Ref _pool_update, "self", "The update to apply")] ~allowed_roles:_R_POOL_OP () @@ -639,20 +751,36 @@ module Pool_update = struct ~doc: "Removes the update's files from all hosts in the pool, but does not \ revert the update" - ~in_oss_since:None ~in_product_since:rel_ely + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_ely + , "Removes the update's files from all hosts in the pool, but does \ + not revert the update" + ) + ] ~params:[(Ref _pool_update, "self", "The update to clean up")] ~allowed_roles:_R_POOL_OP () let destroy = call ~name:"destroy" ~doc:"Removes the database entry. Only works on unapplied update." - ~in_oss_since:None ~in_product_since:rel_ely + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_ely + , "Removes the database entry. Only works on unapplied update." + ) + ] ~params:[(Ref _pool_update, "self", "The update to destroy")] ~allowed_roles:_R_POOL_OP () let attach = call ~name:"attach" ~hide_from_docs:true ~doc:"Attach the pool update VDI" - ~in_oss_since:None ~in_product_since:rel_ely + ~in_oss_since:None + ~lifecycle:[(Published, rel_ely, "Attach the pool update VDI")] ~versioned_params: [ { @@ -675,14 +803,16 @@ module Pool_update = struct let detach = call ~name:"detach" ~hide_from_docs:true ~doc:"Detach the pool update VDI" - ~in_oss_since:None ~in_product_since:rel_ely + ~in_oss_since:None + ~lifecycle:[(Published, rel_ely, "Detach the pool update VDI")] ~params:[(Ref _pool_update, "self", "The update to be detached")] ~allowed_roles:_R_POOL_OP () let resync_host = call ~name:"resync_host" ~hide_from_docs:true ~doc:"Resync the applied updates of the host" ~in_oss_since:None - ~in_product_since:rel_ely + ~lifecycle: + [(Published, rel_ely, "Resync the applied updates of the host")] ~params:[(Ref _host, "host", "The host to resync the applied updates")] ~allowed_roles:_R_POOL_OP () @@ -764,72 +894,129 @@ module Pool_patch = struct let apply = call ~name:"apply" ~doc:"Apply the selected patch to a host and return its output" - ~in_oss_since:None ~in_product_since:rel_miami + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_miami + , "Apply the selected patch to a host and return its output" + ) + ; (Deprecated, rel_ely, "") + ] ~params: [ (Ref _pool_patch, "self", "The patch to apply") ; (Ref _host, "host", "The host to apply the patch too") ] ~result:(String, "the output of the patch application process") - ~allowed_roles:_R_POOL_OP ~internal_deprecated_since:rel_ely () + ~allowed_roles:_R_POOL_OP () let precheck = call ~name:"precheck" ~doc: "Execute the precheck stage of the selected patch on a host and return \ its output" - ~in_oss_since:None ~in_product_since:rel_miami + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_miami + , "Execute the precheck stage of the selected patch on a host and \ + return its output" + ) + ; (Deprecated, rel_ely, "") + ] ~params: [ (Ref _pool_patch, "self", "The patch whose prechecks will be run") ; (Ref _host, "host", "The host to run the prechecks on") ] ~result:(String, "the output of the patch prechecks") - ~allowed_roles:_R_POOL_OP ~internal_deprecated_since:rel_ely () + ~allowed_roles:_R_POOL_OP () let clean = call ~name:"clean" ~doc:"Removes the patch's files from the server" - ~in_oss_since:None ~in_product_since:rel_miami + ~in_oss_since:None + ~lifecycle: + [ + (Published, rel_miami, "Removes the patch's files from the server") + ; (Deprecated, rel_ely, "") + ] ~params:[(Ref _pool_patch, "self", "The patch to clean up")] - ~allowed_roles:_R_POOL_OP ~internal_deprecated_since:rel_ely () + ~allowed_roles:_R_POOL_OP () let clean_on_host = call ~name:"clean_on_host" ~doc:"Removes the patch's files from the specified host" - ~in_oss_since:None ~in_product_since:rel_tampa + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_tampa + , "Removes the patch's files from the specified host" + ) + ; (Deprecated, rel_ely, "") + ] ~params: [ (Ref _pool_patch, "self", "The patch to clean up") ; (Ref _host, "host", "The host on which to clean the patch") ] - ~allowed_roles:_R_POOL_OP ~internal_deprecated_since:rel_ely () + ~allowed_roles:_R_POOL_OP () let pool_clean = call ~name:"pool_clean" ~doc: "Removes the patch's files from all hosts in the pool, but does not \ remove the database entries" - ~in_oss_since:None ~in_product_since:rel_tampa + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_tampa + , "Removes the patch's files from all hosts in the pool, but does \ + not remove the database entries" + ) + ; (Deprecated, rel_ely, "") + ] ~params:[(Ref _pool_patch, "self", "The patch to clean up")] - ~allowed_roles:_R_POOL_OP ~internal_deprecated_since:rel_ely () + ~allowed_roles:_R_POOL_OP () let destroy = call ~name:"destroy" ~doc: "Removes the patch's files from all hosts in the pool, and removes the \ database entries. Only works on unapplied patches." - ~in_oss_since:None ~in_product_since:rel_miami + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_miami + , "Removes the patch's files from all hosts in the pool, and removes \ + the database entries. Only works on unapplied patches." + ) + ; (Deprecated, rel_ely, "") + ] ~params:[(Ref _pool_patch, "self", "The patch to destroy")] - ~allowed_roles:_R_POOL_OP ~internal_deprecated_since:rel_ely () + ~allowed_roles:_R_POOL_OP () let pool_apply = call ~name:"pool_apply" ~doc: "Apply the selected patch to all hosts in the pool and return a map of \ host_ref -> patch output" - ~in_oss_since:None ~in_product_since:rel_miami + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_miami + , "Apply the selected patch to all hosts in the pool and return a \ + map of host_ref -> patch output" + ) + ; (Deprecated, rel_ely, "") + ] ~params:[(Ref _pool_patch, "self", "The patch to apply")] - ~allowed_roles:_R_POOL_OP ~internal_deprecated_since:rel_ely () + ~allowed_roles:_R_POOL_OP () let t = create_obj ~in_db:true ~in_product_since:rel_miami ~in_oss_since:None @@ -882,16 +1069,30 @@ module Host_patch = struct ~doc: "Destroy the specified host patch, removing it from the disk. This \ does NOT reverse the patch" - ~in_oss_since:None ~in_product_since:rel_rio + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Destroy the specified host patch, removing it from the disk. This \ + does NOT reverse the patch" + ) + ; (Deprecated, rel_miami, "") + ] ~params:[(Ref _host_patch, "self", "The patch to destroy")] - ~internal_deprecated_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~allowed_roles:_R_POOL_OP () let apply = call ~name:"apply" ~doc:"Apply the selected patch and return its output" - ~in_oss_since:None ~in_product_since:rel_rio + ~in_oss_since:None + ~lifecycle: + [ + (Published, rel_rio, "Apply the selected patch and return its output") + ; (Deprecated, rel_miami, "") + ] ~params:[(Ref _host_patch, "self", "The patch to apply")] ~result:(String, "the output of the patch application process") - ~internal_deprecated_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~allowed_roles:_R_POOL_OP () let t = create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:None @@ -1062,8 +1263,14 @@ module Network = struct ) ; (Ref _host, "host", "physical machine to which this PIF is connected") ] - ~in_product_since:rel_miami ~hide_from_docs:true ~allowed_roles:_R_POOL_OP - () + ~lifecycle: + [ + ( Published + , rel_miami + , "Makes the network immediately available on a particular host" + ) + ] + ~hide_from_docs:true ~allowed_roles:_R_POOL_OP () let purpose = Enum @@ -1134,14 +1341,29 @@ module Network = struct (* network pool introduce is used to copy network records on pool join -- it's the network analogue of VDI/PIF.pool_introduce *) let pool_introduce = - call ~name:"pool_introduce" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"pool_introduce" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Create a new network record in the database only" + ) + ] ~versioned_params:(introduce_params miami_release) ~doc:"Create a new network record in the database only" ~result:(Ref _network, "The ref of the newly created network record.") ~hide_from_docs:true ~allowed_roles:_R_POOL_OP () let create_new_blob = - call ~name:"create_new_blob" ~in_product_since:rel_orlando + call ~name:"create_new_blob" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Create a placeholder for a named binary blob of data that is \ + associated with this pool" + ) + ] ~doc: "Create a placeholder for a named binary blob of data that is \ associated with this pool" @@ -1183,7 +1405,14 @@ module Network = struct ~allowed_roles:_R_POOL_OP () let set_default_locking_mode = - call ~name:"set_default_locking_mode" ~in_product_since:rel_tampa + call ~name:"set_default_locking_mode" + ~lifecycle: + [ + ( Published + , rel_tampa + , "Set the default locking mode for VIFs attached to this network" + ) + ] ~doc:"Set the default locking mode for VIFs attached to this network" ~params: [ @@ -1206,8 +1435,14 @@ module Network = struct ) ; (Ref _vm, "vm", "The virtual machine") ] - ~in_product_since:rel_tampa ~hide_from_docs:true - ~allowed_roles:_R_VM_POWER_ADMIN () + ~lifecycle: + [ + ( Published + , rel_tampa + , "Attaches all networks needed by a given VM on a particular host" + ) + ] + ~hide_from_docs:true ~allowed_roles:_R_VM_POWER_ADMIN () let detach_for_vm = call ~name:"detach_for_vm" @@ -1220,8 +1455,14 @@ module Network = struct ) ; (Ref _vm, "vm", "The virtual machine") ] - ~in_product_since:rel_tampa ~hide_from_docs:true - ~allowed_roles:_R_VM_POWER_ADMIN () + ~lifecycle: + [ + ( Published + , rel_tampa + , "Detaches all networks of a given VM from a particular host" + ) + ] + ~hide_from_docs:true ~allowed_roles:_R_VM_POWER_ADMIN () let add_purpose = call ~name:"add_purpose" @@ -1232,7 +1473,14 @@ module Network = struct ; (purpose, "value", "The purpose to add") ] ~errs:[Api_errors.network_incompatible_purposes] - ~in_product_since:rel_inverness ~allowed_roles:_R_POOL_ADMIN () + ~lifecycle: + [ + ( Published + , rel_inverness + , "Give a network a new purpose (if not present already)" + ) + ] + ~allowed_roles:_R_POOL_ADMIN () let remove_purpose = call ~name:"remove_purpose" @@ -1242,7 +1490,14 @@ module Network = struct (Ref _network, "self", "The network") ; (purpose, "value", "The purpose to remove") ] - ~in_product_since:rel_inverness ~allowed_roles:_R_POOL_ADMIN () + ~lifecycle: + [ + ( Published + , rel_inverness + , "Remove a purpose from a network (if present)" + ) + ] + ~allowed_roles:_R_POOL_ADMIN () (** A virtual network *) let t = @@ -1333,7 +1588,7 @@ end module PIF = struct let create_VLAN = - call ~name:"create_VLAN" ~in_product_since:rel_rio + call ~name:"create_VLAN" ~doc: "Create a VLAN interface from an existing physical interface. This \ call is deprecated: use VLAN.create instead" @@ -1360,10 +1615,10 @@ module PIF = struct ] ~result:(Ref _pif, "The reference of the created PIF object") ~errs:[Api_errors.vlan_tag_invalid] - ~internal_deprecated_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~allowed_roles:_R_POOL_OP () let destroy = - call ~name:"destroy" ~in_product_since:rel_rio + call ~name:"destroy" ~doc: "Destroy the PIF object (provided it is a VLAN interface). This call \ is deprecated: use VLAN.destroy or Bond.destroy instead" @@ -1377,19 +1632,23 @@ module PIF = struct ] ~params:[(Ref _pif, "self", "the PIF object to destroy")] ~errs:[Api_errors.pif_is_physical] - ~internal_deprecated_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~allowed_roles:_R_POOL_OP () let plug = call ~name:"plug" ~doc:"Attempt to bring up a physical interface" ~params:[(Ref _pif, "self", "the PIF object to plug")] - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP + ~lifecycle: + [(Published, rel_miami, "Attempt to bring up a physical interface")] + ~allowed_roles:_R_POOL_OP ~errs:[Api_errors.transport_pif_not_configured] () let unplug = call ~name:"unplug" ~doc:"Attempt to bring down a physical interface" ~params:[(Ref _pif, "self", "the PIF object to unplug")] - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP + ~lifecycle: + [(Published, rel_miami, "Attempt to bring down a physical interface")] + ~allowed_roles:_R_POOL_OP ~errs: [ Api_errors.ha_operation_would_break_failover_plan @@ -1402,7 +1661,9 @@ module PIF = struct let set_disallow_unplug = call ~name:"set_disallow_unplug" ~doc:"Set whether unplugging the PIF is allowed" ~hide_from_docs:false - ~in_oss_since:None ~in_product_since:rel_orlando + ~in_oss_since:None + ~lifecycle: + [(Published, rel_orlando, "Set whether unplugging the PIF is allowed")] ~params: [ (Ref _pif, "self", "Reference to the object") @@ -1437,7 +1698,14 @@ module PIF = struct ; (String, "gateway", "the new gateway") ; (String, "DNS", "the new DNS settings") ] - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP + ~lifecycle: + [ + ( Published + , rel_miami + , "Reconfigure the IP address settings for this interface" + ) + ] + ~allowed_roles:_R_POOL_OP ~errs:Api_errors.[clustering_enabled] () @@ -1503,7 +1771,15 @@ module PIF = struct "Scan for physical interfaces on a host and create PIF objects to \ represent them" ~params:[(Ref _host, "host", "The host on which to scan")] - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~lifecycle: + [ + ( Published + , rel_miami + , "Scan for physical interfaces on a host and create PIF objects to \ + represent them" + ) + ] + ~allowed_roles:_R_POOL_OP () let introduce_params = [ @@ -1542,7 +1818,14 @@ module PIF = struct let introduce = call ~name:"introduce" ~doc:"Create a PIF object matching a particular network interface" - ~versioned_params:introduce_params ~in_product_since:rel_miami + ~versioned_params:introduce_params + ~lifecycle: + [ + ( Published + , rel_miami + , "Create a PIF object matching a particular network interface" + ) + ] ~result:(Ref _pif, "The reference of the created PIF object") ~allowed_roles:_R_POOL_OP () @@ -1550,7 +1833,14 @@ module PIF = struct call ~name:"forget" ~doc:"Destroy the PIF object matching a particular network interface" ~params:[(Ref _pif, "self", "The PIF object to destroy")] - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP + ~lifecycle: + [ + ( Published + , rel_miami + , "Destroy the PIF object matching a particular network interface" + ) + ] + ~allowed_roles:_R_POOL_OP ~errs:Api_errors.[pif_tunnel_still_exists; clustering_enabled] () @@ -1721,21 +2011,31 @@ module PIF = struct (* PIF pool introduce is used to copy PIF records on pool join -- it's the PIF analogue of VDI.pool_introduce *) let pool_introduce = - call ~name:"pool_introduce" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"pool_introduce" ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Create a new PIF record in the database only")] ~versioned_params:(pool_introduce_params miami_release) ~doc:"Create a new PIF record in the database only" ~result:(Ref _pif, "The ref of the newly created PIF record.") ~hide_from_docs:true ~allowed_roles:_R_POOL_OP () let db_introduce = - call ~name:"db_introduce" ~in_oss_since:None ~in_product_since:rel_orlando + call ~name:"db_introduce" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_orlando + , "Create a new PIF record in the database only" + ) + ] ~versioned_params:(pool_introduce_params orlando_release) ~doc:"Create a new PIF record in the database only" ~result:(Ref _pif, "The ref of the newly created PIF record.") ~hide_from_docs:false ~allowed_roles:_R_POOL_OP () let db_forget = - call ~name:"db_forget" ~in_oss_since:None ~in_product_since:rel_orlando + call ~name:"db_forget" ~in_oss_since:None + ~lifecycle:[(Published, rel_orlando, "Destroy a PIF database record.")] ~params: [ ( Ref _pif @@ -2051,12 +2351,14 @@ module Bond = struct } ] ~result:(Ref _bond, "The reference of the created Bond object") - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~lifecycle:[(Published, rel_miami, "Create an interface bond")] + ~allowed_roles:_R_POOL_OP () let destroy = call ~name:"destroy" ~doc:"Destroy an interface bond" ~params:[(Ref _bond, "self", "Bond to destroy")] - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~lifecycle:[(Published, rel_miami, "Destroy an interface bond")] + ~allowed_roles:_R_POOL_OP () let set_mode = call ~name:"set_mode" ~doc:"Change the bond mode" @@ -2073,7 +2375,9 @@ module Bond = struct ; (String, "name", "The property name") ; (String, "value", "The property value") ] - ~in_product_since:rel_tampa ~allowed_roles:_R_POOL_OP () + ~lifecycle: + [(Published, rel_tampa, "Set the value of a property of the bond")] + ~allowed_roles:_R_POOL_OP () let t = create_obj ~in_db:true ~in_product_since:rel_miami ~in_oss_since:None @@ -2162,7 +2466,13 @@ module VLAN = struct (* vlan pool introduce is used to copy management vlan record on pool join -- it's the vlan analogue of VDI/PIF.pool_introduce *) let pool_introduce = call ~name:"pool_introduce" ~in_oss_since:None - ~in_product_since:rel_inverness + ~lifecycle: + [ + ( Published + , rel_inverness + , "Create a new vlan record in the database only" + ) + ] ~versioned_params:(introduce_params inverness_release) ~doc:"Create a new vlan record in the database only" ~result:(Ref _vlan, "The reference of the created VLAN object") @@ -2177,12 +2487,14 @@ module VLAN = struct ; (Ref _network, "network", "Network to receive the untagged traffic") ] ~result:(Ref _vlan, "The reference of the created VLAN object") - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~lifecycle:[(Published, rel_miami, "Create a VLAN mux/demuxer")] + ~allowed_roles:_R_POOL_OP () let destroy = call ~name:"destroy" ~doc:"Destroy a VLAN mux/demuxer" ~params:[(Ref _vlan, "self", "VLAN mux/demuxer to destroy")] - ~in_product_since:rel_miami ~allowed_roles:_R_POOL_OP () + ~lifecycle:[(Published, rel_miami, "Destroy a VLAN mux/demuxer")] + ~allowed_roles:_R_POOL_OP () let t = create_obj ~in_db:true ~in_product_since:rel_miami ~in_oss_since:None @@ -2304,7 +2616,15 @@ end module PBD = struct let plug = - call ~name:"plug" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"plug" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Activate the specified PBD, causing the referenced SR to be \ + attached and scanned" + ) + ] ~doc: "Activate the specified PBD, causing the referenced SR to be attached \ and scanned" @@ -2313,7 +2633,15 @@ module PBD = struct ~allowed_roles:_R_POOL_OP () let unplug = - call ~name:"unplug" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"unplug" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Deactivate the specified PBD, causing the referenced SR to be \ + detached and nolonger scanned" + ) + ] ~doc: "Deactivate the specified PBD, causing the referenced SR to be \ detached and nolonger scanned" @@ -2322,7 +2650,7 @@ module PBD = struct let set_device_config = call ~name:"set_device_config" ~in_oss_since:None - ~in_product_since:rel_miami + ~lifecycle:[(Published, rel_miami, "Sets the PBD's device_config field")] ~params: [ (Ref _pbd, "self", "The PBD to modify") @@ -2416,14 +2744,30 @@ module VIF = struct ) let plug = - call ~name:"plug" ~in_product_since:rel_rio + call ~name:"plug" + ~lifecycle: + [ + ( Published + , rel_rio + , "Hotplug the specified VIF, dynamically attaching it to the \ + running VM" + ) + ] ~doc: "Hotplug the specified VIF, dynamically attaching it to the running VM" ~params:[(Ref _vif, "self", "The VIF to hotplug")] ~allowed_roles:_R_VM_ADMIN () let unplug = - call ~name:"unplug" ~in_product_since:rel_rio + call ~name:"unplug" + ~lifecycle: + [ + ( Published + , rel_rio + , "Hot-unplug the specified VIF, dynamically unattaching it from the \ + running VM" + ) + ] ~doc: "Hot-unplug the specified VIF, dynamically unattaching it from the \ running VM" @@ -2431,13 +2775,22 @@ module VIF = struct ~allowed_roles:_R_VM_ADMIN () let unplug_force = - call ~name:"unplug_force" ~in_product_since:rel_boston + call ~name:"unplug_force" + ~lifecycle:[(Published, rel_boston, "Forcibly unplug the specified VIF")] ~doc:"Forcibly unplug the specified VIF" ~params:[(Ref _vif, "self", "The VIF to forcibly unplug")] ~allowed_roles:_R_VM_ADMIN () let move = - call ~name:"move" ~in_product_since:rel_ely + call ~name:"move" + ~lifecycle: + [ + ( Published + , rel_ely + , "Move the specified VIF to the specified network, even while the \ + VM is running" + ) + ] ~doc: "Move the specified VIF to the specified network, even while the VM is \ running" @@ -2475,7 +2828,8 @@ module VIF = struct ) let set_locking_mode = - call ~name:"set_locking_mode" ~in_product_since:rel_tampa + call ~name:"set_locking_mode" + ~lifecycle:[(Published, rel_tampa, "Set the locking mode for this VIF")] ~doc:"Set the locking mode for this VIF" ~params: [ @@ -2485,7 +2839,15 @@ module VIF = struct ~allowed_roles:_R_POOL_OP () let set_ipv4_allowed = - call ~name:"set_ipv4_allowed" ~in_product_since:rel_tampa + call ~name:"set_ipv4_allowed" + ~lifecycle: + [ + ( Published + , rel_tampa + , "Set the IPv4 addresses to which traffic on this VIF can be \ + restricted" + ) + ] ~doc: "Set the IPv4 addresses to which traffic on this VIF can be restricted" ~params: @@ -2502,7 +2864,9 @@ module VIF = struct ~allowed_roles:_R_POOL_OP () let add_ipv4_allowed = - call ~name:"add_ipv4_allowed" ~in_product_since:rel_tampa + call ~name:"add_ipv4_allowed" + ~lifecycle: + [(Published, rel_tampa, "Associates an IPv4 address with this VIF")] ~doc:"Associates an IPv4 address with this VIF" ~params: [ @@ -2518,7 +2882,9 @@ module VIF = struct ~allowed_roles:_R_POOL_OP () let remove_ipv4_allowed = - call ~name:"remove_ipv4_allowed" ~in_product_since:rel_tampa + call ~name:"remove_ipv4_allowed" + ~lifecycle: + [(Published, rel_tampa, "Removes an IPv4 address from this VIF")] ~doc:"Removes an IPv4 address from this VIF" ~params: [ @@ -2528,7 +2894,15 @@ module VIF = struct ~allowed_roles:_R_POOL_OP () let set_ipv6_allowed = - call ~name:"set_ipv6_allowed" ~in_product_since:rel_tampa + call ~name:"set_ipv6_allowed" + ~lifecycle: + [ + ( Published + , rel_tampa + , "Set the IPv6 addresses to which traffic on this VIF can be \ + restricted" + ) + ] ~doc: "Set the IPv6 addresses to which traffic on this VIF can be restricted" ~params: @@ -2545,7 +2919,9 @@ module VIF = struct ~allowed_roles:_R_POOL_OP () let add_ipv6_allowed = - call ~name:"add_ipv6_allowed" ~in_product_since:rel_tampa + call ~name:"add_ipv6_allowed" + ~lifecycle: + [(Published, rel_tampa, "Associates an IPv6 address with this VIF")] ~doc:"Associates an IPv6 address with this VIF" ~params: [ @@ -2561,7 +2937,9 @@ module VIF = struct ~allowed_roles:_R_POOL_OP () let remove_ipv6_allowed = - call ~name:"remove_ipv6_allowed" ~in_product_since:rel_tampa + call ~name:"remove_ipv6_allowed" + ~lifecycle: + [(Published, rel_tampa, "Removes an IPv6 address from this VIF")] ~doc:"Removes an IPv6 address from this VIF" ~params: [ @@ -2571,7 +2949,14 @@ module VIF = struct ~allowed_roles:_R_POOL_OP () let configure_ipv4 = - call ~name:"configure_ipv4" ~in_product_since:rel_dundee + call ~name:"configure_ipv4" + ~lifecycle: + [ + ( Published + , rel_dundee + , "Configure IPv4 settings for this virtual interface" + ) + ] ~doc:"Configure IPv4 settings for this virtual interface" ~versioned_params: [ @@ -2611,7 +2996,14 @@ module VIF = struct ~allowed_roles:_R_VM_OP () let configure_ipv6 = - call ~name:"configure_ipv6" ~in_product_since:rel_dundee + call ~name:"configure_ipv6" + ~lifecycle: + [ + ( Published + , rel_dundee + , "Configure IPv6 settings for this virtual interface" + ) + ] ~doc:"Configure IPv6 settings for this virtual interface" ~versioned_params: [ @@ -3020,7 +3412,16 @@ module SR = struct } let create = - call ~name:"create" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"create" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Create a new Storage Repository and introduce it into the managed \ + system, creating both SR record and PBD record to attach it to \ + current host (with specified device_config parameters)" + ) + ] ~versioned_params: (host_param :: dev_config_param @@ -3038,7 +3439,17 @@ module SR = struct let destroy_self_param = (Ref _sr, "sr", "The SR to destroy") let destroy = - call ~name:"destroy" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"destroy" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Destroy specified SR, removing SR-record from database and remove \ + SR from disk. (In order to affect this operation the appropriate \ + device_config is read from the specified SR's PBD on current \ + host)" + ) + ] ~doc: "Destroy specified SR, removing SR-record from database and remove SR \ from disk. (In order to affect this operation the appropriate \ @@ -3047,7 +3458,15 @@ module SR = struct ~allowed_roles:_R_POOL_OP () let forget = - call ~name:"forget" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"forget" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Removing specified SR-record from database, without attempting to \ + remove SR from disk" + ) + ] ~doc: "Removing specified SR-record from database, without attempting to \ remove SR from disk" @@ -3055,7 +3474,14 @@ module SR = struct ~allowed_roles:_R_POOL_OP () let introduce = - call ~name:"introduce" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"introduce" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Introduce a new Storage Repository into the managed system" + ) + ] ~versioned_params: ({ param_type= String @@ -3072,7 +3498,19 @@ module SR = struct ~allowed_roles:_R_POOL_OP () let probe = - call ~name:"probe" ~in_oss_since:None ~in_product_since:rel_miami + call ~name:"probe" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_miami + , "Perform a backend-specific scan, using the given device_config. \ + If the device_config is complete, then this will return a list of \ + the SRs present of this type on the device, if any. If the \ + device_config is partial, then a backend-specific scan will be \ + performed, returning results that will guide the user in \ + improving the device_config." + ) + ] ~versioned_params: [ host_param @@ -3130,8 +3568,7 @@ module SR = struct ~allowed_roles:_R_POOL_OP () let make = - call ~name:"make" ~in_oss_since:None ~in_product_since:rel_rio - ~internal_deprecated_since:rel_miami + call ~name:"make" ~in_oss_since:None ~lifecycle: [ (Published, rel_rio, "Create a new Storage Repository on disk") @@ -3150,27 +3587,44 @@ module SR = struct ~allowed_roles:_R_POOL_OP () let get_supported_types = - call ~name:"get_supported_types" ~in_product_since:rel_rio ~flags:[`Session] + call ~name:"get_supported_types" + ~lifecycle: + [ + ( Published + , rel_rio + , "Return a set of all the SR types supported by the system" + ) + ] + ~flags:[`Session] ~doc:"Return a set of all the SR types supported by the system" ~params:[] ~result:(Set String, "the supported SR types") ~allowed_roles:_R_READ_ONLY () let scan = - call ~name:"scan" ~in_product_since:rel_rio + call ~name:"scan" + ~lifecycle: + [ + ( Published + , rel_rio + , "Refreshes the list of VDIs associated with an SR" + ) + ] ~doc:"Refreshes the list of VDIs associated with an SR" ~params:[(Ref _sr, "sr", "The SR to scan")] ~allowed_roles:_R_VM_POWER_ADMIN () (* Nb, although this is a new explicit call, it's actually been in the API since rio - just autogenerated. So no setting of rel_miami. *) let set_shared = - call ~name:"set_shared" ~in_product_since:rel_rio + call ~name:"set_shared" + ~lifecycle:[(Published, rel_rio, "Sets the shared flag on the SR")] ~doc:"Sets the shared flag on the SR" ~params: [(Ref _sr, "sr", "The SR"); (Bool, "value", "True if the SR is shared")] ~allowed_roles:_R_POOL_OP () let set_name_label = - call ~name:"set_name_label" ~in_product_since:rel_rio + call ~name:"set_name_label" + ~lifecycle:[(Published, rel_rio, "Set the name label of the SR")] ~doc:"Set the name label of the SR" ~params: [ @@ -3180,7 +3634,8 @@ module SR = struct ~allowed_roles:_R_POOL_OP () let set_name_description = - call ~name:"set_name_description" ~in_product_since:rel_rio + call ~name:"set_name_description" + ~lifecycle:[(Published, rel_rio, "Set the name description of the SR")] ~doc:"Set the name description of the SR" ~params: [ @@ -3190,7 +3645,15 @@ module SR = struct ~allowed_roles:_R_POOL_OP () let create_new_blob = - call ~name:"create_new_blob" ~in_product_since:rel_orlando + call ~name:"create_new_blob" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Create a placeholder for a named binary blob of data that is \ + associated with this SR" + ) + ] ~doc: "Create a placeholder for a named binary blob of data that is \ associated with this SR" @@ -3233,14 +3696,16 @@ module SR = struct let get_data_sources = call ~name:"get_data_sources" ~in_oss_since:None - ~in_product_since:rel_dundee ~doc:"" + ~lifecycle:[(Published, rel_dundee, "")] + ~doc:"" ~result:(Set (Record _data_source), "A set of data sources") ~params:[(Ref _sr, "sr", "The SR to interrogate")] ~errs:[] ~flags:[`Session] ~allowed_roles:_R_READ_ONLY () let record_data_source = call ~name:"record_data_source" ~in_oss_since:None - ~in_product_since:rel_dundee + ~lifecycle: + [(Published, rel_dundee, "Start recording the specified data source")] ~doc:"Start recording the specified data source" ~params: [ @@ -3251,7 +3716,13 @@ module SR = struct let query_data_source = call ~name:"query_data_source" ~in_oss_since:None - ~in_product_since:rel_dundee + ~lifecycle: + [ + ( Published + , rel_dundee + , "Query the latest value of the specified data source" + ) + ] ~doc:"Query the latest value of the specified data source" ~params: [ @@ -3263,7 +3734,14 @@ module SR = struct let forget_data_source_archives = call ~name:"forget_data_source_archives" ~in_oss_since:None - ~in_product_since:rel_dundee + ~lifecycle: + [ + ( Published + , rel_dundee + , "Forget the recorded statistics related to the specified data \ + source" + ) + ] ~doc:"Forget the recorded statistics related to the specified data source" ~params: [ @@ -3277,7 +3755,8 @@ module SR = struct let set_virtual_allocation = call ~name:"set_virtual_allocation" ~in_oss_since:None - ~in_product_since:rel_miami + ~lifecycle: + [(Published, rel_miami, "Sets the SR's virtual_allocation field")] ~params: [ (Ref _sr, "self", "The SR to modify") @@ -3288,7 +3767,7 @@ module SR = struct let set_physical_size = call ~name:"set_physical_size" ~in_oss_since:None - ~in_product_since:rel_miami + ~lifecycle:[(Published, rel_miami, "Sets the SR's physical_size field")] ~params: [ (Ref _sr, "self", "The SR to modify") @@ -3299,7 +3778,9 @@ module SR = struct let set_physical_utilisation = call ~name:"set_physical_utilisation" ~in_oss_since:None - ~in_product_since:rel_miami ~flags:[`Session] + ~lifecycle: + [(Published, rel_miami, "Sets the SR's physical_utilisation field")] + ~flags:[`Session] ~params: [ (Ref _sr, "self", "The SR to modify") @@ -3309,13 +3790,21 @@ module SR = struct ~allowed_roles:_R_LOCAL_ROOT_ONLY () let update = - call ~name:"update" ~in_oss_since:None ~in_product_since:rel_symc + call ~name:"update" ~in_oss_since:None + ~lifecycle:[(Published, rel_symc, "Refresh the fields on the SR object")] ~params:[(Ref _sr, "sr", "The SR whose fields should be refreshed")] ~doc:"Refresh the fields on the SR object" ~allowed_roles:_R_POOL_OP () let assert_can_host_ha_statefile = call ~name:"assert_can_host_ha_statefile" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Returns successfully if the given SR can host an HA statefile. \ + Otherwise returns an error to explain why not" + ) + ] ~params:[(Ref _sr, "sr", "The SR to query")] ~doc: "Returns successfully if the given SR can host an HA statefile. \ @@ -3324,7 +3813,14 @@ module SR = struct let assert_supports_database_replication = call ~name:"assert_supports_database_replication" ~in_oss_since:None - ~in_product_since:rel_boston + ~lifecycle: + [ + ( Published + , rel_boston + , "Returns successfully if the given SR supports database \ + replication. Otherwise returns an error to explain why not." + ) + ] ~params:[(Ref _sr, "sr", "The SR to query")] ~doc: "Returns successfully if the given SR supports database replication. \ @@ -3333,13 +3829,13 @@ module SR = struct let enable_database_replication = call ~name:"enable_database_replication" ~in_oss_since:None - ~in_product_since:rel_boston + ~lifecycle:[(Published, rel_boston, "")] ~params:[(Ref _sr, "sr", "The SR to which metadata should be replicated")] ~allowed_roles:_R_POOL_OP () let disable_database_replication = call ~name:"disable_database_replication" ~in_oss_since:None - ~in_product_since:rel_boston + ~lifecycle:[(Published, rel_boston, "")] ~params: [ ( Ref _sr @@ -3351,7 +3847,8 @@ module SR = struct let get_live_hosts = call ~in_oss_since:None ~name:"get_live_hosts" - ~in_product_since:rel_stockholm + ~lifecycle: + [(Published, rel_stockholm, "Get all live hosts attached to this SR")] ~doc:"Get all live hosts attached to this SR" ~params:[(Ref _sr, "sr", "The SR from which to query attached hosts")] ~allowed_roles:_R_POOL_OP ~hide_from_docs:true @@ -3469,7 +3966,8 @@ module SM = struct (** XXX: just make this a field and be done with it. Cowardly refusing to change the schema for now. *) let get_driver_filename = call ~name:"get_driver_filename" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [(Published, rel_orlando, "Gets the SM's driver_filename field")] ~params:[(Ref _sm, "self", "The SM to query")] ~result:(String, "The SM's driver_filename field") ~doc:"Gets the SM's driver_filename field" () @@ -3531,7 +4029,17 @@ end module LVHD = struct let enable_thin_provisioning = call ~name:"enable_thin_provisioning" ~in_oss_since:None - ~in_product_since:rel_dundee ~allowed_roles:_R_POOL_ADMIN + ~lifecycle: + [ + ( Published + , rel_dundee + , "Upgrades an LVHD SR to enable thin-provisioning. Future VDIs \ + created in this SR will be thinly-provisioned, although existing \ + VDIs will be left alone. Note that the SR must be attached to the \ + SRmaster for upgrade to work." + ) + ] + ~allowed_roles:_R_POOL_ADMIN ~params: [ ( Ref _host @@ -3644,7 +4152,18 @@ module VDI = struct ) let snapshot = - call ~name:"snapshot" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"snapshot" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Take a read-only snapshot of the VDI, returning a reference to \ + the snapshot. If any driver_params are specified then these are \ + passed through to the storage-specific substrate driver that \ + takes the snapshot. NB the snapshot lives in the same Storage \ + Repository as its parent." + ) + ] ~versioned_params: [ { @@ -3675,7 +4194,18 @@ module VDI = struct ~allowed_roles:_R_VM_ADMIN ~doc_tags:[Snapshots] () let clone = - call ~name:"clone" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"clone" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Take an exact copy of the VDI and return a reference to the new \ + disk. If any driver_params are specified then these are passed \ + through to the storage-specific substrate driver that implements \ + the clone operation. NB the clone lives in the same Storage \ + Repository as its parent." + ) + ] ~params:[(Ref _vdi, "vdi", "The VDI to clone")] ~versioned_params: [ @@ -3706,7 +4236,9 @@ module VDI = struct ~allowed_roles:_R_VM_ADMIN ~doc_tags:[Snapshots] () let resize = - call ~name:"resize" ~in_product_since:rel_rio ~in_oss_since:None + call ~name:"resize" + ~lifecycle:[(Published, rel_rio, "Resize the VDI.")] + ~in_oss_since:None ~params: [ (Ref _vdi, "vdi", "The VDI to resize") @@ -3805,7 +4337,15 @@ module VDI = struct ~allowed_roles:_R_VM_ADMIN () let pool_migrate = - call ~name:"pool_migrate" ~in_oss_since:None ~in_product_since:rel_tampa + call ~name:"pool_migrate" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_tampa + , "Migrate a VDI, which may be attached to a running guest, to a \ + different SR. The destination SR must be visible to the guest." + ) + ] ~params: [ (Ref _vdi, "vdi", "The VDI to migrate") @@ -3952,7 +4492,9 @@ module VDI = struct (* This used to be called VDI.introduce but it was always an internal call *) let pool_introduce = - call ~name:"pool_introduce" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"pool_introduce" ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Create a new VDI record in the database only")] ~versioned_params: (introduce_params miami_release @ [ @@ -3981,7 +4523,9 @@ module VDI = struct call ~name:"db_forget" ~in_oss_since:None ~params:[(Ref _vdi, "vdi", "The VDI to forget about")] ~doc:"Removes a VDI record from the database" ~hide_from_docs:true - ~in_product_since:rel_miami ~allowed_roles:_R_LOCAL_ROOT_ONLY () + ~lifecycle: + [(Published, rel_miami, "Removes a VDI record from the database")] + ~allowed_roles:_R_LOCAL_ROOT_ONLY () let introduce = call ~name:"introduce" ~in_oss_since:None @@ -3989,17 +4533,29 @@ module VDI = struct ~doc:"Create a new VDI record in the database only" ~result:(Ref _vdi, "The ref of the newly created VDI record.") ~errs:[Api_errors.sr_operation_not_supported] - ~in_product_since:rel_miami ~allowed_roles:_R_VM_ADMIN () + ~lifecycle: + [(Published, rel_miami, "Create a new VDI record in the database only")] + ~allowed_roles:_R_VM_ADMIN () let forget = - call ~name:"forget" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"forget" ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Removes a VDI record from the database")] ~params:[(Ref _vdi, "vdi", "The VDI to forget about")] ~doc:"Removes a VDI record from the database" ~allowed_roles:_R_VM_ADMIN () let force_unlock = - call ~name:"force_unlock" ~in_oss_since:None ~in_product_since:rel_rio - ~internal_deprecated_since:rel_miami + call ~name:"force_unlock" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Steals the lock on this VDI and leaves it unlocked. This function \ + is extremely dangerous. This call is deprecated." + ) + ; (Deprecated, rel_miami, "") + ] ~params:[(Ref _vdi, "vdi", "The VDI to forcibly unlock")] ~doc: "Steals the lock on this VDI and leaves it unlocked. This function is \ @@ -4012,7 +4568,14 @@ module VDI = struct [(Ref _vdi, "vdi", "The VDI whose stats (eg size) should be updated")] ~doc:"Ask the storage backend to refresh the fields in the VDI object" ~errs:[Api_errors.sr_operation_not_supported] - ~in_product_since:rel_symc ~allowed_roles:_R_VM_ADMIN () + ~lifecycle: + [ + ( Published + , rel_symc + , "Ask the storage backend to refresh the fields in the VDI object" + ) + ] + ~allowed_roles:_R_VM_ADMIN () let operations = Enum @@ -4041,7 +4604,8 @@ module VDI = struct ) let set_missing = - call ~name:"set_missing" ~in_oss_since:None ~in_product_since:rel_miami + call ~name:"set_missing" ~in_oss_since:None + ~lifecycle:[(Published, rel_miami, "Sets the VDI's missing field")] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4051,7 +4615,8 @@ module VDI = struct ~allowed_roles:_R_LOCAL_ROOT_ONLY () let set_read_only = - call ~name:"set_read_only" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"set_read_only" ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Sets the VDI's read_only field")] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4061,7 +4626,8 @@ module VDI = struct ~allowed_roles:_R_VM_ADMIN () let set_sharable = - call ~name:"set_sharable" ~in_oss_since:None ~in_product_since:rel_george + call ~name:"set_sharable" ~in_oss_since:None + ~lifecycle:[(Published, rel_george, "Sets the VDI's sharable field")] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4071,7 +4637,8 @@ module VDI = struct ~allowed_roles:_R_VM_ADMIN () let set_managed = - call ~name:"set_managed" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"set_managed" ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Sets the VDI's managed field")] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4081,7 +4648,8 @@ module VDI = struct ~allowed_roles:_R_LOCAL_ROOT_ONLY () let set_virtual_size = - call ~name:"set_virtual_size" ~in_oss_since:None ~in_product_since:rel_miami + call ~name:"set_virtual_size" ~in_oss_since:None + ~lifecycle:[(Published, rel_miami, "Sets the VDI's virtual_size field")] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4092,7 +4660,8 @@ module VDI = struct let set_physical_utilisation = call ~name:"set_physical_utilisation" ~in_oss_since:None - ~in_product_since:rel_miami + ~lifecycle: + [(Published, rel_miami, "Sets the VDI's physical_utilisation field")] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4103,7 +4672,8 @@ module VDI = struct let set_is_a_snapshot = call ~name:"set_is_a_snapshot" ~in_oss_since:None - ~in_product_since:rel_boston + ~lifecycle: + [(Published, rel_boston, "Sets whether this VDI is a snapshot")] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4116,7 +4686,11 @@ module VDI = struct ~hide_from_docs:true ~allowed_roles:_R_LOCAL_ROOT_ONLY () let set_snapshot_of = - call ~name:"set_snapshot_of" ~in_oss_since:None ~in_product_since:rel_boston + call ~name:"set_snapshot_of" ~in_oss_since:None + ~lifecycle: + [ + (Published, rel_boston, "Sets the VDI of which this VDI is a snapshot") + ] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4127,7 +4701,8 @@ module VDI = struct let set_snapshot_time = call ~name:"set_snapshot_time" ~in_oss_since:None - ~in_product_since:rel_boston + ~lifecycle: + [(Published, rel_boston, "Sets the snapshot time of this VDI.")] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4142,7 +4717,13 @@ module VDI = struct let set_metadata_of_pool = call ~name:"set_metadata_of_pool" ~in_oss_since:None - ~in_product_since:rel_boston + ~lifecycle: + [ + ( Published + , rel_boston + , "Records the pool whose metadata is contained by this VDI." + ) + ] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4158,7 +4739,8 @@ module VDI = struct (** An API call for debugging and testing only *) let generate_config = call ~name:"generate_config" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [(Published, rel_orlando, "Internal function for debugging only")] ~params: [ (Ref _host, "host", "The host on which to generate the configuration") @@ -4181,7 +4763,15 @@ module VDI = struct ) let set_on_boot = - call ~name:"set_on_boot" ~in_oss_since:None ~in_product_since:rel_cowley + call ~name:"set_on_boot" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_cowley + , "Set the value of the on_boot parameter. This value can only be \ + changed when the VDI is not attached to a running VM." + ) + ] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4194,7 +4784,18 @@ module VDI = struct let set_allow_caching = call ~name:"set_allow_caching" ~in_oss_since:None - ~in_product_since:rel_cowley + ~lifecycle: + [ + ( Published + , rel_cowley + , "Set the value of the allow_caching parameter. This value can only \ + be changed when the VDI is not attached to a running VM. The \ + caching behaviour is only affected by this flag for VHD-based \ + VDIs that have one parent and no child VHDs. Moreover, caching \ + only takes place when the host running the VM containing this VDI \ + has a nominated SR for local caching." + ) + ] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4210,7 +4811,15 @@ module VDI = struct ~allowed_roles:_R_VM_ADMIN () let set_name_label = - call ~name:"set_name_label" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"set_name_label" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Set the name label of the VDI. This can only happen when then its \ + SR is currently attached." + ) + ] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4223,7 +4832,14 @@ module VDI = struct let set_name_description = call ~name:"set_name_description" ~in_oss_since:None - ~in_product_since:rel_rio + ~lifecycle: + [ + ( Published + , rel_rio + , "Set the name description of the VDI. This can only happen when \ + its SR is currently attached." + ) + ] ~params: [ (Ref _vdi, "self", "The VDI to modify") @@ -4235,7 +4851,15 @@ module VDI = struct ~allowed_roles:_R_VM_ADMIN () let open_database = - call ~name:"open_database" ~in_oss_since:None ~in_product_since:rel_boston + call ~name:"open_database" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_boston + , "Load the metadata found on the supplied VDI and return a session \ + reference which can be used in API calls to query its contents." + ) + ] ~params: [(Ref _vdi, "self", "The VDI which contains the database to open")] ~result:(Ref _session, "A session which can be used to query the database") @@ -4245,7 +4869,14 @@ module VDI = struct ~allowed_roles:_R_POOL_OP () let checksum = - call ~name:"checksum" ~in_oss_since:None ~in_product_since:rel_boston + call ~name:"checksum" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_boston + , "Internal function to calculate VDI checksum and return a string" + ) + ] ~params:[(Ref _vdi, "self", "The VDI to checksum")] ~result:(String, "The md5sum of the vdi") ~doc:"Internal function to calculate VDI checksum and return a string" @@ -4258,14 +4889,29 @@ module VDI = struct let read_database_pool_uuid = call ~name:"read_database_pool_uuid" ~in_oss_since:None - ~in_product_since:rel_boston + ~lifecycle: + [ + ( Published + , rel_boston + , "Check the VDI cache for the pool UUID of the database on this VDI." + ) + ] ~params:[(Ref _vdi, "self", "The metadata VDI to look up in the cache.")] ~result:(String, "The cached pool UUID of the database on the VDI.") ~doc:"Check the VDI cache for the pool UUID of the database on this VDI." ~allowed_roles:_R_READ_ONLY () let enable_cbt = - call ~name:"enable_cbt" ~in_oss_since:None ~in_product_since:rel_inverness + call ~name:"enable_cbt" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_inverness + , "Enable changed block tracking for the VDI. This call is \ + idempotent - enabling CBT for a VDI for which CBT is already \ + enabled results in a no-op, and no error will be thrown." + ) + ] ~params:[(Ref _vdi, "self", "The VDI for which CBT should be enabled")] ~errs: [ @@ -4284,7 +4930,17 @@ module VDI = struct ~allowed_roles:_R_VM_ADMIN () let disable_cbt = - call ~name:"disable_cbt" ~in_oss_since:None ~in_product_since:rel_inverness + call ~name:"disable_cbt" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_inverness + , "Disable changed block tracking for the VDI. This call is only \ + allowed on VDIs that support enabling CBT. It is an idempotent \ + operation - disabling CBT for a VDI for which CBT is not enabled \ + results in a no-op, and no error will be thrown." + ) + ] ~params:[(Ref _vdi, "self", "The VDI for which CBT should be disabled")] ~errs: [ @@ -4306,7 +4962,7 @@ module VDI = struct (** This command is for internal use by SM to set the cbt_enabled field when it needs to disable cbt for its own reasons. This command should be removed once SMAPIv3 is implemented *) let set_cbt_enabled = call ~name:"set_cbt_enabled" ~in_oss_since:None - ~in_product_since:rel_inverness + ~lifecycle:[(Published, rel_inverness, "")] ~params: [ ( Ref _vdi @@ -4318,7 +4974,18 @@ module VDI = struct ~errs:[] ~hide_from_docs:true ~allowed_roles:_R_LOCAL_ROOT_ONLY () let data_destroy = - call ~name:"data_destroy" ~in_oss_since:None ~in_product_since:rel_inverness + call ~name:"data_destroy" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_inverness + , "Delete the data of the snapshot VDI, but keep its changed block \ + tracking metadata. When successful, this call changes the type of \ + the VDI to cbt_metadata. This operation is idempotent: calling it \ + on a VDI of type cbt_metadata results in a no-op, and no error \ + will be thrown." + ) + ] ~params:[(Ref _vdi, "self", "The VDI whose data should be deleted.")] ~errs: [ @@ -4342,7 +5009,15 @@ module VDI = struct let list_changed_blocks = call ~name:"list_changed_blocks" ~in_oss_since:None - ~in_product_since:rel_inverness + ~lifecycle: + [ + ( Published + , rel_inverness + , "Compare two VDIs in 64k block increments and report which blocks \ + differ. This operation is not allowed when vdi_to is attached to \ + a VM." + ) + ] ~params: [ (Ref _vdi, "vdi_from", "The first VDI.") @@ -4368,7 +5043,25 @@ module VDI = struct ~allowed_roles:_R_VM_OP () let get_nbd_info = - call ~name:"get_nbd_info" ~in_oss_since:None ~in_product_since:rel_inverness + call ~name:"get_nbd_info" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_inverness + , "Get details specifying how to access this VDI via a Network Block \ + Device server. For each of a set of NBD server addresses on which \ + the VDI is available, the return value set contains a \ + vdi_nbd_server_info object that contains an exportname to request \ + once the NBD connection is established, and connection details \ + for the address. An empty list is returned if there is no network \ + that has a PIF on a host with access to the relevant SR, or if no \ + such network has been assigned an NBD-related purpose in its \ + purpose field. To access the given VDI, any of the \ + vdi_nbd_server_info objects can be used to make a connection to a \ + server, and then the VDI will be available by requesting the \ + exportname." + ) + ] ~params: [ ( Ref _vdi @@ -4594,14 +5287,22 @@ module VBD = struct ) let eject = - call ~name:"eject" ~in_product_since:rel_rio + call ~name:"eject" + ~lifecycle: + [ + ( Published + , rel_rio + , "Remove the media from the device and leave it empty" + ) + ] ~doc:"Remove the media from the device and leave it empty" ~params:[(Ref _vbd, "vbd", "The vbd representing the CDROM-like device")] ~errs:[Api_errors.vbd_not_removable_media; Api_errors.vbd_is_empty] ~allowed_roles:_R_VM_OP () let insert = - call ~name:"insert" ~in_product_since:rel_rio + call ~name:"insert" + ~lifecycle:[(Published, rel_rio, "Insert new media into the device")] ~doc:"Insert new media into the device" ~params: [ @@ -4612,14 +5313,30 @@ module VBD = struct ~allowed_roles:_R_VM_OP () let plug = - call ~name:"plug" ~in_product_since:rel_rio + call ~name:"plug" + ~lifecycle: + [ + ( Published + , rel_rio + , "Hotplug the specified VBD, dynamically attaching it to the \ + running VM" + ) + ] ~doc: "Hotplug the specified VBD, dynamically attaching it to the running VM" ~params:[(Ref _vbd, "self", "The VBD to hotplug")] ~allowed_roles:_R_VM_ADMIN () let unplug = - call ~name:"unplug" ~in_product_since:rel_rio + call ~name:"unplug" + ~lifecycle: + [ + ( Published + , rel_rio + , "Hot-unplug the specified VBD, dynamically unattaching it from the \ + running VM" + ) + ] ~doc: "Hot-unplug the specified VBD, dynamically unattaching it from the \ running VM" @@ -4629,7 +5346,8 @@ module VBD = struct ~allowed_roles:_R_VM_ADMIN () let unplug_force = - call ~name:"unplug_force" ~in_product_since:rel_rio + call ~name:"unplug_force" + ~lifecycle:[(Published, rel_rio, "Forcibly unplug the specified VBD")] ~doc:"Forcibly unplug the specified VBD" ~params:[(Ref _vbd, "self", "The VBD to forcibly unplug")] ~allowed_roles:_R_VM_ADMIN () @@ -4650,8 +5368,20 @@ module VBD = struct if the device supports surprise-remove)" ) ] - ~internal_deprecated_since:rel_ely ~hide_from_docs:true - ~in_product_since:rel_symc ~allowed_roles:_R_VM_ADMIN () + ~hide_from_docs:true + ~lifecycle: + [ + ( Published + , rel_symc + , "Deprecated: use 'unplug_force' instead. Forcibly unplug the \ + specified VBD without any safety checks. This is an extremely \ + dangerous operation in the general case that can cause guest \ + crashes and data corruption; it should be called with extreme \ + caution. Functionally equivalent with 'unplug_force'." + ) + ; (Deprecated, rel_ely, "") + ] + ~allowed_roles:_R_VM_ADMIN () let pause = call ~name:"pause" @@ -4659,7 +5389,15 @@ module VBD = struct "Stop the backend device servicing requests so that an operation can \ be performed on the disk (eg live resize, snapshot)" ~params:[(Ref _vbd, "self", "The VBD to pause")] - ~hide_from_docs:true ~in_product_since:rel_symc + ~hide_from_docs:true + ~lifecycle: + [ + ( Published + , rel_symc + , "Stop the backend device servicing requests so that an operation \ + can be performed on the disk (eg live resize, snapshot)" + ) + ] ~result: ( String , "Token to uniquely identify this pause instance, used to match the \ @@ -4690,11 +5428,27 @@ module VBD = struct ; param_default= Some (VString "") } ] - ~hide_from_docs:true ~in_product_since:rel_symc ~allowed_roles:_R_VM_ADMIN - () + ~hide_from_docs:true + ~lifecycle: + [ + ( Published + , rel_symc + , "Restart the backend device after it was paused while an operation \ + was performed on the disk (eg live resize, snapshot)" + ) + ] + ~allowed_roles:_R_VM_ADMIN () let assert_attachable = - call ~name:"assert_attachable" ~in_product_since:rel_rio + call ~name:"assert_attachable" + ~lifecycle: + [ + ( Published + , rel_rio + , "Throws an error if this VBD could not be attached to this VM if \ + the VM were running. Intended for debugging." + ) + ] ~doc: "Throws an error if this VBD could not be attached to this VM if the \ VM were running. Intended for debugging." @@ -4702,7 +5456,15 @@ module VBD = struct ~in_oss_since:None ~allowed_roles:_R_VM_ADMIN () let set_mode = - call ~name:"set_mode" ~in_product_since:rel_rio + call ~name:"set_mode" + ~lifecycle: + [ + ( Published + , rel_rio + , "Sets the mode of the VBD. The power_state of the VM must be \ + halted." + ) + ] ~doc:"Sets the mode of the VBD. The power_state of the VM must be halted." ~params: [ @@ -4837,7 +5599,8 @@ end module Crashdump = struct let destroy = - call ~name:"destroy" ~in_product_since:rel_rio + call ~name:"destroy" + ~lifecycle:[(Published, rel_rio, "Destroy the specified crashdump")] ~doc:"Destroy the specified crashdump" ~params:[(Ref _crashdump, "self", "The crashdump to destroy")] ~allowed_roles:_R_POOL_OP () @@ -4867,7 +5630,15 @@ module Auth = struct (** Auth class *) let get_subject_identifier = call ~flags:[`Session] ~name:"get_subject_identifier" ~in_oss_since:None - ~in_product_since:rel_george + ~lifecycle: + [ + ( Published + , rel_george + , "This call queries the external directory service to obtain the \ + subject_identifier as a string from the human-readable \ + subject_name" + ) + ] ~params: [ (*Ref _auth, "auth", "???";*) @@ -4887,7 +5658,16 @@ module Auth = struct let get_subject_information_from_identifier = call ~flags:[`Session] ~name:"get_subject_information_from_identifier" - ~in_oss_since:None ~in_product_since:rel_george + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "This call queries the external directory service to obtain the \ + user information (e.g. username, organization etc) from the \ + specified subject_identifier" + ) + ] ~params: [ ( String @@ -4908,7 +5688,15 @@ module Auth = struct let get_group_membership = call ~flags:[`Session] ~name:"get_group_membership" ~in_oss_since:None - ~in_product_since:rel_george + ~lifecycle: + [ + ( Published + , rel_george + , "This calls queries the external directory service to obtain the \ + transitively-closed set of groups that the the subject_identifier \ + is member of." + ) + ] ~params: [ ( String @@ -4947,7 +5735,13 @@ module Subject = struct (** Subject class *) let add_to_roles = call ~flags:[`Session] ~name:"add_to_roles" ~in_oss_since:None - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "This call adds a new role to a subject" + ) + ] ~params: [ (Ref _subject, "self", "The subject who we want to add the role to") @@ -4958,7 +5752,13 @@ module Subject = struct let remove_from_roles = call ~flags:[`Session] ~name:"remove_from_roles" ~in_oss_since:None - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "This call removes a role from a subject" + ) + ] ~params: [ ( Ref _subject @@ -4975,7 +5775,13 @@ module Subject = struct let get_permissions_name_label = call ~flags:[`Session] ~name:"get_permissions_name_label" ~in_oss_since:None - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "This call returns a list of permission names given a subject" + ) + ] ~params: [ ( Ref _subject @@ -5020,7 +5826,13 @@ module Role = struct (** Role class *) let get_permissions = call ~flags:[`Session] ~name:"get_permissions" ~in_oss_since:None - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "This call returns a list of permissions given a role" + ) + ] ~params:[(Ref _role, "self", "a reference to a role")] ~result:(Set (Ref _role), "a list of permissions") ~doc:"This call returns a list of permissions given a role" @@ -5028,7 +5840,13 @@ module Role = struct let get_permissions_name_label = call ~flags:[`Session] ~name:"get_permissions_name_label" ~in_oss_since:None - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "This call returns a list of permission names given a role" + ) + ] ~params:[(Ref _role, "self", "a reference to a role")] ~result:(Set String, "a list of permission names") ~doc:"This call returns a list of permission names given a role" @@ -5036,7 +5854,13 @@ module Role = struct let get_by_permission = call ~flags:[`Session] ~name:"get_by_permission" ~in_oss_since:None - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "This call returns a list of roles given a permission" + ) + ] ~params:[(Ref _role, "permission", "a reference to a permission")] ~result:(Set (Ref _role), "a list of references to roles") ~doc:"This call returns a list of roles given a permission" @@ -5044,7 +5868,14 @@ module Role = struct let get_by_permission_name_label = call ~flags:[`Session] ~name:"get_by_permission_name_label" - ~in_oss_since:None ~in_product_since:rel_midnight_ride + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "This call returns a list of roles given a permission name" + ) + ] ~params:[(String, "label", "The short friendly name of the role")] ~result:(Set (Ref _role), "a list of references to roles") ~doc:"This call returns a list of roles given a permission name" @@ -5791,7 +6622,13 @@ module VMSS = struct (* VM schedule snapshot *) let snapshot_now = call ~flags:[`Session] ~name:"snapshot_now" ~in_oss_since:None - ~in_product_since:rel_falcon + ~lifecycle: + [ + ( Published + , rel_falcon + , "This call executes the snapshot schedule immediately" + ) + ] ~params:[(Ref _vmss, "vmss", "Snapshot Schedule to execute")] ~doc:"This call executes the snapshot schedule immediately" ~allowed_roles:_R_POOL_OP @@ -5826,7 +6663,8 @@ module VMSS = struct let set_retained_snapshots = call ~flags:[`Session] ~name:"set_retained_snapshots" ~in_oss_since:None - ~in_product_since:rel_falcon ~allowed_roles:_R_POOL_OP + ~lifecycle:[(Published, rel_falcon, "")] + ~allowed_roles:_R_POOL_OP ~params: [ (Ref _vmss, "self", "The schedule snapshot") @@ -5836,7 +6674,8 @@ module VMSS = struct let set_frequency = call ~flags:[`Session] ~name:"set_frequency" ~in_oss_since:None - ~in_product_since:rel_falcon + ~lifecycle: + [(Published, rel_falcon, "Set the value of the frequency field")] ~params: [ (Ref _vmss, "self", "The snapshot schedule") @@ -5846,7 +6685,8 @@ module VMSS = struct let set_schedule = call ~flags:[`Session] ~name:"set_schedule" ~in_oss_since:None - ~in_product_since:rel_falcon ~allowed_roles:_R_POOL_OP + ~lifecycle:[(Published, rel_falcon, "")] + ~allowed_roles:_R_POOL_OP ~params: [ (Ref _vmss, "self", "The snapshot schedule") @@ -5856,7 +6696,8 @@ module VMSS = struct let set_last_run_time = call ~flags:[`Session] ~name:"set_last_run_time" ~in_oss_since:None - ~in_product_since:rel_falcon ~allowed_roles:_R_LOCAL_ROOT_ONLY + ~lifecycle:[(Published, rel_falcon, "")] + ~allowed_roles:_R_LOCAL_ROOT_ONLY ~params: [ (Ref _vmss, "self", "The snapshot schedule") @@ -5870,7 +6711,8 @@ module VMSS = struct let add_to_schedule = call ~flags:[`Session] ~name:"add_to_schedule" ~in_oss_since:None - ~in_product_since:rel_falcon ~allowed_roles:_R_POOL_OP + ~lifecycle:[(Published, rel_falcon, "")] + ~allowed_roles:_R_POOL_OP ~params: [ (Ref _vmss, "self", "The snapshot schedule") @@ -5881,7 +6723,8 @@ module VMSS = struct let remove_from_schedule = call ~flags:[`Session] ~name:"remove_from_schedule" ~in_oss_since:None - ~in_product_since:rel_falcon ~allowed_roles:_R_POOL_OP + ~lifecycle:[(Published, rel_falcon, "")] + ~allowed_roles:_R_POOL_OP ~params: [ (Ref _vmss, "self", "The snapshot schedule") @@ -5891,7 +6734,8 @@ module VMSS = struct let set_type = call ~flags:[`Session] ~name:"set_type" ~in_oss_since:None - ~in_product_since:rel_falcon ~allowed_roles:_R_POOL_OP + ~lifecycle:[(Published, rel_falcon, "")] + ~allowed_roles:_R_POOL_OP ~params: [ (Ref _vmss, "self", "The snapshot schedule") @@ -5961,7 +6805,8 @@ module VM_appliance = struct ) let start = - call ~name:"start" ~in_product_since:rel_boston + call ~name:"start" + ~lifecycle:[(Published, rel_boston, "Start all VMs in the appliance")] ~params: [ (Ref _vm_appliance, "self", "The VM appliance") @@ -5975,21 +6820,43 @@ module VM_appliance = struct ~doc:"Start all VMs in the appliance" ~allowed_roles:_R_POOL_OP () let clean_shutdown = - call ~name:"clean_shutdown" ~in_product_since:rel_boston + call ~name:"clean_shutdown" + ~lifecycle: + [ + ( Published + , rel_boston + , "Perform a clean shutdown of all the VMs in the appliance" + ) + ] ~params:[(Ref _vm_appliance, "self", "The VM appliance")] ~errs:[Api_errors.operation_partially_failed] ~doc:"Perform a clean shutdown of all the VMs in the appliance" ~allowed_roles:_R_POOL_OP () let hard_shutdown = - call ~name:"hard_shutdown" ~in_product_since:rel_boston + call ~name:"hard_shutdown" + ~lifecycle: + [ + ( Published + , rel_boston + , "Perform a hard shutdown of all the VMs in the appliance" + ) + ] ~params:[(Ref _vm_appliance, "self", "The VM appliance")] ~errs:[Api_errors.operation_partially_failed] ~doc:"Perform a hard shutdown of all the VMs in the appliance" ~allowed_roles:_R_POOL_OP () let shutdown = - call ~name:"shutdown" ~in_product_since:rel_boston + call ~name:"shutdown" + ~lifecycle: + [ + ( Published + , rel_boston + , "For each VM in the appliance, try to shut it down cleanly. If \ + this fails, perform a hard shutdown of the VM." + ) + ] ~params:[(Ref _vm_appliance, "self", "The VM appliance")] ~errs:[Api_errors.operation_partially_failed] ~doc: @@ -5998,7 +6865,15 @@ module VM_appliance = struct ~allowed_roles:_R_POOL_OP () let assert_can_be_recovered = - call ~name:"assert_can_be_recovered" ~in_product_since:rel_boston + call ~name:"assert_can_be_recovered" + ~lifecycle: + [ + ( Published + , rel_boston + , "Assert whether all SRs required to recover this VM appliance are \ + available." + ) + ] ~params: [ (Ref _vm_appliance, "self", "The VM appliance to recover") @@ -6014,7 +6889,14 @@ module VM_appliance = struct ~allowed_roles:_R_READ_ONLY () let get_SRs_required_for_recovery = - call ~name:"get_SRs_required_for_recovery" ~in_product_since:rel_creedence + call ~name:"get_SRs_required_for_recovery" + ~lifecycle: + [ + ( Published + , rel_creedence + , "Get the list of SRs required by the VM appliance to recover." + ) + ] ~params: [ ( Ref _vm_appliance @@ -6033,7 +6915,8 @@ module VM_appliance = struct ~allowed_roles:_R_READ_ONLY () let recover = - call ~name:"recover" ~in_product_since:rel_boston + call ~name:"recover" + ~lifecycle:[(Published, rel_boston, "Recover the VM appliance")] ~params: [ (Ref _vm_appliance, "self", "The VM appliance to recover") @@ -6080,7 +6963,15 @@ end module DR_task = struct (* DR_task *) let create = - call ~name:"create" ~in_product_since:rel_boston + call ~name:"create" + ~lifecycle: + [ + ( Published + , rel_boston + , "Create a disaster recovery task which will query the supplied \ + list of devices" + ) + ] ~params: [ (String, "type", "The SR driver type of the SRs to introduce") @@ -6097,7 +6988,15 @@ module DR_task = struct ~allowed_roles:_R_POOL_OP () let destroy = - call ~name:"destroy" ~in_product_since:rel_boston + call ~name:"destroy" + ~lifecycle: + [ + ( Published + , rel_boston + , "Destroy the disaster recovery task, detaching and forgetting any \ + SRs introduced which are no longer required" + ) + ] ~params:[(Ref _dr_task, "self", "The disaster recovery task to destroy")] ~doc: "Destroy the disaster recovery task, detaching and forgetting any SRs \ @@ -6133,8 +7032,17 @@ module Event = struct ) let register = - call ~name:"register" ~in_product_since:rel_rio - ~internal_deprecated_since:rel_boston + call ~name:"register" + ~lifecycle: + [ + ( Published + , rel_rio + , "Registers this session with the event system for a set of given \ + classes. This method is only recommended for legacy use in \ + conjunction with event.next." + ) + ; (Deprecated, rel_boston, "") + ] ~params: [ ( Set String @@ -6151,8 +7059,17 @@ module Event = struct ~allowed_roles:_R_ALL () let unregister = - call ~name:"unregister" ~in_product_since:rel_rio - ~internal_deprecated_since:rel_boston + call ~name:"unregister" + ~lifecycle: + [ + ( Published + , rel_rio + , "Removes this session's registration with the event system for a \ + set of given classes. This method is only recommended for legacy \ + use in conjunction with event.next." + ) + ; (Deprecated, rel_boston, "") + ] ~params: [ ( Set String @@ -6168,8 +7085,17 @@ module Event = struct ~allowed_roles:_R_ALL () let next = - call ~name:"next" ~params:[] ~in_product_since:rel_rio - ~internal_deprecated_since:rel_boston + call ~name:"next" ~params:[] + ~lifecycle: + [ + ( Published + , rel_rio + , "Blocking call which returns a (possibly empty) batch of events. \ + This method is only recommended for legacy use. New development \ + should use event.from which supersedes this method." + ) + ; (Deprecated, rel_boston, "") + ] ~doc: "Blocking call which returns a (possibly empty) batch of events. This \ method is only recommended for legacy use. New development should use \ @@ -6194,7 +7120,15 @@ module Event = struct ) ; (Float, "timeout", "Return after this many seconds if no events match") ] - ~in_product_since:rel_boston + ~lifecycle: + [ + ( Published + , rel_boston + , "Blocking call which returns a new token and a (possibly empty) \ + batch of events. The returned token can be used in subsequent \ + calls to this function." + ) + ] ~doc: "Blocking call which returns a new token and a (possibly empty) batch \ of events. The returned token can be used in subsequent calls to this \ @@ -6213,7 +7147,14 @@ module Event = struct ~allowed_roles:_R_ALL () let get_current_id = - call ~name:"get_current_id" ~params:[] ~in_product_since:rel_rio + call ~name:"get_current_id" ~params:[] + ~lifecycle: + [ + ( Published + , rel_rio + , "Return the ID of the next event to be generated by the system" + ) + ] ~doc:"Return the ID of the next event to be generated by the system" ~flags:[`Session] ~result:(Int, "the event ID") ~allowed_roles:_R_ALL () @@ -6224,7 +7165,20 @@ module Event = struct (String, "class", "class of the object") ; (String, "ref", "A reference to the object that will be changed.") ] - ~in_product_since:rel_tampa + ~lifecycle: + [ + ( Published + , rel_tampa + , "Injects an artificial event on the given object and returns the \ + corresponding ID in the form of a token, which can be used as a \ + point of reference for database events. For example, to check \ + whether an object has reached the right state before attempting \ + an operation, one can inject an artificial event on the object \ + and wait until the token returned by consecutive event.from calls \ + is lexicographically greater than the one returned by \ + event.inject." + ) + ] ~doc: "Injects an artificial event on the given object and returns the \ corresponding ID in the form of a token, which can be used as a point \ @@ -6291,7 +7245,9 @@ end module Blob = struct let create = - call ~name:"create" ~in_product_since:rel_orlando + call ~name:"create" + ~lifecycle: + [(Published, rel_orlando, "Create a placeholder for a binary blob")] ~versioned_params: [ { @@ -6316,7 +7272,8 @@ module Blob = struct ~allowed_roles:_R_POOL_OP () let destroy = - call ~name:"destroy" ~in_product_since:rel_orlando + call ~name:"destroy" + ~lifecycle:[(Published, rel_orlando, "")] ~params:[(Ref _blob, "self", "The reference of the blob to destroy")] ~flags:[`Session] ~allowed_roles:_R_POOL_OP () @@ -6362,7 +7319,8 @@ module Message = struct ) let create = - call ~name:"create" ~in_product_since:rel_orlando + call ~name:"create" + ~lifecycle:[(Published, rel_orlando, "")] ~params: [ (String, "name", "The name of the message") @@ -6379,7 +7337,8 @@ module Message = struct ~allowed_roles:_R_POOL_OP () let destroy = - call ~name:"destroy" ~in_product_since:rel_orlando + call ~name:"destroy" + ~lifecycle:[(Published, rel_orlando, "")] ~params: [(Ref _message, "self", "The reference of the message to destroy")] ~flags:[`Session] ~allowed_roles:_R_POOL_OP () @@ -6390,13 +7349,15 @@ module Message = struct ~allowed_roles:_R_POOL_OP () let get_all = - call ~name:"get_all" ~in_product_since:rel_orlando ~params:[] - ~flags:[`Session] + call ~name:"get_all" + ~lifecycle:[(Published, rel_orlando, "")] + ~params:[] ~flags:[`Session] ~result:(Set (Ref _message), "The references to the messages") ~allowed_roles:_R_READ_ONLY () let get = - call ~name:"get" ~in_product_since:rel_orlando + call ~name:"get" + ~lifecycle:[(Published, rel_orlando, "")] ~params: [ (cls, "cls", "The class of object") @@ -6411,7 +7372,8 @@ module Message = struct ~allowed_roles:_R_READ_ONLY () let get_since = - call ~name:"get_since" ~in_product_since:rel_orlando + call ~name:"get_since" + ~lifecycle:[(Published, rel_orlando, "")] ~params: [ ( DateTime @@ -6424,27 +7386,31 @@ module Message = struct ~allowed_roles:_R_READ_ONLY () let get_by_uuid = - call ~name:"get_by_uuid" ~in_product_since:rel_orlando + call ~name:"get_by_uuid" + ~lifecycle:[(Published, rel_orlando, "")] ~params:[(String, "uuid", "The uuid of the message")] ~flags:[`Session] ~result:(Ref _message, "The message reference") ~allowed_roles:_R_READ_ONLY () let get_record = - call ~name:"get_record" ~in_product_since:rel_orlando + call ~name:"get_record" + ~lifecycle:[(Published, rel_orlando, "")] ~params:[(Ref _message, "self", "The reference to the message")] ~flags:[`Session] ~result:(Record _message, "The message record") ~allowed_roles:_R_READ_ONLY () let get_all_records = - call ~name:"get_all_records" ~in_product_since:rel_orlando ~params:[] - ~flags:[`Session] + call ~name:"get_all_records" + ~lifecycle:[(Published, rel_orlando, "")] + ~params:[] ~flags:[`Session] ~result:(Map (Ref _message, Record _message), "The messages") ~allowed_roles:_R_READ_ONLY () let get_all_records_where = - call ~name:"get_all_records_where" ~in_product_since:rel_orlando + call ~name:"get_all_records_where" + ~lifecycle:[(Published, rel_orlando, "")] ~params:[(String, "expr", "The expression to match (not currently used)")] ~flags:[`Session] ~result:(Map (Ref _message, Record _message), "The messages") @@ -6495,7 +7461,8 @@ end module Secret = struct let introduce = - call ~name:"introduce" ~in_product_since:rel_midnight_ride + call ~name:"introduce" + ~lifecycle:[(Published, rel_midnight_ride, "")] ~versioned_params: [ { diff --git a/ocaml/idl/datamodel_common.ml b/ocaml/idl/datamodel_common.ml index 8b34e41c8ec..07ea70f90a4 100644 --- a/ocaml/idl/datamodel_common.ml +++ b/ocaml/idl/datamodel_common.ml @@ -573,36 +573,20 @@ let get_deprecated lifecycle = Some deprecated with Not_found -> None -let call ~name ?(doc = "") ?(in_oss_since = Some "3.0.3") ?in_product_since - ?internal_deprecated_since ?result ?(flags = [`Session; `Async]) - ?(effect = true) ?(tag = Custom) ?(errs = []) ?(custom_marshaller = false) - ?(db_only = false) ?(no_current_operations = false) ?(secret = false) - ?(hide_from_docs = false) ?(pool_internal = false) ~allowed_roles - ?(map_keys_roles = []) ?(params = []) ?versioned_params ?lifecycle - ?(doc_tags = []) ?forward_to () = +let call ~name ?(doc = "") ?(in_oss_since = Some "3.0.3") ?result + ?(flags = [`Session; `Async]) ?(effect = true) ?(tag = Custom) ?(errs = []) + ?(custom_marshaller = false) ?(db_only = false) + ?(no_current_operations = false) ?(secret = false) ?(hide_from_docs = false) + ?(pool_internal = false) ~allowed_roles ?(map_keys_roles = []) + ?(params = []) ?versioned_params ?lifecycle ?(doc_tags = []) ?forward_to () + = (* if you specify versioned_params then these get put in the params field of the message record; * otherwise params go in with no default values and param_release=call_release... *) - if lifecycle = None && in_product_since = None then - failwith ("Lifecycle for message '" ^ name ^ "' not specified") ; let lifecycle = match lifecycle with | None -> - let published = - match in_product_since with - | None -> - [] - | Some rel -> - [(Published, rel, doc)] - in - let deprecated = - match internal_deprecated_since with - | None -> - [] - | Some rel -> - [(Deprecated, rel, "")] - in - published @ deprecated + failwith ("Lifecycle for message '" ^ name ^ "' not specified") | Some l -> l in diff --git a/ocaml/idl/datamodel_diagnostics.ml b/ocaml/idl/datamodel_diagnostics.ml index 88c40eb47cc..b81d12ca905 100644 --- a/ocaml/idl/datamodel_diagnostics.ml +++ b/ocaml/idl/datamodel_diagnostics.ml @@ -1,14 +1,23 @@ open Datamodel_common let gc_compact = - call ~name:"gc_compact" ~in_product_since:Datamodel_types.rel_stockholm + call ~name:"gc_compact" + ~lifecycle: + [ + ( Published + , Datamodel_types.rel_stockholm + , "Perform a full major collection and compact the heap on a host" + ) + ] ~doc:"Perform a full major collection and compact the heap on a host" ~hide_from_docs:true ~params:[(Ref _host, "host", "The host to perform GC")] ~errs:[] ~allowed_roles:Datamodel_roles._R_POOL_OP () let gc_stats = - call ~name:"gc_stats" ~in_product_since:Datamodel_types.rel_stockholm + call ~name:"gc_stats" + ~lifecycle: + [(Published, Datamodel_types.rel_stockholm, "Get GC stats of a host")] ~doc:"Get GC stats of a host" ~hide_from_docs:true ~params:[(Ref _host, "host", "The host from which to obtain GC stats")] ~errs:[] ~allowed_roles:Datamodel_roles._R_POOL_OP @@ -16,14 +25,25 @@ let gc_stats = () let db_stats = - call ~name:"db_stats" ~in_product_since:Datamodel_types.rel_stockholm + call ~name:"db_stats" + ~lifecycle: + [ + ( Published + , Datamodel_types.rel_stockholm + , "Get the database stats of the pool" + ) + ] ~doc:"Get the database stats of the pool" ~hide_from_docs:true ~params:[] ~errs:[] ~allowed_roles:Datamodel_roles._R_POOL_OP ~result:(Map (String, String), "Collection of database stats") () let network_stats = - call ~name:"network_stats" ~in_product_since:Datamodel_types.rel_stockholm + call ~name:"network_stats" + ~lifecycle: + [ + (Published, Datamodel_types.rel_stockholm, "Get network stats of a host") + ] ~doc:"Get network stats of a host" ~hide_from_docs:true ~params: [ diff --git a/ocaml/idl/datamodel_host.ml b/ocaml/idl/datamodel_host.ml index 5bb9887a046..76508745467 100644 --- a/ocaml/idl/datamodel_host.ml +++ b/ocaml/idl/datamodel_host.ml @@ -26,7 +26,16 @@ let api_version = ] let migrate_receive = - call ~in_oss_since:None ~in_product_since:rel_tampa ~name:"migrate_receive" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_tampa + , "Prepare to receive a VM, returning a token which can be passed to \ + VM.migrate." + ) + ] + ~name:"migrate_receive" ~doc: "Prepare to receive a VM, returning a token which can be passed to \ VM.migrate." @@ -44,7 +53,17 @@ let migrate_receive = ~allowed_roles:_R_VM_POWER_ADMIN () let ha_disable_failover_decisions = - call ~in_product_since:rel_orlando ~name:"ha_disable_failover_decisions" + call + ~lifecycle: + [ + ( Published + , rel_orlando + , "Prevents future failover decisions happening on this node. This \ + function should only be used as part of a controlled shutdown of \ + the HA system." + ) + ] + ~name:"ha_disable_failover_decisions" ~doc: "Prevents future failover decisions happening on this node. This \ function should only be used as part of a controlled shutdown of the HA \ @@ -54,7 +73,17 @@ let ha_disable_failover_decisions = () let ha_disarm_fencing = - call ~in_product_since:rel_orlando ~name:"ha_disarm_fencing" + call + ~lifecycle: + [ + ( Published + , rel_orlando + , "Disarms the fencing function of the HA subsystem. This function is \ + extremely dangerous and should only be used as part of a controlled \ + shutdown of the HA system." + ) + ] + ~name:"ha_disarm_fencing" ~doc: "Disarms the fencing function of the HA subsystem. This function is \ extremely dangerous and should only be used as part of a controlled \ @@ -64,7 +93,17 @@ let ha_disarm_fencing = () let ha_stop_daemon = - call ~in_product_since:rel_orlando ~name:"ha_stop_daemon" + call + ~lifecycle: + [ + ( Published + , rel_orlando + , "Stops the HA daemon. This function is extremely dangerous and \ + should only be used as part of a controlled shutdown of the HA \ + system." + ) + ] + ~name:"ha_stop_daemon" ~doc: "Stops the HA daemon. This function is extremely dangerous and should \ only be used as part of a controlled shutdown of the HA system." @@ -73,7 +112,16 @@ let ha_stop_daemon = () let ha_release_resources = - call ~in_product_since:rel_orlando ~name:"ha_release_resources" + call + ~lifecycle: + [ + ( Published + , rel_orlando + , "Cleans up any resources on the host associated with this HA \ + instance." + ) + ] + ~name:"ha_release_resources" ~doc:"Cleans up any resources on the host associated with this HA instance." ~params: [(Ref _host, "host", "The Host whose resources should be cleaned up")] @@ -81,7 +129,15 @@ let ha_release_resources = () let local_assert_healthy = - call ~flags:[`Session] ~in_product_since:rel_miami + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_miami + , "Returns nothing if this host is healthy, otherwise it throws an \ + error explaining why the host is unhealthy" + ) + ] ~name:"local_assert_healthy" ~doc: "Returns nothing if this host is healthy, otherwise it throws an error \ @@ -102,7 +158,16 @@ let local_assert_healthy = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let preconfigure_ha = - call ~in_product_since:rel_miami ~name:"preconfigure_ha" + call + ~lifecycle: + [ + ( Published + , rel_miami + , "Attach statefiles, generate config files but do not start the xHA \ + daemon." + ) + ] + ~name:"preconfigure_ha" ~doc: "Attach statefiles, generate config files but do not start the xHA \ daemon." @@ -117,14 +182,26 @@ let preconfigure_ha = () let ha_join_liveset = - call ~in_product_since:rel_orlando ~name:"ha_join_liveset" - ~doc:"Block until this host joins the liveset." + call + ~lifecycle: + [(Published, rel_orlando, "Block until this host joins the liveset.")] + ~name:"ha_join_liveset" ~doc:"Block until this host joins the liveset." ~params:[(Ref _host, "host", "The Host whose HA daemon to start")] ~pool_internal:true ~hide_from_docs:true ~allowed_roles:_R_LOCAL_ROOT_ONLY () let ha_wait_for_shutdown_via_statefile = - call ~in_product_since:rel_orlando ~name:"ha_wait_for_shutdown_via_statefile" + call + ~lifecycle: + [ + ( Published + , rel_orlando + , "Block until this host xHA daemon exits after having seen the \ + invalid statefile. If the host loses statefile access then throw an \ + exception" + ) + ] + ~name:"ha_wait_for_shutdown_via_statefile" ~doc: "Block until this host xHA daemon exits after having seen the invalid \ statefile. If the host loses statefile access then throw an exception" @@ -144,7 +221,9 @@ let host_query_ha = call ~flags:[`Session] () *) let request_backup = - call ~flags:[`Session] ~name:"request_backup" ~in_product_since:rel_rio + call ~flags:[`Session] ~name:"request_backup" + ~lifecycle: + [(Published, rel_rio, "Request this host performs a database backup")] ~doc:"Request this host performs a database backup" ~params: [ @@ -161,7 +240,9 @@ let request_backup = let request_config_file_sync = call ~flags:[`Session] ~name:"request_config_file_sync" - ~in_product_since:rel_rio ~doc:"Request this host syncs dom0 config files" + ~lifecycle: + [(Published, rel_rio, "Request this host syncs dom0 config files")] + ~doc:"Request this host syncs dom0 config files" ~params: [ (Ref _host, "host", "The Host to send the request to") @@ -173,7 +254,18 @@ let request_config_file_sync = (* Since there are no async versions, no tasks are generated (!) this is important otherwise the call would block doing a Db.Task.create *) let propose_new_master = - call ~flags:[`Session] ~in_product_since:rel_miami ~name:"propose_new_master" + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_miami + , "First phase of a two-phase commit protocol to set the new master. \ + If the host has already committed to another configuration or if \ + the proposed new master is not in this node's membership set then \ + the call will return an exception." + ) + ] + ~name:"propose_new_master" ~doc: "First phase of a two-phase commit protocol to set the new master. If \ the host has already committed to another configuration or if the \ @@ -195,8 +287,10 @@ let propose_new_master = () let abort_new_master = - call ~flags:[`Session] ~in_product_since:rel_miami ~name:"abort_new_master" - ~doc:"Causes the new master transaction to abort" + call ~flags:[`Session] + ~lifecycle: + [(Published, rel_miami, "Causes the new master transaction to abort")] + ~name:"abort_new_master" ~doc:"Causes the new master transaction to abort" ~params: [ ( String @@ -208,7 +302,15 @@ let abort_new_master = () let commit_new_master = - call ~flags:[`Session] ~in_product_since:rel_miami ~name:"commit_new_master" + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_miami + , "Second phase of a two-phase commit protocol to set the new master." + ) + ] + ~name:"commit_new_master" ~doc:"Second phase of a two-phase commit protocol to set the new master." ~params: [ @@ -221,7 +323,15 @@ let commit_new_master = () let compute_free_memory = - call ~in_product_since:rel_orlando ~name:"compute_free_memory" + call + ~lifecycle: + [ + ( Published + , rel_orlando + , "Computes the amount of free memory on the host." + ) + ] + ~name:"compute_free_memory" ~doc:"Computes the amount of free memory on the host." ~params:[(Ref _host, "host", "The host to send the request to")] ~pool_internal:false ~hide_from_docs:false @@ -229,7 +339,15 @@ let compute_free_memory = ~allowed_roles:_R_READ_ONLY ~doc_tags:[Memory] () let compute_memory_overhead = - call ~in_product_since:rel_midnight_ride ~name:"compute_memory_overhead" + call + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Computes the virtualization memory overhead of a host." + ) + ] + ~name:"compute_memory_overhead" ~doc:"Computes the virtualization memory overhead of a host." ~params: [(Ref _host, "host", "The host for which to compute the memory overhead")] @@ -239,7 +357,14 @@ let compute_memory_overhead = (* Diagnostics see if host is in emergency mode *) let is_in_emergency_mode = - call ~flags:[`Session] ~in_product_since:rel_miami + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_miami + , "Diagnostics call to discover if host is in emergency mode" + ) + ] ~name:"is_in_emergency_mode" ~doc:"Diagnostics call to discover if host is in emergency mode" ~params:[] ~pool_internal:false ~hide_from_docs:true @@ -248,7 +373,15 @@ let is_in_emergency_mode = (* Signal that the management IP address or hostname has been changed beneath us. *) let signal_networking_change = - call ~flags:[`Session] ~in_product_since:rel_miami + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_miami + , "Signals that the management IP address or hostname has been changed \ + beneath us." + ) + ] ~name:"signal_networking_change" ~doc: "Signals that the management IP address or hostname has been changed \ @@ -257,7 +390,9 @@ let signal_networking_change = ~doc_tags:[Networking] () let notify = - call ~in_product_since:rel_miami ~name:"notify" ~doc:"Notify an event" + call + ~lifecycle:[(Published, rel_miami, "Notify an event")] + ~name:"notify" ~doc:"Notify an event" ~params: [ (String, "ty", "type of the notification") @@ -267,8 +402,9 @@ let notify = () let syslog_reconfigure = - call ~in_product_since:rel_miami ~name:"syslog_reconfigure" - ~doc:"Re-configure syslog logging" + call + ~lifecycle:[(Published, rel_miami, "Re-configure syslog logging")] + ~name:"syslog_reconfigure" ~doc:"Re-configure syslog logging" ~params: [ ( Ref _host @@ -280,7 +416,10 @@ let syslog_reconfigure = ~allowed_roles:_R_POOL_OP () let management_reconfigure = - call ~in_product_since:rel_miami ~name:"management_reconfigure" + call + ~lifecycle: + [(Published, rel_miami, "Reconfigure the management network interface")] + ~name:"management_reconfigure" ~doc:"Reconfigure the management network interface" ~params: [ @@ -292,7 +431,16 @@ let management_reconfigure = ~allowed_roles:_R_POOL_OP ~doc_tags:[Networking] () let local_management_reconfigure = - call ~flags:[`Session] ~in_product_since:rel_miami + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_miami + , "Reconfigure the management network interface. Should only be used \ + if Host.management_reconfigure is impossible because the network \ + configuration is broken." + ) + ] ~name:"local_management_reconfigure" ~doc: "Reconfigure the management network interface. Should only be used if \ @@ -308,16 +456,25 @@ let local_management_reconfigure = ~allowed_roles:_R_POOL_OP () let ha_xapi_healthcheck = - call ~flags:[`Session] ~in_product_since:rel_orlando + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_orlando + , "Returns true if xapi appears to be functioning normally." + ) + ] ~name:"ha_xapi_healthcheck" ~doc:"Returns true if xapi appears to be functioning normally." ~result:(Bool, "true if xapi is functioning normally.") ~hide_from_docs:true ~allowed_roles:_R_POOL_ADMIN () let management_disable = - call ~flags:[`Session] ~in_product_since:rel_miami ~name:"management_disable" - ~doc:"Disable the management network interface" ~params:[] - ~allowed_roles:_R_POOL_OP ~doc_tags:[Networking] () + call ~flags:[`Session] + ~lifecycle: + [(Published, rel_miami, "Disable the management network interface")] + ~name:"management_disable" ~doc:"Disable the management network interface" + ~params:[] ~allowed_roles:_R_POOL_OP ~doc_tags:[Networking] () let get_management_interface = call @@ -333,15 +490,25 @@ let get_management_interface = Not intended for HA *) let assert_can_evacuate = - call ~in_product_since:rel_miami ~name:"assert_can_evacuate" - ~doc:"Check this host can be evacuated." + call + ~lifecycle:[(Published, rel_miami, "Check this host can be evacuated.")] + ~name:"assert_can_evacuate" ~doc:"Check this host can be evacuated." ~params:[(Ref _host, "host", "The host to evacuate")] ~allowed_roles:_R_POOL_OP () (* New Orlando message which aims to make the GUI less brittle (unexpected errors will trigger a VM suspend) and sensitive to HA planning constraints *) let get_vms_which_prevent_evacuation = - call ~in_product_since:rel_orlando ~name:"get_vms_which_prevent_evacuation" + call + ~lifecycle: + [ + ( Published + , rel_orlando + , "Return a set of VMs which prevent the host being evacuated, with \ + per-VM error codes" + ) + ] + ~name:"get_vms_which_prevent_evacuation" ~doc: "Return a set of VMs which prevent the host being evacuated, with per-VM \ error codes" @@ -353,8 +520,7 @@ let get_vms_which_prevent_evacuation = ~allowed_roles:_R_READ_ONLY () let evacuate = - call ~in_product_since:rel_miami ~name:"evacuate" - ~doc:"Migrate all VMs off of this host, where possible." + call ~name:"evacuate" ~doc:"Migrate all VMs off of this host, where possible." ~lifecycle: [ (Published, rel_miami, "") @@ -391,7 +557,16 @@ let evacuate = () let get_uncooperative_resident_VMs = - call ~in_product_since:rel_midnight_ride ~internal_deprecated_since:rel_tampa + call + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Return a set of VMs which are not co-operating with the host's \ + memory control system" + ) + ; (Deprecated, rel_tampa, "") + ] ~name:"get_uncooperative_resident_VMs" ~doc: "Return a set of VMs which are not co-operating with the host's memory \ @@ -401,7 +576,16 @@ let get_uncooperative_resident_VMs = ~allowed_roles:_R_READ_ONLY () let get_uncooperative_domains = - call ~in_product_since:rel_midnight_ride ~internal_deprecated_since:rel_tampa + call + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Return the set of domain uuids which are not co-operating with the \ + host's memory control system" + ) + ; (Deprecated, rel_tampa, "") + ] ~name:"get_uncooperative_domains" ~doc: "Return the set of domain uuids which are not co-operating with the \ @@ -413,7 +597,15 @@ let get_uncooperative_domains = let retrieve_wlb_evacuate_recommendations = call ~name:"retrieve_wlb_evacuate_recommendations" - ~in_product_since:rel_george + ~lifecycle: + [ + ( Published + , rel_george + , "Retrieves recommended host migrations to perform when evacuating \ + the host from the wlb server. If a VM cannot be migrated from the \ + host the reason is listed instead of a recommendation." + ) + ] ~doc: "Retrieves recommended host migrations to perform when evacuating the \ host from the wlb server. If a VM cannot be migrated from the host the \ @@ -429,7 +621,16 @@ let retrieve_wlb_evacuate_recommendations = (* Host.Disable *) let disable = - call ~in_product_since:rel_rio ~name:"disable" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Puts the host into a state in which no new VMs can be started. \ + Currently active VMs on the host continue to execute." + ) + ] + ~name:"disable" ~doc: "Puts the host into a state in which no new VMs can be started. \ Currently active VMs on the host continue to execute." @@ -440,7 +641,14 @@ let disable = (* Host.Enable *) let enable = - call ~name:"enable" ~in_product_since:rel_rio + call ~name:"enable" + ~lifecycle: + [ + ( Published + , rel_rio + , "Puts the host into a state in which new VMs can be started." + ) + ] ~doc:"Puts the host into a state in which new VMs can be started." ~params:[(Ref _host, "host", "The Host to enable")] ~allowed_roles:(_R_POOL_OP ++ _R_CLIENT_CERT) @@ -449,7 +657,15 @@ let enable = (* Host.Shutdown *) let shutdown = - call ~name:"shutdown" ~in_product_since:rel_rio + call ~name:"shutdown" + ~lifecycle: + [ + ( Published + , rel_rio + , "Shutdown the host. (This function can only be called if there are \ + no currently running VMs on the host and it is disabled.)" + ) + ] ~doc: "Shutdown the host. (This function can only be called if there are no \ currently running VMs on the host and it is disabled.)" @@ -459,7 +675,15 @@ let shutdown = (* Host.reboot *) let reboot = - call ~name:"reboot" ~in_product_since:rel_rio + call ~name:"reboot" + ~lifecycle: + [ + ( Published + , rel_rio + , "Reboot the host. (This function can only be called if there are no \ + currently running VMs on the host and it is disabled.)" + ) + ] ~doc: "Reboot the host. (This function can only be called if there are no \ currently running VMs on the host and it is disabled.)" @@ -469,7 +693,14 @@ let reboot = (* Host.prepare_for_poweroff *) let prepare_for_poweroff = - call ~name:"prepare_for_poweroff" ~in_product_since:rel_kolkata + call ~name:"prepare_for_poweroff" + ~lifecycle: + [ + ( Published + , rel_kolkata + , "Performs the necessary actions before host shutdown or reboot." + ) + ] ~doc:"Performs the necessary actions before host shutdown or reboot." ~params: [(Ref _host, "host", "The Host that is about to reboot or shutdown")] @@ -478,13 +709,31 @@ let prepare_for_poweroff = (* Host.power_on *) let power_on = - call ~name:"power_on" ~in_product_since:rel_orlando + call ~name:"power_on" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Attempt to power-on the host (if the capability exists)." + ) + ] ~doc:"Attempt to power-on the host (if the capability exists)." ~params:[(Ref _host, "host", "The Host to power on")] ~allowed_roles:_R_POOL_OP () let restart_agent = - call ~name:"restart_agent" ~in_product_since:rel_rio + call ~name:"restart_agent" + ~lifecycle: + [ + ( Published + , rel_rio + , "Restarts the agent after a 10 second pause. WARNING: this is a \ + dangerous operation. Any operations in progress will be aborted, \ + and unrecoverable data loss may occur. The caller is responsible \ + for ensuring that there are no operations in progress when this \ + method is called." + ) + ] ~doc: "Restarts the agent after a 10 second pause. WARNING: this is a \ dangerous operation. Any operations in progress will be aborted, and \ @@ -496,7 +745,18 @@ let restart_agent = ~allowed_roles:_R_POOL_OP () let shutdown_agent = - call ~name:"shutdown_agent" ~in_product_since:rel_orlando + call ~name:"shutdown_agent" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Shuts the agent down after a 10 second pause. WARNING: this is a \ + dangerous operation. Any operations in progress will be aborted, \ + and unrecoverable data loss may occur. The caller is responsible \ + for ensuring that there are no operations in progress when this \ + method is called." + ) + ] ~doc: "Shuts the agent down after a 10 second pause. WARNING: this is a \ dangerous operation. Any operations in progress will be aborted, and \ @@ -507,31 +767,45 @@ let shutdown_agent = ~allowed_roles:_R_POOL_OP () let dmesg = - call ~name:"dmesg" ~in_product_since:rel_rio ~doc:"Get the host xen dmesg." + call ~name:"dmesg" + ~lifecycle:[(Published, rel_rio, "Get the host xen dmesg.")] + ~doc:"Get the host xen dmesg." ~params:[(Ref _host, "host", "The Host to query")] ~result:(String, "dmesg string") ~allowed_roles:_R_POOL_OP () let dmesg_clear = - call ~name:"dmesg_clear" ~in_product_since:rel_rio + call ~name:"dmesg_clear" + ~lifecycle: + [(Published, rel_rio, "Get the host xen dmesg, and clear the buffer.")] ~doc:"Get the host xen dmesg, and clear the buffer." ~params:[(Ref _host, "host", "The Host to query")] ~result:(String, "dmesg string") ~allowed_roles:_R_POOL_OP () let get_log = - call ~name:"get_log" ~in_product_since:rel_rio ~doc:"Get the host's log file" + call ~name:"get_log" + ~lifecycle:[(Published, rel_rio, "Get the host's log file")] + ~doc:"Get the host's log file" ~params:[(Ref _host, "host", "The Host to query")] ~result:(String, "The contents of the host's primary log file") ~allowed_roles:_R_READ_ONLY () let send_debug_keys = - call ~name:"send_debug_keys" ~in_product_since:rel_rio + call ~name:"send_debug_keys" + ~lifecycle: + [ + ( Published + , rel_rio + , "Inject the given string as debugging keys into Xen" + ) + ] ~doc:"Inject the given string as debugging keys into Xen" ~params: [(Ref _host, "host", "The host"); (String, "keys", "The keys to send")] ~allowed_roles:_R_POOL_ADMIN () let get_data_sources = - call ~name:"get_data_sources" ~in_oss_since:None ~in_product_since:rel_orlando + call ~name:"get_data_sources" ~in_oss_since:None + ~lifecycle:[(Published, rel_orlando, "")] ~doc:"" ~result:(Set (Record _data_source), "A set of data sources") ~params:[(Ref _host, "host", "The host to interrogate")] @@ -539,7 +813,8 @@ let get_data_sources = let record_data_source = call ~name:"record_data_source" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [(Published, rel_orlando, "Start recording the specified data source")] ~doc:"Start recording the specified data source" ~params: [ @@ -550,7 +825,13 @@ let record_data_source = let query_data_source = call ~name:"query_data_source" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Query the latest value of the specified data source" + ) + ] ~doc:"Query the latest value of the specified data source" ~params: [ @@ -561,7 +842,9 @@ let query_data_source = ~errs:[] ~flags:[`Session] ~allowed_roles:_R_READ_ONLY () let attach_static_vdis = - call ~name:"attach_static_vdis" ~in_product_since:rel_midnight_ride + call ~name:"attach_static_vdis" + ~lifecycle: + [(Published, rel_midnight_ride, "Statically attach VDIs on a host.")] ~doc:"Statically attach VDIs on a host." ~params: [ @@ -575,7 +858,9 @@ let attach_static_vdis = () let detach_static_vdis = - call ~name:"detach_static_vdis" ~in_product_since:rel_midnight_ride + call ~name:"detach_static_vdis" + ~lifecycle: + [(Published, rel_midnight_ride, "Detach static VDIs from a host.")] ~doc:"Detach static VDIs from a host." ~params: [ @@ -586,7 +871,16 @@ let detach_static_vdis = () let declare_dead = - call ~name:"declare_dead" ~in_product_since:rel_clearwater + call ~name:"declare_dead" + ~lifecycle: + [ + ( Published + , rel_clearwater + , "Declare that a host is dead. This is a dangerous operation, and \ + should only be called if the administrator is absolutely sure the \ + host is definitely dead" + ) + ] ~doc: "Declare that a host is dead. This is a dangerous operation, and should \ only be called if the administrator is absolutely sure the host is \ @@ -596,7 +890,13 @@ let declare_dead = let forget_data_source_archives = call ~name:"forget_data_source_archives" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Forget the recorded statistics related to the specified data source" + ) + ] ~doc:"Forget the recorded statistics related to the specified data source" ~params: [ @@ -609,7 +909,14 @@ let forget_data_source_archives = ~flags:[`Session] ~allowed_roles:_R_POOL_OP () let get_diagnostic_timing_stats = - call ~flags:[`Session] ~in_product_since:rel_miami + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_miami + , "Return timing statistics for diagnostic purposes" + ) + ] ~name:"get_diagnostic_timing_stats" ~doc:"Return timing statistics for diagnostic purposes" ~params:[(Ref _host, "host", "The host to interrogate")] @@ -617,7 +924,15 @@ let get_diagnostic_timing_stats = ~hide_from_docs:true ~allowed_roles:_R_READ_ONLY () let create_new_blob = - call ~name:"create_new_blob" ~in_product_since:rel_orlando + call ~name:"create_new_blob" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Create a placeholder for a named binary blob of data that is \ + associated with this host" + ) + ] ~doc: "Create a placeholder for a named binary blob of data that is associated \ with this host" @@ -659,7 +974,8 @@ let create_new_blob = ~allowed_roles:_R_POOL_OP () let call_plugin = - call ~name:"call_plugin" ~in_product_since:rel_orlando + call ~name:"call_plugin" + ~lifecycle:[(Published, rel_orlando, "Call an API plugin on this host")] ~doc:"Call an API plugin on this host" ~params: [ @@ -672,7 +988,14 @@ let call_plugin = ~allowed_roles:_R_POOL_ADMIN () let has_extension = - call ~name:"has_extension" ~in_product_since:rel_ely + call ~name:"has_extension" + ~lifecycle: + [ + ( Published + , rel_ely + , "Return true if the extension is available on the host" + ) + ] ~doc:"Return true if the extension is available on the host" ~params: [ @@ -683,8 +1006,9 @@ let has_extension = ~allowed_roles:_R_POOL_ADMIN () let call_extension = - call ~name:"call_extension" ~in_product_since:rel_ely ~custom_marshaller:true - ~doc:"Call an API extension on this host" + call ~name:"call_extension" + ~lifecycle:[(Published, rel_ely, "Call an API extension on this host")] + ~custom_marshaller:true ~doc:"Call an API extension on this host" ~params: [ (Ref _host, "host", "The host") @@ -695,7 +1019,15 @@ let call_extension = () let enable_binary_storage = - call ~name:"enable_binary_storage" ~in_product_since:rel_orlando + call ~name:"enable_binary_storage" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Enable binary storage on a particular host, for storing RRDs, \ + messages and blobs" + ) + ] ~hide_from_docs:true ~pool_internal:true ~doc: "Enable binary storage on a particular host, for storing RRDs, messages \ @@ -704,7 +1036,15 @@ let enable_binary_storage = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let disable_binary_storage = - call ~name:"disable_binary_storage" ~in_product_since:rel_orlando + call ~name:"disable_binary_storage" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Disable binary storage on a particular host, deleting stored RRDs, \ + messages and blobs" + ) + ] ~hide_from_docs:true ~pool_internal:true ~doc: "Disable binary storage on a particular host, deleting stored RRDs, \ @@ -713,7 +1053,8 @@ let disable_binary_storage = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let update_pool_secret = - call ~name:"update_pool_secret" ~in_product_since:rel_midnight_ride + call ~name:"update_pool_secret" + ~lifecycle:[(Published, rel_midnight_ride, "")] ~hide_from_docs:true ~pool_internal:true ~doc:"" ~params: [ @@ -723,7 +1064,8 @@ let update_pool_secret = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let update_master = - call ~name:"update_master" ~in_product_since:rel_midnight_ride + call ~name:"update_master" + ~lifecycle:[(Published, rel_midnight_ride, "")] ~hide_from_docs:true ~pool_internal:true ~doc:"" ~params: [ @@ -733,7 +1075,9 @@ let update_master = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let set_localdb_key = - call ~name:"set_localdb_key" ~in_product_since:rel_midnight_ride + call ~name:"set_localdb_key" + ~lifecycle: + [(Published, rel_midnight_ride, "Set a key in the local DB of the host.")] ~doc:"Set a key in the local DB of the host." ~params: [ @@ -759,7 +1103,14 @@ let refresh_pack_info = let bugreport_upload = call ~name:"bugreport_upload" ~doc:"Run xen-bugtool --yestoall and upload the output to support" - ~in_oss_since:None ~in_product_since:rel_rio + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Run xen-bugtool --yestoall and upload the output to support" + ) + ] ~params: [ (Ref _host, "host", "The host on which to run xen-bugtool") @@ -769,8 +1120,9 @@ let bugreport_upload = ~allowed_roles:_R_POOL_OP () let list_methods = - call ~name:"list_methods" ~in_product_since:rel_rio ~flags:[`Session] - ~doc:"List all supported methods" ~params:[] + call ~name:"list_methods" + ~lifecycle:[(Published, rel_rio, "List all supported methods")] + ~flags:[`Session] ~doc:"List all supported methods" ~params:[] ~result:(Set String, "The name of every supported method.") ~allowed_roles:_R_READ_ONLY () @@ -946,20 +1298,24 @@ let create_params = ] let create = - call ~name:"create" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"create" ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Create a new host record")] ~versioned_params:create_params ~doc:"Create a new host record" ~result:(Ref _host, "Reference to the newly created host object.") ~hide_from_docs:true ~allowed_roles:_R_POOL_OP () let destroy = - call ~name:"destroy" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"destroy" ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Destroy specified host record in database")] ~doc:"Destroy specified host record in database" ~params:[(Ref _host, "self", "The host record to remove")] ~allowed_roles:_R_POOL_OP () let get_system_status_capabilities = call ~flags:[`Session] ~name:"get_system_status_capabilities" - ~in_oss_since:None ~in_product_since:rel_miami + ~in_oss_since:None + ~lifecycle:[(Published, rel_miami, "")] ~params:[(Ref _host, "host", "The host to interrogate")] ~doc:"" ~result: @@ -968,7 +1324,14 @@ let get_system_status_capabilities = let set_hostname_live = call ~flags:[`Session] ~name:"set_hostname_live" ~in_oss_since:None - ~in_product_since:rel_miami + ~lifecycle: + [ + ( Published + , rel_miami + , "Sets the host name to the specified string. Both the API and \ + lower-level system hostname are changed immediately." + ) + ] ~params: [ (Ref _host, "host", "The host whose host name to set") @@ -982,7 +1345,14 @@ let set_hostname_live = let tickle_heartbeat = call ~flags:[`Session] ~name:"tickle_heartbeat" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Needs to be called every 30 seconds for the master to believe the \ + host is alive" + ) + ] ~params: [ ( Ref _host @@ -1003,7 +1373,15 @@ let tickle_heartbeat = let sync_data = call ~flags:[`Session] ~name:"sync_data" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "This causes the synchronisation of the non-database data (messages, \ + RRDs and so on) stored on the master to be synchronised with the \ + host" + ) + ] ~params:[(Ref _host, "host", "The host to whom the data should be sent")] ~doc: "This causes the synchronisation of the non-database data (messages, \ @@ -1012,7 +1390,13 @@ let sync_data = let backup_rrds = call ~flags:[`Session] ~name:"backup_rrds" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "This causes the RRDs to be backed up to the master" + ) + ] ~params: [ (Ref _host, "host", "Schedule a backup of the RRDs of this host") @@ -1027,7 +1411,13 @@ let backup_rrds = let get_servertime = call ~flags:[`Session] ~name:"get_servertime" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "This call queries the host's clock for the current time" + ) + ] ~params:[(Ref _host, "host", "The host whose clock should be queried")] ~doc:"This call queries the host's clock for the current time" ~result:(DateTime, "The current time") @@ -1035,7 +1425,14 @@ let get_servertime = let get_server_localtime = call ~flags:[`Session] ~name:"get_server_localtime" ~in_oss_since:None - ~in_product_since:rel_cowley + ~lifecycle: + [ + ( Published + , rel_cowley + , "This call queries the host's clock for the current time in the \ + host's local timezone" + ) + ] ~params:[(Ref _host, "host", "The host whose clock should be queried")] ~doc: "This call queries the host's clock for the current time in the host's \ @@ -1045,7 +1442,14 @@ let get_server_localtime = let emergency_ha_disable = call ~flags:[`Session] ~name:"emergency_ha_disable" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "This call disables HA on the local host. This should only be used \ + with extreme care." + ) + ] ~versioned_params: [ { @@ -1101,8 +1505,15 @@ let certificate_list = () let crl_install = - call ~in_oss_since:None ~in_product_since:rel_george ~pool_internal:true - ~hide_from_docs:true ~name:"crl_install" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "Install a TLS CA-issued Certificate Revocation List to this host." + ) + ] + ~pool_internal:true ~hide_from_docs:true ~name:"crl_install" ~doc:"Install a TLS CA-issued Certificate Revocation List to this host." ~params: [ @@ -1113,15 +1524,31 @@ let crl_install = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let crl_uninstall = - call ~in_oss_since:None ~in_product_since:rel_george ~pool_internal:true - ~hide_from_docs:true ~name:"crl_uninstall" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "Uninstall a TLS CA-issued certificate revocation list from this \ + host." + ) + ] + ~pool_internal:true ~hide_from_docs:true ~name:"crl_uninstall" ~doc:"Uninstall a TLS CA-issued certificate revocation list from this host." ~params:[(Ref _host, "host", "The host"); (String, "name", "The CRL name")] ~allowed_roles:_R_LOCAL_ROOT_ONLY () let crl_list = - call ~in_oss_since:None ~in_product_since:rel_george ~pool_internal:true - ~hide_from_docs:true ~name:"crl_list" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "List the filenames of all installed TLS CA-issued Certificate \ + Revocation Lists." + ) + ] + ~pool_internal:true ~hide_from_docs:true ~name:"crl_list" ~doc: "List the filenames of all installed TLS CA-issued Certificate \ Revocation Lists." @@ -1130,8 +1557,16 @@ let crl_list = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let certificate_sync = - call ~in_oss_since:None ~in_product_since:rel_george ~pool_internal:true - ~hide_from_docs:true ~name:"certificate_sync" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "Make installed TLS CA certificates and CRLs available to all \ + programs using OpenSSL." + ) + ] + ~pool_internal:true ~hide_from_docs:true ~name:"certificate_sync" ~doc: "Make installed TLS CA certificates and CRLs available to all programs \ using OpenSSL." @@ -1273,7 +1708,13 @@ let operations = let enable_external_auth = call ~flags:[`Session] ~name:"enable_external_auth" ~in_oss_since:None - ~in_product_since:rel_george + ~lifecycle: + [ + ( Published + , rel_george + , "This call enables external authentication on a host" + ) + ] ~params: [ ( Ref _host @@ -1295,7 +1736,13 @@ let enable_external_auth = let disable_external_auth = call ~flags:[`Session] ~name:"disable_external_auth" ~in_oss_since:None - ~in_product_since:rel_george + ~lifecycle: + [ + ( Published + , rel_george + , "This call disables external authentication on the local host" + ) + ] ~versioned_params: [ { @@ -1320,7 +1767,15 @@ let disable_external_auth = let set_license_params = call ~name:"set_license_params" - ~in_product_since:rel_orlando (* actually update 3 aka floodgate *) + ~lifecycle: + [ + ( Published + , rel_orlando + , "Set the new license details in the database, trigger a \ + recomputation of the pool SKU" + ) + ] + (* actually update 3 aka floodgate *) ~doc: "Set the new license details in the database, trigger a recomputation of \ the pool SKU" @@ -1334,7 +1789,15 @@ let set_license_params = let apply_edition = call ~flags:[`Session] ~name:"apply_edition" - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Change to another edition, or reactivate the current edition after \ + a license has expired. This may be subject to the successful \ + checkout of an appropriate license." + ) + ] ~doc: "Change to another edition, or reactivate the current edition after a \ license has expired. This may be subject to the successful checkout of \ @@ -1373,7 +1836,6 @@ let set_power_on_mode = ; (Changed, rel_stockholm, "Removed iLO script") ; (Changed, "24.19.0", "Replaced DRAC mode with IPMI") ] - ~in_product_since:rel_midnight_ride ~doc:"Set the power-on-mode, host, user and password" ~params: [ @@ -1453,7 +1915,13 @@ let reset_networking = let enable_local_storage_caching = call ~flags:[`Session] ~name:"enable_local_storage_caching" - ~in_product_since:rel_cowley + ~lifecycle: + [ + ( Published + , rel_cowley + , "Enable the use of a local SR for caching purposes" + ) + ] ~doc:"Enable the use of a local SR for caching purposes" ~params: [ @@ -1464,13 +1932,20 @@ let enable_local_storage_caching = let disable_local_storage_caching = call ~flags:[`Session] ~name:"disable_local_storage_caching" - ~in_product_since:rel_cowley + ~lifecycle: + [ + ( Published + , rel_cowley + , "Disable the use of a local SR for caching purposes" + ) + ] ~doc:"Disable the use of a local SR for caching purposes" ~params:[(Ref _host, "host", "The host")] ~allowed_roles:_R_POOL_OP () let get_sm_diagnostics = - call ~flags:[`Session] ~name:"get_sm_diagnostics" ~in_product_since:rel_boston + call ~flags:[`Session] ~name:"get_sm_diagnostics" + ~lifecycle:[(Published, rel_boston, "Return live SM diagnostics")] ~doc:"Return live SM diagnostics" ~params:[(Ref _host, "host", "The host")] ~result:(String, "Printable diagnostic data") @@ -1478,13 +1953,21 @@ let get_sm_diagnostics = let get_thread_diagnostics = call ~flags:[`Session] ~name:"get_thread_diagnostics" - ~in_product_since:rel_boston ~doc:"Return live thread diagnostics" + ~lifecycle:[(Published, rel_boston, "Return live thread diagnostics")] + ~doc:"Return live thread diagnostics" ~params:[(Ref _host, "host", "The host")] ~result:(String, "Printable diagnostic data") ~allowed_roles:_R_POOL_OP ~hide_from_docs:true () let sm_dp_destroy = - call ~flags:[`Session] ~name:"sm_dp_destroy" ~in_product_since:rel_boston + call ~flags:[`Session] ~name:"sm_dp_destroy" + ~lifecycle: + [ + ( Published + , rel_boston + , "Attempt to cleanup and destroy a named SM datapath" + ) + ] ~doc:"Attempt to cleanup and destroy a named SM datapath" ~params: [ @@ -1751,7 +2234,8 @@ let emergency_reenable_tls_verification = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let apply_updates = - call ~name:"apply_updates" ~in_oss_since:None ~in_product_since:"1.301.0" + call ~name:"apply_updates" ~in_oss_since:None + ~lifecycle:[(Published, "1.301.0", "")] ~doc:"apply updates from current enabled repository on a host" ~params: [ @@ -1772,7 +2256,7 @@ let apply_updates = let copy_primary_host_certs = call ~name:"copy_primary_host_certs" ~in_oss_since:None - ~in_product_since:"1.307.0" + ~lifecycle:[(Published, "1.307.0", "")] ~doc:"useful for secondary hosts that are missing some certs" ~params: [ diff --git a/ocaml/idl/datamodel_pool.ml b/ocaml/idl/datamodel_pool.ml index f55f98d47ac..d13858363ab 100644 --- a/ocaml/idl/datamodel_pool.ml +++ b/ocaml/idl/datamodel_pool.ml @@ -62,7 +62,9 @@ let telemetry_frequency = ) let enable_ha = - call ~in_product_since:rel_miami ~name:"enable_ha" ~in_oss_since:None + call + ~lifecycle:[(Published, rel_miami, "Turn on High Availability mode")] + ~name:"enable_ha" ~in_oss_since:None ~versioned_params: [ { @@ -85,19 +87,30 @@ let enable_ha = () let disable_ha = - call ~in_product_since:rel_miami ~name:"disable_ha" ~in_oss_since:None - ~params:[] ~doc:"Turn off High Availability mode" + call + ~lifecycle:[(Published, rel_miami, "Turn off High Availability mode")] + ~name:"disable_ha" ~in_oss_since:None ~params:[] + ~doc:"Turn off High Availability mode" ~allowed_roles:(_R_POOL_OP ++ _R_CLIENT_CERT) () let sync_database = - call ~name:"sync_database" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"sync_database" ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Forcibly synchronise the database now")] ~params:[] ~doc:"Forcibly synchronise the database now" ~allowed_roles:_R_POOL_OP () let designate_new_master = - call ~in_product_since:rel_miami ~name:"designate_new_master" - ~in_oss_since:None + call + ~lifecycle: + [ + ( Published + , rel_miami + , "Perform an orderly handover of the role of master to the referenced \ + host." + ) + ] + ~name:"designate_new_master" ~in_oss_since:None ~params:[(Ref _host, "host", "The host who should become the new master")] ~doc: "Perform an orderly handover of the role of master to the referenced \ @@ -105,7 +118,8 @@ let designate_new_master = ~allowed_roles:_R_POOL_OP () let join = - call ~name:"join" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"join" ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Instruct host to join a new pool")] ~params: [ ( String @@ -125,7 +139,8 @@ let join = ~doc:"Instruct host to join a new pool" ~allowed_roles:_R_POOL_OP () let join_force = - call ~name:"join_force" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"join_force" ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Instruct host to join a new pool")] ~params: [ ( String @@ -148,7 +163,7 @@ let certs = Map (String, String) let exchange_certificates_on_join = call ~name:"exchange_certificates_on_join" ~in_oss_since:None - ~in_product_since:"1.298.0" + ~lifecycle:[(Published, "1.298.0", "")] ~params: [ (String, "uuid", "The uuid of the joining host") @@ -162,7 +177,7 @@ let exchange_certificates_on_join = let exchange_ca_certificates_on_join = call ~name:"exchange_ca_certificates_on_join" ~in_oss_since:None - ~in_product_since:"1.320.0" + ~lifecycle:[(Published, "1.320.0", "")] ~params: [ (certs, "import", "The CA certificates that are to be installed") @@ -179,19 +194,41 @@ let exchange_ca_certificates_on_join = let slave_reset_master = call ~flags:[`Session] ~name:"emergency_reset_master" ~in_oss_since:None - ~in_product_since:rel_rio + ~lifecycle: + [ + ( Published + , rel_rio + , "Instruct a slave already in a pool that the master has changed" + ) + ] ~params:[(String, "master_address", "The hostname of the master")] ~doc:"Instruct a slave already in a pool that the master has changed" ~allowed_roles:_R_POOL_OP () let transition_to_master = call ~flags:[`Session] ~name:"emergency_transition_to_master" - ~in_oss_since:None ~in_product_since:rel_rio ~params:[] + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Instruct host that's currently a slave to transition to being master" + ) + ] + ~params:[] ~doc:"Instruct host that's currently a slave to transition to being master" ~allowed_roles:_R_POOL_OP () let recover_slaves = - call ~name:"recover_slaves" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"recover_slaves" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Instruct a pool master, M, to try and contact its slaves and, if \ + slaves are in emergency mode, reset their master address to M." + ) + ] ~params:[] ~result: ( Set (Ref _host) @@ -203,18 +240,29 @@ let recover_slaves = ~allowed_roles:_R_POOL_OP () let eject = - call ~name:"eject" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"eject" ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Instruct a pool master to eject a host from the pool" + ) + ] ~params:[(Ref _host, "host", "The host to eject")] ~doc:"Instruct a pool master to eject a host from the pool" ~allowed_roles:_R_POOL_OP () let initial_auth = - call ~name:"initial_auth" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"initial_auth" ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Internal use only")] ~params:[] ~result:(SecretString, "") ~doc:"Internal use only" ~hide_from_docs:true ~allowed_roles:_R_POOL_OP () let create_VLAN_from_PIF = - call ~in_oss_since:None ~in_product_since:rel_rio ~name:"create_VLAN_from_PIF" + call ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Create a pool-wide VLAN by taking the PIF.")] + ~name:"create_VLAN_from_PIF" ~doc:"Create a pool-wide VLAN by taking the PIF." ~params: [ @@ -236,7 +284,17 @@ let create_VLAN_from_PIF = (* !! THIS IS BROKEN; it takes a device name which in the case of a bond is not homogeneous across all pool hosts. See CA-22613. !! *) let create_VLAN = - call ~in_oss_since:None ~in_product_since:rel_rio ~name:"create_VLAN" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Create PIFs, mapping a network to the same physical interface/VLAN \ + on each host. This call is deprecated: use \ + Pool.create_VLAN_from_PIF instead." + ) + ] + ~name:"create_VLAN" ~doc: "Create PIFs, mapping a network to the same physical interface/VLAN on \ each host. This call is deprecated: use Pool.create_VLAN_from_PIF \ @@ -259,7 +317,14 @@ let create_VLAN = let management_reconfigure = call ~name:"management_reconfigure" ~in_oss_since:None - ~in_product_since:rel_inverness + ~lifecycle: + [ + ( Published + , rel_inverness + , "Reconfigure the management network interface for all Hosts in the \ + Pool" + ) + ] ~params:[(Ref _network, "network", "The network")] ~doc: "Reconfigure the management network interface for all Hosts in the Pool" @@ -281,14 +346,15 @@ let hello_return = ) let hello = - call ~name:"hello" ~in_oss_since:None ~in_product_since:rel_rio + call ~name:"hello" ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Internal use only")] ~params:[(String, "host_uuid", ""); (String, "host_address", "")] ~result:(hello_return, "") ~doc:"Internal use only" ~hide_from_docs:true ~allowed_roles:_R_POOL_OP () let ping_slave = call ~flags:[`Session] ~name:"is_slave" ~in_oss_since:None - ~in_product_since:rel_rio + ~lifecycle:[(Published, rel_rio, "Internal use only")] ~params:[(Ref _host, "host", "")] ~doc:"Internal use only" ~result: @@ -300,7 +366,15 @@ let ping_slave = let ha_prevent_restarts_for = call ~flags:[`Session] ~name:"ha_prevent_restarts_for" - ~in_product_since:rel_orlando_update_1 + ~lifecycle: + [ + ( Published + , rel_orlando_update_1 + , "When this call returns the VM restart logic will not run for the \ + requested number of seconds. If the argument is zero then the \ + restart thread is immediately unblocked" + ) + ] ~doc: "When this call returns the VM restart logic will not run for the \ requested number of seconds. If the argument is zero then the restart \ @@ -313,7 +387,14 @@ let ha_prevent_restarts_for = let ha_failover_plan_exists = call ~flags:[`Session] ~name:"ha_failover_plan_exists" - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Returns true if a VM failover plan exists for up to 'n' host \ + failures" + ) + ] ~doc:"Returns true if a VM failover plan exists for up to 'n' host failures" ~params:[(Int, "n", "The number of host failures to plan for")] ~result: @@ -325,7 +406,14 @@ let ha_failover_plan_exists = let ha_compute_max_host_failures_to_tolerate = call ~flags:[`Session] ~name:"ha_compute_max_host_failures_to_tolerate" - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Returns the maximum number of host failures we could tolerate \ + before we would be unable to restart configured VMs" + ) + ] ~doc: "Returns the maximum number of host failures we could tolerate before we \ would be unable to restart configured VMs" @@ -340,7 +428,14 @@ let ha_compute_max_host_failures_to_tolerate = let ha_compute_hypothetical_max_host_failures_to_tolerate = call ~flags:[`Session] ~name:"ha_compute_hypothetical_max_host_failures_to_tolerate" - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Returns the maximum number of host failures we could tolerate \ + before we would be unable to restart the provided VMs" + ) + ] ~doc: "Returns the maximum number of host failures we could tolerate before we \ would be unable to restart the provided VMs" @@ -360,7 +455,13 @@ let ha_compute_hypothetical_max_host_failures_to_tolerate = let ha_compute_vm_failover_plan = call ~flags:[`Session] ~name:"ha_compute_vm_failover_plan" - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Return a VM failover plan assuming a given subset of hosts fail" + ) + ] ~doc:"Return a VM failover plan assuming a given subset of hosts fail" ~params: [ @@ -377,7 +478,15 @@ let ha_compute_vm_failover_plan = ~allowed_roles:_R_POOL_OP () let create_new_blob = - call ~name:"create_new_blob" ~in_product_since:rel_orlando + call ~name:"create_new_blob" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Create a placeholder for a named binary blob of data that is \ + associated with this pool" + ) + ] ~doc: "Create a placeholder for a named binary blob of data that is associated \ with this pool" @@ -419,7 +528,15 @@ let create_new_blob = ~allowed_roles:_R_POOL_OP () let set_ha_host_failures_to_tolerate = - call ~name:"set_ha_host_failures_to_tolerate" ~in_product_since:rel_orlando + call ~name:"set_ha_host_failures_to_tolerate" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Set the maximum number of host failures to consider in the HA VM \ + restart planner" + ) + ] ~doc: "Set the maximum number of host failures to consider in the HA VM \ restart planner" @@ -431,13 +548,29 @@ let set_ha_host_failures_to_tolerate = ~allowed_roles:_R_POOL_OP () let ha_schedule_plan_recomputation = - call ~name:"ha_schedule_plan_recomputation" ~in_product_since:rel_orlando + call ~name:"ha_schedule_plan_recomputation" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Signal that the plan should be recomputed (eg a host has come \ + online)" + ) + ] ~doc:"Signal that the plan should be recomputed (eg a host has come online)" ~params:[] ~hide_from_docs:true ~pool_internal:true ~allowed_roles:_R_LOCAL_ROOT_ONLY () let enable_binary_storage = - call ~name:"enable_binary_storage" ~in_product_since:rel_orlando + call ~name:"enable_binary_storage" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Enable the storage of larger objects, such as RRDs, messages and \ + binary blobs across all hosts in the pool" + ) + ] ~hide_from_docs:true ~doc: "Enable the storage of larger objects, such as RRDs, messages and binary \ @@ -445,7 +578,16 @@ let enable_binary_storage = ~params:[] ~allowed_roles:_R_POOL_OP () let disable_binary_storage = - call ~name:"disable_binary_storage" ~in_product_since:rel_orlando + call ~name:"disable_binary_storage" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Disable the storage of larger objects, such as RRDs, messages and \ + binary blobs across all hosts in the pool. This will destroy all of \ + these objects where they exist." + ) + ] ~hide_from_docs:true ~doc: "Disable the storage of larger objects, such as RRDs, messages and \ @@ -455,7 +597,14 @@ let disable_binary_storage = let enable_external_auth = call ~flags:[`Session] ~name:"enable_external_auth" ~in_oss_since:None - ~in_product_since:rel_george + ~lifecycle: + [ + ( Published + , rel_george + , "This call enables external authentication on all the hosts of the \ + pool" + ) + ] ~params: [ ( Ref _pool @@ -478,7 +627,14 @@ let enable_external_auth = let disable_external_auth = call ~flags:[`Session] ~name:"disable_external_auth" ~in_oss_since:None - ~in_product_since:rel_george + ~lifecycle: + [ + ( Published + , rel_george + , "This call disables external authentication on all the hosts of the \ + pool" + ) + ] ~versioned_params: [ { @@ -504,7 +660,16 @@ let disable_external_auth = let detect_nonhomogeneous_external_auth = call ~flags:[`Session] ~name:"detect_nonhomogeneous_external_auth" - ~in_oss_since:None ~in_product_since:rel_george + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "This call asynchronously detects if the external authentication \ + configuration in any slave is different from that in the master and \ + raises appropriate alerts" + ) + ] ~params: [ ( Ref _pool @@ -520,7 +685,15 @@ let detect_nonhomogeneous_external_auth = ~allowed_roles:_R_POOL_OP () let initialize_wlb = - call ~name:"initialize_wlb" ~in_product_since:rel_george + call ~name:"initialize_wlb" + ~lifecycle: + [ + ( Published + , rel_george + , "Initializes workload balancing monitoring on this pool with the \ + specified wlb server" + ) + ] ~doc: "Initializes workload balancing monitoring on this pool with the \ specified wlb server" @@ -552,12 +725,27 @@ let initialize_wlb = ~allowed_roles:_R_POOL_OP () let deconfigure_wlb = - call ~name:"deconfigure_wlb" ~in_product_since:rel_george + call ~name:"deconfigure_wlb" + ~lifecycle: + [ + ( Published + , rel_george + , "Permanently deconfigures workload balancing monitoring on this pool" + ) + ] ~doc:"Permanently deconfigures workload balancing monitoring on this pool" ~params:[] ~allowed_roles:_R_POOL_OP () let send_wlb_configuration = - call ~name:"send_wlb_configuration" ~in_product_since:rel_george + call ~name:"send_wlb_configuration" + ~lifecycle: + [ + ( Published + , rel_george + , "Sets the pool optimization criteria for the workload balancing \ + server" + ) + ] ~doc:"Sets the pool optimization criteria for the workload balancing server" ~params: [ @@ -569,7 +757,15 @@ let send_wlb_configuration = ~allowed_roles:_R_POOL_OP () let retrieve_wlb_configuration = - call ~name:"retrieve_wlb_configuration" ~in_product_since:rel_george + call ~name:"retrieve_wlb_configuration" + ~lifecycle: + [ + ( Published + , rel_george + , "Retrieves the pool optimization criteria from the workload \ + balancing server" + ) + ] ~doc: "Retrieves the pool optimization criteria from the workload balancing \ server" @@ -579,7 +775,15 @@ let retrieve_wlb_configuration = ~allowed_roles:_R_READ_ONLY () let retrieve_wlb_recommendations = - call ~name:"retrieve_wlb_recommendations" ~in_product_since:rel_george + call ~name:"retrieve_wlb_recommendations" + ~lifecycle: + [ + ( Published + , rel_george + , "Retrieves vm migrate recommendations for the pool from the workload \ + balancing server" + ) + ] ~doc: "Retrieves vm migrate recommendations for the pool from the workload \ balancing server" @@ -589,7 +793,15 @@ let retrieve_wlb_recommendations = ~allowed_roles:_R_READ_ONLY () let send_test_post = - call ~name:"send_test_post" ~in_product_since:rel_george + call ~name:"send_test_post" + ~lifecycle: + [ + ( Published + , rel_george + , "Send the given body to the given host and port, using HTTPS, and \ + print the response. This is used for debugging the SSL layer." + ) + ] ~doc: "Send the given body to the given host and port, using HTTPS, and print \ the response. This is used for debugging the SSL layer." @@ -657,20 +869,45 @@ let certificate_list = () let crl_install = - call ~in_oss_since:None ~in_product_since:rel_george ~name:"crl_install" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "Install a TLS CA-issued Certificate Revocation List, pool-wide." + ) + ] + ~name:"crl_install" ~doc:"Install a TLS CA-issued Certificate Revocation List, pool-wide." ~params: [(String, "name", "A name to give the CRL"); (String, "cert", "The CRL")] ~allowed_roles:_R_POOL_OP () let crl_uninstall = - call ~in_oss_since:None ~in_product_since:rel_george ~name:"crl_uninstall" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "Remove a pool-wide TLS CA-issued Certificate Revocation List." + ) + ] + ~name:"crl_uninstall" ~doc:"Remove a pool-wide TLS CA-issued Certificate Revocation List." ~params:[(String, "name", "The CRL name")] ~allowed_roles:_R_POOL_OP () let crl_list = - call ~in_oss_since:None ~in_product_since:rel_george ~name:"crl_list" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "List the names of all installed TLS CA-issued Certificate \ + Revocation Lists." + ) + ] + ~name:"crl_list" ~doc: "List the names of all installed TLS CA-issued Certificate Revocation \ Lists." @@ -678,7 +915,15 @@ let crl_list = ~allowed_roles:_R_POOL_OP () let certificate_sync = - call ~in_oss_since:None ~in_product_since:rel_george ~name:"certificate_sync" + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_george + , "Copy the TLS CA certificates and CRLs of the master to all slaves." + ) + ] + ~name:"certificate_sync" ~doc:"Copy the TLS CA certificates and CRLs of the master to all slaves." ~allowed_roles:_R_POOL_OP () @@ -690,7 +935,15 @@ let enable_tls_verification = ~allowed_roles:_R_POOL_ADMIN () let enable_redo_log = - call ~in_oss_since:None ~in_product_since:rel_midnight_ride + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Enable the redo log on the given SR and start using it, unless HA \ + is enabled." + ) + ] ~name:"enable_redo_log" ~params:[(Ref _sr, "sr", "SR to hold the redo log.")] ~doc: @@ -699,20 +952,34 @@ let enable_redo_log = ~allowed_roles:_R_POOL_OP () let disable_redo_log = - call ~in_oss_since:None ~in_product_since:rel_midnight_ride + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Disable the redo log if in use, unless HA is enabled." + ) + ] ~name:"disable_redo_log" ~doc:"Disable the redo log if in use, unless HA is enabled." ~allowed_roles:_R_POOL_OP () let audit_log_append = call ~in_oss_since:None ~pool_internal:true ~hide_from_docs:true - ~in_product_since:rel_midnight_ride ~name:"audit_log_append" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Append a line to the audit log on the master." + ) + ] + ~name:"audit_log_append" ~params:[(String, "line", "line to be appended to the audit log")] ~doc:"Append a line to the audit log on the master." ~allowed_roles:_R_POOL_ADMIN () let set_vswitch_controller = - call ~in_oss_since:None ~in_product_since:rel_midnight_ride + call ~in_oss_since:None ~lifecycle: [ ( Published @@ -736,7 +1003,8 @@ let set_vswitch_controller = let test_archive_target = call ~flags:[`Session] ~name:"test_archive_target" ~in_oss_since:None - ~in_product_since:rel_cowley + ~lifecycle: + [(Published, rel_cowley, "This call tests if a location is valid")] ~params: [ (Ref _pool, "self", "Reference to the pool") @@ -748,21 +1016,39 @@ let test_archive_target = let enable_local_storage_caching = call ~name:"enable_local_storage_caching" ~in_oss_since:None - ~in_product_since:rel_cowley + ~lifecycle: + [ + ( Published + , rel_cowley + , "This call attempts to enable pool-wide local storage caching" + ) + ] ~params:[(Ref _pool, "self", "Reference to the pool")] ~doc:"This call attempts to enable pool-wide local storage caching" ~allowed_roles:_R_POOL_OP () let disable_local_storage_caching = call ~name:"disable_local_storage_caching" ~in_oss_since:None - ~in_product_since:rel_cowley + ~lifecycle: + [ + ( Published + , rel_cowley + , "This call disables pool-wide local storage caching" + ) + ] ~params:[(Ref _pool, "self", "Reference to the pool")] ~doc:"This call disables pool-wide local storage caching" ~allowed_roles:_R_POOL_OP () let get_license_state = call ~name:"get_license_state" ~in_oss_since:None - ~in_product_since:rel_clearwater + ~lifecycle: + [ + ( Published + , rel_clearwater + , "This call returns the license state for the pool" + ) + ] ~params:[(Ref _pool, "self", "Reference to the pool")] ~doc:"This call returns the license state for the pool" ~allowed_roles:_R_READ_ONLY @@ -770,7 +1056,9 @@ let get_license_state = () let apply_edition = - call ~name:"apply_edition" ~in_oss_since:None ~in_product_since:rel_clearwater + call ~name:"apply_edition" ~in_oss_since:None + ~lifecycle: + [(Published, rel_clearwater, "Apply an edition to all hosts in the pool")] ~params: [ (Ref _pool, "self", "Reference to the pool") @@ -825,7 +1113,14 @@ let set_igmp_snooping_enabled = ~allowed_roles:_R_POOL_OP () let has_extension = - call ~name:"has_extension" ~in_product_since:rel_dundee + call ~name:"has_extension" + ~lifecycle: + [ + ( Published + , rel_dundee + , "Return true if the extension is available on the pool" + ) + ] ~doc:"Return true if the extension is available on the pool" ~params: [ @@ -836,7 +1131,14 @@ let has_extension = ~allowed_roles:_R_POOL_ADMIN () let add_to_guest_agent_config = - call ~name:"add_to_guest_agent_config" ~in_product_since:rel_dundee + call ~name:"add_to_guest_agent_config" + ~lifecycle: + [ + ( Published + , rel_dundee + , "Add a key-value pair to the pool-wide guest agent configuration" + ) + ] ~doc:"Add a key-value pair to the pool-wide guest agent configuration" ~params: [ @@ -847,14 +1149,23 @@ let add_to_guest_agent_config = ~allowed_roles:_R_POOL_ADMIN () let remove_from_guest_agent_config = - call ~name:"remove_from_guest_agent_config" ~in_product_since:rel_dundee + call ~name:"remove_from_guest_agent_config" + ~lifecycle: + [ + ( Published + , rel_dundee + , "Remove a key-value pair from the pool-wide guest agent configuration" + ) + ] ~doc:"Remove a key-value pair from the pool-wide guest agent configuration" ~params: [(Ref _pool, "self", "The pool"); (String, "key", "The key to remove")] ~allowed_roles:_R_POOL_ADMIN () let rotate_secret = - call ~in_product_since:rel_stockholm_psr ~name:"rotate_secret" ~params:[] + call + ~lifecycle:[(Published, rel_stockholm_psr, "")] + ~name:"rotate_secret" ~params:[] ~errs: [ Api_errors.internal_error @@ -866,7 +1177,8 @@ let rotate_secret = ~allowed_roles:_R_POOL_ADMIN () let set_repositories = - call ~name:"set_repositories" ~in_product_since:"1.301.0" + call ~name:"set_repositories" + ~lifecycle:[(Published, "1.301.0", "")] ~doc:"Set enabled set of repositories" ~params: [ @@ -877,7 +1189,8 @@ let set_repositories = () let add_repository = - call ~name:"add_repository" ~in_product_since:"1.301.0" + call ~name:"add_repository" + ~lifecycle:[(Published, "1.301.0", "")] ~doc:"Add a repository to the enabled set" ~params: [ @@ -891,7 +1204,8 @@ let add_repository = () let remove_repository = - call ~name:"remove_repository" ~in_product_since:"1.301.0" + call ~name:"remove_repository" + ~lifecycle:[(Published, "1.301.0", "")] ~doc:"Remove a repository from the enabled set" ~params: [ @@ -902,7 +1216,8 @@ let remove_repository = () let sync_updates = - call ~name:"sync_updates" ~in_product_since:"1.329.0" + call ~name:"sync_updates" + ~lifecycle:[(Published, "1.329.0", "")] ~doc:"Sync with the enabled repository" ~versioned_params: [ @@ -1003,7 +1318,8 @@ let disable_client_certificate_auth = () let configure_repository_proxy = - call ~name:"configure_repository_proxy" ~in_product_since:"21.3.0" + call ~name:"configure_repository_proxy" + ~lifecycle:[(Published, "21.3.0", "")] ~doc:"Configure proxy for RPM package repositories." ~params: [ @@ -1022,7 +1338,8 @@ let configure_repository_proxy = () let disable_repository_proxy = - call ~name:"disable_repository_proxy" ~in_product_since:"21.4.0" + call ~name:"disable_repository_proxy" + ~lifecycle:[(Published, "21.4.0", "")] ~doc:"Disable the proxy for RPM package repositories." ~params:[(Ref _pool, "self", "The pool")] ~allowed_roles:(_R_POOL_OP ++ _R_CLIENT_CERT) diff --git a/ocaml/idl/datamodel_vm.ml b/ocaml/idl/datamodel_vm.ml index 377d4c0f667..8a5120ca679 100644 --- a/ocaml/idl/datamodel_vm.ml +++ b/ocaml/idl/datamodel_vm.ml @@ -155,7 +155,8 @@ let actions = let set_actions_after_crash = call ~name:"set_actions_after_crash" ~in_oss_since:None - ~in_product_since:rel_rio ~doc:"Sets the actions_after_crash parameter" + ~lifecycle:[(Published, rel_rio, "Sets the actions_after_crash parameter")] + ~doc:"Sets the actions_after_crash parameter" ~params: [ (Ref _vm, "self", "The VM to set") @@ -197,7 +198,8 @@ let get_boot_record = ~allowed_roles:_R_READ_ONLY () let get_data_sources = - call ~name:"get_data_sources" ~in_oss_since:None ~in_product_since:rel_orlando + call ~name:"get_data_sources" ~in_oss_since:None + ~lifecycle:[(Published, rel_orlando, "")] ~doc:"" ~result:(Set (Record _data_source), "A set of data sources") ~params:[(Ref _vm, "self", "The VM to interrogate")] @@ -205,7 +207,8 @@ let get_data_sources = let record_data_source = call ~name:"record_data_source" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [(Published, rel_orlando, "Start recording the specified data source")] ~doc:"Start recording the specified data source" ~params: [ @@ -216,7 +219,13 @@ let record_data_source = let query_data_source = call ~name:"query_data_source" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Query the latest value of the specified data source" + ) + ] ~doc:"Query the latest value of the specified data source" ~params: [ @@ -228,7 +237,13 @@ let query_data_source = let forget_data_source_archives = call ~name:"forget_data_source_archives" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Forget the recorded statistics related to the specified data source" + ) + ] ~doc:"Forget the recorded statistics related to the specified data source" ~params: [ @@ -242,14 +257,24 @@ let forget_data_source_archives = let set_ha_always_run = call ~name:"set_ha_always_run" ~in_oss_since:None - ~in_product_since:rel_orlando ~doc:"Set the value of the ha_always_run" + ~lifecycle: + [ + (Published, rel_orlando, "Set the value of the ha_always_run") + ; (Deprecated, rel_boston, "") + ] + ~doc:"Set the value of the ha_always_run" ~params:[(Ref _vm, "self", "The VM"); (Bool, "value", "The value")] - ~flags:[`Session] ~allowed_roles:_R_POOL_OP - ~internal_deprecated_since:rel_boston () + ~flags:[`Session] ~allowed_roles:_R_POOL_OP () let set_ha_restart_priority = call ~name:"set_ha_restart_priority" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Set the value of the ha_restart_priority field" + ) + ] ~doc:"Set the value of the ha_restart_priority field" ~params:[(Ref _vm, "self", "The VM"); (String, "value", "The value")] ~flags:[`Session] ~allowed_roles:_R_POOL_OP () @@ -257,7 +282,17 @@ let set_ha_restart_priority = (* VM.Clone *) let clone = - call ~name:"clone" ~in_product_since:rel_rio + call ~name:"clone" + ~lifecycle: + [ + ( Published + , rel_rio + , "Clones the specified VM, making a new VM. Clone automatically \ + exploits the capabilities of the underlying storage repository in \ + which the VM's disk images are stored (e.g. Copy on Write). This \ + function can only be called when the VM is in the Halted State." + ) + ] ~doc: "Clones the specified VM, making a new VM. Clone automatically exploits \ the capabilities of the underlying storage repository in which the VM's \ @@ -346,8 +381,10 @@ let snapshot_with_quiesce = ~allowed_roles:_R_VM_POWER_ADMIN () let update_snapshot_metadata = - call ~name:"update_snapshot_metadata" ~in_product_since:rel_george - ~internal_deprecated_since:rel_midnight_ride ~doc:"" ~hide_from_docs:true + call ~name:"update_snapshot_metadata" + ~lifecycle: + [(Published, rel_george, ""); (Deprecated, rel_midnight_ride, "")] + ~doc:"" ~hide_from_docs:true ~params: [ (Ref _vm, "vm", "The VM to update") @@ -362,7 +399,16 @@ let update_snapshot_metadata = ~allowed_roles:_R_POOL_OP () let snapshot = - call ~name:"snapshot" ~in_product_since:rel_orlando + call ~name:"snapshot" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Snapshots the specified VM, making a new VM. Snapshot automatically \ + exploits the capabilities of the underlying storage repository in \ + which the VM's disk images are stored (e.g. Copy on Write)." + ) + ] ~doc: "Snapshots the specified VM, making a new VM. Snapshot automatically \ exploits the capabilities of the underlying storage repository in which \ @@ -401,7 +447,14 @@ let snapshot = ~allowed_roles:_R_VM_POWER_ADMIN ~doc_tags:[Snapshots] () let revert = - call ~name:"revert" ~in_product_since:rel_midnight_ride + call ~name:"revert" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Reverts the specified VM to a previous state." + ) + ] ~doc:"Reverts the specified VM to a previous state." ~params:[(Ref _vm, "snapshot", "The snapshotted state that we revert to")] ~errs: @@ -414,7 +467,17 @@ let revert = ~allowed_roles:_R_VM_POWER_ADMIN ~doc_tags:[Snapshots] () let checkpoint = - call ~name:"checkpoint" ~in_product_since:rel_midnight_ride + call ~name:"checkpoint" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Checkpoints the specified VM, making a new VM. Checkpoint \ + automatically exploits the capabilities of the underlying storage \ + repository in which the VM's disk images are stored (e.g. Copy on \ + Write) and saves the memory image as well." + ) + ] ~doc: "Checkpoints the specified VM, making a new VM. Checkpoint automatically \ exploits the capabilities of the underlying storage repository in which \ @@ -438,8 +501,14 @@ let checkpoint = let create_template = call ~name:"create_template" ~hide_from_docs:true - ~internal_deprecated_since:rel_midnight_ride - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Deprecated: use VM.clone or VM.copy instead." + ) + ; (Deprecated, rel_midnight_ride, "") + ] ~doc:"Deprecated: use VM.clone or VM.copy instead." ~result:(Ref _vm, "") ~params:[(Ref _vm, "vm", ""); (String, "new_name", "")] ~errs:[] ~allowed_roles:_R_VM_ADMIN () @@ -456,7 +525,8 @@ let set_is_default_template = ~errs:[] ~allowed_roles:_R_POOL_ADMIN () let import_convert = - call ~name:"import_convert" ~in_product_since:rel_tampa + call ~name:"import_convert" + ~lifecycle:[(Published, rel_tampa, "Import using a conversion service.")] ~doc:"Import using a conversion service." ~params: [ @@ -477,13 +547,30 @@ let provision = creates VDIs and VBDs and then executes any applicable post-install \ script." ~params:[(Ref _vm, "vm", "The VM to be provisioned")] - ~in_oss_since:None ~in_product_since:rel_rio ~errs:(errnames_of_call clone) - ~allowed_roles:_R_VM_ADMIN () + ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Inspects the disk configuration contained within the VM's \ + other_config, creates VDIs and VBDs and then executes any \ + applicable post-install script." + ) + ] + ~errs:(errnames_of_call clone) ~allowed_roles:_R_VM_ADMIN () (* VM.Start *) let start = - call ~name:"start" ~in_product_since:rel_rio + call ~name:"start" + ~lifecycle: + [ + ( Published + , rel_rio + , "Start the specified VM. This function can only be called with the \ + VM is in the Halted State." + ) + ] ~doc: "Start the specified VM. This function can only be called with the VM \ is in the Halted State." @@ -513,7 +600,7 @@ let start = ~allowed_roles:_R_VM_OP () let assert_can_boot_here = - call ~name:"assert_can_boot_here" ~in_product_since:rel_rio + call ~name:"assert_can_boot_here" ~lifecycle: [ (Published, rel_rio, "") @@ -553,7 +640,15 @@ let assert_can_boot_here = ~doc_tags:[Memory] () let assert_agile = - call ~name:"assert_agile" ~in_product_since:rel_orlando + call ~name:"assert_agile" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Returns an error if the VM is not considered agile e.g. because it \ + is tied to a resource local to a host" + ) + ] ~doc: "Returns an error if the VM is not considered agile e.g. because it is \ tied to a resource local to a host" @@ -561,14 +656,30 @@ let assert_agile = ~allowed_roles:_R_READ_ONLY () let get_possible_hosts = - call ~name:"get_possible_hosts" ~in_product_since:rel_rio + call ~name:"get_possible_hosts" + ~lifecycle: + [ + ( Published + , rel_rio + , "Return the list of hosts on which this VM may run." + ) + ] ~doc:"Return the list of hosts on which this VM may run." ~params:[(Ref _vm, "vm", "The VM")] ~result:(Set (Ref _host), "The possible hosts") ~allowed_roles:_R_READ_ONLY () let retrieve_wlb_recommendations = - call ~name:"retrieve_wlb_recommendations" ~in_product_since:rel_george + call ~name:"retrieve_wlb_recommendations" + ~lifecycle: + [ + ( Published + , rel_george + , "Returns mapping of hosts to ratings, indicating the suitability of \ + starting the VM at that location according to wlb. Rating is \ + replaced with an error if the VM cannot boot there." + ) + ] ~doc: "Returns mapping of hosts to ratings, indicating the suitability of \ starting the VM at that location according to wlb. Rating is replaced \ @@ -581,7 +692,19 @@ let retrieve_wlb_recommendations = ~allowed_roles:_R_READ_ONLY () let maximise_memory = - call ~in_product_since:rel_miami ~name:"maximise_memory" + call + ~lifecycle: + [ + ( Published + , rel_miami + , "Returns the maximum amount of guest memory which will fit, together \ + with overheads, in the supplied amount of physical memory. If \ + 'exact' is true then an exact calculation is performed using the \ + VM's current settings. If 'exact' is false then a more conservative \ + approximation is used" + ) + ] + ~name:"maximise_memory" ~doc: "Returns the maximum amount of guest memory which will fit, together \ with overheads, in the supplied amount of physical memory. If 'exact' \ @@ -603,7 +726,15 @@ let maximise_memory = ~allowed_roles:_R_READ_ONLY ~doc_tags:[Memory] () let get_allowed_VBD_devices = - call ~flags:[`Session] ~no_current_operations:true ~in_product_since:rel_rio + call ~flags:[`Session] ~no_current_operations:true + ~lifecycle: + [ + ( Published + , rel_rio + , "Returns a list of the allowed values that a VBD device field can \ + take" + ) + ] ~name:"get_allowed_VBD_devices" ~doc:"Returns a list of the allowed values that a VBD device field can take" ~params:[(Ref _vm, "vm", "The VM to query")] @@ -611,7 +742,15 @@ let get_allowed_VBD_devices = ~allowed_roles:_R_READ_ONLY () let get_allowed_VIF_devices = - call ~flags:[`Session] ~no_current_operations:true ~in_product_since:rel_rio + call ~flags:[`Session] ~no_current_operations:true + ~lifecycle: + [ + ( Published + , rel_rio + , "Returns a list of the allowed values that a VIF device field can \ + take" + ) + ] ~name:"get_allowed_VIF_devices" ~doc:"Returns a list of the allowed values that a VIF device field can take" ~params:[(Ref _vm, "vm", "The VM to query")] @@ -622,8 +761,10 @@ let get_allowed_VIF_devices = (* an internal call that sets resident_on and clears the scheduled_to_be_resident_on atomically *) let atomic_set_resident_on = - call ~in_product_since:rel_rio ~pool_internal:true ~hide_from_docs:true - ~name:"atomic_set_resident_on" ~doc:"" + call + ~lifecycle:[(Published, rel_rio, "")] + ~pool_internal:true ~hide_from_docs:true ~name:"atomic_set_resident_on" + ~doc:"" ~params: [ (Ref _vm, "vm", "The VM to modify") @@ -632,7 +773,15 @@ let atomic_set_resident_on = ~allowed_roles:_R_LOCAL_ROOT_ONLY () let compute_memory_overhead = - call ~in_product_since:rel_midnight_ride ~name:"compute_memory_overhead" + call + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Computes the virtualization memory overhead of a VM." + ) + ] + ~name:"compute_memory_overhead" ~doc:"Computes the virtualization memory overhead of a VM." ~params:[(Ref _vm, "vm", "The VM for which to compute the memory overhead")] ~pool_internal:false ~hide_from_docs:false @@ -640,7 +789,14 @@ let compute_memory_overhead = ~allowed_roles:_R_READ_ONLY ~doc_tags:[Memory] () let set_memory_dynamic_max = - call ~flags:[`Session] ~in_product_since:rel_midnight_ride + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Set the value of the memory_dynamic_max field" + ) + ] ~name:"set_memory_dynamic_max" ~doc:"Set the value of the memory_dynamic_max field" ~params: @@ -651,7 +807,14 @@ let set_memory_dynamic_max = ~allowed_roles:_R_VM_POWER_ADMIN ~errs:[] ~doc_tags:[Memory] () let set_memory_dynamic_min = - call ~flags:[`Session] ~in_product_since:rel_midnight_ride + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Set the value of the memory_dynamic_min field" + ) + ] ~name:"set_memory_dynamic_min" ~doc:"Set the value of the memory_dynamic_min field" ~params: @@ -662,7 +825,15 @@ let set_memory_dynamic_min = ~allowed_roles:_R_VM_POWER_ADMIN ~errs:[] ~doc_tags:[Memory] () let set_memory_dynamic_range = - call ~name:"set_memory_dynamic_range" ~in_product_since:rel_midnight_ride + call ~name:"set_memory_dynamic_range" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Set the minimum and maximum amounts of physical memory the VM is \ + allowed to use." + ) + ] ~doc: "Set the minimum and maximum amounts of physical memory the VM is \ allowed to use." @@ -678,7 +849,9 @@ let set_memory_dynamic_range = (* When HA is enabled we need to prevent memory *) (* changes which will break the recovery plan. *) let set_memory_static_max = - call ~flags:[`Session] ~in_product_since:rel_orlando + call ~flags:[`Session] + ~lifecycle: + [(Published, rel_orlando, "Set the value of the memory_static_max field")] ~name:"set_memory_static_max" ~doc:"Set the value of the memory_static_max field" ~errs:[Api_errors.ha_operation_would_break_failover_plan] @@ -691,7 +864,14 @@ let set_memory_static_max = ~doc_tags:[Memory] () let set_memory_static_min = - call ~flags:[`Session] ~in_product_since:rel_midnight_ride + call ~flags:[`Session] + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Set the value of the memory_static_min field" + ) + ] ~name:"set_memory_static_min" ~doc:"Set the value of the memory_static_min field" ~errs:[] ~allowed_roles:_R_VM_POWER_ADMIN @@ -703,7 +883,15 @@ let set_memory_static_min = ~doc_tags:[Memory] () let set_memory_static_range = - call ~name:"set_memory_static_range" ~in_product_since:rel_midnight_ride + call ~name:"set_memory_static_range" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Set the static (ie boot-time) range of virtual memory that the VM \ + is allowed to use." + ) + ] ~doc: "Set the static (ie boot-time) range of virtual memory that the VM is \ allowed to use." @@ -717,7 +905,9 @@ let set_memory_static_range = ~doc_tags:[Memory] () let set_memory_limits = - call ~name:"set_memory_limits" ~in_product_since:rel_midnight_ride + call ~name:"set_memory_limits" + ~lifecycle: + [(Published, rel_midnight_ride, "Set the memory limits of this VM.")] ~doc:"Set the memory limits of this VM." ~allowed_roles:_R_VM_POWER_ADMIN ~params: [ @@ -730,7 +920,16 @@ let set_memory_limits = ~doc_tags:[Memory] () let set_memory = - call ~name:"set_memory" ~in_product_since:rel_ely + call ~name:"set_memory" + ~lifecycle: + [ + ( Published + , rel_ely + , "Set the memory allocation of this VM. Sets all of \ + memory_static_max, memory_dynamic_min, and memory_dynamic_max to \ + the given value, and leaves memory_static_min untouched." + ) + ] ~doc: "Set the memory allocation of this VM. Sets all of memory_static_max, \ memory_dynamic_min, and memory_dynamic_max to the given value, and \ @@ -744,8 +943,12 @@ let set_memory = ~doc_tags:[Memory] () let set_memory_target_live = - call ~name:"set_memory_target_live" ~in_product_since:rel_rio - ~internal_deprecated_since:rel_midnight_ride + call ~name:"set_memory_target_live" + ~lifecycle: + [ + (Published, rel_rio, "Set the memory target for a running VM") + ; (Deprecated, rel_midnight_ride, "") + ] ~doc:"Set the memory target for a running VM" ~allowed_roles:_R_VM_POWER_ADMIN ~params: @@ -753,16 +956,31 @@ let set_memory_target_live = ~doc_tags:[Memory] () let wait_memory_target_live = - call ~name:"wait_memory_target_live" ~in_product_since:rel_orlando - ~internal_deprecated_since:rel_midnight_ride + call ~name:"wait_memory_target_live" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Wait for a running VM to reach its current memory target" + ) + ; (Deprecated, rel_midnight_ride, "") + ] ~doc:"Wait for a running VM to reach its current memory target" ~allowed_roles:_R_READ_ONLY ~params:[(Ref _vm, "self", "The VM")] ~doc_tags:[Memory] () let get_cooperative = - call ~name:"get_cooperative" ~in_product_since:rel_midnight_ride - ~internal_deprecated_since:rel_tampa + call ~name:"get_cooperative" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Return true if the VM is currently 'co-operative' i.e. is expected \ + to reach a balloon target and actually has done" + ) + ; (Deprecated, rel_tampa, "") + ] ~doc: "Return true if the VM is currently 'co-operative' i.e. is expected to \ reach a balloon target and actually has done" @@ -771,7 +989,15 @@ let get_cooperative = ~allowed_roles:_R_READ_ONLY ~doc_tags:[Memory] () let query_services = - call ~name:"query_services" ~in_product_since:rel_tampa + call ~name:"query_services" + ~lifecycle: + [ + ( Published + , rel_tampa + , "Query the system services advertised by this VM and register them. \ + This can only be applied to a system domain." + ) + ] ~doc: "Query the system services advertised by this VM and register them. This \ can only be applied to a system domain." @@ -782,7 +1008,16 @@ let query_services = (* VM.StartOn *) let start_on = - call ~in_product_since:rel_rio ~name:"start_on" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Start the specified VM on a particular host. This function can \ + only be called with the VM is in the Halted State." + ) + ] + ~name:"start_on" ~doc: "Start the specified VM on a particular host. This function can only be \ called with the VM is in the Halted State." @@ -814,7 +1049,16 @@ let start_on = (* VM.Pause *) let pause = - call ~in_product_since:rel_rio ~name:"pause" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Pause the specified VM. This can only be called when the specified \ + VM is in the Running state." + ) + ] + ~name:"pause" ~doc: "Pause the specified VM. This can only be called when the specified VM \ is in the Running state." @@ -831,7 +1075,16 @@ let pause = (* VM.UnPause *) let unpause = - call ~in_product_since:rel_rio ~name:"unpause" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Resume the specified VM. This can only be called when the specified \ + VM is in the Paused state." + ) + ] + ~name:"unpause" ~doc: "Resume the specified VM. This can only be called when the specified VM \ is in the Paused state." @@ -847,7 +1100,17 @@ let unpause = (* VM.CleanShutdown *) let cleanShutdown = - call ~in_product_since:rel_rio ~name:"clean_shutdown" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Attempt to cleanly shutdown the specified VM. (Note: this may not \ + be supported---e.g. if a guest agent is not installed). This can \ + only be called when the specified VM is in the Running state." + ) + ] + ~name:"clean_shutdown" ~doc: "Attempt to cleanly shutdown the specified VM. (Note: this may not be \ supported---e.g. if a guest agent is not installed). This can only be \ @@ -865,7 +1128,17 @@ let cleanShutdown = (* VM.CleanReboot *) let cleanReboot = - call ~in_product_since:rel_rio ~name:"clean_reboot" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Attempt to cleanly shutdown the specified VM (Note: this may not be \ + supported---e.g. if a guest agent is not installed). This can only \ + be called when the specified VM is in the Running state." + ) + ] + ~name:"clean_reboot" ~doc: "Attempt to cleanly shutdown the specified VM (Note: this may not be \ supported---e.g. if a guest agent is not installed). This can only be \ @@ -883,7 +1156,15 @@ let cleanReboot = (* VM.HardShutdown *) let hardShutdown = - call ~in_product_since:rel_rio ~name:"hard_shutdown" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Stop executing the specified VM without attempting a clean shutdown." + ) + ] + ~name:"hard_shutdown" ~doc:"Stop executing the specified VM without attempting a clean shutdown." ~params:[(Ref _vm, "vm", "The VM to destroy")] ~errs: @@ -898,7 +1179,16 @@ let hardShutdown = (* VM.Shutdown *) let shutdown = - call ~in_product_since:rel_clearwater ~name:"shutdown" + call + ~lifecycle: + [ + ( Published + , rel_clearwater + , "Attempts to first clean shutdown a VM and if it should fail then \ + perform a hard shutdown on it." + ) + ] + ~name:"shutdown" ~doc: "Attempts to first clean shutdown a VM and if it should fail then \ perform a hard shutdown on it." @@ -916,7 +1206,18 @@ let shutdown = (* VM.PowerStateReset *) let stateReset = - call ~in_product_since:rel_rio ~name:"power_state_reset" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Reset the power-state of the VM to halted in the database only. \ + (Used to recover from slave failures in pooling scenarios by \ + resetting the power-states of VMs running on dead slaves to \ + halted.) This is a potentially dangerous operation; use with care." + ) + ] + ~name:"power_state_reset" ~doc: "Reset the power-state of the VM to halted in the database only. (Used \ to recover from slave failures in pooling scenarios by resetting the \ @@ -928,7 +1229,16 @@ let stateReset = (* VM.HardReboot *) let hardReboot = - call ~in_product_since:rel_rio ~name:"hard_reboot" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Stop executing the specified VM without attempting a clean shutdown \ + and immediately restart the VM." + ) + ] + ~name:"hard_reboot" ~doc: "Stop executing the specified VM without attempting a clean shutdown and \ immediately restart the VM." @@ -943,17 +1253,34 @@ let hardReboot = ~allowed_roles:_R_VM_OP () let hardReboot_internal = - call ~in_product_since:rel_orlando ~name:"hard_reboot_internal" + call + ~lifecycle: + [ + ( Published + , rel_orlando + , "Internal function which immediately restarts the specified VM." + ) + ; (Deprecated, rel_midnight_ride, "") + ] + ~name:"hard_reboot_internal" ~doc:"Internal function which immediately restarts the specified VM." ~params:[(Ref _vm, "vm", "The VM to reboot")] - ~pool_internal:true ~hide_from_docs:true - ~internal_deprecated_since:rel_midnight_ride - ~allowed_roles:_R_LOCAL_ROOT_ONLY () + ~pool_internal:true ~hide_from_docs:true ~allowed_roles:_R_LOCAL_ROOT_ONLY + () (* VM.Hibernate *) let suspend = - call ~in_product_since:rel_rio ~name:"suspend" + call + ~lifecycle: + [ + ( Published + , rel_rio + , "Suspend the specified VM to disk. This can only be called when the \ + specified VM is in the Running state." + ) + ] + ~name:"suspend" ~doc: "Suspend the specified VM to disk. This can only be called when the \ specified VM is in the Running state." @@ -971,16 +1298,32 @@ let suspend = (* VM.clsp -- clone suspended, undocumented API for VMLogix *) let csvm = - call ~name:"csvm" ~in_product_since:rel_rio + call ~name:"csvm" + ~lifecycle: + [ + ( Published + , rel_rio + , "undocumented. internal use only. This call is deprecated." + ) + ; (Deprecated, rel_miami, "") + ] ~doc:"undocumented. internal use only. This call is deprecated." ~params:[(Ref _vm, "vm", "")] ~result:(Ref _vm, "") ~errs:(errnames_of_call clone) ~hide_from_docs:true - ~internal_deprecated_since:rel_miami ~allowed_roles:_R_VM_ADMIN () + ~allowed_roles:_R_VM_ADMIN () (* VM.UnHibernate *) let resume = - call ~name:"resume" ~in_product_since:rel_rio + call ~name:"resume" + ~lifecycle: + [ + ( Published + , rel_rio + , "Awaken the specified VM and resume it. This can only be called \ + when the specified VM is in the Suspended state." + ) + ] ~doc: "Awaken the specified VM and resume it. This can only be called when \ the specified VM is in the Suspended state." @@ -1004,7 +1347,15 @@ let resume = ~allowed_roles:_R_VM_OP () let resume_on = - call ~name:"resume_on" ~in_product_since:rel_rio + call ~name:"resume_on" + ~lifecycle: + [ + ( Published + , rel_rio + , "Awaken the specified VM and resume it on a particular Host. This \ + can only be called when the specified VM is in the Suspended state." + ) + ] ~doc: "Awaken the specified VM and resume it on a particular Host. This can \ only be called when the specified VM is in the Suspended state." @@ -1031,8 +1382,9 @@ let resume_on = () let pool_migrate = - call ~in_oss_since:None ~in_product_since:rel_rio ~name:"pool_migrate" - ~doc:"Migrate a VM to another Host." + call ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Migrate a VM to another Host.")] + ~name:"pool_migrate" ~doc:"Migrate a VM to another Host." ~params: [ (Ref _vm, "vm", "The VM to migrate") @@ -1056,7 +1408,14 @@ let pool_migrate = () let pool_migrate_complete = - call ~in_oss_since:None ~in_product_since:rel_tampa + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_tampa + , "Tell a destination host that migration is complete." + ) + ] ~name:"pool_migrate_complete" ~doc:"Tell a destination host that migration is complete." ~params: @@ -1070,7 +1429,7 @@ let pool_migrate_complete = () let set_vcpus_number_live = - call ~name:"set_VCPUs_number_live" ~in_product_since:rel_rio + call ~name:"set_VCPUs_number_live" ~lifecycle: [ (Published, rel_rio, "Set the number of VCPUs for a running VM") @@ -1088,7 +1447,13 @@ let set_vcpus_number_live = let set_VCPUs_max = call ~flags:[`Session] ~name:"set_VCPUs_max" - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Set the maximum number of VCPUs for a halted VM" + ) + ] ~doc:"Set the maximum number of VCPUs for a halted VM" ~params: [ @@ -1099,7 +1464,13 @@ let set_VCPUs_max = let set_VCPUs_at_startup = call ~flags:[`Session] ~name:"set_VCPUs_at_startup" - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Set the number of startup VCPUs for a halted VM" + ) + ] ~doc:"Set the number of startup VCPUs for a halted VM" ~params: [ @@ -1110,7 +1481,13 @@ let set_VCPUs_at_startup = let set_HVM_shadow_multiplier = call ~flags:[`Session] ~name:"set_HVM_shadow_multiplier" - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Set the shadow memory multiplier on a halted VM" + ) + ] ~doc:"Set the shadow memory multiplier on a halted VM" ~params: [ @@ -1120,7 +1497,9 @@ let set_HVM_shadow_multiplier = ~allowed_roles:_R_VM_POWER_ADMIN () let set_shadow_multiplier_live = - call ~name:"set_shadow_multiplier_live" ~in_product_since:rel_rio + call ~name:"set_shadow_multiplier_live" + ~lifecycle: + [(Published, rel_rio, "Set the shadow memory multiplier on a running VM")] ~doc:"Set the shadow memory multiplier on a running VM" ~params: [ @@ -1130,7 +1509,15 @@ let set_shadow_multiplier_live = ~allowed_roles:_R_VM_POWER_ADMIN () let add_to_VCPUs_params_live = - call ~name:"add_to_VCPUs_params_live" ~in_product_since:rel_rio + call ~name:"add_to_VCPUs_params_live" + ~lifecycle: + [ + ( Published + , rel_rio + , "Add the given key-value pair to VM.VCPUs_params, and apply that \ + value on the running VM" + ) + ] ~doc: "Add the given key-value pair to VM.VCPUs_params, and apply that value \ on the running VM" @@ -1169,7 +1556,16 @@ let set_NVRAM = ~allowed_roles:_R_VM_ADMIN () let send_sysrq = - call ~name:"send_sysrq" ~in_product_since:rel_rio + call ~name:"send_sysrq" + ~lifecycle: + [ + ( Published + , rel_rio + , "Send the given key as a sysrq to this VM. The key is specified as \ + a single character (a String of length 1). This can only be called \ + when the specified VM is in the Running state." + ) + ] ~doc: "Send the given key as a sysrq to this VM. The key is specified as a \ single character (a String of length 1). This can only be called when \ @@ -1179,7 +1575,15 @@ let send_sysrq = ~allowed_roles:_R_POOL_ADMIN () let send_trigger = - call ~name:"send_trigger" ~in_product_since:rel_rio + call ~name:"send_trigger" + ~lifecycle: + [ + ( Published + , rel_rio + , "Send the named trigger to this VM. This can only be called when \ + the specified VM is in the Running state." + ) + ] ~doc: "Send the named trigger to this VM. This can only be called when the \ specified VM is in the Running state." @@ -1189,7 +1593,15 @@ let send_trigger = ~allowed_roles:_R_POOL_ADMIN () let migrate_send = - call ~name:"migrate_send" ~in_product_since:rel_tampa + call ~name:"migrate_send" + ~lifecycle: + [ + ( Published + , rel_tampa + , "Migrate the VM to another host. This can only be called when the \ + specified VM is in the Running state." + ) + ] ~doc: "Migrate the VM to another host. This can only be called when the \ specified VM is in the Running state." @@ -1251,7 +1663,14 @@ let migrate_send = ~allowed_roles:_R_VM_POWER_ADMIN () let assert_can_migrate = - call ~name:"assert_can_migrate" ~in_product_since:rel_tampa + call ~name:"assert_can_migrate" + ~lifecycle: + [ + ( Published + , rel_tampa + , "Assert whether a VM can be migrated to the specified destination." + ) + ] ~doc:"Assert whether a VM can be migrated to the specified destination." ~versioned_params: [ @@ -1340,19 +1759,33 @@ let assert_can_migrate_sender = ~allowed_roles:_R_VM_POWER_ADMIN ~hide_from_docs:true () let s3_suspend = - call ~name:"s3_suspend" ~in_product_since:rel_midnight_ride + call ~name:"s3_suspend" + ~lifecycle: + [(Published, rel_midnight_ride, "Try to put the VM into ACPI S3 state")] ~doc:"Try to put the VM into ACPI S3 state" ~params:[(Ref _vm, "vm", "The VM")] ~hide_from_docs:true ~allowed_roles:_R_VM_OP () let s3_resume = - call ~name:"s3_resume" ~in_product_since:rel_midnight_ride + call ~name:"s3_resume" + ~lifecycle: + [ + (Published, rel_midnight_ride, "Try to resume the VM from ACPI S3 state") + ] ~doc:"Try to resume the VM from ACPI S3 state" ~params:[(Ref _vm, "vm", "The VM")] ~hide_from_docs:true ~allowed_roles:_R_VM_OP () let create_new_blob = - call ~name:"create_new_blob" ~in_product_since:rel_orlando + call ~name:"create_new_blob" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Create a placeholder for a named binary blob of data that is \ + associated with this VM" + ) + ] ~doc: "Create a placeholder for a named binary blob of data that is associated \ with this VM" @@ -1394,7 +1827,22 @@ let create_new_blob = ~allowed_roles:_R_VM_POWER_ADMIN () let set_bios_strings = - call ~name:"set_bios_strings" ~in_product_since:rel_inverness + call ~name:"set_bios_strings" + ~lifecycle: + [ + ( Published + , rel_inverness + , "Set custom BIOS strings to this VM. VM will be given a default set \ + of BIOS strings, only some of which can be overridden by the \ + supplied values. Allowed keys are: 'bios-vendor', 'bios-version', \ + 'system-manufacturer', 'system-product-name', 'system-version', \ + 'system-serial-number', 'enclosure-asset-tag', \ + 'baseboard-manufacturer', 'baseboard-product-name', \ + 'baseboard-version', 'baseboard-serial-number', \ + 'baseboard-asset-tag', 'baseboard-location-in-chassis', \ + 'enclosure-asset-tag'" + ) + ] ~doc: "Set custom BIOS strings to this VM. VM will be given a default set of \ BIOS strings, only some of which can be overridden by the supplied \ @@ -1417,7 +1865,14 @@ let set_bios_strings = () let copy_bios_strings = - call ~name:"copy_bios_strings" ~in_product_since:rel_midnight_ride + call ~name:"copy_bios_strings" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Copy the BIOS strings from the given host to this VM" + ) + ] ~doc:"Copy the BIOS strings from the given host to this VM" ~params: [ @@ -1434,13 +1889,15 @@ let set_protection_policy = let set_snapshot_schedule = call ~name:"set_snapshot_schedule" ~in_oss_since:None - ~in_product_since:rel_falcon + ~lifecycle: + [(Published, rel_falcon, "Set the value of the snapshot schedule field")] ~doc:"Set the value of the snapshot schedule field" ~params:[(Ref _vm, "self", "The VM"); (Ref _vmss, "value", "The value")] ~flags:[`Session] ~allowed_roles:_R_POOL_OP () let set_start_delay = - call ~name:"set_start_delay" ~in_product_since:rel_boston + call ~name:"set_start_delay" + ~lifecycle:[(Published, rel_boston, "Set this VM's start delay in seconds")] ~doc:"Set this VM's start delay in seconds" ~params: [ @@ -1450,7 +1907,9 @@ let set_start_delay = ~allowed_roles:_R_POOL_OP () let set_shutdown_delay = - call ~name:"set_shutdown_delay" ~in_product_since:rel_boston + call ~name:"set_shutdown_delay" + ~lifecycle: + [(Published, rel_boston, "Set this VM's shutdown delay in seconds")] ~doc:"Set this VM's shutdown delay in seconds" ~params: [ @@ -1460,14 +1919,23 @@ let set_shutdown_delay = ~allowed_roles:_R_POOL_OP () let set_order = - call ~name:"set_order" ~in_product_since:rel_boston + call ~name:"set_order" + ~lifecycle:[(Published, rel_boston, "Set this VM's boot order")] ~doc:"Set this VM's boot order" ~params: [(Ref _vm, "self", "The VM"); (Int, "value", "This VM's boot order")] ~allowed_roles:_R_POOL_OP () let set_suspend_VDI = - call ~name:"set_suspend_VDI" ~in_product_since:rel_boston + call ~name:"set_suspend_VDI" + ~lifecycle: + [ + ( Published + , rel_boston + , "Set this VM's suspend VDI, which must be indentical to its current \ + one" + ) + ] ~doc: "Set this VM's suspend VDI, which must be indentical to its current one" ~params: @@ -1475,7 +1943,14 @@ let set_suspend_VDI = ~allowed_roles:_R_POOL_OP () let assert_can_be_recovered = - call ~name:"assert_can_be_recovered" ~in_product_since:rel_boston + call ~name:"assert_can_be_recovered" + ~lifecycle: + [ + ( Published + , rel_boston + , "Assert whether all SRs required to recover this VM are available." + ) + ] ~doc:"Assert whether all SRs required to recover this VM are available." ~params: [ @@ -1489,7 +1964,14 @@ let assert_can_be_recovered = ~allowed_roles:_R_READ_ONLY () let get_SRs_required_for_recovery = - call ~name:"get_SRs_required_for_recovery" ~in_product_since:rel_creedence + call ~name:"get_SRs_required_for_recovery" + ~lifecycle: + [ + ( Published + , rel_creedence + , "List all the SR's that are required for the VM to be recovered" + ) + ] ~doc:"List all the SR's that are required for the VM to be recovered" ~params: [ @@ -1503,7 +1985,9 @@ let get_SRs_required_for_recovery = ~errs:[] ~allowed_roles:_R_READ_ONLY () let recover = - call ~name:"recover" ~in_product_since:rel_boston ~doc:"Recover the VM" + call ~name:"recover" + ~lifecycle:[(Published, rel_boston, "Recover the VM")] + ~doc:"Recover the VM" ~params: [ (Ref _vm, "self", "The VM to recover") @@ -1519,7 +2003,8 @@ let recover = ~allowed_roles:_R_READ_ONLY () let set_appliance = - call ~name:"set_appliance" ~in_product_since:rel_boston + call ~name:"set_appliance" + ~lifecycle:[(Published, rel_boston, "Assign this VM to an appliance.")] ~doc:"Assign this VM to an appliance." ~params: [ @@ -1542,7 +2027,8 @@ let set_groups = ~allowed_roles:_R_VM_ADMIN () let call_plugin = - call ~name:"call_plugin" ~in_product_since:rel_cream + call ~name:"call_plugin" + ~lifecycle:[(Published, rel_cream, "Call an API plugin on this vm")] ~doc:"Call an API plugin on this vm" ~params: [ @@ -1555,7 +2041,18 @@ let call_plugin = ~allowed_roles:_R_VM_OP () let set_has_vendor_device = - call ~name:"set_has_vendor_device" ~in_product_since:rel_dundee + call ~name:"set_has_vendor_device" + ~lifecycle: + [ + ( Published + , rel_dundee + , "Controls whether, when the VM starts in HVM mode, its virtual \ + hardware will include the emulated PCI device for which drivers may \ + be available through Windows Update. Usually this should never be \ + changed on a VM on which Windows has been installed: changing it on \ + such a VM is likely to lead to a crash on next start." + ) + ] ~doc: "Controls whether, when the VM starts in HVM mode, its virtual hardware \ will include the emulated PCI device for which drivers may be available \ @@ -1570,7 +2067,8 @@ let set_has_vendor_device = ~allowed_roles:_R_VM_ADMIN ~doc_tags:[Windows] () let import = - call ~name:"import" ~in_product_since:rel_dundee + call ~name:"import" + ~lifecycle:[(Published, rel_dundee, "Import an XVA from a URI")] ~doc:"Import an XVA from a URI" ~params: [ @@ -1647,7 +2145,15 @@ let operations = let set_blocked_operations = call ~name:"set_blocked_operations" - ~in_product_since:rel_orlando (* but updated 2024 *) + ~lifecycle: + [ + ( Published + , rel_orlando + , "Update list of operations which have been explicitly blocked and an \ + error code" + ) + ] + (* but updated 2024 *) ~doc: "Update list of operations which have been explicitly blocked and an \ error code" @@ -1660,7 +2166,15 @@ let set_blocked_operations = let add_to_blocked_operations = call ~name:"add_to_blocked_operations" - ~in_product_since:rel_orlando (* but updated 2024 *) + ~lifecycle: + [ + ( Published + , rel_orlando + , "Update list of operations which have been explicitly blocked and an \ + error code" + ) + ] + (* but updated 2024 *) ~doc: "Update list of operations which have been explicitly blocked and an \ error code" @@ -1674,7 +2188,15 @@ let add_to_blocked_operations = let remove_from_blocked_operations = call ~name:"remove_from_blocked_operations" - ~in_product_since:rel_orlando (* but updated 2024 *) + ~lifecycle: + [ + ( Published + , rel_orlando + , "Update list of operations which have been explicitly blocked and an \ + error code" + ) + ] + (* but updated 2024 *) ~doc: "Update list of operations which have been explicitly blocked and an \ error code" @@ -1683,7 +2205,16 @@ let remove_from_blocked_operations = ~allowed_roles:_R_VM_ADMIN () let assert_operation_valid = - call ~in_oss_since:None ~in_product_since:rel_rio + call ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Check to see whether this operation is acceptable in the current \ + state of the system, raising an error if the operation is invalid \ + for some reason" + ) + ] ~name:"assert_operation_valid" ~doc: "Check to see whether this operation is acceptable in the current state \ @@ -1697,7 +2228,9 @@ let assert_operation_valid = ~allowed_roles:_R_READ_ONLY () let update_allowed_operations = - call ~in_oss_since:None ~in_product_since:rel_rio + call ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Recomputes the list of acceptable operations")] ~name:"update_allowed_operations" ~doc:"Recomputes the list of acceptable operations" ~params:[(Ref _vm, _self, "reference to the object")] From ef7c4d3c9eb7a0fe0e36481bd3de6367495c672e Mon Sep 17 00:00:00 2001 From: Andrii Sultanov Date: Mon, 23 Sep 2024 14:03:01 +0100 Subject: [PATCH 3/8] idl: Remove long-unused code Signed-off-by: Andrii Sultanov --- ocaml/idl/datamodel.ml | 37 +------------------------------------ ocaml/idl/datamodel_host.ml | 11 ----------- ocaml/idl/datamodel_vm.ml | 8 -------- 3 files changed, 1 insertion(+), 55 deletions(-) diff --git a/ocaml/idl/datamodel.ml b/ocaml/idl/datamodel.ml index b72087fb432..6677c88009c 100644 --- a/ocaml/idl/datamodel.ml +++ b/ocaml/idl/datamodel.ml @@ -526,8 +526,7 @@ module Task = struct ; ("XenCenterUUID", _R_VM_OP) ; ("XenCenterMeddlingActionTitle", _R_VM_OP) ] - ; (* field ~ty:(Set(Ref _alert)) ~in_product_since:rel_miami ~qualifier:DynamicRO "alerts" "all alerts related to this task"; *) - field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando ~default_value:(Some (VRef "")) ~ty:(Ref _task) "subtask_of" "Ref pointing to the task this is a substask of." ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando @@ -4077,21 +4076,6 @@ module LVHD = struct () end -(* --- rws: removed this after talking to Andy and Julian - let filesystem = - { name = _filesystem; description = "An on-disk filesystem"; - messages = []; - contents = - field "uuid" "globally-unique ID" :: - let field ?(ty=Int) = field ~qualifier:DynamicRO ~ty in - [ field "block_size" "block size"; - field "total_blocks" "total blocks on disk"; - field "available_blocks" "blocks available for allocation"; - field "used_blocks" "blocks already in use"; - field "percentage_free" "Percentage of free space left in filesystem"; - field ~ty:String "type" "filesystem type" ] } -*) - module Vdi_nbd_server_info = struct let t = let lifecycle = [(Published, rel_inverness, "")] in @@ -7510,25 +7494,6 @@ module Secret = struct () end -(* - -let alert = - create_obj ~in_product_since:rel_miami ~in_oss_since:None ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_alert ~descr:"Notification information" - ~gen_events:true - ~doccomments:[] - ~messages: [] - ~contents: - [ - uid ~in_oss_since:None _alert; - field ~in_oss_since:None ~qualifier:StaticRO ~ty:String "message" "description of the alert"; - field ~in_oss_since:None ~qualifier:StaticRO ~ty:(Map (String, String)) ~default_value:(Some (VMap [])) "params" "parameters of the alert"; - field ~in_oss_since:None ~qualifier:StaticRO ~ty:alert_level "level" "level of importance (info/warning/error/critical)"; - field ~in_oss_since:None ~qualifier:DynamicRO ~ty:Bool "system" "system task"; - field ~in_oss_since:None ~qualifier:DynamicRO ~ty:(Ref _task) "task" "task related to this alert (null reference if there's no task associated)"; - ] - () -*) - (** network sriov **) module Network_sriov = struct let lifecycle = [(Published, rel_kolkata, "")] diff --git a/ocaml/idl/datamodel_host.ml b/ocaml/idl/datamodel_host.ml index 76508745467..669ffeab248 100644 --- a/ocaml/idl/datamodel_host.ml +++ b/ocaml/idl/datamodel_host.ml @@ -209,17 +209,6 @@ let ha_wait_for_shutdown_via_statefile = ~pool_internal:true ~hide_from_docs:true ~allowed_roles:_R_LOCAL_ROOT_ONLY () -(* -let host_query_ha = call ~flags:[`Session] - ~in_product_since:rel_miami - ~name:"query_ha" - ~doc:"Return the local HA configuration as seen by this host" - ~params:[] - ~custom_marshaller:true - ~pool_internal:true - ~hide_from_docs:true - () -*) let request_backup = call ~flags:[`Session] ~name:"request_backup" ~lifecycle: diff --git a/ocaml/idl/datamodel_vm.ml b/ocaml/idl/datamodel_vm.ml index 8a5120ca679..69bae5f43d9 100644 --- a/ocaml/idl/datamodel_vm.ml +++ b/ocaml/idl/datamodel_vm.ml @@ -83,14 +83,6 @@ let guest_memory = ~doc_tags:[Memory] ] -(* -let power_behaviour = - Enum ("power_behaviour", [ "destroy", "destroy the VM state"; - "restart", "automatically restart the VM"; - "preserve", "leave VM running"; - "rename_restart", "leave VM running and restart a new one" ]) -*) - (** Action to take on guest reboot/power off/sleep etc *) let on_crash_behaviour = Enum From b1ac9f2da25de5c4fbde5876a995948c5bbae709 Mon Sep 17 00:00:00 2001 From: Andrii Sultanov Date: Mon, 23 Sep 2024 14:13:23 +0100 Subject: [PATCH 4/8] idl: Remove in_product_since and internal_deprecated_since parameters for create_obj These were already being replaced with lifecycle equivalents in datamodel_common, search and replace them all and remove parameters as such. Signed-off-by: Andrii Sultanov --- ocaml/idl/datamodel.ml | 294 ++++++++++++++++++++--------- ocaml/idl/datamodel_common.ml | 21 +-- ocaml/idl/datamodel_diagnostics.ml | 9 +- ocaml/idl/datamodel_host.ml | 9 +- ocaml/idl/datamodel_pool.ml | 9 +- ocaml/idl/datamodel_vm.ml | 4 +- 6 files changed, 224 insertions(+), 122 deletions(-) diff --git a/ocaml/idl/datamodel.ml b/ocaml/idl/datamodel.ml index 6677c88009c..88341f3f6b2 100644 --- a/ocaml/idl/datamodel.ml +++ b/ocaml/idl/datamodel.ml @@ -235,9 +235,11 @@ module Session = struct ~in_oss_since:None ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistNothing ~gen_constructor_destructor:false ~name:_session - ~descr:"A session" ~gen_events:false ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A session")] + ~in_oss_since:oss_since_303 ~persist:PersistNothing + ~gen_constructor_destructor:false ~name:_session ~descr:"A session" + ~gen_events:false ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_ADMIN ~messages: [ @@ -447,8 +449,10 @@ module Task = struct Enum ("task_allowed_operations", List.map operation_enum [cancel; destroy]) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistNothing ~gen_constructor_destructor:false ~name:_task + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A long-running asynchronous task")] + ~in_oss_since:oss_since_303 ~persist:PersistNothing + ~gen_constructor_destructor:false ~name:_task ~descr:"A long-running asynchronous task" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages: @@ -570,7 +574,7 @@ let iobandwidth = module User = struct let t = (* DEPRECATED in favor of subject *) - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 + create_obj ~in_db:true ~in_oss_since:oss_since_303 ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_user ~descr:"A user of the system" ~gen_events:false ~lifecycle: @@ -632,9 +636,10 @@ module Host_crashdump = struct ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false - ~name:_host_crashdump ~gen_events:true + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "Represents a host crash dump")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_host_crashdump ~gen_events:true ~descr:"Represents a host crash dump" ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[destroy; upload] ~contents: @@ -816,9 +821,11 @@ module Pool_update = struct ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_ely ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false - ~gen_events:true ~name:_pool_update + create_obj ~in_db:true + ~lifecycle: + [(Published, rel_ely, "Pool-wide updates to the host software")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~gen_events:true ~name:_pool_update ~descr:"Pool-wide updates to the host software" ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages: @@ -1018,8 +1025,10 @@ module Pool_patch = struct ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_miami ~in_oss_since:None - ~internal_deprecated_since:(Some rel_ely) ~persist:PersistEverything + create_obj ~in_db:true + ~lifecycle: + [(Published, rel_miami, "Pool-wide patches"); (Deprecated, rel_ely, "")] + ~in_oss_since:None ~persist:PersistEverything ~gen_constructor_destructor:false ~gen_events:true ~name:_pool_patch ~descr:"Pool-wide patches" ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP @@ -1094,8 +1103,13 @@ module Host_patch = struct ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:None - ~internal_deprecated_since:(Some rel_ely) ~persist:PersistEverything + create_obj ~in_db:true + ~lifecycle: + [ + (Published, rel_rio, "Represents a patch stored on a server") + ; (Deprecated, rel_ely, "") + ] + ~in_oss_since:None ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_host_patch ~gen_events:true ~descr:"Represents a patch stored on a server" ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[destroy; apply] @@ -1145,11 +1159,12 @@ module Host_metrics = struct ] let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:false - ~name:_host_metrics ~descr:"The metrics associated with a host" - ~gen_events:true ~doccomments:[] - ~messages_default_allowed_roles:_R_POOL_OP ~messages:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "The metrics associated with a host")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_host_metrics + ~descr:"The metrics associated with a host" ~gen_events:true + ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[] ~contents: [ uid _host_metrics @@ -1169,7 +1184,7 @@ end module Host_cpu = struct let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 + create_obj ~in_db:true ~in_oss_since:oss_since_303 ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_hostcpu ~descr:"A physical CPU" ~gen_events:true ~lifecycle: @@ -1500,9 +1515,11 @@ module Network = struct (** A virtual network *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_network - ~descr:"A virtual network" ~gen_events:true ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A virtual network")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_network ~descr:"A virtual network" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_VM_ADMIN (* vm admins can create/destroy networks without PIFs *) ~doc_tags:[Networking] @@ -2074,8 +2091,17 @@ module PIF = struct ) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_pif + create_obj ~in_db:true + ~lifecycle: + [ + ( Published + , rel_rio + , "A physical network interface (note separate VLANs are represented \ + as several PIFs)" + ) + ] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_pif ~descr: "A physical network interface (note separate VLANs are represented as \ several PIFs)" @@ -2256,9 +2282,16 @@ end module PIF_metrics = struct let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:false - ~name:_pif_metrics + create_obj ~in_db:true + ~lifecycle: + [ + ( Published + , rel_rio + , "The metrics associated with a physical network interface" + ) + ] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_pif_metrics ~descr:"The metrics associated with a physical network interface" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~doc_tags:[Networking] @@ -2379,8 +2412,17 @@ module Bond = struct ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_miami ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_bond + create_obj ~in_db:true + ~lifecycle: + [ + ( Published + , rel_miami + , "A Network bond that combines physical network interfaces, also \ + known as link aggregation" + ) + ] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_bond ~descr: "A Network bond that combines physical network interfaces, also known \ as link aggregation" @@ -2496,9 +2538,11 @@ module VLAN = struct ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_miami ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_vlan - ~descr:"A VLAN mux/demux" ~gen_events:true ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_miami, "A VLAN mux/demux")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_vlan ~descr:"A VLAN mux/demux" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~doc_tags:[Networking] ~messages:[pool_introduce; create; destroy] ~contents: @@ -2661,8 +2705,16 @@ module PBD = struct ~doc:"Sets the PBD's device_config field" ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_pbd + create_obj ~in_db:true + ~lifecycle: + [ + ( Published + , rel_rio + , "The physical block devices through which hosts access SRs" + ) + ] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_pbd ~descr:"The physical block devices through which hosts access SRs" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP @@ -3043,8 +3095,10 @@ module VIF = struct (** A virtual network interface *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_vif + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A virtual network interface")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_vif ~descr:"A virtual network interface" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_VM_ADMIN ~doc_tags:[Networking] ~messages: @@ -3177,11 +3231,12 @@ end module Data_source = struct let t = - create_obj ~in_db:false ~in_product_since:rel_orlando ~in_oss_since:None - ~persist:PersistNothing ~gen_constructor_destructor:false - ~name:_data_source ~descr:"Data sources for logging in RRDs" - ~gen_events:false ~doccomments:[] - ~messages_default_allowed_roles:_R_POOL_ADMIN ~messages:[] + create_obj ~in_db:false + ~lifecycle:[(Published, rel_orlando, "Data sources for logging in RRDs")] + ~in_oss_since:None ~persist:PersistNothing + ~gen_constructor_destructor:false ~name:_data_source + ~descr:"Data sources for logging in RRDs" ~gen_events:false + ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_ADMIN ~messages:[] ~contents: [ namespace ~name:"name" ~contents:(names oss_since_303 DynamicRO) () @@ -3856,9 +3911,11 @@ module SR = struct (** A storage repository. Note we overide default create/destroy methods with our own here... *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_sr - ~descr:"A storage repository" ~gen_events:true ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A storage repository")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_sr ~descr:"A storage repository" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages: [ @@ -3972,8 +4029,10 @@ module SM = struct ~doc:"Gets the SM's driver_filename field" () let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_sm + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A storage manager plugin")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_sm ~descr:"A storage manager plugin" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[] ~contents: @@ -4067,8 +4126,10 @@ module LVHD = struct () let t = - create_obj ~in_db:true ~in_product_since:rel_dundee ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_lvhd + create_obj ~in_db:true + ~lifecycle:[(Published, rel_dundee, "LVHD SR specific operations")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_lvhd ~descr:"LVHD SR specific operations" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_ADMIN ~messages:[enable_thin_provisioning] @@ -5077,9 +5138,11 @@ module VDI = struct (** A virtual disk *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_vdi - ~descr:"A virtual disk image" ~gen_events:true ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A virtual disk image")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_vdi ~descr:"A virtual disk image" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_VM_ADMIN ~messages: [ @@ -5459,8 +5522,10 @@ module VBD = struct (** A virtual disk interface *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_vbd + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A virtual block device")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_vbd ~descr:"A virtual block device" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_VM_ADMIN ~messages: @@ -5591,8 +5656,12 @@ module Crashdump = struct (** A crashdump for a particular VM, stored in a particular VDI *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:None - ~internal_deprecated_since:(Some rel_inverness) ~persist:PersistEverything + create_obj ~in_db:true + ~lifecycle: + [ + (Published, rel_rio, "A VM crashdump"); (Deprecated, rel_inverness, "") + ] + ~in_oss_since:None ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_crashdump ~descr:"A VM crashdump" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[destroy] @@ -5702,8 +5771,13 @@ module Auth = struct ~allowed_roles:_R_READ_ONLY () let t = - create_obj ~in_db:false ~in_product_since:rel_george ~in_oss_since:None - ~persist:PersistNothing ~gen_constructor_destructor:false ~name:_auth + create_obj ~in_db:false + ~lifecycle: + [ + (Published, rel_george, "Management of remote authentication services") + ] + ~in_oss_since:None ~persist:PersistNothing + ~gen_constructor_destructor:false ~name:_auth ~descr:"Management of remote authentication services" ~gen_events:false ~doccomments:[] ~messages_default_allowed_roles:_R_READ_ONLY ~messages: @@ -5779,8 +5853,11 @@ module Subject = struct (* a subject is a user/group that can log in xapi *) let t = - create_obj ~in_db:true ~in_product_since:rel_george ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_subject + create_obj ~in_db:true + ~lifecycle: + [(Published, rel_george, "A user or group that can log in xapi")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_subject ~descr:"A user or group that can log in xapi" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_ADMIN ~messages:[add_to_roles; remove_from_roles; get_permissions_name_label] @@ -5872,9 +5949,16 @@ module Role = struct (* - basic role: is the 1x1 mapping to each XAPI/HTTP call being protected, a leaf in the tree of roles *) (* - intermediate role: an intermediate node in the recursive tree of roles, usually not meant to the end-user *) let t = - create_obj ~in_db:true ~in_product_since:rel_midnight_ride - ~in_oss_since:None ~internal_deprecated_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_role + create_obj ~in_db:true + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "A set of permissions associated with a subject" + ) + ] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_role ~descr:"A set of permissions associated with a subject" ~gen_events:true ~force_custom_actions:(Some StaticRO) (* force custom actions for getters *) @@ -5927,9 +6011,11 @@ module Console = struct (** A virtual console device *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_console - ~descr:"A console" ~gen_events:true ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A console")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_console ~descr:"A console" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_VM_ADMIN ~messages:[] ~contents: [ @@ -5986,10 +6072,11 @@ module VM_metrics = struct ] let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:false - ~name:_vm_metrics ~descr:"The metrics associated with a VM" - ~gen_events:true ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "The metrics associated with a VM")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_vm_metrics + ~descr:"The metrics associated with a VM" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_VM_ADMIN ~messages:[] ~contents: [ @@ -6048,9 +6135,17 @@ module VM_guest_metrics = struct (* Some of this stuff needs to persist (like PV drivers vsns etc.) so we know about what's likely to be in the VM even when it's off. Other things don't need to persist, so we specify these on a per-field basis *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:false - ~name:_vm_guest_metrics + create_obj ~in_db:true + ~lifecycle: + [ + ( Published + , rel_rio + , "The metrics reported by the guest (as opposed to inferred from \ + outside)" + ) + ] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_vm_guest_metrics ~descr: "The metrics reported by the guest (as opposed to inferred from \ outside)" @@ -6728,11 +6823,11 @@ module VMSS = struct () let t = - create_obj ~in_db:true ~in_oss_since:None ~internal_deprecated_since:None - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_vmss - ~descr:"VM Snapshot Schedule" ~gen_events:true - ~in_product_since:rel_falcon ~doccomments:[] - ~messages_default_allowed_roles:_R_POOL_OP + create_obj ~in_db:true ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_vmss ~descr:"VM Snapshot Schedule" + ~gen_events:true + ~lifecycle:[(Published, rel_falcon, "VM Snapshot Schedule")] + ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages: [ snapshot_now @@ -6917,9 +7012,11 @@ module VM_appliance = struct ~doc:"Recover the VM appliance" ~allowed_roles:_R_READ_ONLY () let t = - create_obj ~in_db:true ~in_product_since:rel_boston ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:true - ~name:_vm_appliance ~descr:"VM appliance" ~gen_events:true ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_boston, "VM appliance")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_vm_appliance ~descr:"VM appliance" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages: [ @@ -6988,9 +7085,11 @@ module DR_task = struct ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_boston ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false - ~name:_dr_task ~descr:"DR task" ~gen_events:true ~doccomments:[] + create_obj ~in_db:true + ~lifecycle:[(Published, rel_boston, "DR task")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_dr_task ~descr:"DR task" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[create; destroy] ~contents: [ @@ -7262,8 +7361,10 @@ module Blob = struct ~flags:[`Session] ~allowed_roles:_R_POOL_OP () let t = - create_obj ~in_db:true ~in_product_since:rel_orlando ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_blob + create_obj ~in_db:true + ~lifecycle:[(Published, rel_orlando, "A placeholder for a binary blob")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_blob ~descr:"A placeholder for a binary blob" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[create; destroy] ~contents: @@ -7401,10 +7502,18 @@ module Message = struct ~allowed_roles:_R_READ_ONLY () let t = - create_obj ~in_db:false ~in_product_since:rel_orlando ~in_oss_since:None - ~persist:PersistNothing ~gen_constructor_destructor:false ~name:_message + create_obj ~in_db:false + ~lifecycle: + [ + ( Published + , rel_orlando + , "An message for the attention of the administrator" + ) + ] + ~in_oss_since:None ~persist:PersistNothing + ~gen_constructor_destructor:false ~name:_message ~descr:"An message for the attention of the administrator" - ~gen_events:true ~doccomments:[] ~internal_deprecated_since:None + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages: [ @@ -7477,7 +7586,8 @@ module Secret = struct let t = create_obj ~descr:"A secret" ~doccomments:[] ~gen_constructor_destructor:true ~gen_events:false ~in_db:true - ~in_oss_since:None ~in_product_since:rel_midnight_ride + ~in_oss_since:None + ~lifecycle:[(Published, rel_midnight_ride, "A secret")] ~messages:[introduce] ~messages_default_allowed_roles:_R_POOL_OP ~implicit_messages_allowed_roles:_R_POOL_OP ~name:_secret ~persist:PersistEverything diff --git a/ocaml/idl/datamodel_common.ml b/ocaml/idl/datamodel_common.ml index 07ea70f90a4..3ee1bcebd99 100644 --- a/ocaml/idl/datamodel_common.ml +++ b/ocaml/idl/datamodel_common.ml @@ -792,8 +792,7 @@ let default_field_writer_roles = _R_POOL_ADMIN (* by default, only root can write to them *) (** Create an object and map the object name into the messages *) -let create_obj ?lifecycle ~in_oss_since ?in_product_since - ?(internal_deprecated_since = None) ~gen_constructor_destructor ~gen_events +let create_obj ?lifecycle ~in_oss_since ~gen_constructor_destructor ~gen_events ~persist ~name ~descr ~doccomments ~contents ~messages ~in_db ?(contents_default_reader_roles = default_field_reader_roles) ?(contents_default_writer_roles = None) @@ -844,26 +843,10 @@ let create_obj ?lifecycle ~in_oss_since ?in_product_since ) contents in - if lifecycle = None && in_product_since = None then - failwith ("Lifecycle for class '" ^ name ^ "' not specified") ; let lifecycle = match lifecycle with | None -> - let published = - match in_product_since with - | None -> - [] - | Some rel -> - [(Published, rel, descr)] - in - let deprecated = - match internal_deprecated_since with - | None -> - [] - | Some rel -> - [(Deprecated, rel, "")] - in - published @ deprecated + failwith ("Lifecycle for class '" ^ name ^ "' not specified") | Some l -> l in diff --git a/ocaml/idl/datamodel_diagnostics.ml b/ocaml/idl/datamodel_diagnostics.ml index b81d12ca905..2abcfcdc7ba 100644 --- a/ocaml/idl/datamodel_diagnostics.ml +++ b/ocaml/idl/datamodel_diagnostics.ml @@ -58,7 +58,14 @@ let network_stats = () let t = - create_obj ~in_db:false ~in_product_since:Datamodel_types.rel_stockholm + create_obj ~in_db:false + ~lifecycle: + [ + ( Published + , Datamodel_types.rel_stockholm + , "A set of functions for diagnostic purpose" + ) + ] ~in_oss_since:None ~persist:PersistNothing ~gen_constructor_destructor:false ~name:_diagnostics ~descr:"A set of functions for diagnostic purpose" ~gen_events:false ~doccomments:[] diff --git a/ocaml/idl/datamodel_host.ml b/ocaml/idl/datamodel_host.ml index 669ffeab248..c6648b0b9b4 100644 --- a/ocaml/idl/datamodel_host.ml +++ b/ocaml/idl/datamodel_host.ml @@ -2314,10 +2314,11 @@ let latest_synced_updates_applied_state = (** Hosts *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_host - ~descr:"A physical host" ~gen_events:true ~doccomments:[] - ~messages_default_allowed_roles:_R_POOL_OP + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "A physical host")] + ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_host ~descr:"A physical host" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages: [ disable diff --git a/ocaml/idl/datamodel_pool.ml b/ocaml/idl/datamodel_pool.ml index d13858363ab..f9b0de3d65c 100644 --- a/ocaml/idl/datamodel_pool.ml +++ b/ocaml/idl/datamodel_pool.ml @@ -1509,10 +1509,11 @@ let get_guest_secureboot_readiness = (** A pool class *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:None - ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_pool - ~descr:"Pool-wide information" ~gen_events:true ~doccomments:[] - ~messages_default_allowed_roles:_R_POOL_OP + create_obj ~in_db:true + ~lifecycle:[(Published, rel_rio, "Pool-wide information")] + ~in_oss_since:None ~persist:PersistEverything + ~gen_constructor_destructor:false ~name:_pool ~descr:"Pool-wide information" + ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages: [ join diff --git a/ocaml/idl/datamodel_vm.ml b/ocaml/idl/datamodel_vm.ml index 69bae5f43d9..acbf67df3f8 100644 --- a/ocaml/idl/datamodel_vm.ml +++ b/ocaml/idl/datamodel_vm.ml @@ -2353,8 +2353,8 @@ let get_secureboot_readiness = (** VM (or 'guest') configuration: *) let t = - create_obj ~in_db:true ~in_product_since:rel_rio ~in_oss_since:oss_since_303 - ~persist:PersistEverything ~gen_constructor_destructor:true ~name:_vm + create_obj ~in_db:true ~in_oss_since:oss_since_303 ~persist:PersistEverything + ~gen_constructor_destructor:true ~name:_vm ~descr:"A virtual machine (or 'guest')." ~gen_events:true ~doccomments: [ From 3c857e14835ed216698cc4fe783b856e98bc9310 Mon Sep 17 00:00:00 2001 From: Andrii Sultanov Date: Tue, 24 Sep 2024 08:31:57 +0100 Subject: [PATCH 5/8] idl: Make lifecycle explicit for callers of 'names' This is the only commit in the series that changes the schematest hash, because previous implementation of names created two fields with different lifecycle descriptions, and when the callers are changed to provide an explicit lifecycle argument, the description is the same for both fields. It's been chosen to provide an empty description instead (since any actual description would be duplicated for both fields, further confusing matters), except for one case where it follows the rest of the class with 'lifecycle:removed'. Signed-off-by: Andrii Sultanov --- ocaml/idl/datamodel.ml | 72 +++++++++++++++++++++++++------ ocaml/idl/datamodel_host.ml | 4 +- ocaml/idl/datamodel_observer.ml | 4 +- ocaml/idl/datamodel_repository.ml | 7 ++- ocaml/idl/datamodel_vm.ml | 5 ++- ocaml/idl/datamodel_vm_group.ml | 4 +- ocaml/idl/schematest.ml | 2 +- 7 files changed, 78 insertions(+), 20 deletions(-) diff --git a/ocaml/idl/datamodel.ml b/ocaml/idl/datamodel.ml index 88341f3f6b2..1e813b17d1f 100644 --- a/ocaml/idl/datamodel.ml +++ b/ocaml/idl/datamodel.ml @@ -468,7 +468,13 @@ module Task = struct ~contents: ([ uid _task - ; namespace ~name:"name" ~contents:(names oss_since_303 DynamicRO) () + ; namespace ~name:"name" + ~contents: + (names + ~lifecycle:[(Published, rel_rio, "")] + oss_since_303 DynamicRO + ) + () ] @ allowed_and_current_operations task_allowed_operations @ [ @@ -843,7 +849,9 @@ module Pool_update = struct ~contents: [ uid ~in_oss_since:None _pool_update - ; namespace ~name:"name" ~contents:(names None StaticRO) () + ; namespace ~name:"name" + ~contents:(names None StaticRO ~lifecycle:[(Published, rel_rio, "")]) + () ; field ~in_product_since:rel_ely ~default_value:(Some (VString "")) ~in_oss_since:None ~qualifier:StaticRO ~ty:String "version" "Update version number" @@ -1037,7 +1045,9 @@ module Pool_patch = struct ~contents: [ uid ~in_oss_since:None _pool_patch - ; namespace ~name:"name" ~contents:(names None StaticRO) () + ; namespace ~name:"name" + ~contents:(names None StaticRO ~lifecycle:[(Published, rel_rio, "")]) + () ; field ~in_product_since:rel_miami ~default_value:(Some (VString "")) ~in_oss_since:None ~qualifier:StaticRO ~ty:String "version" "Patch version number" @@ -1116,7 +1126,9 @@ module Host_patch = struct ~contents: [ uid ~in_oss_since:None _host_patch - ; namespace ~name:"name" ~contents:(names None StaticRO) () + ; namespace ~name:"name" + ~contents:(names None StaticRO ~lifecycle:[(Published, rel_rio, "")]) + () ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO ~ty:String "version" "Patch version number" ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO @@ -1538,7 +1550,11 @@ module Network = struct ([ uid _network ; namespace ~name:"name" - ~contents:(names ~writer_roles:_R_POOL_OP oss_since_303 RW) + ~contents: + (names ~writer_roles:_R_POOL_OP + ~lifecycle:[(Published, rel_rio, "")] + oss_since_303 RW + ) () ] @ allowed_and_current_operations ~writer_roles:_R_POOL_OP operations @@ -3239,7 +3255,12 @@ module Data_source = struct ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_ADMIN ~messages:[] ~contents: [ - namespace ~name:"name" ~contents:(names oss_since_303 DynamicRO) () + namespace ~name:"name" + ~contents: + (names oss_since_303 DynamicRO + ~lifecycle:[(Published, rel_rio, "")] + ) + () ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio "enabled" "true if the data source is being logged" ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio @@ -3949,7 +3970,12 @@ module SR = struct ~contents: ([ uid _sr - ; namespace ~name:"name" ~contents:(names oss_since_303 StaticRO) () + ; namespace ~name:"name" + ~contents: + (names oss_since_303 StaticRO + ~lifecycle:[(Published, rel_rio, "")] + ) + () ] @ allowed_and_current_operations operations @ [ @@ -4038,7 +4064,10 @@ module SM = struct ~contents: [ uid _sm - ; namespace ~name:"name" ~contents:(names None DynamicRO) () + ; namespace ~name:"name" + ~contents: + (names None DynamicRO ~lifecycle:[(Published, rel_rio, "")]) + () ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:DynamicRO "type" "SR.type" ; field ~in_oss_since:None ~in_product_since:rel_rio @@ -5187,7 +5216,12 @@ module VDI = struct ~contents: ([ uid _vdi - ; namespace ~name:"name" ~contents:(names oss_since_303 StaticRO) () + ; namespace ~name:"name" + ~contents: + (names oss_since_303 StaticRO + ~lifecycle:[(Published, rel_rio, "")] + ) + () ] @ allowed_and_current_operations operations @ [ @@ -6633,7 +6667,7 @@ module VMPP = struct ~contents: [ uid ~lifecycle:removed _vmpp - ; namespace ~name:"name" ~contents:(names None RW) () + ; namespace ~name:"name" ~contents:(names None RW ~lifecycle:removed) () ; field ~lifecycle:removed ~qualifier:RW ~ty:Bool "is_policy_enabled" "enable or disable this policy" ~default_value:(Some (VBool true)) ; field ~lifecycle:removed ~qualifier:RW ~ty:backup_type "backup_type" @@ -6842,7 +6876,9 @@ module VMSS = struct ~contents: [ uid _vmss - ; namespace ~name:"name" ~contents:(names None RW) () + ; namespace ~name:"name" + ~contents:(names None RW ~lifecycle:[(Published, rel_rio, "")]) + () ; field ~qualifier:RW ~ty:Bool ~in_product_since:rel_rio "enabled" "enable or disable this snapshot schedule" ~default_value:(Some (VBool true)) @@ -7030,7 +7066,10 @@ module VM_appliance = struct ] ~contents: ([ - uid _vm_appliance; namespace ~name:"name" ~contents:(names None RW) () + uid _vm_appliance + ; namespace ~name:"name" + ~contents:(names None RW ~lifecycle:[(Published, rel_rio, "")]) + () ] @ allowed_and_current_operations operations @ [ @@ -7370,7 +7409,10 @@ module Blob = struct ~contents: [ uid _blob - ; namespace ~name:"name" ~contents:(names oss_since_303 RW) () + ; namespace ~name:"name" + ~contents: + (names oss_since_303 RW ~lifecycle:[(Published, rel_rio, "")]) + () ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "size" "Size of the binary data, in bytes" ; field ~writer_roles:_R_POOL_OP ~qualifier:RW @@ -8648,7 +8690,9 @@ module Feature = struct ~contents: [ uid _feature ~lifecycle:[(Published, rel_falcon, "")] - ; namespace ~name:"name" ~contents:(names None StaticRO) () + ; namespace ~name:"name" + ~contents:(names None StaticRO ~lifecycle:[(Published, rel_rio, "")]) + () ; field ~qualifier:DynamicRO ~ty:Bool ~lifecycle:[(Published, rel_falcon, "")] ~default_value:(Some (VBool false)) "enabled" diff --git a/ocaml/idl/datamodel_host.ml b/ocaml/idl/datamodel_host.ml index c6648b0b9b4..d34daafc08a 100644 --- a/ocaml/idl/datamodel_host.ml +++ b/ocaml/idl/datamodel_host.ml @@ -2454,7 +2454,9 @@ let t = ~contents: ([ uid _host - ; namespace ~name:"name" ~contents:(names None RW) () + ; namespace ~name:"name" + ~contents:(names None RW ~lifecycle:[(Published, rel_rio, "")]) + () ; namespace ~name:"memory" ~contents:host_memory () ] @ allowed_and_current_operations operations diff --git a/ocaml/idl/datamodel_observer.ml b/ocaml/idl/datamodel_observer.ml index 1d80d030a62..523c63aef7c 100644 --- a/ocaml/idl/datamodel_observer.ml +++ b/ocaml/idl/datamodel_observer.ml @@ -114,7 +114,9 @@ let t = ~contents: ([ uid _observer ~lifecycle:[] - ; namespace ~name:"name" ~contents:(names None RW) () + ; namespace ~name:"name" + ~contents:(names None RW ~lifecycle:[(Published, rel_rio, "")]) + () ] @ [ field ~qualifier:StaticRO ~ty:(Set (Ref _host)) ~lifecycle:[] "hosts" diff --git a/ocaml/idl/datamodel_repository.ml b/ocaml/idl/datamodel_repository.ml index 114242d913f..2142084c984 100644 --- a/ocaml/idl/datamodel_repository.ml +++ b/ocaml/idl/datamodel_repository.ml @@ -182,7 +182,12 @@ let t = [ uid _repository ~lifecycle:[(Published, "1.301.0", "")] ; namespace ~name:"name" - ~contents:(names ~writer_roles:(_R_POOL_OP ++ _R_CLIENT_CERT) None RW) + ~contents: + (names + ~writer_roles:(_R_POOL_OP ++ _R_CLIENT_CERT) + ~lifecycle:[(Published, rel_rio, "")] + None RW + ) () ; field ~qualifier:StaticRO ~lifecycle:[(Published, "1.301.0", "")] diff --git a/ocaml/idl/datamodel_vm.ml b/ocaml/idl/datamodel_vm.ml index acbf67df3f8..4815a29c1ce 100644 --- a/ocaml/idl/datamodel_vm.ml +++ b/ocaml/idl/datamodel_vm.ml @@ -2496,7 +2496,10 @@ let t = ([uid _vm] @ allowed_and_current_operations operations @ [ - namespace ~name:"name" ~contents:(names oss_since_303 RW) () + namespace ~name:"name" + ~contents: + (names oss_since_303 RW ~lifecycle:[(Published, rel_rio, "")]) + () ; field ~writer_roles:_R_VM_OP ~qualifier:StaticRO ~default_value:(Some (VEnum "Halted")) ~lifecycle: diff --git a/ocaml/idl/datamodel_vm_group.ml b/ocaml/idl/datamodel_vm_group.ml index 58016a31d0a..efc86791bd8 100644 --- a/ocaml/idl/datamodel_vm_group.ml +++ b/ocaml/idl/datamodel_vm_group.ml @@ -33,7 +33,9 @@ let t = ~contents: [ uid _vm_group - ; namespace ~name:"name" ~contents:(names None RW) () + ; namespace ~name:"name" + ~contents:(names ~lifecycle:[(Published, rel_rio, "")] None RW) + () ; field ~qualifier:StaticRO ~lifecycle:[] ~ty:placement_policy "placement" ~default_value:(Some (VEnum "normal")) "The placement policy of the VM group" diff --git a/ocaml/idl/schematest.ml b/ocaml/idl/schematest.ml index 611dc17f605..016a90960f3 100644 --- a/ocaml/idl/schematest.ml +++ b/ocaml/idl/schematest.ml @@ -3,7 +3,7 @@ let hash x = Digest.string x |> Digest.to_hex (* BEWARE: if this changes, check that schema has been bumped accordingly in ocaml/idl/datamodel_common.ml, usually schema_minor_vsn *) -let last_known_schema_hash = "5f1637f4ddfaa2a0dfb6cfc318451855" +let last_known_schema_hash = "8fcd8892ec0c7d130b0da44c5fd3990b" let current_schema_hash : string = let open Datamodel_types in From 9790ccb407e5e50d9a9f5721c31c99b6fd41f38b Mon Sep 17 00:00:00 2001 From: Andrii Sultanov Date: Tue, 24 Sep 2024 08:35:24 +0100 Subject: [PATCH 6/8] idl: Convert {in_product,internal_deprecated}_since parameters to lifecycle for fields These were already being replaced with lifecycle equivalents in datamodel_common, search and replace them all and remove parameters as such. Signed-off-by: Andrii Sultanov --- ocaml/idl/datamodel.ml | 2278 ++++++++++++++++++++++++------- ocaml/idl/datamodel_common.ml | 22 +- ocaml/idl/datamodel_host.ml | 307 ++++- ocaml/idl/datamodel_pool.ml | 343 ++++- ocaml/idl/datamodel_vm.ml | 556 ++++++-- ocaml/idl/datamodel_vm_group.ml | 2 + ocaml/idl/datamodel_vtpm.ml | 23 +- 7 files changed, 2837 insertions(+), 694 deletions(-) diff --git a/ocaml/idl/datamodel.ml b/ocaml/idl/datamodel.ml index 1e813b17d1f..22b918a8a52 100644 --- a/ocaml/idl/datamodel.ml +++ b/ocaml/idl/datamodel.ml @@ -257,56 +257,159 @@ module Session = struct ~contents: [ uid _session - ; field ~qualifier:DynamicRO ~ty:(Ref _host) ~in_product_since:rel_rio + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + ; field ~qualifier:DynamicRO ~ty:(Ref _host) + ~lifecycle:[(Published, rel_rio, "Currently connected host")] "this_host" "Currently connected host" - ; field ~qualifier:DynamicRO ~ty:(Ref _user) ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:(Ref _user) + ~lifecycle:[(Published, rel_rio, "Currently connected user")] "this_user" "Currently connected user" - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [ + ( Published + , rel_rio + , "Timestamp for last time session was active" + ) + ] "last_active" "Timestamp for last time session was active" ; field ~qualifier:DynamicRO ~ty:Bool ~in_oss_since:None - ~in_product_since:rel_rio "pool" + ~lifecycle: + [ + ( Published + , rel_rio + , "True if this session relates to a intra-pool login, false \ + otherwise" + ) + ] + "pool" "True if this session relates to a intra-pool login, false \ otherwise" - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" - ; field ~in_product_since:rel_george ~qualifier:DynamicRO - ~default_value:(Some (VBool false)) ~ty:Bool "is_local_superuser" + ; field + ~lifecycle: + [ + ( Published + , rel_george + , "true iff this session was created using local superuser \ + credentials" + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VBool false)) ~ty:Bool + "is_local_superuser" "true iff this session was created using local superuser \ credentials" - ; field ~in_product_since:rel_george ~qualifier:DynamicRO - ~default_value:(Some (VRef null_ref)) ~ty:(Ref _subject) "subject" + ; field + ~lifecycle: + [ + ( Published + , rel_george + , "references the subject instance that created the session. \ + If a session instance has is_local_superuser set, then the \ + value of this field is undefined." + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VRef null_ref)) + ~ty:(Ref _subject) "subject" "references the subject instance that created the session. If a \ session instance has is_local_superuser set, then the value of \ this field is undefined." - ; field ~in_product_since:rel_george ~qualifier:DynamicRO - ~default_value:(Some (VDateTime Date.epoch)) ~ty:DateTime - "validation_time" "time when session was last validated" - ; field ~in_product_since:rel_george ~qualifier:DynamicRO - ~default_value:(Some (VString "")) ~ty:String "auth_user_sid" + ; field + ~lifecycle: + [(Published, rel_george, "time when session was last validated")] + ~qualifier:DynamicRO ~default_value:(Some (VDateTime Date.epoch)) + ~ty:DateTime "validation_time" + "time when session was last validated" + ; field + ~lifecycle: + [ + ( Published + , rel_george + , "the subject identifier of the user that was externally \ + authenticated. If a session instance has is_local_superuser \ + set, then the value of this field is undefined." + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VString "")) ~ty:String + "auth_user_sid" "the subject identifier of the user that was externally \ authenticated. If a session instance has is_local_superuser set, \ then the value of this field is undefined." - ; field ~in_product_since:rel_midnight_ride ~qualifier:DynamicRO - ~default_value:(Some (VString "")) ~ty:String "auth_user_name" + ; field + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "the subject name of the user that was externally \ + authenticated. If a session instance has is_local_superuser \ + set, then the value of this field is undefined." + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VString "")) ~ty:String + "auth_user_name" "the subject name of the user that was externally authenticated. \ If a session instance has is_local_superuser set, then the value \ of this field is undefined." - ; field ~in_product_since:rel_midnight_ride ~qualifier:StaticRO - ~default_value:(Some (VSet [])) ~ty:(Set String) "rbac_permissions" - "list with all RBAC permissions for this session" - ; field ~in_product_since:rel_midnight_ride ~qualifier:DynamicRO - ~ty:(Set (Ref _task)) "tasks" + ; field + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "list with all RBAC permissions for this session" + ) + ] + ~qualifier:StaticRO ~default_value:(Some (VSet [])) ~ty:(Set String) + "rbac_permissions" "list with all RBAC permissions for this session" + ; field + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "list of tasks created using the current session" + ) + ] + ~qualifier:DynamicRO ~ty:(Set (Ref _task)) "tasks" "list of tasks created using the current session" - ; field ~in_product_since:rel_midnight_ride ~qualifier:StaticRO - ~default_value:(Some (VRef null_ref)) ~ty:(Ref _session) "parent" + ; field + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "references the parent session that created this session" + ) + ] + ~qualifier:StaticRO ~default_value:(Some (VRef null_ref)) + ~ty:(Ref _session) "parent" "references the parent session that created this session" - ; field ~in_product_since:rel_clearwater ~qualifier:DynamicRO - ~default_value:(Some (VString "")) ~ty:String "originator" + ; field + ~lifecycle: + [ + ( Published + , rel_clearwater + , "a key string provided by a API user to distinguish itself \ + from other users sharing the same login name" + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VString "")) ~ty:String + "originator" "a key string provided by a API user to distinguish itself from \ other users sharing the same login name" - ; field ~in_product_since:"21.2.0" ~qualifier:DynamicRO - ~default_value:(Some (VBool false)) ~ty:Bool "client_certificate" + ; field + ~lifecycle: + [ + ( Published + , "21.2.0" + , "indicates whether this session was authenticated using a \ + client certificate" + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VBool false)) ~ty:Bool + "client_certificate" "indicates whether this session was authenticated using a client \ certificate" ] @@ -468,6 +571,8 @@ module Task = struct ~contents: ([ uid _task + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] ; namespace ~name:"name" ~contents: (names @@ -478,56 +583,142 @@ module Task = struct ] @ allowed_and_current_operations task_allowed_operations @ [ - field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle:[(Published, rel_rio, "Time task was created")] "created" "Time task was created" - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [ + ( Published + , rel_rio + , "Time task finished (i.e. succeeded or failed). If \ + task-status is pending, then the value of this field has \ + no meaning" + ) + ] "finished" "Time task finished (i.e. succeeded or failed). If task-status \ is pending, then the value of this field has no meaning" - ; field ~qualifier:DynamicRO ~ty:status_type ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:status_type + ~lifecycle:[(Published, rel_rio, "current status of the task")] "status" "current status of the task" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "the session that created the task")] ~internal_only:true ~qualifier:DynamicRO ~ty:(Ref _session) "session" "the session that created the task" - ; field ~qualifier:DynamicRO ~ty:(Ref _host) ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:(Ref _host) + ~lifecycle: + [(Published, rel_rio, "the host on which the task is running")] "resident_on" "the host on which the task is running" - ; field ~qualifier:DynamicRO ~ty:Float ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Float + ~lifecycle: + [ + ( Published + , rel_rio + , "This field contains the estimated fraction of the task \ + which is complete. This field should not be used to \ + determine whether the task is complete - for this the \ + status field of the task should be used." + ) + ] "progress" "This field contains the estimated fraction of the task which is \ complete. This field should not be used to determine whether \ the task is complete - for this the status field of the task \ should be used." - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "If the task has spawned a program, the field record the \ + PID of the process that the task is waiting on. (-1 if no \ + waiting completion of an external program )" + ) + ] ~internal_only:true ~qualifier:DynamicRO ~ty:Int "externalpid" "If the task has spawned a program, the field record the PID of \ the process that the task is waiting on. (-1 if no waiting \ completion of an external program )" - ; field ~in_oss_since:None ~in_product_since:rel_rio - ~internal_deprecated_since:rel_boston ~internal_only:true - ~qualifier:DynamicRO ~ty:Int "stunnelpid" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "If the task has been forwarded, this field records the \ + pid of the stunnel process spawned to manage the \ + forwarding connection" + ) + ; (Deprecated, rel_boston, "") + ] + ~internal_only:true ~qualifier:DynamicRO ~ty:Int "stunnelpid" "If the task has been forwarded, this field records the pid of \ the stunnel process spawned to manage the forwarding connection" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "True if this task has been forwarded to a slave" + ) + ] ~internal_only:true ~qualifier:DynamicRO ~ty:Bool "forwarded" "True if this task has been forwarded to a slave" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "The host to which the task has been forwarded" + ) + ] ~internal_only:true ~qualifier:DynamicRO ~ty:(Ref _host) "forwarded_to" "The host to which the task has been forwarded" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle: + [ + ( Published + , rel_rio + , "if the task has completed successfully, this field \ + contains the type of the encoded result (i.e. name of the \ + class whose reference is in the result field). Undefined \ + otherwise." + ) + ] "type" "if the task has completed successfully, this field contains the \ type of the encoded result (i.e. name of the class whose \ reference is in the result field). Undefined otherwise." - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle: + [ + ( Published + , rel_rio + , "if the task has completed successfully, this field \ + contains the result value (either Void or an object \ + reference). Undefined otherwise." + ) + ] "result" "if the task has completed successfully, this field contains the \ result value (either Void or an object reference). Undefined \ otherwise." ; field ~qualifier:DynamicRO ~ty:(Set String) - ~in_product_since:rel_rio "error_info" + ~lifecycle: + [ + ( Published + , rel_rio + , "if the task has failed, this field contains the set of \ + associated error strings. Undefined otherwise." + ) + ] + "error_info" "if the task has failed, this field contains the set of \ associated error strings. Undefined otherwise." - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ~map_keys_roles: @@ -536,13 +727,27 @@ module Task = struct ; ("XenCenterUUID", _R_VM_OP) ; ("XenCenterMeddlingActionTitle", _R_VM_OP) ] - ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_orlando + , "Ref pointing to the task this is a substask of." + ) + ] ~default_value:(Some (VRef "")) ~ty:(Ref _task) "subtask_of" "Ref pointing to the task this is a substask of." - ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + (Published, rel_orlando, "List pointing to all the substasks.") + ] ~ty:(Set (Ref _task)) "subtasks" "List pointing to all the substasks." - ; field ~qualifier:DynamicRO ~in_product_since:rel_dundee ~ty:String + ; field ~qualifier:DynamicRO + ~lifecycle: + [(Published, rel_dundee, "Function call trace for debugging.")] + ~ty:String ~default_value: (Some (VString (Sexplib0.Sexp.to_string Backtrace.(sexp_of_t empty)) @@ -592,10 +797,17 @@ module User = struct ~contents: [ uid _user - ; field ~qualifier:StaticRO ~in_product_since:rel_rio "short_name" - "short name (e.g. userid)" - ; field ~in_product_since:rel_rio "fullname" "full name" - ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + ; field ~qualifier:StaticRO + ~lifecycle:[(Published, rel_rio, "short name (e.g. userid)")] + "short_name" "short name (e.g. userid)" + ; field + ~lifecycle:[(Published, rel_rio, "full name")] + "fullname" "full name" + ; field + ~lifecycle:[(Published, rel_orlando, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -650,18 +862,27 @@ module Host_crashdump = struct ~messages_default_allowed_roles:_R_POOL_OP ~messages:[destroy; upload] ~contents: [ - uid ~in_oss_since:None _host_crashdump - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO - ~ty:(Ref _host) "host" "Host the crashdump relates to" - ; field ~in_oss_since:None ~in_product_since:rel_rio + uid ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _host_crashdump + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Host the crashdump relates to")] + ~qualifier:StaticRO ~ty:(Ref _host) "host" + "Host the crashdump relates to" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Time the crash happened")] ~qualifier:DynamicRO ~ty:DateTime "timestamp" "Time the crash happened" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Size of the crashdump")] ~qualifier:DynamicRO ~ty:Int "size" "Size of the crashdump" ; field ~qualifier:StaticRO ~ty:String ~in_oss_since:None - ~in_product_since:rel_rio ~internal_only:true "filename" - "filename of crash dir" - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ~lifecycle:[(Published, rel_rio, "filename of crash dir")] + ~internal_only:true "filename" "filename of crash dir" + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -848,34 +1069,61 @@ module Pool_update = struct ] ~contents: [ - uid ~in_oss_since:None _pool_update + uid ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _pool_update ; namespace ~name:"name" ~contents:(names None StaticRO ~lifecycle:[(Published, rel_rio, "")]) () - ; field ~in_product_since:rel_ely ~default_value:(Some (VString "")) - ~in_oss_since:None ~qualifier:StaticRO ~ty:String "version" - "Update version number" - ; field ~in_product_since:rel_ely + ; field + ~lifecycle:[(Published, rel_ely, "Update version number")] + ~default_value:(Some (VString "")) ~in_oss_since:None + ~qualifier:StaticRO ~ty:String "version" "Update version number" + ; field + ~lifecycle:[(Published, rel_ely, "Size of the update in bytes")] ~default_value:(Some (VInt Int64.zero)) ~in_oss_since:None ~qualifier:StaticRO ~ty:Int "installation_size" "Size of the update in bytes" - ; field ~in_product_since:rel_ely ~default_value:(Some (VString "")) - ~in_oss_since:None ~qualifier:StaticRO ~ty:String "key" - "GPG key of the update" - ; field ~in_product_since:rel_ely ~default_value:(Some (VSet [])) - ~in_oss_since:None ~qualifier:StaticRO - ~ty:(Set after_apply_guidance) "after_apply_guidance" + ; field + ~lifecycle:[(Published, rel_ely, "GPG key of the update")] + ~default_value:(Some (VString "")) ~in_oss_since:None + ~qualifier:StaticRO ~ty:String "key" "GPG key of the update" + ; field + ~lifecycle: + [ + ( Published + , rel_ely + , "What the client should do after this update has been \ + applied." + ) + ] + ~default_value:(Some (VSet [])) ~in_oss_since:None + ~qualifier:StaticRO ~ty:(Set after_apply_guidance) + "after_apply_guidance" "What the client should do after this update has been applied." - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO - ~ty:(Ref _vdi) "vdi" "VDI the update was uploaded to" - ; field ~in_product_since:rel_ely ~in_oss_since:None - ~qualifier:DynamicRO ~ty:(Set (Ref _host)) "hosts" - "The hosts that have applied this update." - ; field ~in_product_since:rel_inverness ~default_value:(Some (VMap [])) - ~in_oss_since:None + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "VDI the update was uploaded to")] + ~qualifier:StaticRO ~ty:(Ref _vdi) "vdi" + "VDI the update was uploaded to" + ; field + ~lifecycle: + [(Published, rel_ely, "The hosts that have applied this update.")] + ~in_oss_since:None ~qualifier:DynamicRO ~ty:(Set (Ref _host)) + "hosts" "The hosts that have applied this update." + ; field + ~lifecycle:[(Published, rel_inverness, "additional configuration")] + ~default_value:(Some (VMap [])) ~in_oss_since:None ~ty:(Map (String, String)) "other_config" "additional configuration" - ; field ~in_product_since:rel_inverness + ; field + ~lifecycle: + [ + ( Published + , rel_inverness + , "Flag - if true, all hosts in a pool must apply this update" + ) + ] ~default_value:(Some (VBool false)) ~in_oss_since:None ~qualifier:StaticRO ~ty:Bool "enforce_homogeneity" "Flag - if true, all hosts in a pool must apply this update" @@ -1044,34 +1292,68 @@ module Pool_patch = struct [apply; pool_apply; precheck; clean; pool_clean; destroy; clean_on_host] ~contents: [ - uid ~in_oss_since:None _pool_patch + uid ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _pool_patch ; namespace ~name:"name" ~contents:(names None StaticRO ~lifecycle:[(Published, rel_rio, "")]) () - ; field ~in_product_since:rel_miami ~default_value:(Some (VString "")) - ~in_oss_since:None ~qualifier:StaticRO ~ty:String "version" - "Patch version number" - ; field ~in_product_since:rel_miami ~default_value:(Some (VString "")) - ~in_oss_since:None ~internal_only:true ~qualifier:DynamicRO - ~ty:String "filename" "Filename of the patch" - ; field ~in_product_since:rel_miami + ; field + ~lifecycle:[(Published, rel_miami, "Patch version number")] + ~default_value:(Some (VString "")) ~in_oss_since:None + ~qualifier:StaticRO ~ty:String "version" "Patch version number" + ; field + ~lifecycle:[(Published, rel_miami, "Filename of the patch")] + ~default_value:(Some (VString "")) ~in_oss_since:None + ~internal_only:true ~qualifier:DynamicRO ~ty:String "filename" + "Filename of the patch" + ; field + ~lifecycle:[(Published, rel_miami, "Size of the patch")] ~default_value:(Some (VInt Int64.zero)) ~in_oss_since:None ~qualifier:DynamicRO ~ty:Int "size" "Size of the patch" - ; field ~in_product_since:rel_miami ~default_value:(Some (VBool false)) - ~in_oss_since:None ~qualifier:DynamicRO ~ty:Bool "pool_applied" + ; field + ~lifecycle: + [ + ( Published + , rel_miami + , "This patch should be applied across the entire pool" + ) + ] + ~default_value:(Some (VBool false)) ~in_oss_since:None + ~qualifier:DynamicRO ~ty:Bool "pool_applied" "This patch should be applied across the entire pool" - ; field ~in_product_since:rel_miami ~in_oss_since:None - ~qualifier:DynamicRO ~ty:(Set (Ref _host_patch)) "host_patches" - "This hosts this patch is applied to." - ; field ~in_product_since:rel_miami ~default_value:(Some (VSet [])) - ~in_oss_since:None ~qualifier:DynamicRO - ~ty:(Set after_apply_guidance) "after_apply_guidance" + ; field + ~lifecycle: + [(Published, rel_miami, "This hosts this patch is applied to.")] + ~in_oss_since:None ~qualifier:DynamicRO ~ty:(Set (Ref _host_patch)) + "host_patches" "This hosts this patch is applied to." + ; field + ~lifecycle: + [ + ( Published + , rel_miami + , "What the client should do after this patch has been applied." + ) + ] + ~default_value:(Some (VSet [])) ~in_oss_since:None + ~qualifier:DynamicRO ~ty:(Set after_apply_guidance) + "after_apply_guidance" "What the client should do after this patch has been applied." - ; field ~in_product_since:rel_ely ~default_value:(Some (VRef null_ref)) - ~in_oss_since:None ~qualifier:StaticRO ~ty:(Ref _pool_update) - "pool_update" "A reference to the associated pool_update object" - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) - ~in_oss_since:None + ; field + ~lifecycle: + [ + ( Published + , rel_ely + , "A reference to the associated pool_update object" + ) + ] + ~default_value:(Some (VRef null_ref)) ~in_oss_since:None + ~qualifier:StaticRO ~ty:(Ref _pool_update) "pool_update" + "A reference to the associated pool_update object" + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~in_oss_since:None ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -1125,29 +1407,43 @@ module Host_patch = struct ~messages_default_allowed_roles:_R_POOL_OP ~messages:[destroy; apply] ~contents: [ - uid ~in_oss_since:None _host_patch + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + ~in_oss_since:None _host_patch ; namespace ~name:"name" ~contents:(names None StaticRO ~lifecycle:[(Published, rel_rio, "")]) () - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO - ~ty:String "version" "Patch version number" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO - ~ty:(Ref _host) "host" "Host the patch relates to" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~internal_only:true - ~qualifier:DynamicRO ~ty:String "filename" "Filename of the patch" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Patch version number")] + ~qualifier:StaticRO ~ty:String "version" "Patch version number" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Host the patch relates to")] + ~qualifier:StaticRO ~ty:(Ref _host) "host" + "Host the patch relates to" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Filename of the patch")] + ~internal_only:true ~qualifier:DynamicRO ~ty:String "filename" + "Filename of the patch" + ; field ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "True if the patch has been applied")] ~qualifier:DynamicRO ~ty:Bool "applied" "True if the patch has been applied" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Time the patch was applied")] ~qualifier:DynamicRO ~ty:DateTime "timestamp_applied" "Time the patch was applied" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Size of the patch")] ~qualifier:DynamicRO ~ty:Int "size" "Size of the patch" - ; field ~in_product_since:rel_miami ~in_oss_since:None - ~qualifier:StaticRO ~ty:(Ref _pool_patch) + ; field + ~lifecycle:[(Published, rel_miami, "The patch applied")] + ~in_oss_since:None ~qualifier:StaticRO ~ty:(Ref _pool_patch) ~default_value:(Some (VRef "")) "pool_patch" "The patch applied" - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) - ~in_oss_since:None + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~in_oss_since:None ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -1158,8 +1454,9 @@ module Host_metrics = struct let host_metrics_memory = let field = field ~ty:Int in [ - field ~qualifier:DynamicRO ~in_product_since:rel_rio "total" - "Total host memory (bytes)" ~doc_tags:[Memory] + field ~qualifier:DynamicRO + ~lifecycle:[(Published, rel_rio, "Total host memory (bytes)")] + "total" "Total host memory (bytes)" ~doc_tags:[Memory] ; field "free" "Free host memory (bytes)" ~default_value:(Some (VInt 0L)) ~lifecycle: [ @@ -1179,13 +1476,27 @@ module Host_metrics = struct ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[] ~contents: [ - uid _host_metrics + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _host_metrics ; namespace ~name:"memory" ~contents:host_metrics_memory () ; field ~qualifier:DynamicRO ~ty:Bool ~in_oss_since:None "live" - ~in_product_since:rel_rio "Pool master thinks this host is live" - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ~lifecycle: + [(Published, rel_rio, "Pool master thinks this host is live")] + "Pool master thinks this host is live" + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [ + ( Published + , rel_rio + , "Time at which this information was last updated" + ) + ] "last_updated" "Time at which this information was last updated" - ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_orlando, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -1210,33 +1521,65 @@ module Host_cpu = struct ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_OP ~messages:[] ~contents: [ - uid _hostcpu - ; field ~qualifier:DynamicRO ~ty:(Ref _host) ~in_product_since:rel_rio + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _hostcpu + ; field ~qualifier:DynamicRO ~ty:(Ref _host) + ~lifecycle:[(Published, rel_rio, "the host the CPU is in")] "host" "the host the CPU is in" - ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "number" - "the number of the physical CPU within the host" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Int + ~lifecycle: + [ + ( Published + , rel_rio + , "the number of the physical CPU within the host" + ) + ] + "number" "the number of the physical CPU within the host" + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "the vendor of the physical CPU")] "vendor" "the vendor of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "speed" - "the speed of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Int + ~lifecycle:[(Published, rel_rio, "the speed of the physical CPU")] + "speed" "the speed of the physical CPU" + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle: + [(Published, rel_rio, "the model name of the physical CPU")] "modelname" "the model name of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "family" - "the family (number) of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "model" - "the model number of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Int + ~lifecycle: + [(Published, rel_rio, "the family (number) of the physical CPU")] + "family" "the family (number) of the physical CPU" + ; field ~qualifier:DynamicRO ~ty:Int + ~lifecycle: + [(Published, rel_rio, "the model number of the physical CPU")] + "model" "the model number of the physical CPU" + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle: + [(Published, rel_rio, "the stepping of the physical CPU")] "stepping" "the stepping of the physical CPU" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle: + [ + ( Published + , rel_rio + , "the flags of the physical CPU (a decoded version of the \ + features field)" + ) + ] "flags" "the flags of the physical CPU (a decoded version of the features \ field)" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "the physical CPU feature bitmap")] "features" "the physical CPU feature bitmap" ; field ~qualifier:DynamicRO ~persist:false ~ty:Float - ~in_product_since:rel_rio "utilisation" - "the current CPU utilisation" - ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) + ~lifecycle:[(Published, rel_rio, "the current CPU utilisation")] + "utilisation" "the current CPU utilisation" + ; field + ~lifecycle:[(Published, rel_orlando, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -1246,12 +1589,16 @@ end (** Disk and network interfaces are associated with QoS parameters: *) let qos devtype = [ - field ~in_product_since:rel_rio "algorithm_type" "QoS algorithm to use" + field + ~lifecycle:[(Published, rel_rio, "QoS algorithm to use")] + "algorithm_type" "QoS algorithm to use" ; field ~ty:(Map (String, String)) - ~in_product_since:rel_rio "algorithm_params" - "parameters for chosen QoS algorithm" - ; field ~qualifier:DynamicRO ~ty:(Set String) ~in_product_since:rel_rio + ~lifecycle:[(Published, rel_rio, "parameters for chosen QoS algorithm")] + "algorithm_params" "parameters for chosen QoS algorithm" + ; field ~qualifier:DynamicRO ~ty:(Set String) + ~lifecycle: + [(Published, rel_rio, "supported QoS algorithms for this " ^ devtype)] "supported_algorithms" ("supported QoS algorithms for this " ^ devtype) ] @@ -1548,7 +1895,10 @@ module Network = struct ] ~contents: ([ - uid _network + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _network ; namespace ~name:"name" ~contents: (names ~writer_roles:_R_POOL_OP @@ -1560,11 +1910,14 @@ module Network = struct @ allowed_and_current_operations ~writer_roles:_R_POOL_OP operations @ [ field ~qualifier:DynamicRO ~ty:(Set (Ref _vif)) - ~in_product_since:rel_rio "VIFs" "list of connected vifs" + ~lifecycle:[(Published, rel_rio, "list of connected vifs")] + "VIFs" "list of connected vifs" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pif)) - ~in_product_since:rel_rio "PIFs" "list of connected pifs" + ~lifecycle:[(Published, rel_rio, "list of connected pifs")] + "PIFs" "list of connected pifs" ; field ~qualifier:RW ~ty:Int ~default_value:(Some (VInt 1500L)) - ~in_product_since:rel_midnight_ride "MTU" "MTU in octets" + ~lifecycle:[(Published, rel_midnight_ride, "MTU in octets")] + "MTU" "MTU in octets" ; field ~writer_roles:_R_POOL_OP ~ty:(Map (String, String)) "other_config" "additional configuration" @@ -1574,7 +1927,7 @@ module Network = struct ; ("XenCenter.CustomFields.*", _R_VM_OP) ; ("XenCenterCreateInProgress", _R_VM_OP) ] - ~in_product_since:rel_rio + ~lifecycle:[(Published, rel_rio, "additional configuration")] ; field ~lifecycle: [ @@ -1592,25 +1945,62 @@ module Network = struct ~lifecycle:[(Published, rel_falcon, "")] ~qualifier:StaticRO ~ty:Bool ~default_value:(Some (VBool true)) "managed" "true if the bridge is managed by xapi" - ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_orlando + , "Binary blobs associated with this network" + ) + ] ~ty:(Map (String, Ref _blob)) ~default_value:(Some (VMap [])) "blobs" "Binary blobs associated with this network" - ; field ~writer_roles:_R_VM_OP ~in_product_since:rel_orlando + ; field ~writer_roles:_R_VM_OP + ~lifecycle: + [ + ( Published + , rel_orlando + , "user-specified tags for categorization purposes" + ) + ] ~default_value:(Some (VSet [])) ~ty:(Set String) "tags" "user-specified tags for categorization purposes" - ; field ~qualifier:DynamicRO ~in_product_since:rel_tampa + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_tampa + , "The network will use this value to determine the \ + behaviour of all VIFs where locking_mode = default" + ) + ] ~default_value:(Some (VEnum "unlocked")) ~ty:default_locking_mode "default_locking_mode" "The network will use this value to determine the behaviour of \ all VIFs where locking_mode = default" - ; field ~qualifier:DynamicRO ~in_product_since:rel_creedence + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_creedence + , "The IP addresses assigned to VIFs on networks that have \ + active xapi-managed DHCP" + ) + ] ~default_value:(Some (VMap [])) ~ty:(Map (Ref _vif, String)) "assigned_ips" "The IP addresses assigned to VIFs on networks that have active \ xapi-managed DHCP" - ; field ~qualifier:DynamicRO ~in_product_since:rel_inverness + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_inverness + , "Set of purposes for which the server will use this network" + ) + ] ~default_value:(Some (VSet [])) ~ty:(Set purpose) "purpose" "Set of purposes for which the server will use this network" ] @@ -2143,77 +2533,195 @@ module PIF = struct ] ~contents: [ - uid _pif + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _pif ; (* qualifier changed RW -> StaticRO in Miami *) - field ~qualifier:StaticRO ~in_product_since:rel_rio "device" - "machine-readable name of the interface (e.g. eth0)" - ; field ~qualifier:StaticRO ~ty:(Ref _network) ~in_product_since:rel_rio + field ~qualifier:StaticRO + ~lifecycle: + [ + ( Published + , rel_rio + , "machine-readable name of the interface (e.g. eth0)" + ) + ] + "device" "machine-readable name of the interface (e.g. eth0)" + ; field ~qualifier:StaticRO ~ty:(Ref _network) + ~lifecycle: + [ + ( Published + , rel_rio + , "virtual network to which this pif is connected" + ) + ] "network" "virtual network to which this pif is connected" - ; field ~qualifier:StaticRO ~ty:(Ref _host) ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:(Ref _host) + ~lifecycle: + [ + ( Published + , rel_rio + , "physical machine to which this pif is connected" + ) + ] "host" "physical machine to which this pif is connected" ; (* qualifier changed RW -> StaticRO in Miami *) - field ~qualifier:StaticRO ~in_product_since:rel_rio "MAC" - "ethernet MAC address of physical interface" + field ~qualifier:StaticRO + ~lifecycle: + [ + ( Published + , rel_rio + , "ethernet MAC address of physical interface" + ) + ] + "MAC" "ethernet MAC address of physical interface" ; (* qualifier changed RW -> StaticRO in Miami *) - field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio "MTU" - "MTU in octets" + field ~qualifier:StaticRO ~ty:Int + ~lifecycle:[(Published, rel_rio, "MTU in octets")] + "MTU" "MTU in octets" ; (* qualifier changed RW -> StaticRO in Miami *) - field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio "VLAN" - "VLAN tag for all traffic passing through this interface" - ; field ~in_oss_since:None ~internal_only:true ~in_product_since:rel_rio + field ~qualifier:StaticRO ~ty:Int + ~lifecycle: + [ + ( Published + , rel_rio + , "VLAN tag for all traffic passing through this interface" + ) + ] + "VLAN" "VLAN tag for all traffic passing through this interface" + ; field ~in_oss_since:None ~internal_only:true + ~lifecycle:[(Published, rel_rio, "actual dom0 device name")] "device_name" "actual dom0 device name" ; field ~qualifier:DynamicRO ~ty:(Ref _pif_metrics) - ~in_product_since:rel_rio "metrics" - "metrics associated with this PIF" - ; field ~in_oss_since:None ~ty:Bool ~in_product_since:rel_miami + ~lifecycle: + [(Published, rel_rio, "metrics associated with this PIF")] + "metrics" "metrics associated with this PIF" + ; field ~in_oss_since:None ~ty:Bool + ~lifecycle: + [ + ( Published + , rel_miami + , "true if this represents a physical network interface" + ) + ] ~qualifier:DynamicRO "physical" "true if this represents a physical network interface" ~default_value:(Some (VBool false)) - ; field ~in_oss_since:None ~ty:Bool ~in_product_since:rel_miami + ; field ~in_oss_since:None ~ty:Bool + ~lifecycle: + [(Published, rel_miami, "true if this interface is online")] ~qualifier:DynamicRO "currently_attached" "true if this interface is online" ~default_value:(Some (VBool true)) ; field ~in_oss_since:None ~ty:ip_configuration_mode - ~in_product_since:rel_miami ~qualifier:DynamicRO - "ip_configuration_mode" + ~lifecycle: + [ + ( Published + , rel_miami + , "Sets if and how this interface gets an IP address" + ) + ] + ~qualifier:DynamicRO "ip_configuration_mode" "Sets if and how this interface gets an IP address" ~default_value:(Some (VEnum "None")) - ; field ~in_oss_since:None ~ty:String ~in_product_since:rel_miami + ; field ~in_oss_since:None ~ty:String + ~lifecycle:[(Published, rel_miami, "IP address")] ~qualifier:DynamicRO "IP" "IP address" ~default_value:(Some (VString "")) - ; field ~in_oss_since:None ~ty:String ~in_product_since:rel_miami + ; field ~in_oss_since:None ~ty:String + ~lifecycle:[(Published, rel_miami, "IP netmask")] ~qualifier:DynamicRO "netmask" "IP netmask" ~default_value:(Some (VString "")) - ; field ~in_oss_since:None ~ty:String ~in_product_since:rel_miami + ; field ~in_oss_since:None ~ty:String + ~lifecycle:[(Published, rel_miami, "IP gateway")] ~qualifier:DynamicRO "gateway" "IP gateway" ~default_value:(Some (VString "")) - ; field ~in_oss_since:None ~ty:String ~in_product_since:rel_miami + ; field ~in_oss_since:None ~ty:String + ~lifecycle: + [ + ( Published + , rel_miami + , "Comma separated list of the IP addresses of the DNS servers \ + to use" + ) + ] ~qualifier:DynamicRO "DNS" "Comma separated list of the IP addresses of the DNS servers to use" ~default_value:(Some (VString "")) - ; field ~in_oss_since:None ~ty:(Ref _bond) ~in_product_since:rel_miami + ; field ~in_oss_since:None ~ty:(Ref _bond) + ~lifecycle: + [ + ( Published + , rel_miami + , "Indicates which bond this interface is part of" + ) + ] ~qualifier:DynamicRO "bond_slave_of" "Indicates which bond this interface is part of" ~default_value:(Some (VRef "")) ; field ~in_oss_since:None ~ty:(Set (Ref _bond)) - ~in_product_since:rel_miami ~qualifier:DynamicRO "bond_master_of" + ~lifecycle: + [ + ( Published + , rel_miami + , "Indicates this PIF represents the results of a bond" + ) + ] + ~qualifier:DynamicRO "bond_master_of" "Indicates this PIF represents the results of a bond" - ; field ~in_oss_since:None ~ty:(Ref _vlan) ~in_product_since:rel_miami + ; field ~in_oss_since:None ~ty:(Ref _vlan) + ~lifecycle: + [ + ( Published + , rel_miami + , "Indicates which VLAN this interface receives untagged \ + traffic from" + ) + ] ~qualifier:DynamicRO "VLAN_master_of" "Indicates which VLAN this interface receives untagged traffic from" ~default_value:(Some (VRef "")) ; field ~in_oss_since:None ~ty:(Set (Ref _vlan)) - ~in_product_since:rel_miami ~qualifier:DynamicRO "VLAN_slave_of" + ~lifecycle: + [ + ( Published + , rel_miami + , "Indicates which VLANs this interface transmits tagged \ + traffic to" + ) + ] + ~qualifier:DynamicRO "VLAN_slave_of" "Indicates which VLANs this interface transmits tagged traffic to" - ; field ~in_oss_since:None ~ty:Bool ~in_product_since:rel_miami + ; field ~in_oss_since:None ~ty:Bool + ~lifecycle: + [ + ( Published + , rel_miami + , "Indicates whether the control software is listening for \ + connections on this interface" + ) + ] ~qualifier:DynamicRO "management" "Indicates whether the control software is listening for \ connections on this interface" ~default_value:(Some (VBool false)) - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_miami, "Additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "Additional configuration" - ; field ~in_product_since:rel_orlando ~qualifier:DynamicRO - ~default_value:(Some (VBool false)) ~ty:Bool "disallow_unplug" + ; field + ~lifecycle: + [ + ( Published + , rel_orlando + , "Prevent this PIF from being unplugged; set this to notify \ + the management tool-stack that the PIF has a special use \ + and should not be unplugged under any circumstances (e.g. \ + because you're running storage traffic over it)" + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VBool false)) ~ty:Bool + "disallow_unplug" "Prevent this PIF from being unplugged; set this to notify the \ management tool-stack that the PIF has a special use and should \ not be unplugged under any circumstances (e.g. because you're \ @@ -2281,12 +2789,24 @@ module PIF = struct ~default_value:(Some (VEnum "unknown")) "igmp_snooping_status" "The IGMP snooping status of the corresponding network bridge" ; field ~in_oss_since:None ~ty:(Set (Ref _network_sriov)) - ~in_product_since:rel_kolkata ~qualifier:DynamicRO - "sriov_physical_PIF_of" + ~lifecycle: + [ + ( Published + , rel_kolkata + , "Indicates which network_sriov this interface is physical of" + ) + ] + ~qualifier:DynamicRO "sriov_physical_PIF_of" "Indicates which network_sriov this interface is physical of" ; field ~in_oss_since:None ~ty:(Set (Ref _network_sriov)) - ~in_product_since:rel_kolkata ~qualifier:DynamicRO - "sriov_logical_PIF_of" + ~lifecycle: + [ + ( Published + , rel_kolkata + , "Indicates which network_sriov this interface is logical of" + ) + ] + ~qualifier:DynamicRO "sriov_logical_PIF_of" "Indicates which network_sriov this interface is logical of" ; field ~qualifier:DynamicRO ~ty:(Ref _pci) ~lifecycle:[(Published, rel_kolkata, "")] @@ -2314,27 +2834,61 @@ module PIF_metrics = struct ~messages:[] ~contents: [ - uid _pif_metrics + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _pif_metrics ; namespace ~name:"io" ~contents:iobandwidth () - ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Bool + ~lifecycle: + [(Published, rel_rio, "Report if the PIF got a carrier or not")] "carrier" "Report if the PIF got a carrier or not" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "Report vendor ID")] "vendor_id" "Report vendor ID" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "Report vendor name")] "vendor_name" "Report vendor name" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "Report device ID")] "device_id" "Report device ID" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "Report device name")] "device_name" "Report device name" - ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "speed" - "Speed of the link in Mbit/s (if available)" - ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio "duplex" - "Full duplex capability of the link (if available)" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Int + ~lifecycle: + [ + ( Published + , rel_rio + , "Speed of the link in Mbit/s (if available)" + ) + ] + "speed" "Speed of the link in Mbit/s (if available)" + ; field ~qualifier:DynamicRO ~ty:Bool + ~lifecycle: + [ + ( Published + , rel_rio + , "Full duplex capability of the link (if available)" + ) + ] + "duplex" "Full duplex capability of the link (if available)" + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle: + [(Published, rel_rio, "PCI bus path of the pif (if available)")] "pci_bus_path" "PCI bus path of the pif (if available)" - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [ + ( Published + , rel_rio + , "Time at which this information was last updated" + ) + ] "last_updated" "Time at which this information was last updated" - ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_orlando, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -2447,14 +3001,27 @@ module Bond = struct ~messages:[create; destroy; set_mode; set_property] ~contents: [ - uid _bond - ; field ~in_oss_since:None ~in_product_since:rel_miami + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _bond + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_miami, "The bonded interface")] ~qualifier:StaticRO ~ty:(Ref _pif) "master" "The bonded interface" ~default_value:(Some (VRef "")) - ; field ~in_oss_since:None ~in_product_since:rel_miami + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_miami + , "The interfaces which are part of this bond" + ) + ] ~qualifier:DynamicRO ~ty:(Set (Ref _pif)) "slaves" "The interfaces which are part of this bond" - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ; field @@ -2469,12 +3036,22 @@ module Bond = struct ~qualifier:DynamicRO ~default_value:(Some (VEnum "balance-slb")) ~ty:mode "mode" "The algorithm used to distribute traffic among the bonded NICs" - ; field ~in_oss_since:None ~in_product_since:rel_tampa + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_tampa + , "Additional configuration properties specific to the bond \ + mode." + ) + ] ~qualifier:DynamicRO ~ty:(Map (String, String)) ~default_value:(Some (VMap [])) "properties" "Additional configuration properties specific to the bond mode." - ; field ~in_oss_since:None ~in_product_since:rel_tampa + ; field ~in_oss_since:None + ~lifecycle: + [(Published, rel_tampa, "Number of links up in this bond")] ~qualifier:DynamicRO ~ty:Int ~default_value:(Some (VInt 0L)) "links_up" "Number of links up in this bond" ; field @@ -2563,16 +3140,26 @@ module VLAN = struct ~messages:[pool_introduce; create; destroy] ~contents: [ - uid _vlan - ; field ~qualifier:StaticRO ~ty:(Ref _pif) ~in_product_since:rel_miami + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vlan + ; field ~qualifier:StaticRO ~ty:(Ref _pif) + ~lifecycle: + [(Published, rel_miami, "interface on which traffic is tagged")] "tagged_PIF" "interface on which traffic is tagged" ~default_value:(Some (VRef "")) - ; field ~qualifier:DynamicRO ~ty:(Ref _pif) ~in_product_since:rel_miami + ; field ~qualifier:DynamicRO ~ty:(Ref _pif) + ~lifecycle: + [(Published, rel_miami, "interface on which traffic is untagged")] "untagged_PIF" "interface on which traffic is untagged" ~default_value:(Some (VRef "")) - ; field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_miami "tag" - "VLAN tag in use" ~default_value:(Some (VInt (-1L))) - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ; field ~qualifier:StaticRO ~ty:Int + ~lifecycle:[(Published, rel_miami, "VLAN tag in use")] + "tag" "VLAN tag in use" ~default_value:(Some (VInt (-1L))) + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -2737,19 +3324,53 @@ module PBD = struct ~messages:[plug; unplug; set_device_config] ~contents: [ - uid _pbd - ; field ~qualifier:StaticRO ~ty:(Ref _host) ~in_product_since:rel_rio + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _pbd + ; field ~qualifier:StaticRO ~ty:(Ref _host) + ~lifecycle: + [ + ( Published + , rel_rio + , "physical machine on which the pbd is available" + ) + ] "host" "physical machine on which the pbd is available" - ; field ~qualifier:StaticRO ~ty:(Ref _sr) ~in_product_since:rel_rio "SR" - "the storage repository that the pbd realises" + ; field ~qualifier:StaticRO ~ty:(Ref _sr) + ~lifecycle: + [ + ( Published + , rel_rio + , "the storage repository that the pbd realises" + ) + ] + "SR" "the storage repository that the pbd realises" ; field ~ty:(Map (String, String)) - ~qualifier:StaticRO "device_config" ~in_product_since:rel_rio + ~qualifier:StaticRO "device_config" + ~lifecycle: + [ + ( Published + , rel_rio + , "a config string to string map that is provided to the \ + host's SR-backend-driver" + ) + ] "a config string to string map that is provided to the host's \ SR-backend-driver" - ; field ~ty:Bool ~qualifier:DynamicRO ~in_product_since:rel_rio + ; field ~ty:Bool ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_rio + , "is the SR currently attached on this host?" + ) + ] "currently_attached" "is the SR currently attached on this host?" - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -2770,17 +3391,35 @@ let device_status_fields = ) ] "currently_attached" "is the device currently attached (erased on reboot)" - ; field ~ty:Int ~qualifier:DynamicRO ~in_product_since:rel_rio "status_code" + ; field ~ty:Int ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_rio + , "error/success code associated with last attach-operation (erased \ + on reboot)" + ) + ] + "status_code" "error/success code associated with last attach-operation (erased on \ reboot)" - ; field ~ty:String ~qualifier:DynamicRO ~in_product_since:rel_rio + ; field ~ty:String ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_rio + , "error/success information associated with last attach-operation \ + status (erased on reboot)" + ) + ] "status_detail" "error/success information associated with last attach-operation status \ (erased on reboot)" ; field ~ty:(Map (String, String)) - ~qualifier:DynamicRO ~in_product_since:rel_rio "runtime_properties" - "Device runtime properties" + ~qualifier:DynamicRO + ~lifecycle:[(Published, rel_rio, "Device runtime properties")] + "runtime_properties" "Device runtime properties" ] module VIF = struct @@ -3134,27 +3773,69 @@ module VIF = struct ; configure_ipv6 ] ~contents: - ([uid _vif] + ([ + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vif + ] @ allowed_and_current_operations operations @ [ - field ~qualifier:StaticRO ~in_product_since:rel_rio "device" - "order in which VIF backends are created by xapi" + field ~qualifier:StaticRO + ~lifecycle: + [ + ( Published + , rel_rio + , "order in which VIF backends are created by xapi" + ) + ] + "device" "order in which VIF backends are created by xapi" ; field ~qualifier:StaticRO ~ty:(Ref _network) - ~in_product_since:rel_rio "network" - "virtual network to which this vif is connected" - ; field ~qualifier:StaticRO ~ty:(Ref _vm) ~in_product_since:rel_rio + ~lifecycle: + [ + ( Published + , rel_rio + , "virtual network to which this vif is connected" + ) + ] + "network" "virtual network to which this vif is connected" + ; field ~qualifier:StaticRO ~ty:(Ref _vm) + ~lifecycle: + [ + ( Published + , rel_rio + , "virtual machine to which this vif is connected" + ) + ] "VM" "virtual machine to which this vif is connected" - ; field ~qualifier:StaticRO ~ty:String ~in_product_since:rel_rio "MAC" + ; field ~qualifier:StaticRO ~ty:String + ~lifecycle: + [ + ( Published + , rel_rio + , "ethernet MAC address of virtual interface, as exposed to \ + guest" + ) + ] + "MAC" "ethernet MAC address of virtual interface, as exposed to guest" - ; field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio "MTU" - "MTU in octets" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:Int + ~lifecycle:[(Published, rel_rio, "MTU in octets")] + "MTU" "MTU in octets" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "true if the VIF is reserved pending a reboot/migrate" + ) + ] ~internal_only:true ~qualifier:DynamicRO ~ty:Bool "reserved" "true if the VIF is reserved pending a reboot/migrate" ; field ~ty:(Map (String, String)) - ~in_product_since:rel_rio "other_config" - "additional configuration" + ~lifecycle:[(Published, rel_rio, "additional configuration")] + "other_config" "additional configuration" ] @ device_status_fields @ [namespace ~name:"qos" ~contents:(qos "VIF") ()] @@ -3168,44 +3849,113 @@ module VIF = struct ; (Removed, rel_tampa, "Disabled in favour of RRDs") ] "metrics" "metrics associated with this VIF" - ; field ~qualifier:DynamicRO ~in_product_since:rel_george + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_george + , "true if the MAC was autogenerated; false indicates it was \ + set manually" + ) + ] ~default_value:(Some (VBool false)) ~ty:Bool "MAC_autogenerated" "true if the MAC was autogenerated; false indicates it was set \ manually" - ; field ~qualifier:StaticRO ~in_product_since:rel_tampa + ; field ~qualifier:StaticRO + ~lifecycle: + [(Published, rel_tampa, "current locking mode of the VIF")] ~default_value:(Some (VEnum "network_default")) ~ty:locking_mode "locking_mode" "current locking mode of the VIF" - ; field ~qualifier:StaticRO ~in_product_since:rel_tampa + ; field ~qualifier:StaticRO + ~lifecycle: + [ + ( Published + , rel_tampa + , "A list of IPv4 addresses which can be used to filter \ + traffic passing through this VIF" + ) + ] ~default_value:(Some (VSet [])) ~ty:(Set String) "ipv4_allowed" "A list of IPv4 addresses which can be used to filter traffic \ passing through this VIF" - ; field ~qualifier:StaticRO ~in_product_since:rel_tampa + ; field ~qualifier:StaticRO + ~lifecycle: + [ + ( Published + , rel_tampa + , "A list of IPv6 addresses which can be used to filter \ + traffic passing through this VIF" + ) + ] ~default_value:(Some (VSet [])) ~ty:(Set String) "ipv6_allowed" "A list of IPv6 addresses which can be used to filter traffic \ passing through this VIF" - ; field ~ty:ipv4_configuration_mode ~in_product_since:rel_dundee + ; field ~ty:ipv4_configuration_mode + ~lifecycle: + [ + ( Published + , rel_dundee + , "Determines whether IPv4 addresses are configured on the \ + VIF" + ) + ] ~qualifier:DynamicRO "ipv4_configuration_mode" "Determines whether IPv4 addresses are configured on the VIF" ~default_value:(Some (VEnum "None")) - ; field ~ty:(Set String) ~in_product_since:rel_dundee + ; field ~ty:(Set String) + ~lifecycle: + [(Published, rel_dundee, "IPv4 addresses in CIDR format")] ~qualifier:DynamicRO "ipv4_addresses" "IPv4 addresses in CIDR format" ~default_value:(Some (VSet [])) - ; field ~ty:String ~in_product_since:rel_dundee ~qualifier:DynamicRO - "ipv4_gateway" + ; field ~ty:String + ~lifecycle: + [ + ( Published + , rel_dundee + , "IPv4 gateway (the empty string means that no gateway is \ + set)" + ) + ] + ~qualifier:DynamicRO "ipv4_gateway" "IPv4 gateway (the empty string means that no gateway is set)" ~default_value:(Some (VString "")) - ; field ~ty:ipv6_configuration_mode ~in_product_since:rel_dundee + ; field ~ty:ipv6_configuration_mode + ~lifecycle: + [ + ( Published + , rel_dundee + , "Determines whether IPv6 addresses are configured on the \ + VIF" + ) + ] ~qualifier:DynamicRO "ipv6_configuration_mode" "Determines whether IPv6 addresses are configured on the VIF" ~default_value:(Some (VEnum "None")) - ; field ~ty:(Set String) ~in_product_since:rel_dundee + ; field ~ty:(Set String) + ~lifecycle: + [(Published, rel_dundee, "IPv6 addresses in CIDR format")] ~qualifier:DynamicRO "ipv6_addresses" "IPv6 addresses in CIDR format" ~default_value:(Some (VSet [])) - ; field ~ty:String ~in_product_since:rel_dundee ~qualifier:DynamicRO - "ipv6_gateway" + ; field ~ty:String + ~lifecycle: + [ + ( Published + , rel_dundee + , "IPv6 gateway (the empty string means that no gateway is \ + set)" + ) + ] + ~qualifier:DynamicRO "ipv6_gateway" "IPv6 gateway (the empty string means that no gateway is set)" ~default_value:(Some (VString "")) - ; field ~ty:(Ref _pci) ~in_product_since:rel_kolkata + ; field ~ty:(Ref _pci) + ~lifecycle: + [ + ( Published + , rel_kolkata + , "pci of network SR-IOV VF which is reserved for this vif" + ) + ] ~internal_only:true ~qualifier:DynamicRO "reserved_pci" "pci of network SR-IOV VF which is reserved for this vif" ~default_value:(Some (VRef null_ref)) @@ -3234,11 +3984,23 @@ module VIF_metrics = struct ~messages:[] ~contents: [ - uid _vif_metrics + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vif_metrics ; namespace ~name:"io" ~contents:iobandwidth () - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [ + ( Published + , rel_rio + , "Time at which this information was last updated" + ) + ] "last_updated" "Time at which this information was last updated" - ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_orlando, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -3261,20 +4023,37 @@ module Data_source = struct ~lifecycle:[(Published, rel_rio, "")] ) () - ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Bool + ~lifecycle: + [(Published, rel_rio, "true if the data source is being logged")] "enabled" "true if the data source is being logged" - ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Bool + ~lifecycle: + [ + ( Published + , rel_rio + , "true if the data source is enabled by default. Non-default \ + data sources cannot be disabled" + ) + ] "standard" "true if the data source is enabled by default. Non-default data \ sources cannot be disabled" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "the units of the value")] "units" "the units of the value" - ; field ~qualifier:DynamicRO ~ty:Float ~in_product_since:rel_rio "min" - "the minimum value of the data source" - ; field ~qualifier:DynamicRO ~ty:Float ~in_product_since:rel_rio "max" - "the maximum value of the data source" - ; field ~qualifier:DynamicRO ~ty:Float ~in_product_since:rel_rio "value" - "current value of the data source" + ; field ~qualifier:DynamicRO ~ty:Float + ~lifecycle: + [(Published, rel_rio, "the minimum value of the data source")] + "min" "the minimum value of the data source" + ; field ~qualifier:DynamicRO ~ty:Float + ~lifecycle: + [(Published, rel_rio, "the maximum value of the data source")] + "max" "the maximum value of the data source" + ; field ~qualifier:DynamicRO ~ty:Float + ~lifecycle: + [(Published, rel_rio, "current value of the data source")] + "value" "current value of the data source" ] () end @@ -3969,7 +4748,10 @@ module SR = struct ] ~contents: ([ - uid _sr + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _sr ; namespace ~name:"name" ~contents: (names oss_since_303 StaticRO @@ -3980,28 +4762,83 @@ module SR = struct @ allowed_and_current_operations operations @ [ field ~ty:(Set (Ref _vdi)) ~qualifier:DynamicRO - ~in_product_since:rel_rio "VDIs" - "all virtual disks known to this storage repository" + ~lifecycle: + [ + ( Published + , rel_rio + , "all virtual disks known to this storage repository" + ) + ] + "VDIs" "all virtual disks known to this storage repository" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pbd)) - ~in_product_since:rel_rio "PBDs" + ~lifecycle: + [ + ( Published + , rel_rio + , "describes how particular hosts can see this storage \ + repository" + ) + ] + "PBDs" "describes how particular hosts can see this storage repository" - ; field ~ty:Int ~qualifier:DynamicRO ~in_product_since:rel_rio + ; field ~ty:Int ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_rio + , "sum of virtual_sizes of all VDIs in this storage \ + repository (in bytes)" + ) + ] "virtual_allocation" "sum of virtual_sizes of all VDIs in this storage repository (in \ bytes)" - ; field ~ty:Int ~qualifier:DynamicRO ~in_product_since:rel_rio + ; field ~ty:Int ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_rio + , "physical space currently utilised on this storage \ + repository (in bytes). Note that for sparse disk formats, \ + physical_utilisation may be less than virtual_allocation" + ) + ] "physical_utilisation" "physical space currently utilised on this storage repository \ (in bytes). Note that for sparse disk formats, \ physical_utilisation may be less than virtual_allocation" - ; field ~ty:Int ~qualifier:StaticRO ~in_product_since:rel_rio + ; field ~ty:Int ~qualifier:StaticRO + ~lifecycle: + [ + ( Published + , rel_rio + , "total physical size of the repository (in bytes)" + ) + ] "physical_size" "total physical size of the repository (in bytes)" - ; field ~qualifier:StaticRO ~in_product_since:rel_rio "type" - "type of the storage repository" - ; field ~qualifier:StaticRO ~in_product_since:rel_rio "content_type" + ; field ~qualifier:StaticRO + ~lifecycle: + [(Published, rel_rio, "type of the storage repository")] + "type" "type of the storage repository" + ; field ~qualifier:StaticRO + ~lifecycle: + [ + ( Published + , rel_rio + , "the type of the SR's content, if required (e.g. ISOs)" + ) + ] + "content_type" "the type of the SR's content, if required (e.g. ISOs)" ; field ~qualifier:DynamicRO "shared" ~ty:Bool - ~in_product_since:rel_rio + ~lifecycle: + [ + ( Published + , rel_rio + , "true if this SR is (capable of being) shared between \ + multiple hosts" + ) + ] "true if this SR is (capable of being) shared between multiple \ hosts" ; field @@ -4009,25 +4846,55 @@ module SR = struct "other_config" "additional configuration" ~map_keys_roles: [("folder", _R_VM_OP); ("XenCenter.CustomFields.*", _R_VM_OP)] - ~in_product_since:rel_rio - ; field ~writer_roles:_R_VM_OP ~in_product_since:rel_orlando + ~lifecycle:[(Published, rel_rio, "additional configuration")] + ; field ~writer_roles:_R_VM_OP + ~lifecycle: + [ + ( Published + , rel_orlando + , "user-specified tags for categorization purposes" + ) + ] ~default_value:(Some (VSet [])) ~ty:(Set String) "tags" "user-specified tags for categorization purposes" ; field ~ty:Bool ~qualifier:DynamicRO ~in_oss_since:None - ~in_product_since:rel_rio ~internal_only:true - "default_vdi_visibility" "" + ~lifecycle:[(Published, rel_rio, "")] + ~internal_only:true "default_vdi_visibility" "" ; field ~in_oss_since:None ~ty:(Map (String, String)) - ~in_product_since:rel_miami ~qualifier:RW "sm_config" - "SM dependent data" ~default_value:(Some (VMap [])) - ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ~lifecycle:[(Published, rel_miami, "SM dependent data")] + ~qualifier:RW "sm_config" "SM dependent data" + ~default_value:(Some (VMap [])) + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_orlando + , "Binary blobs associated with this SR" + ) + ] ~ty:(Map (String, Ref _blob)) ~default_value:(Some (VMap [])) "blobs" "Binary blobs associated with this SR" - ; field ~qualifier:DynamicRO ~in_product_since:rel_cowley ~ty:Bool - ~default_value:(Some (VBool false)) "local_cache_enabled" + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_cowley + , "True if this SR is assigned to be the local cache for its \ + host" + ) + ] + ~ty:Bool ~default_value:(Some (VBool false)) "local_cache_enabled" "True if this SR is assigned to be the local cache for its host" - ; field ~qualifier:DynamicRO ~in_product_since:rel_boston + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_boston + , "The disaster recovery task which introduced this SR" + ) + ] ~ty:(Ref _dr_task) ~default_value:(Some (VRef null_ref)) "introduced_by" "The disaster recovery task which introduced this SR" @@ -4063,24 +4930,51 @@ module SM = struct ~messages_default_allowed_roles:_R_POOL_OP ~messages:[] ~contents: [ - uid _sm + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _sm ; namespace ~name:"name" ~contents: (names None DynamicRO ~lifecycle:[(Published, rel_rio, "")]) () - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "SR.type")] ~qualifier:DynamicRO "type" "SR.type" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Vendor who created this plugin")] ~qualifier:DynamicRO "vendor" "Vendor who created this plugin" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Entity which owns the copyright of this plugin" + ) + ] ~qualifier:DynamicRO "copyright" "Entity which owns the copyright of this plugin" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Version of the plugin")] ~qualifier:DynamicRO "version" "Version of the plugin" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "Minimum SM API version required on the server" + ) + ] ~qualifier:DynamicRO "required_api_version" "Minimum SM API version required on the server" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "names and descriptions of device config keys" + ) + ] ~qualifier:DynamicRO ~ty:(Map (String, String)) "configuration" "names and descriptions of device config keys" @@ -4093,20 +4987,39 @@ module SM = struct ~ty:(Set String) "capabilities" "capabilities of the SM plugin" ~default_value:(Some (VSet [])) ; field ~in_oss_since:None ~qualifier:DynamicRO - ~in_product_since:rel_clearwater + ~lifecycle: + [ + ( Published + , rel_clearwater + , "capabilities of the SM plugin, with capability version \ + numbers" + ) + ] ~ty:(Map (String, Int)) "features" "capabilities of the SM plugin, with capability version numbers" ~default_value:(Some (VMap [])) - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" - ; field ~in_product_since:rel_orlando ~qualifier:DynamicRO - ~default_value:(Some (VString "")) ~ty:String "driver_filename" - "filename of the storage driver" - ; field ~in_product_since:rel_dundee ~qualifier:DynamicRO - ~default_value:(Some (VSet [])) ~ty:(Set String) - "required_cluster_stack" + ; field + ~lifecycle: + [(Published, rel_orlando, "filename of the storage driver")] + ~qualifier:DynamicRO ~default_value:(Some (VString "")) ~ty:String + "driver_filename" "filename of the storage driver" + ; field + ~lifecycle: + [ + ( Published + , rel_dundee + , "The storage plugin requires that one of these cluster \ + stacks is configured and running." + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VSet [])) + ~ty:(Set String) "required_cluster_stack" "The storage plugin requires that one of these cluster stacks is \ configured and running." ] @@ -4162,7 +5075,13 @@ module LVHD = struct ~descr:"LVHD SR specific operations" ~gen_events:true ~doccomments:[] ~messages_default_allowed_roles:_R_POOL_ADMIN ~messages:[enable_thin_provisioning] - ~contents:[uid _lvhd] + ~contents: + [ + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _lvhd + ] () end @@ -5215,7 +6134,10 @@ module VDI = struct ] ~contents: ([ - uid _vdi + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vdi ; namespace ~name:"name" ~contents: (names oss_since_303 StaticRO @@ -5225,46 +6147,103 @@ module VDI = struct ] @ allowed_and_current_operations operations @ [ - field ~qualifier:StaticRO ~ty:(Ref _sr) ~in_product_since:rel_rio + field ~qualifier:StaticRO ~ty:(Ref _sr) + ~lifecycle: + [ + ( Published + , rel_rio + , "storage repository in which the VDI resides" + ) + ] "SR" "storage repository in which the VDI resides" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vbd)) - ~in_product_since:rel_rio "VBDs" - "list of vbds that refer to this disk" + ~lifecycle: + [(Published, rel_rio, "list of vbds that refer to this disk")] + "VBDs" "list of vbds that refer to this disk" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _crashdump)) - ~in_product_since:rel_rio "crash_dumps" - "list of crash dumps that refer to this disk" - ; field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio + ~lifecycle: + [ + ( Published + , rel_rio + , "list of crash dumps that refer to this disk" + ) + ] + "crash_dumps" "list of crash dumps that refer to this disk" + ; field ~qualifier:StaticRO ~ty:Int + ~lifecycle: + [ + ( Published + , rel_rio + , "size of disk as presented to the guest (in bytes). Note \ + that, depending on storage backend type, requested size \ + may not be respected exactly" + ) + ] "virtual_size" "size of disk as presented to the guest (in bytes). Note that, \ depending on storage backend type, requested size may not be \ respected exactly" - ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Int + ~lifecycle: + [ + ( Published + , rel_rio + , "amount of physical space that the disk image is currently \ + taking up on the storage repository (in bytes)" + ) + ] "physical_utilisation" "amount of physical space that the disk image is currently \ taking up on the storage repository (in bytes)" - ; field ~qualifier:StaticRO ~ty:type' ~in_product_since:rel_rio "type" - "type of the VDI" - ; field ~qualifier:StaticRO ~ty:Bool ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:type' + ~lifecycle:[(Published, rel_rio, "type of the VDI")] + "type" "type of the VDI" + ; field ~qualifier:StaticRO ~ty:Bool + ~lifecycle: + [(Published, rel_rio, "true if this disk may be shared")] "sharable" "true if this disk may be shared" - ; field ~qualifier:StaticRO ~ty:Bool ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:Bool + ~lifecycle: + [ + ( Published + , rel_rio + , "true if this disk may ONLY be mounted read-only" + ) + ] "read_only" "true if this disk may ONLY be mounted read-only" ; field ~ty:(Map (String, String)) - ~in_product_since:rel_rio "other_config" - "additional configuration" + ~lifecycle:[(Published, rel_rio, "additional configuration")] + "other_config" "additional configuration" ~map_keys_roles: [("folder", _R_VM_OP); ("XenCenter.CustomFields.*", _R_VM_OP)] ; field ~qualifier:DynamicRO ~ty:Bool "storage_lock" - ~in_product_since:rel_rio + ~lifecycle: + [ + ( Published + , rel_rio + , "true if this disk is locked at the storage level" + ) + ] "true if this disk is locked at the storage level" ; (* XXX: location field was in the database in rio, now API in miami *) - field ~in_oss_since:None ~in_product_since:rel_miami ~ty:String - ~qualifier:DynamicRO ~default_value:(Some (VString "")) "location" - "location information" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~ty:Bool - ~qualifier:DynamicRO "managed" "" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~ty:Bool - ~qualifier:DynamicRO "missing" + field ~in_oss_since:None + ~lifecycle:[(Published, rel_miami, "location information")] + ~ty:String ~qualifier:DynamicRO ~default_value:(Some (VString "")) + "location" "location information" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "")] + ~ty:Bool ~qualifier:DynamicRO "managed" "" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "true if SR scan operation reported this VDI as not \ + present on disk" + ) + ] + ~ty:Bool ~qualifier:DynamicRO "missing" "true if SR scan operation reported this VDI as not present on \ disk" ; field ~in_oss_since:None ~ty:(Ref _vdi) ~qualifier:DynamicRO @@ -5276,7 +6255,17 @@ module VDI = struct "parent" "This field is always null. Deprecated" ; field ~in_oss_since:None ~ty:(Map (String, String)) - ~in_product_since:rel_miami ~qualifier:RW "xenstore_data" + ~lifecycle: + [ + ( Published + , rel_miami + , "data to be inserted into the xenstore tree \ + (/local/domain/0/backend/vbd///sm-data) \ + after the VDI is attached. This is generally set by the \ + SM backends on vdi_attach." + ) + ] + ~qualifier:RW "xenstore_data" "data to be inserted into the xenstore tree \ (/local/domain/0/backend/vbd///sm-data) after \ the VDI is attached. This is generally set by the SM backends \ @@ -5284,37 +6273,101 @@ module VDI = struct ~default_value:(Some (VMap [])) ; field ~in_oss_since:None ~ty:(Map (String, String)) - ~in_product_since:rel_miami ~qualifier:RW "sm_config" - "SM dependent data" ~default_value:(Some (VMap [])) - ; field ~in_product_since:rel_orlando + ~lifecycle:[(Published, rel_miami, "SM dependent data")] + ~qualifier:RW "sm_config" "SM dependent data" + ~default_value:(Some (VMap [])) + ; field + ~lifecycle: + [(Published, rel_orlando, "true if this is a snapshot.")] ~default_value:(Some (VBool false)) ~qualifier:DynamicRO ~ty:Bool ~doc_tags:[Snapshots] "is_a_snapshot" "true if this is a snapshot." - ; field ~in_product_since:rel_orlando ~default_value:(Some (VRef "")) - ~qualifier:DynamicRO ~ty:(Ref _vdi) ~doc_tags:[Snapshots] - "snapshot_of" "Ref pointing to the VDI this snapshot is of." - ; field ~in_product_since:rel_orlando ~qualifier:DynamicRO - ~ty:(Set (Ref _vdi)) ~doc_tags:[Snapshots] "snapshots" - "List pointing to all the VDIs snapshots." - ; field ~in_product_since:rel_orlando + ; field + ~lifecycle: + [ + ( Published + , rel_orlando + , "Ref pointing to the VDI this snapshot is of." + ) + ] + ~default_value:(Some (VRef "")) ~qualifier:DynamicRO + ~ty:(Ref _vdi) ~doc_tags:[Snapshots] "snapshot_of" + "Ref pointing to the VDI this snapshot is of." + ; field + ~lifecycle: + [ + ( Published + , rel_orlando + , "List pointing to all the VDIs snapshots." + ) + ] + ~qualifier:DynamicRO ~ty:(Set (Ref _vdi)) ~doc_tags:[Snapshots] + "snapshots" "List pointing to all the VDIs snapshots." + ; field + ~lifecycle: + [ + ( Published + , rel_orlando + , "Date/time when this snapshot was created." + ) + ] ~default_value:(Some (VDateTime Date.epoch)) ~qualifier:DynamicRO ~ty:DateTime ~doc_tags:[Snapshots] "snapshot_time" "Date/time when this snapshot was created." - ; field ~writer_roles:_R_VM_OP ~in_product_since:rel_orlando + ; field ~writer_roles:_R_VM_OP + ~lifecycle: + [ + ( Published + , rel_orlando + , "user-specified tags for categorization purposes" + ) + ] ~default_value:(Some (VSet [])) ~ty:(Set String) "tags" "user-specified tags for categorization purposes" - ; field ~in_product_since:rel_cowley ~qualifier:DynamicRO ~ty:Bool - ~default_value:(Some (VBool false)) "allow_caching" + ; field + ~lifecycle: + [ + ( Published + , rel_cowley + , "true if this VDI is to be cached in the local cache SR" + ) + ] + ~qualifier:DynamicRO ~ty:Bool ~default_value:(Some (VBool false)) + "allow_caching" "true if this VDI is to be cached in the local cache SR" - ; field ~in_product_since:rel_cowley ~qualifier:DynamicRO ~ty:on_boot + ; field + ~lifecycle: + [ + ( Published + , rel_cowley + , "The behaviour of this VDI on a VM boot" + ) + ] + ~qualifier:DynamicRO ~ty:on_boot ~default_value:(Some (VEnum "persist")) "on_boot" "The behaviour of this VDI on a VM boot" - ; field ~in_product_since:rel_boston ~qualifier:DynamicRO - ~ty:(Ref _pool) ~default_value:(Some (VRef null_ref)) - "metadata_of_pool" + ; field + ~lifecycle: + [ + ( Published + , rel_boston + , "The pool whose metadata is contained in this VDI" + ) + ] + ~qualifier:DynamicRO ~ty:(Ref _pool) + ~default_value:(Some (VRef null_ref)) "metadata_of_pool" "The pool whose metadata is contained in this VDI" - ; field ~in_product_since:rel_boston ~qualifier:DynamicRO ~ty:Bool - ~default_value:(Some (VBool false)) "metadata_latest" + ; field + ~lifecycle: + [ + ( Published + , rel_boston + , "Whether this VDI contains the latest known accessible \ + metadata for the pool" + ) + ] + ~qualifier:DynamicRO ~ty:Bool ~default_value:(Some (VBool false)) + "metadata_latest" "Whether this VDI contains the latest known accessible metadata \ for the pool" ; field @@ -5576,12 +6629,19 @@ module VBD = struct ; set_mode ] ~contents: - ([uid _vbd] + ([ + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vbd + ] @ allowed_and_current_operations operations @ [ - field ~qualifier:StaticRO ~ty:(Ref _vm) ~in_product_since:rel_rio + field ~qualifier:StaticRO ~ty:(Ref _vm) + ~lifecycle:[(Published, rel_rio, "the virtual machine")] "VM" "the virtual machine" - ; field ~qualifier:StaticRO ~ty:(Ref _vdi) ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:(Ref _vdi) + ~lifecycle:[(Published, rel_rio, "the virtual disk")] "VDI" "the virtual disk" ; field ~qualifier:StaticRO ~ty:String ~default_value:(Some (VString "")) @@ -5595,29 +6655,71 @@ module VBD = struct ) ] "device" "device seen by the guest e.g. hda1" - ; field ~in_product_since:rel_rio "userdevice" - "user-friendly device name e.g. 0,1,2,etc." - ; field ~ty:Bool ~in_product_since:rel_rio "bootable" - "true if this VBD is bootable" - ; field ~qualifier:StaticRO ~ty:mode ~in_product_since:rel_rio "mode" - "the mode the VBD should be mounted with" - ; field ~ty:type' ~in_product_since:rel_rio "type" - "how the VBD will appear to the guest (e.g. disk or CD)" - ; field ~in_oss_since:None ~in_product_since:rel_miami ~ty:Bool - ~default_value:(Some (VBool true)) "unpluggable" + ; field + ~lifecycle: + [ + ( Published + , rel_rio + , "user-friendly device name e.g. 0,1,2,etc." + ) + ] + "userdevice" "user-friendly device name e.g. 0,1,2,etc." + ; field ~ty:Bool + ~lifecycle:[(Published, rel_rio, "true if this VBD is bootable")] + "bootable" "true if this VBD is bootable" + ; field ~qualifier:StaticRO ~ty:mode + ~lifecycle: + [ + (Published, rel_rio, "the mode the VBD should be mounted with") + ] + "mode" "the mode the VBD should be mounted with" + ; field ~ty:type' + ~lifecycle: + [ + ( Published + , rel_rio + , "how the VBD will appear to the guest (e.g. disk or CD)" + ) + ] + "type" "how the VBD will appear to the guest (e.g. disk or CD)" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_miami + , "true if this VBD will support hot-unplug" + ) + ] + ~ty:Bool ~default_value:(Some (VBool true)) "unpluggable" "true if this VBD will support hot-unplug" - ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Bool + ~lifecycle: + [ + ( Published + , rel_rio + , "true if a storage level lock was acquired" + ) + ] "storage_lock" "true if a storage level lock was acquired" - ; field ~qualifier:StaticRO ~ty:Bool ~in_product_since:rel_rio "empty" - "if true this represents an empty drive" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:Bool + ~lifecycle: + [(Published, rel_rio, "if true this represents an empty drive")] + "empty" "if true this represents an empty drive" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "true if the VBD is reserved pending a reboot/migrate" + ) + ] ~internal_only:true ~qualifier:DynamicRO ~ty:Bool ~default_value:(Some (VBool false)) "reserved" "true if the VBD is reserved pending a reboot/migrate" ; field ~ty:(Map (String, String)) - ~in_product_since:rel_rio "other_config" - "additional configuration" + ~lifecycle:[(Published, rel_rio, "additional configuration")] + "other_config" "additional configuration" ] @ device_status_fields @ [namespace ~name:"qos" ~contents:(qos "VBD") ()] @@ -5655,7 +6757,10 @@ module VBD_metrics = struct ~messages_default_allowed_roles:_R_VM_ADMIN ~messages:[] ~contents: [ - uid _vbd_metrics + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vbd_metrics ; namespace ~name:"io" ~contents:iobandwidth () ; field ~qualifier:DynamicRO ~ty:DateTime ~default_value:(Some (VDateTime Date.epoch)) @@ -5701,12 +6806,19 @@ module Crashdump = struct ~messages_default_allowed_roles:_R_POOL_OP ~messages:[destroy] ~contents: [ - uid _crashdump - ; field ~qualifier:StaticRO ~ty:(Ref _vm) ~in_product_since:rel_rio "VM" - "the virtual machine" - ; field ~qualifier:StaticRO ~ty:(Ref _vdi) ~in_product_since:rel_rio + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _crashdump + ; field ~qualifier:StaticRO ~ty:(Ref _vm) + ~lifecycle:[(Published, rel_rio, "the virtual machine")] + "VM" "the virtual machine" + ; field ~qualifier:StaticRO ~ty:(Ref _vdi) + ~lifecycle:[(Published, rel_rio, "the virtual disk")] "VDI" "the virtual disk" - ; field ~in_product_since:rel_miami ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_miami, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ] @@ -5897,16 +7009,36 @@ module Subject = struct ~messages:[add_to_roles; remove_from_roles; get_permissions_name_label] ~contents: [ - uid ~in_oss_since:None _subject - ; field ~in_product_since:rel_george ~default_value:(Some (VString "")) - ~qualifier:StaticRO ~ty:String "subject_identifier" + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + ~in_oss_since:None _subject + ; field + ~lifecycle: + [ + ( Published + , rel_george + , "the subject identifier, unique in the external directory \ + service" + ) + ] + ~default_value:(Some (VString "")) ~qualifier:StaticRO ~ty:String + "subject_identifier" "the subject identifier, unique in the external directory service" - ; field ~in_product_since:rel_george ~default_value:(Some (VMap [])) - ~qualifier:StaticRO + ; field + ~lifecycle:[(Published, rel_george, "additional configuration")] + ~default_value:(Some (VMap [])) ~qualifier:StaticRO ~ty:(Map (String, String)) "other_config" "additional configuration" ; (* DynamicRO fields do not show up in the constructor, as it should be because a subject must be created without receiving any roles as a parameter *) - field ~in_product_since:rel_midnight_ride + field + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "the roles associated with this subject" + ) + ] ~default_value: (Some (VSet [VRef ("OpaqueRef:" ^ Constants.rbac_pool_admin_uuid)]) ) @@ -6006,24 +7138,52 @@ module Role = struct ] ~contents: [ - uid ~in_oss_since:None _role + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + ~in_oss_since:None _role ; namespace ~name:"name" ~contents: [ - field ~in_product_since:rel_midnight_ride + field + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "a short user-friendly name for the role" + ) + ] ~default_value:(Some (VString "")) ~qualifier:StaticRO ~ty:String "label" "a short user-friendly name for the role" - ; field ~in_product_since:rel_midnight_ride + ; field + ~lifecycle: + [(Published, rel_midnight_ride, "what this role is for")] ~default_value:(Some (VString "")) ~qualifier:StaticRO ~ty:String "description" "what this role is for" ] () - ; field ~in_product_since:rel_midnight_ride + ; field + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "a list of pointers to other roles or permissions" + ) + ] ~default_value:(Some (VSet [])) ~ignore_foreign_key:true ~qualifier:StaticRO ~ty:(Set (Ref _role)) "subroles" "a list of pointers to other roles or permissions" - ; field ~in_product_since:"22.5.0" ~default_value:(Some (VBool false)) - ~qualifier:DynamicRO ~ty:Bool "is_internal" + ; field + ~lifecycle: + [ + ( Published + , "22.5.0" + , "Indicates whether the role is only to be assigned \ + internally by xapi, or can be used by clients" + ) + ] + ~default_value:(Some (VBool false)) ~qualifier:DynamicRO ~ty:Bool + "is_internal" "Indicates whether the role is only to be assigned internally by \ xapi, or can be used by clients" (*RBAC2: field ~in_product_since:rel_midnight_ride ~default_value:(Some (VBool false)) ~qualifier:StaticRO ~ty:Bool "is_complete" "if this is a complete role, meant to be used by the end-user";*) @@ -6053,18 +7213,34 @@ module Console = struct ~messages_default_allowed_roles:_R_VM_ADMIN ~messages:[] ~contents: [ - uid _console - ; field ~qualifier:DynamicRO ~ty:protocol ~in_product_since:rel_rio + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _console + ; field ~qualifier:DynamicRO ~ty:protocol + ~lifecycle: + [(Published, rel_rio, "the protocol used by this console")] "protocol" "the protocol used by this console" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "URI for the console service")] "location" "URI for the console service" - ; field ~qualifier:DynamicRO ~ty:(Ref _vm) ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:(Ref _vm) + ~lifecycle: + [(Published, rel_rio, "VM to which this console is attached")] "VM" "VM to which this console is attached" ; field ~ty:(Map (String, String)) - ~in_product_since:rel_rio "other_config" "additional configuration" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~internal_only:true - ~ty:Int "port" + ~lifecycle:[(Published, rel_rio, "additional configuration")] + "other_config" "additional configuration" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "port in dom0 on which the console server is listening" + ) + ] + ~internal_only:true ~ty:Int "port" "port in dom0 on which the console server is listening" ] () @@ -6073,14 +7249,16 @@ end module VM_metrics = struct let vm_memory_metrics = [ - field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "actual" - "Guest's actual memory (bytes)" ~persist:false + field ~qualifier:DynamicRO ~ty:Int + ~lifecycle:[(Published, rel_rio, "Guest's actual memory (bytes)")] + "actual" "Guest's actual memory (bytes)" ~persist:false ] let vm_vcpu_metrics = [ - field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "number" - "Current number of VCPUs" ~persist:true + field ~qualifier:DynamicRO ~ty:Int + ~lifecycle:[(Published, rel_rio, "Current number of VCPUs")] + "number" "Current number of VCPUs" ~persist:true ; field ~qualifier:DynamicRO ~ty:(Map (Int, Float)) ~persist:false "utilisation" @@ -6094,15 +7272,17 @@ module VM_metrics = struct ] ; field ~qualifier:DynamicRO ~ty:(Map (Int, Int)) - ~in_product_since:rel_rio "CPU" "VCPU to PCPU map" ~persist:false + ~lifecycle:[(Published, rel_rio, "VCPU to PCPU map")] + "CPU" "VCPU to PCPU map" ~persist:false ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - ~in_product_since:rel_rio "params" - "The live equivalent to VM.VCPUs_params" ~persist:false + ~lifecycle: + [(Published, rel_rio, "The live equivalent to VM.VCPUs_params")] + "params" "The live equivalent to VM.VCPUs_params" ~persist:false ; field ~qualifier:DynamicRO ~ty:(Map (Int, Set String)) - ~in_product_since:rel_rio "flags" "CPU flags (blocked,online,running)" - ~persist:false + ~lifecycle:[(Published, rel_rio, "CPU flags (blocked,online,running)")] + "flags" "CPU flags (blocked,online,running)" ~persist:false ] let t = @@ -6114,32 +7294,65 @@ module VM_metrics = struct ~messages_default_allowed_roles:_R_VM_ADMIN ~messages:[] ~contents: [ - uid _vm_metrics + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vm_metrics ; namespace ~name:"memory" ~contents:vm_memory_metrics () ; namespace ~name:"VCPUs" ~contents:vm_vcpu_metrics () - ; field ~qualifier:DynamicRO ~ty:(Set String) ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:(Set String) + ~lifecycle: + [ + ( Published + , rel_rio + , "The state of the guest, eg blocked, dying etc" + ) + ] "state" "The state of the guest, eg blocked, dying etc" ~persist:false - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [(Published, rel_rio, "Time at which this VM was last booted")] "start_time" "Time at which this VM was last booted" ; field ~in_oss_since:None ~qualifier:DynamicRO ~ty:DateTime - ~in_product_since:rel_rio "install_time" - "Time at which the VM was installed" - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ~lifecycle: + [(Published, rel_rio, "Time at which the VM was installed")] + "install_time" "Time at which the VM was installed" + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [ + ( Published + , rel_rio + , "Time at which this information was last updated" + ) + ] "last_updated" "Time at which this information was last updated" ~persist:false - ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_orlando, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" ~persist:false - ; field ~in_product_since:rel_ely ~default_value:(Some (VBool false)) - ~ty:Bool ~qualifier:DynamicRO "hvm" "hardware virtual machine" + ; field + ~lifecycle:[(Published, rel_ely, "hardware virtual machine")] + ~default_value:(Some (VBool false)) ~ty:Bool ~qualifier:DynamicRO + "hvm" "hardware virtual machine" ~persist:false + ; field + ~lifecycle: + [(Published, rel_ely, "VM supports nested virtualisation")] + ~default_value:(Some (VBool false)) ~ty:Bool ~qualifier:DynamicRO + "nested_virt" "VM supports nested virtualisation" ~persist:false + ; field + ~lifecycle: + [ + ( Published + , rel_ely + , "VM is immobile and can't migrate between hosts" + ) + ] + ~default_value:(Some (VBool false)) ~ty:Bool ~qualifier:DynamicRO + "nomigrate" "VM is immobile and can't migrate between hosts" ~persist:false - ; field ~in_product_since:rel_ely ~default_value:(Some (VBool false)) - ~ty:Bool ~qualifier:DynamicRO "nested_virt" - "VM supports nested virtualisation" ~persist:false - ; field ~in_product_since:rel_ely ~default_value:(Some (VBool false)) - ~ty:Bool ~qualifier:DynamicRO "nomigrate" - "VM is immobile and can't migrate between hosts" ~persist:false ; field ~lifecycle: [ @@ -6187,18 +7400,22 @@ module VM_guest_metrics = struct ~messages_default_allowed_roles:_R_VM_ADMIN ~messages:[] ~contents: [ - uid _vm_guest_metrics + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vm_guest_metrics ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - ~in_product_since:rel_rio "os_version" "version of the OS" + ~lifecycle:[(Published, rel_rio, "version of the OS")] + "os_version" "version of the OS" ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) ~lifecycle:[] "netbios_name" "The NETBIOS name of the machine" ~default_value:(Some (VMap [])) ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - ~in_product_since:rel_rio "PV_drivers_version" - "version of the PV drivers" + ~lifecycle:[(Published, rel_rio, "version of the PV drivers")] + "PV_drivers_version" "version of the PV drivers" ; field ~qualifier:DynamicRO ~ty:Bool ~in_oss_since:None ~lifecycle: [ @@ -6241,16 +7458,35 @@ module VM_guest_metrics = struct "disks" "This field exists but has no data." ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - ~in_product_since:rel_rio "networks" "network configuration" + ~lifecycle:[(Published, rel_rio, "network configuration")] + "networks" "network configuration" ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - ~in_product_since:rel_rio "other" "anything else" - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ~lifecycle:[(Published, rel_rio, "anything else")] + "other" "anything else" + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [ + ( Published + , rel_rio + , "Time at which this information was last updated" + ) + ] "last_updated" "Time at which this information was last updated" - ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) + ; field + ~lifecycle:[(Published, rel_orlando, "additional configuration")] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "other_config" "additional configuration" - ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_orlando + , "True if the guest is sending heartbeat messages via the \ + guest agent" + ) + ] ~default_value:(Some (VBool false)) ~ty:Bool "live" "True if the guest is sending heartbeat messages via the guest \ agent" @@ -6875,33 +8111,69 @@ module VMSS = struct ] ~contents: [ - uid _vmss + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vmss ; namespace ~name:"name" ~contents:(names None RW ~lifecycle:[(Published, rel_rio, "")]) () - ; field ~qualifier:RW ~ty:Bool ~in_product_since:rel_rio "enabled" - "enable or disable this snapshot schedule" + ; field ~qualifier:RW ~ty:Bool + ~lifecycle: + [(Published, rel_rio, "enable or disable this snapshot schedule")] + "enabled" "enable or disable this snapshot schedule" ~default_value:(Some (VBool true)) - ; field ~qualifier:StaticRO ~ty:type' ~in_product_since:rel_rio "type" - "type of the snapshot schedule" - ; field ~qualifier:StaticRO ~ty:Int ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:type' + ~lifecycle:[(Published, rel_rio, "type of the snapshot schedule")] + "type" "type of the snapshot schedule" + ; field ~qualifier:StaticRO ~ty:Int + ~lifecycle: + [ + ( Published + , rel_rio + , "maximum number of snapshots that should be stored at any \ + time" + ) + ] "retained_snapshots" "maximum number of snapshots that should be stored at any time" ~default_value:(Some (VInt 7L)) - ; field ~qualifier:StaticRO ~ty:frequency ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:frequency + ~lifecycle: + [ + ( Published + , rel_rio + , "frequency of taking snapshot from snapshot schedule" + ) + ] "frequency" "frequency of taking snapshot from snapshot schedule" ; field ~qualifier:StaticRO ~ty:(Map (String, String)) - ~in_product_since:rel_rio "schedule" + ~lifecycle: + [ + ( Published + , rel_rio + , "schedule of the snapshot containing 'hour', 'min', 'days'. \ + Date/time-related information is in Local Timezone" + ) + ] + "schedule" "schedule of the snapshot containing 'hour', 'min', 'days'. \ Date/time-related information is in Local Timezone" ~default_value:(Some (VMap [])) - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle:[(Published, rel_rio, "time of the last snapshot")] "last_run_time" "time of the last snapshot" ~default_value:(Some (VDateTime Date.epoch)) ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) - ~in_product_since:rel_rio "VMs" - "all VMs attached to this snapshot schedule" + ~lifecycle: + [ + ( Published + , rel_rio + , "all VMs attached to this snapshot schedule" + ) + ] + "VMs" "all VMs attached to this snapshot schedule" ] () end @@ -7066,7 +8338,10 @@ module VM_appliance = struct ] ~contents: ([ - uid _vm_appliance + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _vm_appliance ; namespace ~name:"name" ~contents:(names None RW ~lifecycle:[(Published, rel_rio, "")]) () @@ -7074,7 +8349,8 @@ module VM_appliance = struct @ allowed_and_current_operations operations @ [ field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) - ~in_product_since:rel_rio "VMs" "all VMs in this appliance" + ~lifecycle:[(Published, rel_rio, "all VMs in this appliance")] + "VMs" "all VMs in this appliance" ] ) () @@ -7132,10 +8408,14 @@ module DR_task = struct ~messages_default_allowed_roles:_R_POOL_OP ~messages:[create; destroy] ~contents: [ - uid _dr_task + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _dr_task ; field ~qualifier:DynamicRO ~ty:(Set (Ref _sr)) - ~in_product_since:rel_rio "introduced_SRs" - "All SRs introduced by this appliance" + ~lifecycle: + [(Published, rel_rio, "All SRs introduced by this appliance")] + "introduced_SRs" "All SRs introduced by this appliance" ] () end @@ -7332,22 +8612,46 @@ module Event = struct ; contents= [ field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:Int - ~in_product_since:rel_rio "id" + ~lifecycle: + [ + ( Published + , rel_rio + , "An ID, monotonically increasing, and local to the current \ + session" + ) + ] + "id" "An ID, monotonically increasing, and local to the current session" ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:DateTime - ~in_product_since:rel_rio ~internal_deprecated_since:rel_boston + ~lifecycle: + [ + (Published, rel_rio, "The time at which the event occurred") + ; (Deprecated, rel_boston, "") + ] "timestamp" "The time at which the event occurred" ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:String - ~in_product_since:rel_rio "class" - "The name of the class of the object that changed" + ~lifecycle: + [ + ( Published + , rel_rio + , "The name of the class of the object that changed" + ) + ] + "class" "The name of the class of the object that changed" ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:operation - ~in_product_since:rel_rio "operation" - "The operation that was performed" + ~lifecycle: + [(Published, rel_rio, "The operation that was performed")] + "operation" "The operation that was performed" ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:String - ~in_product_since:rel_rio "ref" - "A reference to the object that changed" + ~lifecycle: + [(Published, rel_rio, "A reference to the object that changed")] + "ref" "A reference to the object that changed" ; field ~reader_roles:_R_ALL ~qualifier:StaticRO ~ty:String - ~in_product_since:rel_rio ~internal_deprecated_since:rel_boston + ~lifecycle: + [ + (Published, rel_rio, "The uuid of the object that changed") + ; (Deprecated, rel_boston, "") + ] "obj_uuid" "The uuid of the object that changed" ] ; (* As of tampa, the event record has one more field, snapshot, which is the record of the object changed. @@ -7408,19 +8712,43 @@ module Blob = struct ~messages_default_allowed_roles:_R_POOL_OP ~messages:[create; destroy] ~contents: [ - uid _blob + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _blob ; namespace ~name:"name" ~contents: (names oss_since_303 RW ~lifecycle:[(Published, rel_rio, "")]) () - ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio "size" - "Size of the binary data, in bytes" + ; field ~qualifier:DynamicRO ~ty:Int + ~lifecycle: + [(Published, rel_rio, "Size of the binary data, in bytes")] + "size" "Size of the binary data, in bytes" ; field ~writer_roles:_R_POOL_OP ~qualifier:RW - ~in_product_since:rel_tampa ~default_value:(Some (VBool false)) - ~ty:Bool "public" "True if the blob is publicly accessible" - ; field ~qualifier:StaticRO ~ty:DateTime ~in_product_since:rel_rio + ~lifecycle: + [ + (Published, rel_tampa, "True if the blob is publicly accessible") + ] + ~default_value:(Some (VBool false)) ~ty:Bool "public" + "True if the blob is publicly accessible" + ; field ~qualifier:StaticRO ~ty:DateTime + ~lifecycle: + [ + ( Published + , rel_rio + , "Time at which the data in the blob was last updated" + ) + ] "last_updated" "Time at which the data in the blob was last updated" - ; field ~qualifier:StaticRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:String + ~lifecycle: + [ + ( Published + , rel_rio + , "The mime type associated with this object. Defaults to \ + 'application/octet-stream' if the empty string is supplied" + ) + ] "mime_type" "The mime type associated with this object. Defaults to \ 'application/octet-stream' if the empty string is supplied" @@ -7572,10 +8900,21 @@ module Message = struct ] ~contents: [ - uid _message - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio "name" - "The name of the message" - ; field ~qualifier:DynamicRO ~ty:Int ~in_product_since:rel_rio + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _message + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "The name of the message")] + "name" "The name of the message" + ; field ~qualifier:DynamicRO ~ty:Int + ~lifecycle: + [ + ( Published + , rel_rio + , "The message priority, 0 being low priority" + ) + ] "priority" "The message priority, 0 being low priority" ; field ~qualifier:DynamicRO ~ty:cls ~lifecycle: @@ -7584,12 +8923,24 @@ module Message = struct ; (Extended, "1.313.0", "Added Certificate class") ] "cls" "The class of the object this message is associated with" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle: + [ + ( Published + , rel_rio + , "The uuid of the object this message is associated with" + ) + ] "obj_uuid" "The uuid of the object this message is associated with" - ; field ~qualifier:DynamicRO ~ty:DateTime ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:DateTime + ~lifecycle: + [ + (Published, rel_rio, "The time at which the message was created") + ] "timestamp" "The time at which the message was created" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio "body" - "The body of the message" + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle:[(Published, rel_rio, "The body of the message")] + "body" "The body of the message" ] () end @@ -7635,13 +8986,17 @@ module Secret = struct ~persist:PersistEverything ~contents: [ - uid ~reader_roles:_R_POOL_OP _secret + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + ~reader_roles:_R_POOL_OP _secret ; field ~reader_roles:_R_POOL_OP ~qualifier:RW ~ty:String - ~in_product_since:rel_rio "value" "the secret" + ~lifecycle:[(Published, rel_rio, "the secret")] + "value" "the secret" ; field ~qualifier:RW ~ty:(Map (String, String)) - ~in_product_since:rel_rio "other_config" "other_config" - ~default_value:(Some (VMap [])) + ~lifecycle:[(Published, rel_rio, "other_config")] + "other_config" "other_config" ~default_value:(Some (VMap [])) ] () end @@ -7705,7 +9060,10 @@ module Network_sriov = struct ~in_oss_since:None ~contents: [ - uid _network_sriov + uid + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _network_sriov ; field ~qualifier:StaticRO ~ty:(Ref _pif) ~lifecycle "physical_PIF" "The PIF that has SR-IOV enabled" ~default_value:(Some (VRef "")) ; field ~qualifier:StaticRO ~ty:(Ref _pif) ~lifecycle "logical_PIF" @@ -8978,7 +10336,9 @@ module VUSB = struct ~ty:(Map (String, String)) ~lifecycle "other_config" "Additional configuration" ~default_value:(Some (VMap [])) - ; field ~qualifier:DynamicRO ~ty:Bool ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Bool + ~lifecycle: + [(Published, rel_rio, "is the device currently attached")] "currently_attached" "is the device currently attached" ~default_value:(Some (VBool false)) ] diff --git a/ocaml/idl/datamodel_common.ml b/ocaml/idl/datamodel_common.ml index 3ee1bcebd99..6ae642be5b3 100644 --- a/ocaml/idl/datamodel_common.ml +++ b/ocaml/idl/datamodel_common.ml @@ -742,13 +742,31 @@ let allowed_and_current_operations ?(writer_roles = None) ?(reader_roles = None) operations_type = [ field ~writer_roles ~reader_roles ~persist:false ~in_oss_since:None - ~in_product_since:rel_rio ~qualifier:DynamicRO ~ty:(Set operations_type) + ~lifecycle: + [ + ( Published + , rel_rio + , "list of the operations allowed in this state. This list is \ + advisory only and the server state may have changed by the time \ + this field is read by a client." + ) + ] + ~qualifier:DynamicRO ~ty:(Set operations_type) ~default_value:(Some (VSet [])) "allowed_operations" "list of the operations allowed in this state. This list is advisory \ only and the server state may have changed by the time this field is \ read by a client." ; field ~writer_roles ~reader_roles ~persist:false ~in_oss_since:None - ~in_product_since:rel_rio ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_rio + , "links each of the running tasks using this object (by reference) \ + to a current_operation enum which describes the nature of the \ + task." + ) + ] + ~qualifier:DynamicRO ~ty:(Map (String, operations_type)) ~default_value:(Some (VMap [])) "current_operations" "links each of the running tasks using this object (by reference) to a \ diff --git a/ocaml/idl/datamodel_host.ml b/ocaml/idl/datamodel_host.ml index d34daafc08a..266d695fa34 100644 --- a/ocaml/idl/datamodel_host.ml +++ b/ocaml/idl/datamodel_host.ml @@ -7,7 +7,9 @@ open Datamodel_types let host_memory = let field = field ~ty:Int in [ - field ~qualifier:DynamicRO "overhead" ~in_product_since:rel_rio + field ~qualifier:DynamicRO "overhead" + ~lifecycle: + [(Published, rel_rio, "Virtualization memory overhead (bytes).")] "Virtualization memory overhead (bytes)." ~default_value:(Some (VInt 0L)) ~doc_tags:[Memory] ] @@ -15,14 +17,19 @@ let host_memory = let api_version = let field' = field ~qualifier:DynamicRO in [ - field' ~ty:Int ~in_product_since:rel_rio "major" "major version number" - ; field' ~ty:Int ~in_product_since:rel_rio "minor" "minor version number" - ; field' ~ty:String ~in_product_since:rel_rio "vendor" - "identification of vendor" + field' ~ty:Int + ~lifecycle:[(Published, rel_rio, "major version number")] + "major" "major version number" + ; field' ~ty:Int + ~lifecycle:[(Published, rel_rio, "minor version number")] + "minor" "minor version number" + ; field' ~ty:String + ~lifecycle:[(Published, rel_rio, "identification of vendor")] + "vendor" "identification of vendor" ; field' ~ty:(Map (String, String)) - ~in_product_since:rel_rio "vendor_implementation" - "details of vendor implementation" + ~lifecycle:[(Published, rel_rio, "details of vendor implementation")] + "vendor_implementation" "details of vendor implementation" ] let migrate_receive = @@ -2454,6 +2461,8 @@ let t = ~contents: ([ uid _host + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] ; namespace ~name:"name" ~contents:(names None RW ~lifecycle:[(Published, rel_rio, "")]) () @@ -2463,110 +2472,239 @@ let t = @ [ namespace ~name:"API_version" ~contents:api_version () ; field ~qualifier:DynamicRO ~ty:Bool "enabled" - ~in_product_since:rel_rio "True if the host is currently enabled" + ~lifecycle: + [(Published, rel_rio, "True if the host is currently enabled")] + "True if the host is currently enabled" ; field ~qualifier:StaticRO ~ty:(Map (String, String)) - ~in_product_since:rel_rio "software_version" "version strings" + ~lifecycle:[(Published, rel_rio, "version strings")] + "software_version" "version strings" ; field ~ty:(Map (String, String)) - ~in_product_since:rel_rio "other_config" "additional configuration" + ~lifecycle:[(Published, rel_rio, "additional configuration")] + "other_config" "additional configuration" ~map_keys_roles: [("folder", _R_VM_OP); ("XenCenter.CustomFields.*", _R_VM_OP)] - ; field ~qualifier:StaticRO ~ty:(Set String) ~in_product_since:rel_rio + ; field ~qualifier:StaticRO ~ty:(Set String) + ~lifecycle:[(Published, rel_rio, "Xen capabilities")] "capabilities" "Xen capabilities" ; field ~qualifier:DynamicRO ~ty:(Map (String, String)) - ~in_product_since:rel_rio "cpu_configuration" + ~lifecycle: + [ + ( Published + , rel_rio + , "The CPU configuration on this host. May contain keys such \ + as \"nr_nodes\", \"sockets_per_node\", \ + \"cores_per_socket\", or \"threads_per_core\"" + ) + ] + "cpu_configuration" "The CPU configuration on this host. May contain keys such as \ \"nr_nodes\", \"sockets_per_node\", \"cores_per_socket\", or \ \"threads_per_core\"" - ; field ~qualifier:DynamicRO ~ty:String ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:String + ~lifecycle: + [ + ( Published + , rel_rio + , "Scheduler policy currently in force on this host" + ) + ] "sched_policy" "Scheduler policy currently in force on this host" - ; field ~qualifier:DynamicRO ~ty:(Set String) ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:(Set String) + ~lifecycle: + [ + ( Published + , rel_rio + , "a list of the bootloaders installed on the machine" + ) + ] "supported_bootloaders" "a list of the bootloaders installed on the machine" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _vm)) - ~in_product_since:rel_rio "resident_VMs" - "list of VMs currently resident on host" + ~lifecycle: + [(Published, rel_rio, "list of VMs currently resident on host")] + "resident_VMs" "list of VMs currently resident on host" ; field ~qualifier:RW ~ty:(Map (String, String)) - ~in_product_since:rel_rio "logging" "logging configuration" + ~lifecycle:[(Published, rel_rio, "logging configuration")] + "logging" "logging configuration" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pif)) ~doc_tags:[Networking] - ~in_product_since:rel_rio "PIFs" "physical network interfaces" - ; field ~qualifier:RW ~ty:(Ref _sr) ~in_product_since:rel_rio + ~lifecycle:[(Published, rel_rio, "physical network interfaces")] + "PIFs" "physical network interfaces" + ; field ~qualifier:RW ~ty:(Ref _sr) + ~lifecycle: + [ + ( Published + , rel_rio + , "The SR in which VDIs for suspend images are created" + ) + ] "suspend_image_sr" "The SR in which VDIs for suspend images are created" - ; field ~qualifier:RW ~ty:(Ref _sr) ~in_product_since:rel_rio + ; field ~qualifier:RW ~ty:(Ref _sr) + ~lifecycle: + [ + ( Published + , rel_rio + , "The SR in which VDIs for crash dumps are created" + ) + ] "crash_dump_sr" "The SR in which VDIs for crash dumps are created" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Set of host crash dumps")] ~qualifier:DynamicRO ~ty:(Set (Ref _host_crashdump)) "crashdumps" "Set of host crash dumps" - ; field ~in_oss_since:None ~in_product_since:rel_rio - ~internal_deprecated_since:rel_ely ~qualifier:DynamicRO - ~ty:(Set (Ref _host_patch)) "patches" "Set of host patches" - ; field ~in_oss_since:None ~in_product_since:rel_ely + ; field ~in_oss_since:None + ~lifecycle: + [ + (Published, rel_rio, "Set of host patches") + ; (Deprecated, rel_ely, "") + ] + ~qualifier:DynamicRO ~ty:(Set (Ref _host_patch)) "patches" + "Set of host patches" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_ely, "Set of updates")] ~qualifier:DynamicRO ~ty:(Set (Ref _pool_update)) "updates" "Set of updates" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _pbd)) - ~in_product_since:rel_rio "PBDs" "physical blockdevices" + ~lifecycle:[(Published, rel_rio, "physical blockdevices")] + "PBDs" "physical blockdevices" ; field ~qualifier:DynamicRO ~ty:(Set (Ref _hostcpu)) - ~in_product_since:rel_rio "host_CPUs" - "The physical CPUs on this host" - ; field ~qualifier:DynamicRO ~in_product_since:rel_midnight_ride + ~lifecycle:[(Published, rel_rio, "The physical CPUs on this host")] + "host_CPUs" "The physical CPUs on this host" + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Details about the physical CPUs on this host" + ) + ] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "cpu_info" "Details about the physical CPUs on this host" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW - ~ty:String ~doc_tags:[Networking] "hostname" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "The hostname of this host")] + ~qualifier:RW ~ty:String ~doc_tags:[Networking] "hostname" "The hostname of this host" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW - ~ty:String ~doc_tags:[Networking] "address" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "The address by which this host can be contacted from any \ + other host in the pool" + ) + ] + ~qualifier:RW ~ty:String ~doc_tags:[Networking] "address" "The address by which this host can be contacted from any other \ host in the pool" ; field ~qualifier:DynamicRO ~ty:(Ref _host_metrics) - ~in_product_since:rel_rio "metrics" - "metrics associated with this host" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ~lifecycle: + [(Published, rel_rio, "metrics associated with this host")] + "metrics" "metrics associated with this host" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "State of the current license")] ~qualifier:DynamicRO ~ty:(Map (String, String)) "license_params" "State of the current license" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~internal_only:true - ~qualifier:DynamicRO ~ty:Int "boot_free_mem" + ; field ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Free memory on host at boot time")] + ~internal_only:true ~qualifier:DynamicRO ~ty:Int "boot_free_mem" "Free memory on host at boot time" ; field ~in_oss_since:None ~qualifier:DynamicRO - ~in_product_since:rel_orlando ~ty:(Set String) - ~default_value:(Some (VSet [])) "ha_statefiles" + ~lifecycle: + [ + ( Published + , rel_orlando + , "The set of statefiles accessible from this host" + ) + ] + ~ty:(Set String) ~default_value:(Some (VSet [])) "ha_statefiles" "The set of statefiles accessible from this host" ; field ~in_oss_since:None ~qualifier:DynamicRO - ~in_product_since:rel_orlando ~ty:(Set String) - ~default_value:(Some (VSet [])) "ha_network_peers" + ~lifecycle: + [ + ( Published + , rel_orlando + , "The set of hosts visible via the network from this host" + ) + ] + ~ty:(Set String) ~default_value:(Some (VSet [])) "ha_network_peers" "The set of hosts visible via the network from this host" - ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_orlando + , "Binary blobs associated with this host" + ) + ] ~ty:(Map (String, Ref _blob)) ~default_value:(Some (VMap [])) "blobs" "Binary blobs associated with this host" ; field ~writer_roles:_R_VM_OP ~qualifier:RW - ~in_product_since:rel_orlando ~default_value:(Some (VSet [])) - ~ty:(Set String) "tags" + ~lifecycle: + [ + ( Published + , rel_orlando + , "user-specified tags for categorization purposes" + ) + ] + ~default_value:(Some (VSet [])) ~ty:(Set String) "tags" "user-specified tags for categorization purposes" - ; field ~qualifier:DynamicRO ~in_product_since:rel_george + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_george + , "type of external authentication service configured; empty \ + if none configured." + ) + ] ~default_value:(Some (VString "")) ~ty:String "external_auth_type" "type of external authentication service configured; empty if none \ configured." - ; field ~qualifier:DynamicRO ~in_product_since:rel_george + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_george + , "name of external authentication service configured; empty \ + if none configured." + ) + ] ~default_value:(Some (VString "")) ~ty:String "external_auth_service_name" "name of external authentication service configured; empty if none \ configured." - ; field ~qualifier:DynamicRO ~in_product_since:rel_george + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_george + , "configuration specific to external authentication service" + ) + ] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "external_auth_configuration" "configuration specific to external authentication service" - ; field ~qualifier:DynamicRO ~in_product_since:rel_midnight_ride + ; field ~qualifier:DynamicRO + ~lifecycle:[(Published, rel_midnight_ride, "Product edition")] ~default_value:(Some (VString "")) ~ty:String "edition" "Product edition" - ; field ~qualifier:RW ~in_product_since:rel_midnight_ride + ; field ~qualifier:RW + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Contact information of the license server" + ) + ] ~default_value: (Some (VMap @@ -2578,18 +2716,23 @@ let t = ) ~ty:(Map (String, String)) "license_server" "Contact information of the license server" - ; field ~qualifier:DynamicRO ~in_product_since:rel_midnight_ride + ; field ~qualifier:DynamicRO + ~lifecycle:[(Published, rel_midnight_ride, "BIOS strings")] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "bios_strings" "BIOS strings" - ; field ~qualifier:DynamicRO ~in_product_since:rel_midnight_ride + ; field ~qualifier:DynamicRO + ~lifecycle:[(Published, rel_midnight_ride, "The power on mode")] ~default_value:(Some (VString "")) ~ty:String "power_on_mode" "The power on mode" - ; field ~qualifier:DynamicRO ~in_product_since:rel_midnight_ride + ; field ~qualifier:DynamicRO + ~lifecycle:[(Published, rel_midnight_ride, "The power on config")] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "power_on_config" "The power on config" - ; field ~qualifier:StaticRO ~in_product_since:rel_cowley + ; field ~qualifier:StaticRO + ~lifecycle: + [(Published, rel_cowley, "The SR that is used as a local cache")] ~default_value:(Some (VRef null_ref)) ~ty:(Ref _sr) "local_cache_sr" "The SR that is used as a local cache" ; field ~qualifier:DynamicRO @@ -2619,22 +2762,45 @@ let t = restarts its SSL/TLS listening service; typically this takes less \ than a second but existing connections to it will be broken. API \ login sessions will remain valid." - ; field ~qualifier:RW ~in_product_since:rel_tampa + ; field ~qualifier:RW + ~lifecycle: + [ + ( Published + , rel_tampa + , "VCPUs params to apply to all resident guests" + ) + ] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "guest_VCPUs_params" "VCPUs params to apply to all resident guests" - ; field ~qualifier:RW ~in_product_since:rel_cream + ; field ~qualifier:RW + ~lifecycle: + [ + ( Published + , rel_cream + , "indicates whether the host is configured to output its \ + console to a physical display device" + ) + ] ~default_value:(Some (VEnum "enabled")) ~ty:display "display" "indicates whether the host is configured to output its console to \ a physical display device" - ; field ~qualifier:DynamicRO ~in_product_since:rel_cream + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_cream + , "The set of versions of the virtual hardware platform that \ + the host can offer to its guests" + ) + ] ~default_value:(Some (VSet [VInt 0L])) ~ty:(Set Int) "virtual_hardware_platform_versions" "The set of versions of the virtual hardware platform that the \ host can offer to its guests" ; field ~qualifier:DynamicRO ~default_value:(Some (VRef null_ref)) - ~in_product_since:rel_ely ~ty:(Ref _vm) "control_domain" - "The control domain (domain 0)" + ~lifecycle:[(Published, rel_ely, "The control domain (domain 0)")] + ~ty:(Ref _vm) "control_domain" "The control domain (domain 0)" ; field ~qualifier:DynamicRO ~lifecycle:[(Published, rel_ely, "")] ~ty:(Set (Ref _pool_update)) ~ignore_foreign_key:true @@ -2667,13 +2833,30 @@ let t = ~lifecycle:[(Published, rel_stockholm, "")] ~default_value:(Some (VSet [])) ~ty:(Set String) "editions" "List of all available product editions" - ; field ~qualifier:DynamicRO ~in_product_since:"1.303.0" + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , "1.303.0" + , "The set of pending mandatory guidances after applying \ + updates, which must be applied, as otherwise there may be \ + e.g. VM failures" + ) + ] ~ty:(Set update_guidances) "pending_guidances" ~default_value:(Some (VSet [])) "The set of pending mandatory guidances after applying updates, \ which must be applied, as otherwise there may be e.g. VM failures" - ; field ~qualifier:DynamicRO ~in_product_since:"1.313.0" ~ty:Bool - "tls_verification_enabled" ~default_value:(Some (VBool false)) + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , "1.313.0" + , "True if this host has TLS verifcation enabled" + ) + ] + ~ty:Bool "tls_verification_enabled" + ~default_value:(Some (VBool false)) "True if this host has TLS verifcation enabled" ; field ~qualifier:DynamicRO ~lifecycle:[] ~ty:DateTime "last_software_update" ~default_value:(Some (VDateTime Date.epoch)) diff --git a/ocaml/idl/datamodel_pool.ml b/ocaml/idl/datamodel_pool.ml index f9b0de3d65c..f94a531903c 100644 --- a/ocaml/idl/datamodel_pool.ml +++ b/ocaml/idl/datamodel_pool.ml @@ -1603,24 +1603,48 @@ let t = ; get_guest_secureboot_readiness ] ~contents: - ([uid ~in_oss_since:None _pool] + ([ + uid ~in_oss_since:None + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + _pool + ] @ [ - field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW - ~ty:String "name_label" "Short name" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW - ~ty:String "name_description" "Description" - ; field ~in_oss_since:None ~in_product_since:rel_rio + field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Short name")] + ~qualifier:RW ~ty:String "name_label" "Short name" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Description")] + ~qualifier:RW ~ty:String "name_description" "Description" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "The host that is pool master")] ~qualifier:DynamicRO ~ty:(Ref _host) "master" "The host that is pool master" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW - ~ty:(Ref _sr) "default_SR" "Default SR for VDIs" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW - ~ty:(Ref _sr) "suspend_image_SR" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "Default SR for VDIs")] + ~qualifier:RW ~ty:(Ref _sr) "default_SR" "Default SR for VDIs" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "The SR in which VDIs for suspend images are created" + ) + ] + ~qualifier:RW ~ty:(Ref _sr) "suspend_image_SR" "The SR in which VDIs for suspend images are created" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:RW - ~ty:(Ref _sr) "crash_dump_SR" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "The SR in which VDIs for crash dumps are created" + ) + ] + ~qualifier:RW ~ty:(Ref _sr) "crash_dump_SR" "The SR in which VDIs for crash dumps are created" - ; field ~in_oss_since:None ~in_product_since:rel_rio + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "additional configuration")] ~ty:(Map (String, String)) "other_config" "additional configuration" ~map_keys_roles: @@ -1629,68 +1653,165 @@ let t = ; ("XenCenter.CustomFields.*", _R_VM_OP) ; ("EMPTY_FOLDERS", _R_VM_OP) ] - ; field ~in_oss_since:None ~in_product_since:rel_orlando + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_orlando + , "true if HA is enabled on the pool, false otherwise" + ) + ] ~qualifier:DynamicRO ~ty:Bool ~default_value:(Some (VBool false)) "ha_enabled" "true if HA is enabled on the pool, false otherwise" - ; field ~in_oss_since:None ~in_product_since:rel_orlando + ; field ~in_oss_since:None + ~lifecycle: + [(Published, rel_orlando, "The current HA configuration")] ~qualifier:DynamicRO ~ty:(Map (String, String)) ~default_value:(Some (VMap [])) "ha_configuration" "The current HA configuration" - ; field ~in_oss_since:None ~in_product_since:rel_orlando + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_orlando, "HA statefile VDIs in use")] ~qualifier:DynamicRO ~ty:(Set String) ~default_value:(Some (VSet [])) "ha_statefiles" "HA statefile VDIs in use" - ; field ~in_oss_since:None ~in_product_since:rel_orlando + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_orlando + , "Number of host failures to tolerate before the Pool is \ + declared to be overcommitted" + ) + ] ~qualifier:DynamicRO ~ty:Int ~default_value:(Some (VInt 0L)) "ha_host_failures_to_tolerate" "Number of host failures to tolerate before the Pool is declared \ to be overcommitted" - ; field ~in_oss_since:None ~in_product_since:rel_orlando + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_orlando + , "Number of future host failures we have managed to find a \ + plan for. Once this reaches zero any future host failures \ + will cause the failure of protected VMs." + ) + ] ~qualifier:DynamicRO ~ty:Int ~default_value:(Some (VInt 0L)) "ha_plan_exists_for" "Number of future host failures we have managed to find a plan \ for. Once this reaches zero any future host failures will cause \ the failure of protected VMs." - ; field ~in_oss_since:None ~in_product_since:rel_orlando ~qualifier:RW - ~ty:Bool ~default_value:(Some (VBool false)) "ha_allow_overcommit" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_orlando + , "If set to false then operations which would cause the Pool \ + to become overcommitted will be blocked." + ) + ] + ~qualifier:RW ~ty:Bool ~default_value:(Some (VBool false)) + "ha_allow_overcommit" "If set to false then operations which would cause the Pool to \ become overcommitted will be blocked." - ; field ~in_oss_since:None ~in_product_since:rel_orlando + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_orlando + , "True if the Pool is considered to be overcommitted i.e. if \ + there exist insufficient physical resources to tolerate the \ + configured number of host failures" + ) + ] ~qualifier:DynamicRO ~ty:Bool ~default_value:(Some (VBool false)) "ha_overcommitted" "True if the Pool is considered to be overcommitted i.e. if there \ exist insufficient physical resources to tolerate the configured \ number of host failures" - ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_orlando + , "Binary blobs associated with this pool" + ) + ] ~ty:(Map (String, Ref _blob)) ~default_value:(Some (VMap [])) "blobs" "Binary blobs associated with this pool" - ; field ~writer_roles:_R_VM_OP ~in_product_since:rel_orlando + ; field ~writer_roles:_R_VM_OP + ~lifecycle: + [ + ( Published + , rel_orlando + , "user-specified tags for categorization purposes" + ) + ] ~default_value:(Some (VSet [])) ~ty:(Set String) "tags" "user-specified tags for categorization purposes" - ; field ~writer_roles:_R_VM_OP ~in_product_since:rel_orlando + ; field ~writer_roles:_R_VM_OP + ~lifecycle: + [(Published, rel_orlando, "gui-specific configuration for pool")] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "gui_config" "gui-specific configuration for pool" - ; field ~writer_roles:_R_POOL_OP ~in_product_since:rel_dundee + ; field ~writer_roles:_R_POOL_OP + ~lifecycle: + [ + ( Published + , rel_dundee + , "Configuration for the automatic health check feature" + ) + ] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "health_check_config" "Configuration for the automatic health check feature" - ; field ~in_product_since:rel_george ~qualifier:DynamicRO ~ty:String - ~default_value:(Some (VString "")) "wlb_url" - "Url for the configured workload balancing host" - ; field ~in_product_since:rel_george ~qualifier:DynamicRO ~ty:String - ~default_value:(Some (VString "")) "wlb_username" - "Username for accessing the workload balancing host" - ; field ~in_product_since:rel_george ~internal_only:true - ~qualifier:DynamicRO ~ty:(Ref _secret) "wlb_password" - "Password for accessing the workload balancing host" + ; field + ~lifecycle: + [ + ( Published + , rel_george + , "Url for the configured workload balancing host" + ) + ] + ~qualifier:DynamicRO ~ty:String ~default_value:(Some (VString "")) + "wlb_url" "Url for the configured workload balancing host" + ; field + ~lifecycle: + [ + ( Published + , rel_george + , "Username for accessing the workload balancing host" + ) + ] + ~qualifier:DynamicRO ~ty:String ~default_value:(Some (VString "")) + "wlb_username" "Username for accessing the workload balancing host" + ; field + ~lifecycle: + [ + ( Published + , rel_george + , "Password for accessing the workload balancing host" + ) + ] + ~internal_only:true ~qualifier:DynamicRO ~ty:(Ref _secret) + "wlb_password" "Password for accessing the workload balancing host" ; field ~writer_roles:(_R_POOL_OP ++ _R_CLIENT_CERT) - ~in_product_since:rel_george ~qualifier:RW ~ty:Bool - ~default_value:(Some (VBool false)) "wlb_enabled" + ~lifecycle: + [ + ( Published + , rel_george + , "true if workload balancing is enabled on the pool, false \ + otherwise" + ) + ] + ~qualifier:RW ~ty:Bool ~default_value:(Some (VBool false)) + "wlb_enabled" "true if workload balancing is enabled on the pool, false otherwise" ; field ~qualifier:RW ~ty:Bool ~default_value:(Some (VBool false)) "wlb_verify_cert" @@ -1705,12 +1826,28 @@ let t = Pool.enable_tls_verification instead" ) ] - ; field ~in_oss_since:None ~in_product_since:rel_midnight_ride + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "true a redo-log is to be used other than when HA is \ + enabled, false otherwise" + ) + ] ~qualifier:DynamicRO ~ty:Bool ~default_value:(Some (VBool false)) "redo_log_enabled" "true a redo-log is to be used other than when HA is enabled, \ false otherwise" - ; field ~in_oss_since:None ~in_product_since:rel_midnight_ride + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "indicates the VDI to use for the redo-log other than when \ + HA is enabled" + ) + ] ~qualifier:DynamicRO ~ty:(Ref _vdi) ~default_value:(Some (VRef null_ref)) "redo_log_vdi" "indicates the VDI to use for the redo-log other than when HA is \ @@ -1730,15 +1867,37 @@ let t = SDN_controller instead." ) ] - ; field ~in_oss_since:None ~in_product_since:rel_midnight_ride + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Pool-wide restrictions currently in effect" + ) + ] ~qualifier:DynamicRO ~ty:(Map (String, String)) ~default_value:(Some (VMap [])) "restrictions" "Pool-wide restrictions currently in effect" - ; field ~in_oss_since:None ~in_product_since:rel_boston + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_boston + , "The set of currently known metadata VDIs for this pool" + ) + ] ~qualifier:DynamicRO ~ty:(Set (Ref _vdi)) "metadata_VDIs" "The set of currently known metadata VDIs for this pool" - ; field ~in_oss_since:None ~in_product_since:rel_dundee + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_dundee + , "The HA cluster stack that is currently in use. Only valid \ + when HA is enabled." + ) + ] ~qualifier:DynamicRO ~default_value:(Some (VString "")) ~ty:String "ha_cluster_stack" "The HA cluster stack that is currently in use. Only valid when HA \ @@ -1746,12 +1905,26 @@ let t = ] @ allowed_and_current_operations operations @ [ - field ~in_oss_since:None ~in_product_since:rel_dundee + field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_dundee + , "Pool-wide guest agent configuration information" + ) + ] ~qualifier:DynamicRO ~ty:(Map (String, String)) ~default_value:(Some (VMap [])) "guest_agent_config" "Pool-wide guest agent configuration information" - ; field ~qualifier:DynamicRO ~in_product_since:rel_dundee + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , rel_dundee + , "Details about the physical CPUs on the pool" + ) + ] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "cpu_info" "Details about the physical CPUs on the pool" @@ -1765,13 +1938,30 @@ let t = "This field was consulted when VM.create did not specify a value \ for 'has_vendor_device'; VM.create now uses a simple default and \ no longer consults this value." - ; field ~qualifier:RW ~in_product_since:rel_ely + ; field ~qualifier:RW + ~lifecycle: + [ + ( Published + , rel_ely + , "The pool-wide flag to show if the live patching feauture is \ + disabled or not." + ) + ] ~default_value:(Some (VBool false)) ~ty:Bool "live_patching_disabled" "The pool-wide flag to show if the live patching feauture is \ disabled or not." - ; field ~in_product_since:rel_inverness ~qualifier:DynamicRO ~ty:Bool - ~default_value:(Some (VBool false)) "igmp_snooping_enabled" + ; field + ~lifecycle: + [ + ( Published + , rel_inverness + , "true if IGMP snooping is enabled in the pool, false \ + otherwise." + ) + ] + ~qualifier:DynamicRO ~ty:Bool ~default_value:(Some (VBool false)) + "igmp_snooping_enabled" "true if IGMP snooping is enabled in the pool, false otherwise." ; field ~qualifier:StaticRO ~ty:String ~lifecycle: @@ -1790,8 +1980,17 @@ let t = ; field ~qualifier:StaticRO ~ty:String ~lifecycle:[] ~default_value:(Some (VString "")) "custom_uefi_certificates" "Custom UEFI certificates allowing Secure Boot" - ; field ~in_product_since:rel_stockholm_psr ~qualifier:RW ~ty:Bool - ~default_value:(Some (VBool false)) "is_psr_pending" + ; field + ~lifecycle: + [ + ( Published + , rel_stockholm_psr + , "True if either a PSR is running or we are waiting for a PSR \ + to be re-run" + ) + ] + ~qualifier:RW ~ty:Bool ~default_value:(Some (VBool false)) + "is_psr_pending" "True if either a PSR is running or we are waiting for a PSR to be \ re-run" ; field ~qualifier:DynamicRO @@ -1799,8 +1998,16 @@ let t = ~ty:Bool ~default_value:(Some (VBool false)) "tls_verification_enabled" "True iff TLS certificate verification is enabled" - ; field ~in_product_since:"1.301.0" ~qualifier:DynamicRO - ~ty:(Set (Ref _repository)) ~ignore_foreign_key:true "repositories" + ; field + ~lifecycle: + [ + ( Published + , "1.301.0" + , "The set of currently enabled repositories" + ) + ] + ~qualifier:DynamicRO ~ty:(Set (Ref _repository)) + ~ignore_foreign_key:true "repositories" ~default_value:(Some (VSet [])) "The set of currently enabled repositories" ; field ~qualifier:DynamicRO @@ -1814,11 +2021,29 @@ let t = "client_certificate_auth_name" "The name (CN/SAN) that an incoming client certificate must have \ to allow authentication" - ; field ~in_product_since:"21.3.0" ~qualifier:DynamicRO ~ty:String - ~default_value:(Some (VString "")) "repository_proxy_url" + ; field + ~lifecycle: + [ + ( Published + , "21.3.0" + , "Url of the proxy used in syncing with the enabled \ + repositories" + ) + ] + ~qualifier:DynamicRO ~ty:String ~default_value:(Some (VString "")) + "repository_proxy_url" "Url of the proxy used in syncing with the enabled repositories" - ; field ~in_product_since:"21.3.0" ~qualifier:DynamicRO ~ty:String - ~default_value:(Some (VString "")) "repository_proxy_username" + ; field + ~lifecycle: + [ + ( Published + , "21.3.0" + , "Username for the authentication of the proxy used in \ + syncing with the enabled repositories" + ) + ] + ~qualifier:DynamicRO ~ty:String ~default_value:(Some (VString "")) + "repository_proxy_username" "Username for the authentication of the proxy used in syncing with \ the enabled repositories" ; field ~qualifier:DynamicRO @@ -1836,7 +2061,15 @@ let t = "Default behaviour during migration, True if stream compression \ should be used" ; field ~qualifier:RW ~ty:Bool ~default_value:(Some (VBool true)) - ~in_product_since:rel_rio "coordinator_bias" + ~lifecycle: + [ + ( Published + , rel_rio + , "true if bias against pool master when scheduling vms is \ + enabled, false otherwise" + ) + ] + "coordinator_bias" "true if bias against pool master when scheduling vms is enabled, \ false otherwise" ; field ~qualifier:StaticRO ~ty:Int ~default_value:(Some (VInt 8L)) diff --git a/ocaml/idl/datamodel_vm.ml b/ocaml/idl/datamodel_vm.ml index 4815a29c1ce..44ca1466d78 100644 --- a/ocaml/idl/datamodel_vm.ml +++ b/ocaml/idl/datamodel_vm.ml @@ -21,14 +21,25 @@ let vmpp_deprecated = let pv = [ - field ~in_product_since:rel_rio "bootloader" "name of or path to bootloader" - ; field ~in_product_since:rel_rio "kernel" "path to the kernel" - ; field ~in_product_since:rel_rio "ramdisk" "path to the initrd" - ; field ~in_product_since:rel_rio "args" "kernel command-line arguments" - ; field ~in_product_since:rel_rio "bootloader_args" - "miscellaneous arguments for the bootloader" - ; field ~in_oss_since:None ~in_product_since:rel_rio "legacy_args" - "to make Zurich guests boot" + field + ~lifecycle:[(Published, rel_rio, "name of or path to bootloader")] + "bootloader" "name of or path to bootloader" + ; field + ~lifecycle:[(Published, rel_rio, "path to the kernel")] + "kernel" "path to the kernel" + ; field + ~lifecycle:[(Published, rel_rio, "path to the initrd")] + "ramdisk" "path to the initrd" + ; field + ~lifecycle:[(Published, rel_rio, "kernel command-line arguments")] + "args" "kernel command-line arguments" + ; field + ~lifecycle: + [(Published, rel_rio, "miscellaneous arguments for the bootloader")] + "bootloader_args" "miscellaneous arguments for the bootloader" + ; field ~in_oss_since:None + ~lifecycle:[(Published, rel_rio, "to make Zurich guests boot")] + "legacy_args" "to make Zurich guests boot" ] (** HVM domain booting *) @@ -41,11 +52,20 @@ let hvm = ; (Deprecated, rel_kolkata, "Replaced by VM.domain_type") ] "boot_policy" "HVM boot policy" - ; field ~in_product_since:rel_rio + ; field + ~lifecycle:[(Published, rel_rio, "HVM boot params")] ~ty:(Map (String, String)) "boot_params" "HVM boot params" ; field ~writer_roles:_R_VM_POWER_ADMIN ~in_oss_since:None ~ty:Float - ~in_product_since:rel_miami ~qualifier:StaticRO "shadow_multiplier" + ~lifecycle: + [ + ( Published + , rel_miami + , "multiplier applied to the amount of shadow that will be made \ + available to the guest" + ) + ] + ~qualifier:StaticRO "shadow_multiplier" "multiplier applied to the amount of shadow that will be made available \ to the guest" ~default_value:(Some (VFloat 1.)) @@ -54,29 +74,60 @@ let hvm = let guest_memory = let field = field ~ty:Int in [ - field "overhead" ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN - ~qualifier:DynamicRO "Virtualization memory overhead (bytes)." - ~default_value:(Some (VInt 0L)) ~doc_tags:[Memory] - ; field "target" ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN - ~qualifier:StaticRO + field "overhead" + ~lifecycle: + [(Published, rel_rio, "Virtualization memory overhead (bytes).")] + ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO + "Virtualization memory overhead (bytes)." ~default_value:(Some (VInt 0L)) + ~doc_tags:[Memory] + ; field "target" + ~lifecycle: + [ + ( Published + , rel_rio + , "Dynamically-set memory target (bytes). The value of this field \ + indicates the current target for memory available to this VM." + ) + ; (Deprecated, rel_midnight_ride, "") + ] + ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO "Dynamically-set memory target (bytes). The value of this field \ indicates the current target for memory available to this VM." - ~default_value:(Some (VInt 0L)) - ~internal_deprecated_since:rel_midnight_ride ~doc_tags:[Memory] - ; field "static_max" ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN - ~qualifier:StaticRO + ~default_value:(Some (VInt 0L)) ~doc_tags:[Memory] + ; field "static_max" + ~lifecycle: + [ + ( Published + , rel_rio + , "Statically-set (i.e. absolute) maximum (bytes). The value of this \ + field at VM start time acts as a hard limit of the amount of \ + memory a guest can use. New values only take effect on reboot." + ) + ] + ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO "Statically-set (i.e. absolute) maximum (bytes). The value of this field \ at VM start time acts as a hard limit of the amount of memory a guest \ can use. New values only take effect on reboot." ~doc_tags:[Memory] - ; field "dynamic_max" ~in_product_since:rel_rio + ; field "dynamic_max" + ~lifecycle:[(Published, rel_rio, "Dynamic maximum (bytes)")] ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO "Dynamic maximum (bytes)" ~doc_tags:[Memory] - ; field "dynamic_min" ~in_product_since:rel_rio + ; field "dynamic_min" + ~lifecycle:[(Published, rel_rio, "Dynamic minimum (bytes)")] ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO "Dynamic minimum (bytes)" ~doc_tags:[Memory] - ; field "static_min" ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN - ~qualifier:StaticRO + ; field "static_min" + ~lifecycle: + [ + ( Published + , rel_rio + , "Statically-set (i.e. absolute) mininum (bytes). The value of this \ + field indicates the least amount of memory this VM can boot with \ + without crashing." + ) + ] + ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO "Statically-set (i.e. absolute) mininum (bytes). The value of this field \ indicates the least amount of memory this VM can boot with without \ crashing." @@ -119,21 +170,36 @@ let on_normal_exit_behaviour = (** Virtual CPUs *) let vcpus = [ - field ~in_product_since:rel_rio + field + ~lifecycle: + [ + ( Published + , rel_rio + , "configuration parameters for the selected VCPU policy" + ) + ] ~ty:(Map (String, String)) "params" "configuration parameters for the selected VCPU policy" - ; field ~in_product_since:rel_rio ~qualifier:StaticRO ~ty:Int "max" - "Max number of VCPUs" - ; field ~in_product_since:rel_rio ~qualifier:StaticRO ~ty:Int "at_startup" - "Boot number of VCPUs" + ; field + ~lifecycle:[(Published, rel_rio, "Max number of VCPUs")] + ~qualifier:StaticRO ~ty:Int "max" "Max number of VCPUs" + ; field + ~lifecycle:[(Published, rel_rio, "Boot number of VCPUs")] + ~qualifier:StaticRO ~ty:Int "at_startup" "Boot number of VCPUs" ] (** Default actions *) let actions = - let crash = - field ~in_product_since:rel_rio ~qualifier:StaticRO ~ty:on_crash_behaviour + let crash name descr = + field ~qualifier:StaticRO ~ty:on_crash_behaviour + ~lifecycle:[(Published, rel_rio, descr)] + name descr + in + let normal name descr = + field ~ty:on_normal_exit_behaviour + ~lifecycle:[(Published, rel_rio, descr)] + name descr in - let normal = field ~in_product_since:rel_rio ~ty:on_normal_exit_behaviour in let soft = field ~qualifier:RW ~lifecycle:[] ~ty:on_softreboot_behavior ~default_value:(Some (VEnum "soft_reboot")) @@ -2493,7 +2559,11 @@ let t = ; remove_from_blocked_operations ] ~contents: - ([uid _vm] + ([ + uid _vm + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + ] @ allowed_and_current_operations operations @ [ namespace ~name:"name" @@ -2511,9 +2581,25 @@ let t = ) ] ~ty:power_state "power_state" "Current power state of the machine" - ; field ~ty:Int "user_version" ~in_product_since:rel_rio + ; field ~ty:Int "user_version" + ~lifecycle: + [ + ( Published + , rel_rio + , "Creators of VMs and templates may store version information \ + here." + ) + ] "Creators of VMs and templates may store version information here." - ; field ~effect:true ~ty:Bool "is_a_template" ~in_product_since:rel_rio + ; field ~effect:true ~ty:Bool "is_a_template" + ~lifecycle: + [ + ( Published + , rel_rio + , "true if this is a template. Template VMs can never be \ + started, they are used only for cloning other VMs" + ) + ] "true if this is a template. Template VMs can never be started, \ they are used only for cloning other VMs" ; field ~ty:Bool ~default_value:(Some (VBool false)) @@ -2535,44 +2621,74 @@ let t = ~ty:(Ref _vdi) "suspend_VDI" "The VDI that a suspend image is stored on. (Only has meaning if \ VM is currently suspended)" - ; field ~in_product_since:rel_rio ~writer_roles:_R_VM_POWER_ADMIN - ~qualifier:DynamicRO ~ty:(Ref _host) "resident_on" - "the host the VM is currently resident on" + ; field + ~lifecycle: + [(Published, rel_rio, "the host the VM is currently resident on")] + ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO ~ty:(Ref _host) + "resident_on" "the host the VM is currently resident on" ; field ~writer_roles:_R_VM_POWER_ADMIN ~in_oss_since:None - ~in_product_since:rel_rio ~qualifier:DynamicRO - ~default_value:(Some (VRef null_ref)) ~ty:(Ref _host) - "scheduled_to_be_resident_on" + ~lifecycle: + [ + ( Published + , rel_rio + , "the host on which the VM is due to be \ + started/resumed/migrated. This acts as a memory reservation \ + indicator" + ) + ] + ~qualifier:DynamicRO ~default_value:(Some (VRef null_ref)) + ~ty:(Ref _host) "scheduled_to_be_resident_on" "the host on which the VM is due to be started/resumed/migrated. \ This acts as a memory reservation indicator" ; field ~writer_roles:_R_VM_POWER_ADMIN ~in_oss_since:None - ~in_product_since:rel_rio ~ty:(Ref _host) "affinity" + ~lifecycle: + [ + ( Published + , rel_rio + , "A host which the VM has some affinity for (or NULL). This \ + is used as a hint to the start call when it decides where \ + to run the VM. Resource constraints may cause the VM to be \ + started elsewhere." + ) + ] + ~ty:(Ref _host) "affinity" "A host which the VM has some affinity for (or NULL). This is used \ as a hint to the start call when it decides where to run the VM. \ Resource constraints may cause the VM to be started elsewhere." ; namespace ~name:"memory" ~contents:guest_memory () ; namespace ~name:"VCPUs" ~contents:vcpus () ; namespace ~name:"actions" ~contents:actions () - ; field ~in_product_since:rel_rio ~writer_roles:_R_POOL_ADMIN - ~qualifier:DynamicRO ~ty:(Set (Ref _console)) "consoles" - "virtual console devices" - ; field ~in_product_since:rel_rio ~qualifier:DynamicRO - ~ty:(Set (Ref _vif)) ~doc_tags:[Networking] "VIFs" - "virtual network interfaces" - ; field ~in_product_since:rel_rio ~qualifier:DynamicRO - ~ty:(Set (Ref _vbd)) "VBDs" "virtual block devices" - ; field ~in_product_since:rel_rio ~qualifier:DynamicRO - ~ty:(Set (Ref _vusb)) "VUSBs" "virtual usb devices" - ; field ~in_product_since:rel_rio ~writer_roles:_R_POOL_ADMIN - ~qualifier:DynamicRO ~ty:(Set (Ref _crashdump)) "crash_dumps" + ; field + ~lifecycle:[(Published, rel_rio, "virtual console devices")] + ~writer_roles:_R_POOL_ADMIN ~qualifier:DynamicRO + ~ty:(Set (Ref _console)) "consoles" "virtual console devices" + ; field + ~lifecycle:[(Published, rel_rio, "virtual network interfaces")] + ~qualifier:DynamicRO ~ty:(Set (Ref _vif)) ~doc_tags:[Networking] + "VIFs" "virtual network interfaces" + ; field + ~lifecycle:[(Published, rel_rio, "virtual block devices")] + ~qualifier:DynamicRO ~ty:(Set (Ref _vbd)) "VBDs" + "virtual block devices" + ; field + ~lifecycle:[(Published, rel_rio, "virtual usb devices")] + ~qualifier:DynamicRO ~ty:(Set (Ref _vusb)) "VUSBs" + "virtual usb devices" + ; field + ~lifecycle: + [(Published, rel_rio, "crash dumps associated with this VM")] + ~writer_roles:_R_POOL_ADMIN ~qualifier:DynamicRO + ~ty:(Set (Ref _crashdump)) "crash_dumps" "crash dumps associated with this VM" - ; field ~in_product_since:rel_rio ~qualifier:DynamicRO - ~ty:(Set (Ref _vtpm)) "VTPMs" "virtual TPMs" + ; field + ~lifecycle:[(Published, rel_rio, "virtual TPMs")] + ~qualifier:DynamicRO ~ty:(Set (Ref _vtpm)) "VTPMs" "virtual TPMs" ; namespace ~name:"PV" ~contents:pv () ; namespace ~name:"HVM" ~contents:hvm () ; field ~ty:(Map (String, String)) - ~in_product_since:rel_rio "platform" - "platform-specific configuration" + ~lifecycle:[(Published, rel_rio, "platform-specific configuration")] + "platform" "platform-specific configuration" ; field ~lifecycle: [ @@ -2580,7 +2696,8 @@ let t = ; (Deprecated, rel_boston, "Field was never used") ] "PCI_bus" "PCI bus path for pass-through devices" - ; field ~in_product_since:rel_rio + ; field + ~lifecycle:[(Published, rel_rio, "additional configuration")] ~ty:(Map (String, String)) "other_config" "additional configuration" ~map_keys_roles: @@ -2589,22 +2706,53 @@ let t = ; ("folder", _R_VM_OP) ; ("XenCenter.CustomFields.*", _R_VM_OP) ] - ; field ~qualifier:DynamicRO ~ty:Int "domid" ~in_product_since:rel_rio + ; field ~qualifier:DynamicRO ~ty:Int "domid" + ~lifecycle: + [(Published, rel_rio, "domain ID (if available, -1 otherwise)")] "domain ID (if available, -1 otherwise)" ; field ~qualifier:DynamicRO ~in_oss_since:None - ~in_product_since:rel_rio ~ty:String "domarch" + ~lifecycle: + [ + ( Published + , rel_rio + , "Domain architecture (if available, null string otherwise)" + ) + ] + ~ty:String "domarch" "Domain architecture (if available, null string otherwise)" - ; field ~in_oss_since:None ~in_product_since:rel_rio ~qualifier:StaticRO + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "describes the CPU flags on which the VM was last booted" + ) + ] + ~qualifier:StaticRO ~ty:(Map (String, String)) ~default_value:(Some (VMap [])) "last_boot_CPU_flags" "describes the CPU flags on which the VM was last booted" - ; field ~in_product_since:rel_rio ~qualifier:DynamicRO ~ty:Bool - "is_control_domain" + ; field + ~lifecycle: + [ + ( Published + , rel_rio + , "true if this is a control domain (domain 0 or a driver \ + domain)" + ) + ] + ~qualifier:DynamicRO ~ty:Bool "is_control_domain" "true if this is a control domain (domain 0 or a driver domain)" - ; field ~in_product_since:rel_rio ~qualifier:DynamicRO - ~ty:(Ref _vm_metrics) "metrics" "metrics associated with this VM" - ; field ~in_product_since:rel_rio ~qualifier:DynamicRO - ~ty:(Ref _vm_guest_metrics) "guest_metrics" + ; field + ~lifecycle:[(Published, rel_rio, "metrics associated with this VM")] + ~qualifier:DynamicRO ~ty:(Ref _vm_metrics) "metrics" + "metrics associated with this VM" + ; field + ~lifecycle: + [ + (Published, rel_rio, "metrics associated with the running guest") + ] + ~qualifier:DynamicRO ~ty:(Ref _vm_guest_metrics) "guest_metrics" "metrics associated with the running guest" ; (* This was an internal field in Rio, Miami beta1, Miami beta2 but is now exposed so that it will be included automatically in Miami GA exports and can be restored, important if @@ -2626,25 +2774,59 @@ let t = ~qualifier:StaticRO ~ty:String "last_booted_record" "marshalled value containing VM record at time of last boot" ~default_value:(Some (VString "")) - ; field ~in_oss_since:None ~in_product_since:rel_rio ~ty:String - "recommendations" + ; field ~in_oss_since:None + ~lifecycle: + [ + ( Published + , rel_rio + , "An XML specification of recommended values and ranges for \ + properties of this VM" + ) + ] + ~ty:String "recommendations" "An XML specification of recommended values and ranges for \ properties of this VM" ; field ~effect:true ~in_oss_since:None ~ty:(Map (String, String)) - ~in_product_since:rel_miami ~qualifier:RW "xenstore_data" + ~lifecycle: + [ + ( Published + , rel_miami + , "data to be inserted into the xenstore tree \ + (/local/domain//vm-data) after the VM is created." + ) + ] + ~qualifier:RW "xenstore_data" "data to be inserted into the xenstore tree \ (/local/domain//vm-data) after the VM is created." ~default_value:(Some (VMap [])) ; field ~writer_roles:_R_POOL_OP ~in_oss_since:None ~ty:Bool - ~in_product_since:rel_orlando ~internal_deprecated_since:rel_boston + ~lifecycle: + [ + ( Published + , rel_orlando + , "if true then the system will attempt to keep the VM running \ + as much as possible." + ) + ; (Deprecated, rel_boston, "") + ] ~qualifier:StaticRO "ha_always_run" "if true then the system will attempt to keep the VM running as \ much as possible." ~default_value:(Some (VBool false)) ; field ~writer_roles:_R_POOL_OP ~in_oss_since:None ~ty:String - ~in_product_since:rel_orlando ~qualifier:StaticRO - "ha_restart_priority" + ~lifecycle: + [ + ( Published + , rel_orlando + , "has possible values: \"best-effort\" meaning \"try to \ + restart this VM if possible but don't consider the Pool to \ + be overcommitted if this is not possible\"; \"restart\" \ + meaning \"this VM should be restarted\"; \"\" meaning \"do \ + not try to restart this VM\"" + ) + ] + ~qualifier:StaticRO "ha_restart_priority" "has possible values: \"best-effort\" meaning \"try to restart \ this VM if possible but don't consider the Pool to be \ overcommitted if this is not possible\"; \"restart\" meaning \ @@ -2652,54 +2834,127 @@ let t = restart this VM\"" ~default_value:(Some (VString "")) ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_orlando ~default_value:(Some (VBool false)) - ~ty:Bool "is_a_snapshot" + ~lifecycle: + [ + ( Published + , rel_orlando + , "true if this is a snapshot. Snapshotted VMs can never be \ + started, they are used only for cloning other VMs" + ) + ] + ~default_value:(Some (VBool false)) ~ty:Bool "is_a_snapshot" "true if this is a snapshot. Snapshotted VMs can never be started, \ they are used only for cloning other VMs" ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_orlando ~default_value:(Some (VRef "")) - ~ty:(Ref _vm) "snapshot_of" + ~lifecycle: + [ + ( Published + , rel_orlando + , "Ref pointing to the VM this snapshot is of." + ) + ] + ~default_value:(Some (VRef "")) ~ty:(Ref _vm) "snapshot_of" "Ref pointing to the VM this snapshot is of." ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_orlando ~ty:(Set (Ref _vm)) "snapshots" + ~lifecycle: + [ + ( Published + , rel_orlando + , "List pointing to all the VM snapshots." + ) + ] + ~ty:(Set (Ref _vm)) "snapshots" "List pointing to all the VM snapshots." ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_orlando + ~lifecycle: + [ + ( Published + , rel_orlando + , "Date/time when this snapshot was created." + ) + ] ~default_value:(Some (VDateTime Date.epoch)) ~ty:DateTime "snapshot_time" "Date/time when this snapshot was created." ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_orlando ~default_value:(Some (VString "")) - ~ty:String "transportable_snapshot_id" - "Transportable ID of the snapshot VM" - ; field ~qualifier:DynamicRO ~in_product_since:rel_orlando + ~lifecycle: + [(Published, rel_orlando, "Transportable ID of the snapshot VM")] + ~default_value:(Some (VString "")) ~ty:String + "transportable_snapshot_id" "Transportable ID of the snapshot VM" + ; field ~qualifier:DynamicRO + ~lifecycle: + [(Published, rel_orlando, "Binary blobs associated with this VM")] ~ty:(Map (String, Ref _blob)) ~default_value:(Some (VMap [])) "blobs" "Binary blobs associated with this VM" - ; field ~writer_roles:_R_VM_OP ~in_product_since:rel_orlando + ; field ~writer_roles:_R_VM_OP + ~lifecycle: + [ + ( Published + , rel_orlando + , "user-specified tags for categorization purposes" + ) + ] ~default_value:(Some (VSet [])) ~ty:(Set String) "tags" "user-specified tags for categorization purposes" - ; field ~in_product_since:rel_orlando ~default_value:(Some (VMap [])) - ~qualifier:StaticRO + ; field + ~lifecycle: + [ + ( Published + , rel_orlando + , "List of operations which have been explicitly blocked and \ + an error code" + ) + ] + ~default_value:(Some (VMap [])) ~qualifier:StaticRO ~ty:(Map (operations, String)) "blocked_operations" "List of operations which have been explicitly blocked and an \ error code" ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_midnight_ride ~default_value:(Some (VMap [])) + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Human-readable information concerning this snapshot" + ) + ] + ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "snapshot_info" "Human-readable information concerning this snapshot" ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_midnight_ride + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Encoded information about the VM's metadata this is a \ + snapshot of" + ) + ] ~default_value:(Some (VString "")) ~ty:String "snapshot_metadata" "Encoded information about the VM's metadata this is a snapshot of" ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_midnight_ride ~default_value:(Some (VRef "")) - ~ty:(Ref _vm) "parent" "Ref pointing to the parent of this VM" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "Ref pointing to the parent of this VM" + ) + ] + ~default_value:(Some (VRef "")) ~ty:(Ref _vm) "parent" + "Ref pointing to the parent of this VM" ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:DynamicRO - ~in_product_since:rel_midnight_ride ~ty:(Set (Ref _vm)) "children" + ~lifecycle: + [ + ( Published + , rel_midnight_ride + , "List pointing to all the children of this VM" + ) + ] + ~ty:(Set (Ref _vm)) "children" "List pointing to all the children of this VM" - ; field ~qualifier:DynamicRO ~in_product_since:rel_midnight_ride + ; field ~qualifier:DynamicRO + ~lifecycle:[(Published, rel_midnight_ride, "BIOS strings")] ~default_value:(Some (VMap [])) ~ty:(Map (String, String)) "bios_strings" "BIOS strings" @@ -2712,30 +2967,65 @@ let t = "is_snapshot_from_vmpp" "true if this snapshot was created by the protection policy" ; field ~writer_roles:_R_VM_POWER_ADMIN ~qualifier:StaticRO - ~in_product_since:rel_falcon ~default_value:(Some (VRef null_ref)) - ~ty:(Ref _vmss) "snapshot_schedule" + ~lifecycle: + [ + ( Published + , rel_falcon + , "Ref pointing to a snapshot schedule for this VM" + ) + ] + ~default_value:(Some (VRef null_ref)) ~ty:(Ref _vmss) + "snapshot_schedule" "Ref pointing to a snapshot schedule for this VM" ; field ~writer_roles:_R_POOL_OP ~qualifier:StaticRO - ~in_product_since:rel_falcon ~default_value:(Some (VBool false)) - ~ty:Bool "is_vmss_snapshot" + ~lifecycle: + [ + ( Published + , rel_falcon + , "true if this snapshot was created by the snapshot schedule" + ) + ] + ~default_value:(Some (VBool false)) ~ty:Bool "is_vmss_snapshot" "true if this snapshot was created by the snapshot schedule" ; field ~writer_roles:_R_POOL_OP ~qualifier:StaticRO - ~in_product_since:rel_rio ~ty:(Ref _vm_appliance) - ~default_value:(Some (VRef null_ref)) "appliance" - "the appliance to which this VM belongs" + ~lifecycle: + [(Published, rel_rio, "the appliance to which this VM belongs")] + ~ty:(Ref _vm_appliance) ~default_value:(Some (VRef null_ref)) + "appliance" "the appliance to which this VM belongs" ; field ~writer_roles:_R_POOL_OP ~qualifier:StaticRO - ~in_product_since:rel_boston ~default_value:(Some (VInt 0L)) ~ty:Int - "start_delay" + ~lifecycle: + [ + ( Published + , rel_boston + , "The delay to wait before proceeding to the next order in \ + the startup sequence (seconds)" + ) + ] + ~default_value:(Some (VInt 0L)) ~ty:Int "start_delay" "The delay to wait before proceeding to the next order in the \ startup sequence (seconds)" ; field ~writer_roles:_R_POOL_OP ~qualifier:StaticRO - ~in_product_since:rel_boston ~default_value:(Some (VInt 0L)) ~ty:Int - "shutdown_delay" + ~lifecycle: + [ + ( Published + , rel_boston + , "The delay to wait before proceeding to the next order in \ + the shutdown sequence (seconds)" + ) + ] + ~default_value:(Some (VInt 0L)) ~ty:Int "shutdown_delay" "The delay to wait before proceeding to the next order in the \ shutdown sequence (seconds)" ; field ~writer_roles:_R_POOL_OP ~qualifier:StaticRO - ~in_product_since:rel_boston ~default_value:(Some (VInt 0L)) ~ty:Int - "order" + ~lifecycle: + [ + ( Published + , rel_boston + , "The point in the startup or shutdown sequence at which this \ + VM will be started" + ) + ] + ~default_value:(Some (VInt 0L)) ~ty:Int "order" "The point in the startup or shutdown sequence at which this VM \ will be started" ; field ~qualifier:DynamicRO @@ -2746,18 +3036,38 @@ let t = ~ty:(Set (Ref _pci)) "attached_PCIs" "Currently passed-through PCI devices" ; field ~writer_roles:_R_VM_ADMIN ~qualifier:RW - ~in_product_since:rel_boston ~default_value:(Some (VRef null_ref)) - ~ty:(Ref _sr) "suspend_SR" + ~lifecycle: + [ + ( Published + , rel_boston + , "The SR on which a suspend image is stored" + ) + ] + ~default_value:(Some (VRef null_ref)) ~ty:(Ref _sr) "suspend_SR" "The SR on which a suspend image is stored" - ; field ~qualifier:StaticRO ~in_product_since:rel_boston + ; field ~qualifier:StaticRO + ~lifecycle: + [ + ( Published + , rel_boston + , "The number of times this VM has been recovered" + ) + ] ~default_value:(Some (VInt 0L)) ~ty:Int "version" "The number of times this VM has been recovered" - ; field ~qualifier:StaticRO ~in_product_since:rel_clearwater + ; field ~qualifier:StaticRO + ~lifecycle:[(Published, rel_clearwater, "Generation ID of the VM")] ~default_value:(Some (VString "0:0")) ~ty:String "generation_id" "Generation ID of the VM" ; field ~writer_roles:_R_VM_ADMIN ~qualifier:RW - ~in_product_since:rel_cream ~default_value:(Some (VInt 0L)) ~ty:Int - "hardware_platform_version" + ~lifecycle: + [ + ( Published + , rel_cream + , "The host virtual hardware platform version the VM can run on" + ) + ] + ~default_value:(Some (VInt 0L)) ~ty:Int "hardware_platform_version" "The host virtual hardware platform version the VM can run on" ; field ~qualifier:StaticRO ~lifecycle: @@ -2778,7 +3088,18 @@ let t = ~default_value:(Some (VBool false)) "requires_reboot" "Indicates whether a VM requires a reboot in order to update its \ configuration, e.g. its memory allocation." - ; field ~qualifier:StaticRO ~ty:String ~in_product_since:rel_ely + ; field ~qualifier:StaticRO ~ty:String + ~lifecycle: + [ + ( Published + , rel_ely + , "Textual reference to the template used to create a VM. This \ + can be used by clients in need of an immutable reference to \ + the template since the latter's uuid and name_label may \ + change, for example, after a package installation or \ + upgrade." + ) + ] ~default_value:(Some (VString "")) "reference_label" "Textual reference to the template used to create a VM. This can \ be used by clients in need of an immutable reference to the \ @@ -2802,7 +3123,16 @@ let t = "NVRAM" ~default_value:(Some (VMap [])) "initial value for guest NVRAM (containing UEFI variables, etc). \ Cannot be changed while the VM is running" - ; field ~qualifier:DynamicRO ~in_product_since:"1.303.0" + ; field ~qualifier:DynamicRO + ~lifecycle: + [ + ( Published + , "1.303.0" + , "The set of pending mandatory guidances after applying \ + updates, which must be applied, as otherwise there may be \ + e.g. VM failures" + ) + ] ~ty:(Set update_guidances) "pending_guidances" ~default_value:(Some (VSet [])) "The set of pending mandatory guidances after applying updates, \ diff --git a/ocaml/idl/datamodel_vm_group.ml b/ocaml/idl/datamodel_vm_group.ml index efc86791bd8..75924f8c150 100644 --- a/ocaml/idl/datamodel_vm_group.ml +++ b/ocaml/idl/datamodel_vm_group.ml @@ -33,6 +33,8 @@ let t = ~contents: [ uid _vm_group + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] ; namespace ~name:"name" ~contents:(names ~lifecycle:[(Published, rel_rio, "")] None RW) () diff --git a/ocaml/idl/datamodel_vtpm.ml b/ocaml/idl/datamodel_vtpm.ml index 3c31614a9a1..692aae12637 100644 --- a/ocaml/idl/datamodel_vtpm.ml +++ b/ocaml/idl/datamodel_vtpm.ml @@ -73,14 +73,31 @@ let t = ~contents: (List.concat [ - [uid _vtpm] + [ + uid _vtpm + ~lifecycle: + [(Published, rel_rio, "Unique identifier/object reference")] + ] ; allowed_and_current_operations operations ; [ field ~qualifier:StaticRO ~ty:(Ref _vm) "VM" - ~in_product_since:rel_rio + ~lifecycle: + [ + ( Published + , rel_rio + , "The virtual machine the TPM is attached to" + ) + ] "The virtual machine the TPM is attached to" ; field ~qualifier:DynamicRO ~ty:(Ref _vm) "backend" - ~in_product_since:rel_rio ~default_value:(Some (VRef null_ref)) + ~lifecycle: + [ + ( Published + , rel_rio + , "The domain where the backend is located (unused)" + ) + ] + ~default_value:(Some (VRef null_ref)) "The domain where the backend is located (unused)" ; field ~qualifier:DynamicRO ~ty:persistence_backend ~default_value:(Some (VEnum "xapi")) ~lifecycle:[] From 51ccf7036585a357caf4a62c70c14baa34e391b0 Mon Sep 17 00:00:00 2001 From: Andrii Sultanov Date: Mon, 23 Sep 2024 15:55:34 +0100 Subject: [PATCH 7/8] idl: Remove in_product_since and internal_deprecated_since parameters for fields Signed-off-by: Andrii Sultanov --- ocaml/idl/datamodel_common.ml | 43 ++++------------------------------- 1 file changed, 5 insertions(+), 38 deletions(-) diff --git a/ocaml/idl/datamodel_common.ml b/ocaml/idl/datamodel_common.ml index 6ae642be5b3..7c557282259 100644 --- a/ocaml/idl/datamodel_common.ml +++ b/ocaml/idl/datamodel_common.ml @@ -653,46 +653,16 @@ let operation_enum x = (x.msg_name, Printf.sprintf "refers to the operation \"%s\"" x.msg_name) (** Make an object field record *) -let field ?(in_oss_since = Some "3.0.3") ?in_product_since - ?(internal_only = false) ?internal_deprecated_since +let field ?(in_oss_since = Some "3.0.3") ?(internal_only = false) ?(ignore_foreign_key = false) ?(writer_roles = None) ?(reader_roles = None) ?(qualifier = RW) ?(ty = String) ?(effect = false) ?(default_value = None) ?(persist = true) ?(map_keys_roles = []) ?(* list of (key_name,(writer_roles)) for a map field *) lifecycle ?(doc_tags = []) name desc = - (* in_product_since currently defaults to 'Some rel_rio', for backwards compatibility. - * This should eventually become 'None'. *) - let _ = - match (lifecycle, in_product_since) with - | None, None -> - failwith ("Lifecycle for field '" ^ name ^ "' not specified") - | Some _, Some _ -> - failwith - ("lifecycle is given, in_product_since should not be specified \ - explicitly in " - ^ name - ) - | _, _ -> - () - in let lifecycle = match lifecycle with | None -> - let published = - match in_product_since with - | None -> - [] - | Some rel -> - [(Published, rel, desc)] - in - let deprecated = - match internal_deprecated_since with - | None -> - [] - | Some rel -> - [(Deprecated, rel, "")] - in - published @ deprecated + failwith ("Lifecycle for field '" ^ name ^ "' not specified") | Some l -> l in @@ -731,9 +701,7 @@ let field ?(in_oss_since = Some "3.0.3") ?in_product_since let uid ?(in_oss_since = Some "3.0.3") ?(reader_roles = None) ?lifecycle _refname = - let in_product_since = if lifecycle = None then Some rel_rio else None in - field ~in_oss_since ?in_product_since ?lifecycle ~qualifier:DynamicRO - ~ty:String + field ~in_oss_since ?lifecycle ~qualifier:DynamicRO ~ty:String ~writer_roles:_R_POOL_ADMIN (* only the system should be able to create/modify uuids *) ~reader_roles "uuid" "Unique identifier/object reference" @@ -794,10 +762,9 @@ let namespace ?(get_field_writer_roles = fun x -> x) (** Many of the objects have a set of names of various lengths: *) let names ?(writer_roles = None) ?(reader_roles = None) ?lifecycle in_oss_since qual = - let in_product_since = if lifecycle = None then Some rel_rio else None in let field x y = - field x y ~in_oss_since ?in_product_since ~qualifier:qual ~writer_roles - ~reader_roles ~default_value:(Some (VString "")) ?lifecycle + field x y ~in_oss_since ~qualifier:qual ~writer_roles ~reader_roles + ~default_value:(Some (VString "")) ?lifecycle in [ field "label" "a human-readable name" From 2f50ab1a81ec4bf4cd51a761de9408407667a97b Mon Sep 17 00:00:00 2001 From: Andrii Sultanov Date: Tue, 24 Sep 2024 09:00:11 +0100 Subject: [PATCH 8/8] Update docs on in_product_since, specify that lifecycle is now preferred Signed-off-by: Andrii Sultanov --- .../xapi/guides/howtos/add-function.md | 71 ++++++------------- 1 file changed, 22 insertions(+), 49 deletions(-) diff --git a/doc/content/xapi/guides/howtos/add-function.md b/doc/content/xapi/guides/howtos/add-function.md index 07ef3cebfd4..8aeedfb27fb 100644 --- a/doc/content/xapi/guides/howtos/add-function.md +++ b/doc/content/xapi/guides/howtos/add-function.md @@ -22,7 +22,7 @@ The function to describe the new message will look something like the following: let host_price_of = call ~flags:[`Session] ~name:"price_of" ~in_oss_since:None - ~in_product_since:rel_orlando + ~lifecycle:[] ~params:[(Ref _host, "host", "The host containing the price information"); (String, "item", "The item whose price is queried")] ~result:(Float, "The price of the item") @@ -41,15 +41,14 @@ host_price_of is added to the messages of the host class: ] ... -The parameters passed to call are all optional (except ~name and ~in_product_since). +The parameters passed to call are all optional (except ~name and ~lifecycle). - The ~flags parameter is used to set conditions for the use of the message. For example, `Session is used to indicate that the call must be made in the presence of an existing session. -- The value of the ~in_product_since parameter is a string taken from - `idl/datamodel_types.ml` indicates the XenServer release in which this - message was first introduced. +- The value of the `~lifecycle` parameter should be `[]` in new code, with dune + automatically generating appropriate values (`datamodel_lifecycle.ml`) - The ~params parameter describes a list of the formal parameters of the message. Each parameter is described by a triple. The first component of the triple is @@ -66,7 +65,7 @@ The parameters passed to call are all optional (except ~name and ~in_product_sin - The bool ~hide_from_docs parameter prevents the message from being included in the documentation when generated. -- The bool ~pool_internal parameter is used to indicate if the message should be callable by external systems or only internal hosts. +- The bool ~pool_internal parameter is used to indicate if the message should be callable by external systems or only internal hosts. - The ~errs parameter is a list of possible exceptions that the message can raise. @@ -76,53 +75,27 @@ The parameters passed to call are all optional (except ~name and ~in_product_sin Compiling `xen-api.(hg|git)` will cause the code corresponding to this message -to be generated and output in `ocaml/xapi/server.ml`. In the example above, a +to be generated and output in `ocaml/xapi/server.ml`. In the example above, a section handling an incoming call host.price_of appeared in `ocaml/xapi/server.ml`. -However, after this was generated, the rest of the build failed because this +However, after this was generated, the rest of the build failed because this call expects a price_of function in the Host object. -Expected values in parameter ~in_product_since ----------------------------------------------- - -In the example above, the value of the parameter ~in_product_since informs that -the message host_price_of was added during the rel_orlando release cycle. If a -new release cycle is required, then it needs to be added in the file -`idl/datamodel_types.ml`. The patch below shows how the new rel_george release -identifier was added. Any class, message, etc. added during the rel_george -release cycle should contain ~in_product_since:rel_george entries. -(obs: the release and upgrade infrastructure can handle only one new -`rel_*` identifier -- in this case, rel_george -- in each release) - - --- a/ocaml/idl/datamodel_types.ml Tue Nov 11 15:17:48 2008 +0000 - +++ b/ocaml/idl/datamodel_types.ml Tue Nov 11 15:53:29 2008 +0000 - @@ -27,14 +27,13 @@ - (* useful constants for product vsn tracking *) - let oss_since_303 = Some "3.0.3" - +let rel_george = "george" - let rel_orlando = "orlando" - let rel_orlando_update_1 = "orlando-update-1" - let rel_symc = "symc" - let rel_miami = "miami" - let rel_rio = "rio" - -let release_order = [engp:rel_rio; rel_miami; rel_symc; rel_orlando; rel_orlando_update_1] - +let release_order = [engp:rel_rio; rel_miami; rel_symc; rel_orlando; rel_orlando_update_1; rel_george] - Update expose_get_all_messages_for list --------------------------------------- -If you are adding a new class, do not forget to add your new class \_name to -the expose_get_all_messages_for list, at the bottom of datamodel.ml, in +If you are adding a new class, do not forget to add your new class \_name to +the expose_get_all_messages_for list, at the bottom of datamodel.ml, in order to have automatically generated get_all and get_all_records functions attached to it. Update the RBAC field containing the roles expected to use the new API call --------------------------------------------------------------------------- -After the RBAC integration, Xapi provides by default a set of static roles +After the RBAC integration, Xapi provides by default a set of static roles associated to the most common subject tasks. The api calls associated with each role are defined by a new `~allowed_roles` -parameter in each api call, which specifies the list of static roles that +parameter in each api call, which specifies the list of static roles that should be able to execute the call. The possible roles for this list is one of the following names, defined in `datamodel.ml`: @@ -137,16 +110,16 @@ So, for instance, ~allowed_roles:[role_pool_admin,role_pool_operator] (* this is not the recommended usage, see example below *) -would be a valid list (though it is not the recommended way of using +would be a valid list (though it is not the recommended way of using allowed_roles, see below), meaning that subjects belonging to either role_pool_admin or role_pool_operator can execute the api call. -The RBAC requirements define a policy where the roles in the list above are -supposed to be totally-ordered by the set of api-calls associated with each of -them. That means that any api-call allowed to role_pool_operator should also be -in role_pool_admin; any api-call allowed to role_vm_power_admin should also be -in role_pool_operator and also in role_pool_admin; and so on. Datamodel.ml -provides shortcuts for expressing these totally-ordered set of roles policy +The RBAC requirements define a policy where the roles in the list above are +supposed to be totally-ordered by the set of api-calls associated with each of +them. That means that any api-call allowed to role_pool_operator should also be +in role_pool_admin; any api-call allowed to role_vm_power_admin should also be +in role_pool_operator and also in role_pool_admin; and so on. Datamodel.ml +provides shortcuts for expressing these totally-ordered set of roles policy associated with each api-call: - \_R_POOL_ADMIN, equivalent to [role_pool_admin] @@ -158,11 +131,11 @@ associated with each api-call: The `~allowed_roles` parameter should use one of the shortcuts in the list above, instead of directly using a list of roles, because the shortcuts above make sure -that the roles in the list are in a total order regarding the api-calls +that the roles in the list are in a total order regarding the api-calls permission sets. Creating an api-call with e.g. allowed_roles:[role_pool_admin,role_vm_admin] would be wrong, because that -would mean that a pool_operator cannot execute the api-call that a vm_admin can, -breaking the total-order policy expected in the RBAC 1.0 implementation. +would mean that a pool_operator cannot execute the api-call that a vm_admin can, +breaking the total-order policy expected in the RBAC 1.0 implementation. In the future, this requirement might be relaxed. So, the example above should instead be used as: @@ -224,7 +197,7 @@ We add the following function to `xapi/xapi_host.ml`: let price_of ~__context ~host ~item = if item = "fish" then 3.14 else 0.00 - + We also need to add the function to the interface `xapi/xapi_host.mli`: val price_of :