Document the new userspace-visible features and APIs for handling
synchronous external abort (SEA)
- KVM_CAP_ARM_SEA_TO_USER: How userspace enables the new feature.
- KVM_EXIT_ARM_SEA: exit userspace gets when it needs to handle SEA
and what userspace gets while taking the SEA.
Signed-off-by: Jiaqi Yan <jiaqiyan@google.com>
---
Documentation/virt/kvm/api.rst | 61 ++++++++++++++++++++++++++++++++++
1 file changed, 61 insertions(+)
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 6ae24c5ca5598..43bc2a1d78e01 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -7272,6 +7272,55 @@ exit, even without calls to ``KVM_ENABLE_CAP`` or similar. In this case,
it will enter with output fields already valid; in the common case, the
``unknown.ret`` field of the union will be ``TDVMCALL_STATUS_SUBFUNC_UNSUPPORTED``.
Userspace need not do anything if it does not wish to support a TDVMCALL.
+
+::
+ /* KVM_EXIT_ARM_SEA */
+ struct {
+ #define KVM_EXIT_ARM_SEA_FLAG_GPA_VALID (1ULL << 0)
+ __u64 flags;
+ __u64 esr;
+ __u64 gva;
+ __u64 gpa;
+ } arm_sea;
+
+Used on arm64 systems. When the VM capability KVM_CAP_ARM_SEA_TO_USER is
+enabled, a VM exit is generated if guest causes a synchronous external abort
+(SEA) and the host APEI fails to handle the SEA.
+
+Historically KVM handles SEA by first delegating the SEA to host APEI as there
+is high chance that the SEA is caused by consuming uncorrected memory error.
+However, not all platforms support SEA handling in APEI, and KVM's fallback
+is to inject an asynchronous SError into the guest, which usually panics
+guest kernel unpleasantly. As an alternative, userspace can participate into
+the SEA handling by enabling KVM_CAP_ARM_SEA_TO_USER at VM creation, after
+querying the capability. Once enabled, when KVM has to handle the guest
+caused SEA, it returns to userspace with KVM_EXIT_ARM_SEA, with details
+about the SEA available in 'arm_sea'.
+
+The 'esr' field holds the value of the exception syndrome register (ESR) while
+KVM taking the SEA, which tells userspace the character of the current SEA,
+such as its Exception Class, Synchronous Error Type, Fault Specific Code and
+so on. For more details on ESR, check the Arm Architecture Registers
+documentation.
+
+The following values are defined for the 'flags' field
+
+ - KVM_EXIT_ARM_SEA_FLAG_GPA_VALID -- the faulting guest physical address
+ is valid and userspace can get its value in the 'gpa' field.
+
+Note userspace can tell whether the faulting guest virtual address is valid
+from the FnV bit in 'esr' field. If FnV bit in 'esr' field is not set, the
+'gva' field hols the valid faulting guest virtual address.
+
+Userspace needs to take actions to handle guest SEA synchronously, namely in
+the same thread that runs KVM_RUN and receives KVM_EXIT_ARM_SEA. One of the
+encouraged approaches is to utilize the KVM_SET_VCPU_EVENTS to inject the SEA
+to the faulting VCPU. This way, the guest has the opportunity to keep running
+and limit the blast radius of the SEA to the particular guest application that
+caused the SEA. Userspace may also emulate the SEA to VM by itself using the
+KVM_SET_ONE_REG API. In this case, it can use the valid values from 'gva' and
+'gpa' fields to manipulate VCPU's registers (e.g. FAR_EL1, HPFAR_EL1).
+
::
/* Fix the size of the union. */
@@ -8689,6 +8738,18 @@ This capability indicate to the userspace whether a PFNMAP memory region
can be safely mapped as cacheable. This relies on the presence of
force write back (FWB) feature support on the hardware.
+7.45 KVM_CAP_ARM_SEA_TO_USER
+----------------------------
+
+:Architecture: arm64
+:Target: VM
+:Parameters: none
+:Returns: 0 on success, -EINVAL if unsupported.
+
+This capability, if KVM_CHECK_EXTENSION indicates that it is available, means
+that KVM has an implementation that allows userspace to participate in handling
+synchronous external abort caused by VM, by an exit of KVM_EXIT_ARM_SEA.
+
8. Other capabilities.
======================
--
2.51.0.760.g7b8bcc2412-goog
On 10/13/25 11:59 AM, Jiaqi Yan wrote:
> Document the new userspace-visible features and APIs for handling
> synchronous external abort (SEA)
> - KVM_CAP_ARM_SEA_TO_USER: How userspace enables the new feature.
> - KVM_EXIT_ARM_SEA: exit userspace gets when it needs to handle SEA
> and what userspace gets while taking the SEA.
>
> Signed-off-by: Jiaqi Yan <jiaqiyan@google.com>
> ---
> Documentation/virt/kvm/api.rst | 61 ++++++++++++++++++++++++++++++++++
> 1 file changed, 61 insertions(+)
>
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 6ae24c5ca5598..43bc2a1d78e01 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -7272,6 +7272,55 @@ exit, even without calls to ``KVM_ENABLE_CAP`` or similar. In this case,
> it will enter with output fields already valid; in the common case, the
> ``unknown.ret`` field of the union will be ``TDVMCALL_STATUS_SUBFUNC_UNSUPPORTED``.
> Userspace need not do anything if it does not wish to support a TDVMCALL.
> +
> +::
> + /* KVM_EXIT_ARM_SEA */
> + struct {
> + #define KVM_EXIT_ARM_SEA_FLAG_GPA_VALID (1ULL << 0)
> + __u64 flags;
> + __u64 esr;
> + __u64 gva;
> + __u64 gpa;
> + } arm_sea;
> +
> +Used on arm64 systems. When the VM capability KVM_CAP_ARM_SEA_TO_USER is
> +enabled, a VM exit is generated if guest causes a synchronous external abort
> +(SEA) and the host APEI fails to handle the SEA.
> +
> +Historically KVM handles SEA by first delegating the SEA to host APEI as there
> +is high chance that the SEA is caused by consuming uncorrected memory error.
> +However, not all platforms support SEA handling in APEI, and KVM's fallback
> +is to inject an asynchronous SError into the guest, which usually panics
> +guest kernel unpleasantly. As an alternative, userspace can participate into
in
> +the SEA handling by enabling KVM_CAP_ARM_SEA_TO_USER at VM creation, after
> +querying the capability. Once enabled, when KVM has to handle the guest
guest-
> +caused SEA, it returns to userspace with KVM_EXIT_ARM_SEA, with details
> +about the SEA available in 'arm_sea'.
> +
> +The 'esr' field holds the value of the exception syndrome register (ESR) while
> +KVM taking the SEA, which tells userspace the character of the current SEA,
KVM takes
> +such as its Exception Class, Synchronous Error Type, Fault Specific Code and
> +so on. For more details on ESR, check the Arm Architecture Registers
> +documentation.
> +
> +The following values are defined for the 'flags' field
Above needs an ending like '.' or ':'.
(or maybe "::" depending how it is processed by Sphinx)
> +
> + - KVM_EXIT_ARM_SEA_FLAG_GPA_VALID -- the faulting guest physical address
> + is valid and userspace can get its value in the 'gpa' field.
> +
> +Note userspace can tell whether the faulting guest virtual address is valid
> +from the FnV bit in 'esr' field. If FnV bit in 'esr' field is not set, the
> +'gva' field hols the valid faulting guest virtual address.
holds (or contains)> +
> +Userspace needs to take actions to handle guest SEA synchronously, namely in
> +the same thread that runs KVM_RUN and receives KVM_EXIT_ARM_SEA. One of the
> +encouraged approaches is to utilize the KVM_SET_VCPU_EVENTS to inject the SEA
> +to the faulting VCPU. This way, the guest has the opportunity to keep running
> +and limit the blast radius of the SEA to the particular guest application that
> +caused the SEA. Userspace may also emulate the SEA to VM by itself using the
> +KVM_SET_ONE_REG API. In this case, it can use the valid values from 'gva' and
> +'gpa' fields to manipulate VCPU's registers (e.g. FAR_EL1, HPFAR_EL1).
> +
> ::
>
> /* Fix the size of the union. */
> @@ -8689,6 +8738,18 @@ This capability indicate to the userspace whether a PFNMAP memory region
> can be safely mapped as cacheable. This relies on the presence of
> force write back (FWB) feature support on the hardware.
>
> +7.45 KVM_CAP_ARM_SEA_TO_USER
> +----------------------------
> +
> +:Architecture: arm64
> +:Target: VM
> +:Parameters: none
> +:Returns: 0 on success, -EINVAL if unsupported.
> +
> +This capability, if KVM_CHECK_EXTENSION indicates that it is available, means
> +that KVM has an implementation that allows userspace to participate in handling
> +synchronous external abort caused by VM, by an exit of KVM_EXIT_ARM_SEA.
> +
> 8. Other capabilities.
> ======================
>
--
~Randy
On Mon, Oct 13, 2025 at 6:51 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
>
> On 10/13/25 11:59 AM, Jiaqi Yan wrote:
> > Document the new userspace-visible features and APIs for handling
> > synchronous external abort (SEA)
> > - KVM_CAP_ARM_SEA_TO_USER: How userspace enables the new feature.
> > - KVM_EXIT_ARM_SEA: exit userspace gets when it needs to handle SEA
> > and what userspace gets while taking the SEA.
> >
> > Signed-off-by: Jiaqi Yan <jiaqiyan@google.com>
> > ---
> > Documentation/virt/kvm/api.rst | 61 ++++++++++++++++++++++++++++++++++
> > 1 file changed, 61 insertions(+)
> >
> > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> > index 6ae24c5ca5598..43bc2a1d78e01 100644
> > --- a/Documentation/virt/kvm/api.rst
> > +++ b/Documentation/virt/kvm/api.rst
> > @@ -7272,6 +7272,55 @@ exit, even without calls to ``KVM_ENABLE_CAP`` or similar. In this case,
> > it will enter with output fields already valid; in the common case, the
> > ``unknown.ret`` field of the union will be ``TDVMCALL_STATUS_SUBFUNC_UNSUPPORTED``.
> > Userspace need not do anything if it does not wish to support a TDVMCALL.
> > +
> > +::
> > + /* KVM_EXIT_ARM_SEA */
> > + struct {
> > + #define KVM_EXIT_ARM_SEA_FLAG_GPA_VALID (1ULL << 0)
> > + __u64 flags;
> > + __u64 esr;
> > + __u64 gva;
> > + __u64 gpa;
> > + } arm_sea;
> > +
> > +Used on arm64 systems. When the VM capability KVM_CAP_ARM_SEA_TO_USER is
> > +enabled, a VM exit is generated if guest causes a synchronous external abort
> > +(SEA) and the host APEI fails to handle the SEA.
> > +
> > +Historically KVM handles SEA by first delegating the SEA to host APEI as there
> > +is high chance that the SEA is caused by consuming uncorrected memory error.
> > +However, not all platforms support SEA handling in APEI, and KVM's fallback
> > +is to inject an asynchronous SError into the guest, which usually panics
> > +guest kernel unpleasantly. As an alternative, userspace can participate into
>
> in
>
> > +the SEA handling by enabling KVM_CAP_ARM_SEA_TO_USER at VM creation, after
> > +querying the capability. Once enabled, when KVM has to handle the guest
>
> guest-
> > +caused SEA, it returns to userspace with KVM_EXIT_ARM_SEA, with details
> > +about the SEA available in 'arm_sea'.
> > +
> > +The 'esr' field holds the value of the exception syndrome register (ESR) while
> > +KVM taking the SEA, which tells userspace the character of the current SEA,
> KVM takes
>
> > +such as its Exception Class, Synchronous Error Type, Fault Specific Code and
> > +so on. For more details on ESR, check the Arm Architecture Registers
> > +documentation.
> > +
> > +The following values are defined for the 'flags' field
>
> Above needs an ending like '.' or ':'.
> (or maybe "::" depending how it is processed by Sphinx)
>
> > +
> > + - KVM_EXIT_ARM_SEA_FLAG_GPA_VALID -- the faulting guest physical address
> > + is valid and userspace can get its value in the 'gpa' field.
> > +
> > +Note userspace can tell whether the faulting guest virtual address is valid
> > +from the FnV bit in 'esr' field. If FnV bit in 'esr' field is not set, the
> > +'gva' field hols the valid faulting guest virtual address.
>
> holds (or contains)> +
> > +Userspace needs to take actions to handle guest SEA synchronously, namely in
> > +the same thread that runs KVM_RUN and receives KVM_EXIT_ARM_SEA. One of the
> > +encouraged approaches is to utilize the KVM_SET_VCPU_EVENTS to inject the SEA
> > +to the faulting VCPU. This way, the guest has the opportunity to keep running
> > +and limit the blast radius of the SEA to the particular guest application that
> > +caused the SEA. Userspace may also emulate the SEA to VM by itself using the
> > +KVM_SET_ONE_REG API. In this case, it can use the valid values from 'gva' and
> > +'gpa' fields to manipulate VCPU's registers (e.g. FAR_EL1, HPFAR_EL1).
> > +
> > ::
> >
> > /* Fix the size of the union. */
> > @@ -8689,6 +8738,18 @@ This capability indicate to the userspace whether a PFNMAP memory region
> > can be safely mapped as cacheable. This relies on the presence of
> > force write back (FWB) feature support on the hardware.
> >
> > +7.45 KVM_CAP_ARM_SEA_TO_USER
> > +----------------------------
> > +
> > +:Architecture: arm64
> > +:Target: VM
> > +:Parameters: none
> > +:Returns: 0 on success, -EINVAL if unsupported.
> > +
> > +This capability, if KVM_CHECK_EXTENSION indicates that it is available, means
> > +that KVM has an implementation that allows userspace to participate in handling
> > +synchronous external abort caused by VM, by an exit of KVM_EXIT_ARM_SEA.
> > +
> > 8. Other capabilities.
> > ======================
> >
>
> --
> ~Randy
>
Thanks for your quick review, Randy. I have queued fixes and am
waiting for reviews on other commits in this PATCH.
© 2016 - 2025 Red Hat, Inc.