Merge tag 'for-linus' of git://git.kernel.org/pub/scm/virt/kvm/kvm

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

The kvm API is a set of ioctls that are issued to control various aspects

of a virtual machine.  The ioctls belong to three classes

of a virtual machine.  The ioctls belong to three classes:

 - System ioctls: These query and set global attributes which affect the

   whole kvm subsystem.  In addition a system ioctl is used to create

   virtual machines

   virtual machines.

 - VM ioctls: These query and set attributes that affect an entire virtual

   machine, for example memory layout.  In addition a VM ioctl is used to

   create virtual cpus (vcpus).

   create virtual cpus (vcpus) and devices.

   Only run VM ioctls from the same process (address space) that was used

   to create the VM.

   VM ioctls must be issued from the same process (address space) that was

   used to create the VM.

 - vcpu ioctls: These query and set attributes that control the operation

   of a single virtual cpu.

   Only run vcpu ioctls from the same thread that was used to create the

   vcpu.

   vcpu ioctls should be issued from the same thread that was used to create

   the vcpu, except for asynchronous vcpu ioctl that are marked as such in

   the documentation.  Otherwise, the first ioctl after switching threads

   could see a performance impact.

 - device ioctls: These query and set attributes that control the operation

   of a single device.

   device ioctls must be issued from the same process (address space) that

   was used to create the VM.

2. File descriptors

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

open("/dev/kvm") obtains a handle to the kvm subsystem; this handle

can be used to issue system ioctls.  A KVM_CREATE_VM ioctl on this

handle will create a VM file descriptor which can be used to issue VM

ioctls.  A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu

and return a file descriptor pointing to it.  Finally, ioctls on a vcpu

fd can be used to control the vcpu, including the important task of

actually running guest code.

ioctls.  A KVM_CREATE_VCPU or KVM_CREATE_DEVICE ioctl on a VM fd will

create a virtual cpu or device and return a file descriptor pointing to

the new resource.  Finally, ioctls on a vcpu or device fd can be used

to control the vcpu or device.  For vcpus, this includes the important

task of actually running guest code.

In general file descriptors can be migrated among processes by means

of fork() and the SCM_RIGHTS facility of unix domain socket.  These

kinds of tricks are explicitly not supported by kvm.  While they will

not cause harm to the host, their actual behavior is not guaranteed by

the API.  The only supported use is one virtual machine per process,

and one vcpu per thread.

the API.  See "General description" for details on the ioctl usage

model that is supported by KVM.

It is important to note that althought VM ioctls may only be issued from

the process that created the VM, a VM's lifecycle is associated with its

file descriptor, not its creator (process).  In other words, the VM and

its resources, *including the associated address space*, are not freed

until the last reference to the VM's file descriptor has been released.

For example, if fork() is issued after ioctl(KVM_CREATE_VM), the VM will

not be freed until both the parent (original) process and its child have

put their references to the VM's file descriptor.

Because a VM's resources are not freed until the last reference to its

file descriptor is released, creating additional references to a VM via

via fork(), dup(), etc... without careful consideration is strongly

discouraged and may have unwanted side effects, e.g. memory allocated

by and on behalf of the VM's process may not be freed/unaccounted when

the VM is shut down.

It is important to note that althought VM ioctls may only be issued from

Note that any value for 'irq' other than the ones stated above is invalid

and incurs unexpected behavior.

This is an asynchronous vcpu ioctl and can be invoked from any thread.

MIPS:

Queues an external interrupt to be injected into the virtual CPU. A negative

interrupt number dequeues the interrupt.

This is an asynchronous vcpu ioctl and can be invoked from any thread.

4.17 KVM_DEBUG_GUEST

#define KVM_MEM_LOG_DIRTY_PAGES	(1UL << 0)

#define KVM_MEM_READONLY	(1UL << 1)

This ioctl allows the user to create or modify a guest physical memory

slot.  When changing an existing slot, it may be moved in the guest

physical memory space, or its flags may be modified.  It may not be

resized.  Slots may not overlap in guest physical address space.

Bits 0-15 of "slot" specifies the slot id and this value should be

less than the maximum number of user memory slots supported per VM.

The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS,

if this capability is supported by the architecture.

This ioctl allows the user to create, modify or delete a guest physical

memory slot.  Bits 0-15 of "slot" specify the slot id and this value

should be less than the maximum number of user memory slots supported per

VM.  The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS,

if this capability is supported by the architecture.  Slots may not

overlap in guest physical address space.

If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot"

specifies the address space which is being modified.  They must be

are unrelated; the restriction on overlapping slots only applies within

each address space.

Deleting a slot is done by passing zero for memory_size.  When changing

an existing slot, it may be moved in the guest physical memory space,

or its flags may be modified, but it may not be resized.

Memory for the region is taken starting at the address denoted by the

field userspace_addr, which must point at user addressable memory for

the entire memory slot size.  Any object may back this memory, including

                           machine checks needing further payload are not

                           supported by this ioctl)

Note that the vcpu ioctl is asynchronous to vcpu execution.

This is an asynchronous vcpu ioctl and can be invoked from any thread.

4.78 KVM_PPC_GET_HTAB_FD

KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall

KVM_S390_MCHK - machine check interrupt; parameters in .mchk

Note that the vcpu ioctl is asynchronous to vcpu execution.

This is an asynchronous vcpu ioctl and can be invoked from any thread.

4.94 KVM_S390_GET_IRQ_STATE

    If clear, this page corresponds to a guest page table denoted by the gfn

    field.

  role.quadrant:

    When role.cr4_pae=0, the guest uses 32-bit gptes while the host uses 64-bit

    When role.gpte_is_8_bytes=0, the guest uses 32-bit gptes while the host uses 64-bit

    sptes.  That means a guest page table contains more ptes than the host,

    so multiple shadow pages are needed to shadow one guest page.

    For first-level shadow pages, role.quadrant can be 0 or 1 and denotes the

    The page is invalid and should not be used.  It is a root page that is

    currently pinned (by a cpu hardware register pointing to it); once it is

    unpinned it will be destroyed.

  role.cr4_pae:

    Contains the value of cr4.pae for which the page is valid (e.g. whether

    32-bit or 64-bit gptes are in use).

  role.gpte_is_8_bytes:

    Reflects the size of the guest PTE for which the page is valid, i.e. '1'

    if 64-bit gptes are in use, '0' if 32-bit gptes are in use.

  role.nxe:

    Contains the value of efer.nxe for which the page is valid.

  role.cr0_wp:

    Contains the value of cr4.smap && !cr0.wp for which the page is valid

    (pages for which this is true are different from other pages; see the

    treatment of cr0.wp=0 below).

  role.ept_sp:

    This is a virtual flag to denote a shadowed nested EPT page.  ept_sp

    is true if "cr0_wp && smap_andnot_wp", an otherwise invalid combination.

  role.smm:

    Is 1 if the page is valid in system management mode.  This field

    determines which of the kvm_memslots array was used to build this

generic-y += export.h

generic-y += fb.h

generic-y += irq_work.h

generic-y += kvm_para.h

generic-y += mcs_spinlock.h

generic-y += mm-arch-hooks.h

generic-y += preempt.h

/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */

#include <asm-generic/kvm_para.h>

generic-y += hw_irq.h

generic-y += irq_regs.h

generic-y += irq_work.h

generic-y += kvm_para.h

generic-y += local.h

generic-y += local64.h

generic-y += mcs_spinlock.h