[RFC PATCH] KVM: arm64: Align KVM_EXIT_MEMORY_FAULT error codes with documentation

[Sean Christopherson]

On Wed, May 06, 2026, Alexandru Elisei wrote:
> The documentation for KVM_EXIT_MEMORY_FAULT states:
> 
> 'Note!  KVM_EXIT_MEMORY_FAULT is unique among all KVM exit reasons in that
> it accompanies a return code of '-1', not '0'!  errno will always be set to
> EFAULT or EHWPOISON when KVM exits with KVM_EXIT_MEMORY_FAULT, userspace
> should assume kvm_run.exit_reason is stale/undefined for all other error
> numbers'.
> 
> where a return code of '-1' is special because according to man 2 ioctl:
> 
> 'On error, -1 is returned, and errno is set to indicate the error'.
> 
> Putting the two together means that the ioctl KVM_RUN must 1) complete with
> an error and 2) that error must must be either EFAULT or EHWPOISON for
> userspace to detect a KVM_EXIT_MEMORY_FAULT VCPU exit.

Yes and no.  The key escape valve we (very deliberately) gave ourselves is this:

  userspace should assume kvm_run.exit_reason is stale/undefined for all other
  error numbers.

As arm64 already does, that clause allows KVM to "speculatively" set exit_reason
to KVM_EXIT_MEMORY_FAULT.  Which is by design.  The userspace flow is intended
to be "if KVM_RUN returns EFAULT or EHWPOISON, then check for KVM_EXIT_MEMORY_FAULT
to see if KVM provided more information about why the EFAULT/EHWPOISON error was
returned".

> On a kvm_gmem_get_pfn() error, gmem_abort() prepares the
> KVM_EXIT_MEMORY_FAULT exit_reason and propagates the error back to
> userspace. kvm_gmem_get_pfn() does not massage the error code, and if the
> error is not -EFAULT or -EHWPOISON, userspace implementing the ABI fails to
> detect the memory fault exit.
> 
> Things get more complicated with kvm_handle_vncr_abort().
> kvm_translate_vncr(), similar to gmem_abort(), prepares the VCPU to exit
> with KVM_EXIT_MEMORY_FAULT and propagates the error code from
> kvm_gmem_get_pfn(). Then kvm_handle_vncr_abort() does a number of things
> based on this specific error code:
> 
> - If it's -EAGAIN, KVM resumes the guest. Note that KVM, when handling a
>   *host* fault on a guest_memfd backed VMA, retries the fault handling if
>   kvm_gmem_get_pfn() returns -EAGAIN.

Totally fine.

> - If it's -ENOMEM, -EFAULT, -EIO or -EHWPOISON, it returns to userspace
>   with 0 (success), meaning that, according to the documentation, userspace
>   will not detect the memory fault exit.

Also totally fine, and working as intended.  KVM_EXIT_MEMORY_FAULT is provided
for scenarios where (a) the issue is likely related to the GPA and (b) userspace
can remedy the underlying issue using the information provided in kvm_run.memory_fault.

ENOMEM doesn't meet (a), and EIO doesn't meet (b) (and probably not (a) in the
vast majority of cases either).

> - If it's -EINVAL, -ENOENT, -EACCESS, KVM injects a synchronous exception
>   back to the guest.
> - If it's -EPERM, KVM injects a permission fault.
> - If the error code is something else, KVM resumes the guest.

All of these are totally fine.  The fact that KVM "scribbled" kvm_run a bit is
a non-issue, because KVM will fill kvm_run with the correct information on the
next userspace exit, or will exit with an error that doesn't utilize kvm_run (in
which case userspace shouldn't be looking at it), or KVM is buggy somewhere else.