Merge tag 'kvm-x86-docs-6.7' of https://github.com/kvm-x86/linux into HEAD

PPC:

^^^^

Queues an external interrupt to be injected. This ioctl is overleaded

Queues an external interrupt to be injected. This ioctl is overloaded

with 3 different irq values:

a) KVM_INTERRUPT_SET

The KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL flag requests KVM to generate

the contents of the hypercall page automatically; hypercalls will be

intercepted and passed to userspace through KVM_EXIT_XEN.  In this

ase, all of the blob size and address fields must be zero.

case, all of the blob size and address fields must be zero.

The KVM_XEN_HVM_CONFIG_EVTCHN_SEND flag indicates to KVM that userspace

will always use the KVM_XEN_HVM_EVTCHN_SEND ioctl to deliver event

:Extended by: KVM_CAP_INTR_SHADOW

:Architectures: x86, arm64

:Type: vcpu ioctl

:Parameters: struct kvm_vcpu_event (out)

:Parameters: struct kvm_vcpu_events (out)

:Returns: 0 on success, -1 on error

X86:

:Extended by: KVM_CAP_INTR_SHADOW

:Architectures: x86, arm64

:Type: vcpu ioctl

:Parameters: struct kvm_vcpu_event (in)

:Parameters: struct kvm_vcpu_events (in)

:Returns: 0 on success, -1 on error

X86:

   };

An entry with a "page_shift" of 0 is unused. Because the array is

organized in increasing order, a lookup can stop when encoutering

organized in increasing order, a lookup can stop when encountering

such an entry.

The "slb_enc" field provides the encoding to use in the SLB for the

	      - KVM_RUN and KVM_GET_REG_LIST are not available;

	      - KVM_GET_ONE_REG and KVM_SET_ONE_REG cannot be used to access

	        the scalable archietctural SVE registers

	        the scalable architectural SVE registers

	        KVM_REG_ARM64_SVE_ZREG(), KVM_REG_ARM64_SVE_PREG() or

	        KVM_REG_ARM64_SVE_FFR;

placed itself in a quiescent state where no vcpu will make MMU enabled

memory accesses.

On succsful completion, the pending HPT will become the guest's active

On successful completion, the pending HPT will become the guest's active

HPT and the previous HPT will be discarded.

On failure, the guest will still be operating on its previous HPT.

Between KVM_ARM_VCPU_INIT and KVM_ARM_VCPU_FINALIZE, the feature may be

configured by use of ioctls such as KVM_SET_ONE_REG.  The exact configuration

that should be performaned and how to do it are feature-dependent.

that should be performed and how to do it are feature-dependent.

Other calls that depend on a particular feature being finalized, such as

KVM_RUN, KVM_GET_REG_LIST, KVM_GET_ONE_REG and KVM_SET_ONE_REG, will fail with

  #define KVM_PMU_EVENT_ALLOW 0

  #define KVM_PMU_EVENT_DENY 1

Via this API, KVM userspace can also control the behavior of the VM's fixed

counters (if any) by configuring the "action" and "fixed_counter_bitmap" fields.

Specifically, KVM follows the following pseudo-code when determining whether to

allow the guest FixCtr[i] to count its pre-defined fixed event::

  FixCtr[i]_is_allowed = (action == ALLOW) && (bitmap & BIT(i)) ||

    (action == DENY) && !(bitmap & BIT(i));

  FixCtr[i]_is_denied = !FixCtr[i]_is_allowed;

KVM always consumes fixed_counter_bitmap, it's userspace's responsibility to

ensure fixed_counter_bitmap is set correctly, e.g. if userspace wants to define

a filter that only affects general purpose counters.

Note, the "events" field also applies to fixed counters' hardcoded event_select

and unit_mask values.  "fixed_counter_bitmap" has higher priority than "events"

if there is a contradiction between the two.

4.121 KVM_PPC_SVM_OFF

---------------------

  from the guest. A given sending port number may be directed back to

  a specified vCPU (by APIC ID) / port / priority on the guest, or to

  trigger events on an eventfd. The vCPU and priority can be changed

  by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but but other

  by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but other

  fields cannot change for a given sending port. A port mapping is

  removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags field. Passing

  KVM_XEN_EVTCHN_RESET in the flags field removes all interception of

    Is 1 if the MMU instance cannot use A/D bits.  EPT did not have A/D

    bits before Haswell; shadow EPT page tables also cannot use A/D bits

    if the L1 hypervisor does not enable them.

  role.guest_mode:

    Indicates the shadow page is created for a nested guest.

  role.passthrough:

    The page is not backed by a guest page table, but its first entry

    points to one.  This is set if NPT uses 5-level page tables (host

    CR4.LA57=1) and is shadowing L1's 4-level NPT (L1 CR4.LA57=0).

  mmu_valid_gen:

    The MMU generation of this page, used to fast zap of all MMU pages within a

    VM without blocking vCPUs too long. Specifically, KVM updates the per-VM

    valid MMU generation which causes the mismatch of mmu_valid_gen for each mmu

    page. This makes all existing MMU pages obsolete. Obsolete pages can't be

    used. Therefore, vCPUs must load a new, valid root before re-entering the

    guest. The MMU generation is only ever '0' or '1'. Note, the TDP MMU doesn't

    use this field as non-root TDP MMU pages are reachable only from their

    owning root. Thus it suffices for TDP MMU to use role.invalid in root pages

    to invalidate all MMU pages.

  gfn:

    Either the guest page table containing the translations shadowed by this

    page, or the base page frame for linear translations.  See role.direct.

    at __pa(sp2->spt).  sp2 will point back at sp1 through parent_pte.

    The spt array forms a DAG structure with the shadow page as a node, and

    guest pages as leaves.

  gfns:

    An array of 512 guest frame numbers, one for each present pte.  Used to

    perform a reverse map from a pte to a gfn. When role.direct is set, any

    element of this array can be calculated from the gfn field when used, in

    this case, the array of gfns is not allocated. See role.direct and gfn.

  root_count:

    A counter keeping track of how many hardware registers (guest cr3 or

    pdptrs) are now pointing at the page.  While this counter is nonzero, the

    page cannot be destroyed.  See role.invalid.

  shadowed_translation:

    An array of 512 shadow translation entries, one for each present pte. Used

    to perform a reverse map from a pte to a gfn as well as its access

    permission. When role.direct is set, the shadow_translation array is not

    allocated. This is because the gfn contained in any element of this array

    can be calculated from the gfn field when used.  In addition, when

    role.direct is set, KVM does not track access permission for each of the

    gfn. See role.direct and gfn.

  root_count / tdp_mmu_root_count:

     root_count is a reference counter for root shadow pages in Shadow MMU.

     vCPUs elevate the refcount when getting a shadow page that will be used as

     a root page, i.e. page that will be loaded into hardware directly (CR3,

     PDPTRs, nCR3 EPTP). Root pages cannot be destroyed while their refcount is

     non-zero. See role.invalid. tdp_mmu_root_count is similar but exclusively

     used in TDP MMU as an atomic refcount.

  parent_ptes:

    The reverse mapping for the pte/ptes pointing at this page's spt. If

    parent_ptes bit 0 is zero, only one spte points at this page and

    parent_ptes points at this single spte, otherwise, there exists multiple

    sptes pointing at this page and (parent_ptes & ~0x1) points at a data

    structure with a list of parent sptes.

  ptep:

    The kernel virtual address of the SPTE that points at this shadow page.

    Used exclusively by the TDP MMU, this field is a union with parent_ptes.

  unsync:

    If true, then the translations in this page may not match the guest's

    translation.  This is equivalent to the state of the tlb when a pte is

    since the last time the page table was actually used; if emulation

    is triggered too frequently on this page, KVM will unmap the page

    to avoid emulation in the future.

  tdp_mmu_page:

    Is 1 if the shadow page is a TDP MMU page. This variable is used to

    bifurcate the control flows for KVM when walking any data structure that

    may contain pages from both TDP MMU and shadow MMU.

Reverse map

===========