On Mon, Oct 13, 2025 at 6:51 PM Randy Dunlap <[email protected]> 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 <[email protected]> > > --- > > 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.
