xapi-project · changlei-li · Jul 10, 2025 · May 22, 2025 · May 27, 2025 · May 27, 2025
diff --git a/doc/content/design/sm-supported-image-formats.md b/doc/content/design/sm-supported-image-formats.md
@@ -2,7 +2,7 @@
 title: Add supported image formats in sm-list
 layout: default
 design_doc: true
-revision: 2
+revision: 3
 status: proposed
 ---
 
@@ -22,32 +22,16 @@ available formats.
 # Design Proposal
 
 To expose the available image formats to clients (e.g., XenCenter, XenOrchestra, etc.),
-we propose adding a new field called `supported-image-formats` to the Storage Manager (SM)
-module. This field will be included in the output of the `SM.get_all_records` call.
+we propose adding a new field called `supported_image_formats` to the Storage Manager
+(SM) module. This field will be included in the output of the `SM.get_all_records` call.
 
-The `supported-image-formats` field will be populated by retrieving information
-from the SMAPI drivers. Specifically, each driver will update its `DRIVER_INFO`
-dictionary with a new key, `supported_image_formats`, which will contain a list
-of strings representing the supported image formats
-(for example: `["vhd", "raw", "qcow2"]`).
-
-The list designates the driver's preferred VDI format as its first entry. That
-means that when migrating a VDI, the destination storage repository will
-attempt to create a VDI in this preferred format. If the default format cannot
-be used (e.g., due to size limitations), an error will be generated.
-
-If a driver does not provide this information (as is currently the case with existing
-drivers), the default value will be an empty array. This signifies that it is the
-driver that decides which format it will use. This ensures that the modification
-remains compatible with both current and future drivers.
-
-With this new information, listing all parameters of the SM object will return:
+- With this new information, listing all parameters of the SM object will return:
 
 ```bash
 # xe sm-list params=all
 ```
 
-will output something like:
+Output of the command will look like (notice that CLI uses hyphens):
 
 ```
 uuid ( RO)                         : c6ae9a43-fff6-e482-42a9-8c3f8c533e36
@@ -65,12 +49,118 @@ required-cluster-stack ( RO)       :
 supported-image-formats ( RO)       : vhd, raw, qcow2
 ```
 
-This change impacts the SM data model, and as such, the XAPI database version will
-be incremented.
+## Implementation details
+
+The `supported_image_formats` field will be populated by retrieving information
+from the SMAPI drivers. Specifically, each driver will update its `DRIVER_INFO`
+dictionary with a new key, `supported_image_formats`, which will contain a list
+of strings representing the supported image formats
+(for example: `["vhd", "raw", "qcow2"]`). Although the formats are listed as a
+list of strings, they are treated as a set-specifying the same format multiple
+times has no effect.
+
+### Driver behavior without `supported_image_formats`
+
+If a driver does not provide this information (as is currently the case with
+existing drivers), the default value will be an empty list. This signifies
+that the driver determines which format to use when creating VDI. During a migration,
+the destination driver will choose the format of the VDI if none is explicitly
+specified. This ensures backward compatibility with both current and future drivers.
+
+### Specifying image formats for VDIs creation
+
+If the supported image format is exposed to the client, then, when creating new VDI,
+user can specify the desired format via the `sm_config` parameter `image-format=qcow2` (or
+any format that is supported). If no format is specified, the driver will use its
+preferred default format. If the specified format is not supported, an error will be
+generated indicating that the SR does not support it. Here is how it can be achieved
+using the XE CLI:
+
+```bash
+# xe vdi-create \
+    sr-uuid=cbe2851e-9f9b-f310-9bca-254c1cf3edd8 \
+    name-label="A new VDI" \
+    virtual-size=10240 \
+    sm-config:image-format=vhd
+```
+
+### Specifying image formats for VDIs migration
+
+When migrating a VDI, an API client may need to specify the desired image format if
+the destination SR supports multiple storage formats.
+
+#### VDI pool migrate
+
+To support this, a new parameter, `dest_img_format`, is introduced to
+`VDI.pool_migrate`. This field accepts a string specifying the desired format (e.g., *qcow2*),
+ensuring that the VDI is migrated in the correct format. The new signature of
+`VDI.pool_migrate` will be
+`VDI ref pool_migrate (session ref, VDI ref, SR ref, string, (string -> string) map)`.
+
+If the specified format is not supported or cannot be used (e.g., due to size limitations),
+an error will be generated. Validation will be performed as early as possible to prevent
+disruptions during migration. These checks can be performed by examining the XAPI database
+to determine whether the SR provided as the destination has a corresponding SM object with
+the expected format. If this is not the case, a `format not found` error will be returned.
+If no format is specified by the client, the destination driver will determine the appropriate
+format.
+
+```bash
+# xe vdi-pool-migrate \
+    uuid=<VDI_UUID> \
+    sr-uuid=<SR_UUID> \
+    dest-img-format=qcow2
+```
+
+#### VM migration to remote host
+
+A VDI migration can also occur during a VM migration. In this case, we need to
+be able to specify the expected destination format as well. Unlike `VDI.pool_migrate`,
+which applies to a single VDI, VM migration may involve multiple VDIs.
+The current signature of `VM.migrate_send` is `(session ref, VM ref, (string -> string) map,
+bool, (VDI ref -> SR ref) map, (VIF ref -> network ref) map, (string -> string) map,
+(VGPU ref -> GPU_group ref) map)`. Thus there is already a parameter that maps each source
+VDI to its destination SR. We propose to add a new parameter that allows specifying the
+desired destination format for a given source VDI: `(VDI ref -> string)`. It is
+similar to the VDI-to-SR mapping. We will update the XE cli to support this new format.
+It would be `image_format:<source-vdi-uuid>=<destination-image-format>`:
+
+```bash
+# xe vm-migrate \
+        host-uuid=<HOST_UUID> \
+        remote-master=<IP> \
+        remote-password=<PASS> \
+        remote-username=<USER> \
+        vdi:<VDI1_UUID>=<SR1_DEST_UUID> \
+        vdi:<VDI2_UUID>=<SR2_DEST_UUID> \
+        image-format:<VDI1_UUID>=vhd \
+        image-format:<VDI2_UUID>=qcow2 \
+        uuid=<VM_UUID>
+```
+The destination image format would be a string such as *vhd*, *qcow2*, or another
+supported format. It is optional to specify a format. If omitted, the driver
+managing the destination SR will determine the appropriate format.
+As with VDI pool migration, if this parameter is not supported by the SM driver,
+a `format not found` error will be returned. The validation must happen before
+sending a creation message to the SM driver, ideally at the same time as checking
+whether all VDIs can be migrated.
+
+To be able to check the format, we will need to modify `VM.assert_can_migrate` and
+add the mapping from VDI references to their image formats, as is done in `VM.migrate_send`.
 
 # Impact
 
-- **Data Model:** A new field (`supported-image-formats`) is added to the SM records.
+It should have no impact on existing storage repositories that do not provide any information
+about the supported image format.
+
+This change impacts the SM data model, and as such, the XAPI database version will
+be incremented. It also impacts the API.
+
+- **Data Model:**
+  - A new field (`supported_image_formats`) is added to the SM records.
+  - A new parameter is added to `VM.migrate_send`: `(VDI ref -> string) map`
+  - A new parameter is added to `VM.assert_can_migrate`: `(VDI ref -> string) map`
+  - A new parameter is added to `VDI.pool_migrate`: `string`
 - **Client Awareness:** Clients like the `xe` CLI will now be able to query and display the supported image formats for a given SR.
 - **Database Versioning:** The XAPI database version will be updated to reflect this change.
 
diff --git a/dune-project b/dune-project
@@ -221,7 +221,17 @@
  (name xapi-nbd))
 
 (package
- (name xapi-log))
+ (name xapi-log)
+ (synopsis "A Logs library required by xapi")
+ (description
+  "This package is provided for backwards compatibility only. No new package should use it.")
+ (depends
+  astring
+  fmt
+  logs
+  mtime
+  xapi-backtrace
+  (xapi-stdext-pervasives (= :version))))
 
 (package
  (name xapi-idl))
@@ -651,6 +661,7 @@
    (= :version))
   (xapi-stdext-threads
    (= :version))
+  (xapi-tracing (= :version))
   (odoc :with-doc)))
 
 (package
@@ -669,7 +680,8 @@
   ppx_deriving_rpc
   rpclib
   (xapi-stdext-threads
-   (= :version))))
+   (= :version))
+  (xapi-tracing (= :version))))
 
 (package
  (name message-switch))

diff --git a/ocaml/idl/datamodel_errors.ml b/ocaml/idl/datamodel_errors.ml
@@ -532,28 +532,10 @@ let _ =
       "You attempted an operation on a VM which requires a more recent version \
        of the PV drivers. Please upgrade your PV drivers."
     () ;
-  error Api_errors.vm_lacks_feature_shutdown ["vm"]
-    ~doc:
-      "You attempted an operation which needs the cooperative shutdown feature \
-       on a VM which lacks it."
-    () ;
-  error Api_errors.vm_lacks_feature_vcpu_hotplug ["vm"]
-    ~doc:
-      "You attempted an operation which needs the VM hotplug-vcpu feature on a \
-       VM which lacks it."
-    () ;
-  error Api_errors.vm_lacks_feature_suspend ["vm"]
-    ~doc:
-      "You attempted an operation which needs the VM cooperative suspend \
-       feature on a VM which lacks it."
-    () ;
-  error Api_errors.vm_lacks_feature_static_ip_setting ["vm"]
-    ~doc:
-      "You attempted an operation which needs the VM static-ip-setting feature \
-       on a VM which lacks it."
-    () ;
   error Api_errors.vm_lacks_feature ["vm"]
     ~doc:"You attempted an operation on a VM which lacks the feature." () ;
+  error Api_errors.vm_non_suspendable ["vm"; "reason"]
+    ~doc:"You attempted an operation on a VM which is not suspendable." () ;
   error Api_errors.vm_is_template ["vm"]
     ~doc:"The operation attempted is not valid for a template VM" () ;
   error Api_errors.other_operation_in_progress ["class"; "object"]
@@ -2068,6 +2050,9 @@ let _ =
        enable it in XC or run xe pool-enable-tls-verification instead."
     () ;
 
+  error Api_errors.sysprep ["vm"; "message"]
+    ~doc:"VM.sysprep error with details in the message" () ;
+
   message
     (fst Api_messages.ha_pool_overcommitted)
     ~doc:

diff --git a/ocaml/idl/datamodel_host.ml b/ocaml/idl/datamodel_host.ml
@@ -1304,7 +1304,7 @@ let create_params =
       param_type= Bool
     ; param_name= "ssh_enabled"
     ; param_doc= "True if SSH access is enabled for the host"
-    ; param_release= numbered_release "25.20.0-next"
+    ; param_release= numbered_release "25.21.0"
     ; param_default= Some (VBool Constants.default_ssh_enabled)
     }
   ; {
@@ -1314,7 +1314,7 @@ let create_params =
         "The timeout in seconds after which SSH access will be automatically \
          disabled (0 means never), this setting will be applied every time the \
          SSH is enabled by XAPI"
-    ; param_release= numbered_release "25.20.0-next"
+    ; param_release= numbered_release "25.21.0"
     ; param_default= Some (VInt Constants.default_ssh_enabled_timeout)
     }
   ; {
@@ -1323,7 +1323,7 @@ let create_params =
     ; param_doc=
         "The time in UTC after which the SSH access will be automatically \
          disabled"
-    ; param_release= numbered_release "25.20.0-next"
+    ; param_release= numbered_release "25.21.0"
     ; param_default= Some (VDateTime Date.epoch)
     }
   ; {
@@ -1332,7 +1332,7 @@ let create_params =
     ; param_doc=
         "The timeout in seconds after which idle console will be automatically \
          terminated (0 means never)"
-    ; param_release= numbered_release "25.20.0-next"
+    ; param_release= numbered_release "25.21.0"
     ; param_default= Some (VInt Constants.default_console_idle_timeout)
     }
   ]
@@ -1348,7 +1348,7 @@ let create =
            kept for host joined a pool"
         )
       ; ( Changed
-        , "25.20.0-next"
+        , "25.21.0"
         , "Added --ssh_enabled --ssh_enabled_timeout --ssh_expiry \
            --console_idle_timeout options to allow them to be configured for \
            new host"

diff --git a/ocaml/idl/datamodel_lifecycle.ml b/ocaml/idl/datamodel_lifecycle.ml
@@ -239,14 +239,16 @@ let prototyped_of_message = function
       Some "25.2.0"
   | "host", "set_numa_affinity_policy" ->
       Some "24.0.0"
+  | "VM", "sysprep" ->
+      Some "25.24.0"
   | "VM", "get_secureboot_readiness" ->
       Some "24.17.0"
   | "VM", "set_uefi_mode" ->
       Some "24.17.0"
   | "VM", "restart_device_models" ->
       Some "23.30.0"
   | "VM", "call_host_plugin" ->
-      Some "25.21.0-next"
+      Some "25.22.0"
   | "VM", "set_groups" ->
       Some "24.19.1"
   | "pool", "set_console_idle_timeout" ->

diff --git a/ocaml/idl/datamodel_vm.ml b/ocaml/idl/datamodel_vm.ml
@@ -2211,6 +2211,7 @@ let operations =
         ; ("reverting", "Reverting the VM to a previous snapshotted state")
         ; ("destroy", "refers to the act of uninstalling the VM")
         ; ("create_vtpm", "Creating and adding a VTPM to this VM")
+        ; ("sysprep", "Performing a Windows sysprep on this VM")
         ]
     )
 
@@ -2369,6 +2370,15 @@ let restart_device_models =
     ~allowed_roles:(_R_VM_POWER_ADMIN ++ _R_CLIENT_CERT)
     ()
 
+let sysprep =
+  call ~name:"sysprep" ~lifecycle:[]
+    ~params:
+      [
+        (Ref _vm, "self", "The VM")
+      ; (String, "unattend", "XML content passed to sysprep")
+      ]
+    ~doc:"Pass unattend.xml to Windows sysprep" ~allowed_roles:_R_VM_ADMIN ()
+
 let vm_uefi_mode =
   Enum
     ( "vm_uefi_mode"
@@ -2571,6 +2581,7 @@ let t =
       ; set_blocked_operations
       ; add_to_blocked_operations
       ; remove_from_blocked_operations
+      ; sysprep
       ]
     ~contents:
       ([

diff --git 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 = "4cd835e2557dd7b5cbda6c681730c447"
+let last_known_schema_hash = "9cd32d98d092440c36617546a3d995bd"
 
 let current_schema_hash : string =
   let open Datamodel_types in

diff --git a/ocaml/libs/log/test/dune b/ocaml/libs/log/test/dune
@@ -1,6 +1,6 @@
 (executable
  (name log_test)
- (libraries log xapi-stdext-threads threads.posix xapi-backtrace))
+ (libraries log threads.posix xapi-backtrace))
 
 (cram
  (package xapi-log)

diff --git a/ocaml/libs/log/test/log_test.ml b/ocaml/libs/log/test/log_test.ml
@@ -6,12 +6,16 @@ let a = [||]
 
 let buggy () = a.(1) <- 0
 
+let with_lock mutex f =
+  let finally () = Mutex.unlock mutex in
+  Mutex.lock mutex ; Fun.protect ~finally f
+
 let () =
   Printexc.record_backtrace true ;
   Debug.log_to_stdout () ;
   ()
   |> Debug.with_thread_associated "main" @@ fun () ->
-     try Xapi_stdext_threads.Threadext.Mutex.execute m buggy
+     try with_lock m buggy
      with e ->
        D.log_backtrace e ;
        D.warn "Got exception: %s" (Printexc.to_string e)
diff --git a/ocaml/libs/log/test/log_test.t b/ocaml/libs/log/test/log_test.t
@@ -3,7 +3,7 @@
   [|error||0 |main|backtrace] 1/4 log_test.exe Raised at file ocaml/libs/log/test/log_test.ml, line 7
   [|error||0 |main|backtrace] 2/4 log_test.exe Called from file fun.ml, line 33
   [|error||0 |main|backtrace] 3/4 log_test.exe Called from file fun.ml, line 38
-  [|error||0 |main|backtrace] 4/4 log_test.exe Called from file ocaml/libs/log/test/log_test.ml, line 14
+  [|error||0 |main|backtrace] 4/4 log_test.exe Called from file ocaml/libs/log/test/log_test.ml, line 18
   [|error||0 |main|backtrace] 
   [| warn||0 |main|log_test.ml] Got exception: Invalid_argument("index out of bounds")