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

[ALOK TIWARI <alok.a.tiwari@oracle.com>]

...
> +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