Re: [PATCH v1 6/6] Documentation: kvm: new uAPI for handling SEA

[Jiaqi Yan <jiaqiyan@google.com>]

Thanks ALOK, for pointing out the typos! Queued the fixes to V2 while
awaiting for reviews on other patches.

On Wed, May 7, 2025 at 12:25 PM ALOK TIWARI <alok.a.tiwari@oracle.com> wrote:
>
> ...
> > +Inject SError
> > +~~~~~~~~~~~~~
> > +
> >   Set the pending SError exception state for this VCPU. It is not possible to
> >   'cancel' an Serror that has been made pending.
> >
> > -If the guest performed an access to I/O memory which could not be handled by
> > -userspace, for example because of missing instruction syndrome decode
> > -information or because there is no device mapped at the accessed IPA, then
> > -userspace can ask the kernel to inject an external abort using the address
> > -from the exiting fault on the VCPU. It is a programming error to set
> > -ext_dabt_pending after an exit which was not either KVM_EXIT_MMIO or
> > -KVM_EXIT_ARM_NISV. This feature is only available if the system supports
> > -KVM_CAP_ARM_INJECT_EXT_DABT. This is a helper which provides commonality in
> > -how userspace reports accesses for the above cases to guests, across different
> > -userspace implementations. Nevertheless, userspace can still emulate all Arm
> > -exceptions by manipulating individual registers using the KVM_SET_ONE_REG API.
> > +Inject SEA (synchronous external abort)
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +- If the guest performed an access to I/O memory which could not be handled by
> > +  userspace, for example because of missing instruction syndrome decode
> > +  information or because there is no device mapped at the accessed IPA.
> > +
> > +- If the guest consumed an uncorrected memory error, and RAS extension in the
> > +  Trusted Firmware choose to notify PE with SEA, KVM has to handle it when
> > +  host APEI is unable to claim the SEA. For the following types of faults,
> > +  if userspace enabled KVM_CAP_ARM_SEA_TO_USER, KVM returns to userspace with
> > +  KVM_EXIT_ARM_SEA:
> > +
> > +  - Synchronous external abort, not on translation table walk or hardware
> > +    update of translation table.
> > +
> > +  - Synchronous external abort on translation table walk or hardware update of
> > +    translation table, including all levels.
> > +
> > +  - Synchronous parity or ECC error on memory access, not on translation table
> > +    walk.
> > +
> > +  - Synchronous parity or ECC error on memory access on translation table walk
> > +    or hardware update of translation table, including all levels.
> > +
> > +For the cases above, userspace can ask the kernel to replay either an external
> > +data abort (by setting ext_dabt_pending) or an external instruciton abort
>
> typo instruciton -> instruction
>
> > +(by setting ext_iabt_pending) into the faulting VCPU. KVM will use the address
> > +from the exiting fault on the VCPU. Setting both ext_dabt_pending and
> > +ext_iabt_pending at the same time will return -EINVAL.
> > +
> > +It is a programming error to set ext_dabt_pending or ext_iabt_pending after an
> > +exit which was not KVM_EXIT_MMIO, KVM_EXIT_ARM_NISV or KVM_EXIT_ARM_SEA.
> > +Injecting SEA for data and instruction abort is only available if KVM supports
> > +KVM_CAP_ARM_INJECT_EXT_DABT and KVM_CAP_ARM_INJECT_EXT_IABT respectively.
> > +
> > +This is a helper which provides commonality in how userspace reports accesses
> > +for the above cases to guests, across different userspace implementations.
> > +Nevertheless, userspace can still emulate all Arm exceptions by manipulating
> > +individual registers using the KVM_SET_ONE_REG API.
> >
> >   See KVM_GET_VCPU_EVENTS for the data structure.
> >
> > @@ -7151,6 +7184,55 @@ The valid value for 'flags' is:
> >     - KVM_NOTIFY_CONTEXT_INVALID -- the VM context is corrupted and not valid
> >       in VMCS. It would run into unknown result if resume the target VM.
> >
> > +::
> > +
> > +    /* KVM_EXIT_ARM_SEA */
> > +    struct {
> > +      __u64 esr;
> > +  #define KVM_EXIT_ARM_SEA_FLAG_GVA_VALID   (1ULL << 0)
> > +  #define KVM_EXIT_ARM_SEA_FLAG_GPA_VALID   (1ULL << 1)
> > +      __u64 flags;
> > +      __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 caused 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
> > +handling is to inject an async 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' filed holds the value of the exception syndrome register (ESR) while
>
> 'esr' filed holds -> 'esr' field hold
>
> > +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 'flags' field indicates if the faulting addresses are available while
> > +taking the SEA:
> > +
> > +  - KVM_EXIT_ARM_SEA_FLAG_GVA_VALID -- the faulting guest virtual address
> > +    is valid and userspace can get its value in the 'gva' field.
>
> the 'gpa' filed -> the 'gpa' field.
>
> > +  - KVM_EXIT_ARM_SEA_FLAG_GPA_VALID -- the faulting guest physical address
> > +    is valid and userspace can get its value in the 'gpa' filed.
> > +
> > +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. If the Exception Class indicated by 'esr' field in 'arm_sea'
> > +is data abort, userspace should inject data abort. If the Exception Class is
> > +instruction abort, userspace should inject instruction abort.
>
>
> Thanks,
> Alok