shared: add varlink interface definitions for machine instance control

Add three varlink interface definitions for the machine instance control
hierarchy:

- io.systemd.MachineInstance: generic operations applicable to both
  containers and VMs (PowerOff, Reboot, Pause, Resume, QueryStatus,
  SubscribeEvents). nspawn could implement this same interface later.

- io.systemd.VirtualMachineInstance: VM-specific but VMM-agnostic
  operations. Empty for now, future home for AddBlockDevice and similar.

- io.systemd.QemuMachineInstance: QEMU-specific operations. Defines
  AcquireQMP() for protocol upgrade to a direct QMP connection.

The "Instance" suffix avoids collision with machined's existing
io.systemd.Machine interface.

Signed-off-by: Christian Brauner (Amutable) <brauner@kernel.org>

diff --git a/src/shared/meson.build b/src/shared/meson.build
index 22dccf0e2a7dab0ccdfa6df044a59c7e6cd1680b..924987b024c8263d23736ccec882955dd757cdb7 100644 (file)
--- a/src/shared/meson.build
+++ b/src/shared/meson.build
@@ -216,6 +216,7 @@ shared_sources = files(
         'varlink-io.systemd.Login.c',
         'varlink-io.systemd.Machine.c',
         'varlink-io.systemd.MachineImage.c',
+        'varlink-io.systemd.MachineInstance.c',
         'varlink-io.systemd.ManagedOOM.c',
         'varlink-io.systemd.Manager.c',
         'varlink-io.systemd.Metrics.c',
@@ -226,6 +227,7 @@ shared_sources = files(
         'varlink-io.systemd.Network.Link.c',
         'varlink-io.systemd.PCRExtend.c',
         'varlink-io.systemd.PCRLock.c',
+        'varlink-io.systemd.QemuMachineInstance.c',
         'varlink-io.systemd.Repart.c',
         'varlink-io.systemd.Resolve.c',
         'varlink-io.systemd.Resolve.Hook.c',
@@ -234,6 +236,7 @@ shared_sources = files(
         'varlink-io.systemd.Udev.c',
         'varlink-io.systemd.Unit.c',
         'varlink-io.systemd.UserDatabase.c',
+        'varlink-io.systemd.VirtualMachineInstance.c',
         'varlink-io.systemd.oom.c',
         'varlink-io.systemd.oom.Prekill.c',
         'varlink-io.systemd.service.c',

diff --git a/src/shared/varlink-io.systemd.MachineInstance.c b/src/shared/varlink-io.systemd.MachineInstance.c
new file mode 100644 (file)
index 0000000..365b6f5
--- /dev/null
+++ b/src/shared/varlink-io.systemd.MachineInstance.c
@@ -0,0 +1,51 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+
+#include "varlink-io.systemd.MachineInstance.h"
+
+static SD_VARLINK_DEFINE_METHOD(Terminate);
+static SD_VARLINK_DEFINE_METHOD(PowerOff);
+static SD_VARLINK_DEFINE_METHOD(Reboot);
+static SD_VARLINK_DEFINE_METHOD(Pause);
+static SD_VARLINK_DEFINE_METHOD(Resume);
+
+static SD_VARLINK_DEFINE_METHOD(
+                Describe,
+                SD_VARLINK_FIELD_COMMENT("True iff vCPUs are executing"),
+                SD_VARLINK_DEFINE_OUTPUT(running, SD_VARLINK_BOOL, 0),
+                SD_VARLINK_FIELD_COMMENT("Backend-specific state string (e.g. 'running', 'paused', 'shutdown'); 'unknown' if unavailable"),
+                SD_VARLINK_DEFINE_OUTPUT(status, SD_VARLINK_STRING, 0));
+
+static SD_VARLINK_DEFINE_METHOD_FULL(
+                SubscribeEvents,
+                SD_VARLINK_REQUIRES_MORE,
+                SD_VARLINK_FIELD_COMMENT("If specified, only deliver events whose name matches one of these strings; null means all events"),
+                SD_VARLINK_DEFINE_INPUT(filter, SD_VARLINK_STRING, SD_VARLINK_NULLABLE|SD_VARLINK_ARRAY),
+                SD_VARLINK_FIELD_COMMENT("Name of the event"),
+                SD_VARLINK_DEFINE_OUTPUT(event, SD_VARLINK_STRING, 0),
+                SD_VARLINK_FIELD_COMMENT("Event-specific payload"),
+                SD_VARLINK_DEFINE_OUTPUT(data, SD_VARLINK_OBJECT, SD_VARLINK_NULLABLE));
+
+static SD_VARLINK_DEFINE_ERROR(NotConnected);
+static SD_VARLINK_DEFINE_ERROR(NotSupported);
+
+SD_VARLINK_DEFINE_INTERFACE(
+                io_systemd_MachineInstance,
+                "io.systemd.MachineInstance",
+                SD_VARLINK_SYMBOL_COMMENT("Forcefully terminate the machine immediately"),
+                &vl_method_Terminate,
+                SD_VARLINK_SYMBOL_COMMENT("Request a clean shutdown of the machine"),
+                &vl_method_PowerOff,
+                SD_VARLINK_SYMBOL_COMMENT("Reboot the machine"),
+                &vl_method_Reboot,
+                SD_VARLINK_SYMBOL_COMMENT("Pause/freeze the machine"),
+                &vl_method_Pause,
+                SD_VARLINK_SYMBOL_COMMENT("Resume a paused machine"),
+                &vl_method_Resume,
+                SD_VARLINK_SYMBOL_COMMENT("Query the current status of the machine"),
+                &vl_method_Describe,
+                SD_VARLINK_SYMBOL_COMMENT("Subscribe to machine events. Returns a stream of events as they occur."),
+                &vl_method_SubscribeEvents,
+                SD_VARLINK_SYMBOL_COMMENT("The connection to the machine backend is not available"),
+                &vl_error_NotConnected,
+                SD_VARLINK_SYMBOL_COMMENT("The requested operation is not supported"),
+                &vl_error_NotSupported);

diff --git a/src/shared/varlink-io.systemd.MachineInstance.h b/src/shared/varlink-io.systemd.MachineInstance.h
new file mode 100644 (file)
index 0000000..fa473b2
--- /dev/null
+++ b/src/shared/varlink-io.systemd.MachineInstance.h
@@ -0,0 +1,6 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+#pragma once
+
+#include "sd-varlink-idl.h"
+
+extern const sd_varlink_interface vl_interface_io_systemd_MachineInstance;

diff --git a/src/shared/varlink-io.systemd.QemuMachineInstance.c b/src/shared/varlink-io.systemd.QemuMachineInstance.c
new file mode 100644 (file)
index 0000000..b03fa21
--- /dev/null
+++ b/src/shared/varlink-io.systemd.QemuMachineInstance.c
@@ -0,0 +1,17 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+
+#include "varlink-io.systemd.QemuMachineInstance.h"
+
+static SD_VARLINK_DEFINE_METHOD_FULL(
+                AcquireQMP,
+                SD_VARLINK_REQUIRES_UPGRADE);
+
+static SD_VARLINK_DEFINE_ERROR(AlreadyAcquired);
+
+SD_VARLINK_DEFINE_INTERFACE(
+                io_systemd_QemuMachineInstance,
+                "io.systemd.QemuMachineInstance",
+                SD_VARLINK_SYMBOL_COMMENT("Acquire a direct QMP connection to the QEMU instance via protocol upgrade"),
+                &vl_method_AcquireQMP,
+                SD_VARLINK_SYMBOL_COMMENT("A QMP connection has already been acquired by another client"),
+                &vl_error_AlreadyAcquired);

diff --git a/src/shared/varlink-io.systemd.QemuMachineInstance.h b/src/shared/varlink-io.systemd.QemuMachineInstance.h
new file mode 100644 (file)
index 0000000..203dacb
--- /dev/null
+++ b/src/shared/varlink-io.systemd.QemuMachineInstance.h
@@ -0,0 +1,6 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+#pragma once
+
+#include "sd-varlink-idl.h"
+
+extern const sd_varlink_interface vl_interface_io_systemd_QemuMachineInstance;

diff --git a/src/shared/varlink-io.systemd.VirtualMachineInstance.c b/src/shared/varlink-io.systemd.VirtualMachineInstance.c
new file mode 100644 (file)
index 0000000..f491418
--- /dev/null
+++ b/src/shared/varlink-io.systemd.VirtualMachineInstance.c
@@ -0,0 +1,9 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+
+#include "varlink-io.systemd.VirtualMachineInstance.h"
+
+/* VM-specific control interface. Currently empty — reserved for methods that apply to virtual
+ * machines generically but not to containers (e.g. snapshot, migration, device hotplug). */
+SD_VARLINK_DEFINE_INTERFACE(
+                io_systemd_VirtualMachineInstance,
+                "io.systemd.VirtualMachineInstance");

diff --git a/src/shared/varlink-io.systemd.VirtualMachineInstance.h b/src/shared/varlink-io.systemd.VirtualMachineInstance.h
new file mode 100644 (file)
index 0000000..b6d0600
--- /dev/null
+++ b/src/shared/varlink-io.systemd.VirtualMachineInstance.h
@@ -0,0 +1,6 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+#pragma once
+
+#include "sd-varlink-idl.h"
+
+extern const sd_varlink_interface vl_interface_io_systemd_VirtualMachineInstance;