[PATCH v1 1/2] qapi: add KVM_VCPU_ERROR event

[Tao Cui <cui.tao@linux.dev>]

From: Tao Cui <cuitao@kylinos.cn>

When a KVM vCPU exits with an unrecoverable error (KVM_EXIT_INTERNAL_ERROR,
KVM_EXIT_UNKNOWN, or a failed KVM_RUN ioctl), QEMU currently only logs to
stderr and stops the VM with run state "internal-error". The management
layer must infer what happened from the subsequent STOP event, with no
indication of which vCPU failed or why.

Add a KVM_VCPU_ERROR event, emitted before the VM is stopped, that carries
the failing vCPU (cpu-index, qom-path), an error category
(KvmVcpuErrorReason) and, for KVM_EXIT_INTERNAL_ERROR, the kernel suberror
and extra data words.

Signed-off-by: Tao Cui <cuitao@kylinos.cn>
---
 qapi/run-state.json | 57 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/qapi/run-state.json b/qapi/run-state.json
index a5771ad468..c9993ad9ac 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -732,6 +732,63 @@
   'data': { 'action-required': 'bool',
             'recursive': 'bool'} }
 
+##
+# @KvmVcpuErrorReason:
+#
+# Categorizes a KVM vCPU run error reported through @KVM_VCPU_ERROR.
+#
+# @ioctl-failed: the KVM_RUN ioctl failed; see stderr for the errno.
+#
+# @unknown: KVM_EXIT_UNKNOWN; the hardware exit reason is logged to
+#     stderr.
+#
+# @internal-error: KVM_EXIT_INTERNAL_ERROR; see @suberror and
+#     @exit-data for details.
+#
+# Since: 11.2
+##
+{ 'enum': 'KvmVcpuErrorReason',
+  'data': [ 'ioctl-failed', 'unknown', 'internal-error' ] }
+
+##
+# @KVM_VCPU_ERROR:
+#
+# Emitted when a KVM vCPU exits with an unrecoverable error, before
+# the VM is stopped with run state ``internal-error``.  Lets the
+# management layer learn which vCPU failed and why, instead of
+# inferring it from the subsequent STOP event.
+#
+# @cpu-index: index of the vCPU that failed.
+#
+# @qom-path: the QOM path of the vCPU that failed.
+#
+# @reason: error category.
+#
+# @suberror: KVM internal suberror.  Present only when @reason is
+#     @internal-error.
+#
+# @exit-data: extra KVM data words.  Present only when @reason is
+#     @internal-error and the kernel provided extra data.
+#
+# Since: 11.2
+#
+# .. qmp-example::
+#
+#     <- { "event": "KVM_VCPU_ERROR",
+#          "data": { "cpu-index": 0,
+#                    "qom-path": "/machine/unattached/device[0]",
+#                    "reason": "internal-error",
+#                    "suberror": 1,
+#                    "exit-data": [ 0 ] },
+#          "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+##
+{ 'event': 'KVM_VCPU_ERROR',
+  'data': { 'cpu-index': 'int',
+            'qom-path': 'str',
+            'reason': 'KvmVcpuErrorReason',
+            '*suberror': 'int',
+            '*exit-data': ['uint64'] } }
+
 ##
 # @NotifyVmexitOption:
 #
-- 
2.43.0