Commit e777a5bd authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Paolo Bonzini
Browse files

docs: kvm: convert devices/vcpu.txt to ReST 



- Use title markups;
- adjust indentation and add blank lines as needed;
- adjust tables to match ReST accepted formats;
- use :field: markups;
- mark code blocks as such.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarPaolo Bonzini <pbonzini@redhat.com>
parent e9447430

Documentation/virt/kvm/devices/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -12,3 +12,4 @@ Devices 
   arm-vgic-v3

   mpic

   s390_flic

   vcpu

Documentation/virt/kvm/devices/vcpu.txt→Documentation/virt/kvm/devices/vcpu.rst

+114 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



======================

Generic vcpu interface

====================================

======================



The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR,

KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct
@@ -8,17 +11,26 @@ kvm_device_attr as other devices, but targets VCPU-wide settings and controls. 
The groups and attributes per virtual cpu, if any, are architecture specific.



1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL

Architectures: ARM64

==================================



:Architectures: ARM64



1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ

Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a

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



:Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a

	     pointer to an int

Returns: -EBUSY: The PMU overflow interrupt is already set

         -ENXIO: The overflow interrupt not set when attempting to get it

         -ENODEV: PMUv3 not supported

         -EINVAL: Invalid PMU overflow interrupt number supplied or



Returns:



	 =======  ========================================================

	 -EBUSY   The PMU overflow interrupt is already set

	 -ENXIO   The overflow interrupt not set when attempting to get it

	 -ENODEV  PMUv3 not supported

	 -EINVAL  Invalid PMU overflow interrupt number supplied or

		  trying to set the IRQ number without using an in-kernel

		  irqchip.

	 =======  ========================================================



A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt

number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt
@@ -26,11 +38,18 @@ type must be same for each vcpu. As a PPI, the interrupt number is the same for 
all vcpus, while as an SPI it must be a separate number per vcpu.



1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT

Parameters: no additional parameter in kvm_device_attr.addr

Returns: -ENODEV: PMUv3 not supported or GIC not initialized

         -ENXIO: PMUv3 not properly configured or in-kernel irqchip not

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



:Parameters: no additional parameter in kvm_device_attr.addr



Returns:



	 =======  ======================================================

	 -ENODEV  PMUv3 not supported or GIC not initialized

	 -ENXIO   PMUv3 not properly configured or in-kernel irqchip not

		  configured as required prior to calling this attribute

         -EBUSY: PMUv3 already initialized

	 -EBUSY   PMUv3 already initialized

	 =======  ======================================================



Request the initialization of the PMUv3.  If using the PMUv3 with an in-kernel

virtual GIC implementation, this must be done after initializing the in-kernel
@@ -38,21 +57,31 @@ irqchip. 




2. GROUP: KVM_ARM_VCPU_TIMER_CTRL

Architectures: ARM,ARM64

=================================



2.1. ATTRIBUTE: KVM_ARM_VCPU_TIMER_IRQ_VTIMER

2.2. ATTRIBUTE: KVM_ARM_VCPU_TIMER_IRQ_PTIMER

Parameters: in kvm_device_attr.addr the address for the timer interrupt is a

:Architectures: ARM, ARM64



2.1. ATTRIBUTES: KVM_ARM_VCPU_TIMER_IRQ_VTIMER, KVM_ARM_VCPU_TIMER_IRQ_PTIMER

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



:Parameters: in kvm_device_attr.addr the address for the timer interrupt is a

	     pointer to an int

Returns: -EINVAL: Invalid timer interrupt number

         -EBUSY:  One or more VCPUs has already run



Returns:



	 =======  =================================

	 -EINVAL  Invalid timer interrupt number

	 -EBUSY   One or more VCPUs has already run

	 =======  =================================



A value describing the architected timer interrupt number when connected to an

in-kernel virtual GIC.  These must be a PPI (16 <= intid < 32).  Setting the

attribute overrides the default values (see below).



KVM_ARM_VCPU_TIMER_IRQ_VTIMER: The EL1 virtual timer intid (default: 27)

KVM_ARM_VCPU_TIMER_IRQ_PTIMER: The EL1 physical timer intid (default: 30)

=============================  ==========================================

KVM_ARM_VCPU_TIMER_IRQ_VTIMER  The EL1 virtual timer intid (default: 27)

KVM_ARM_VCPU_TIMER_IRQ_PTIMER  The EL1 physical timer intid (default: 30)

=============================  ==========================================



Setting the same PPI for different timers will prevent the VCPUs from running.

Setting the interrupt number on a VCPU configures all VCPUs created at that
@@ -62,13 +91,22 @@ numbers on at least one VCPU after creating all VCPUs and before running any 
VCPUs.



3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL

Architectures: ARM64

==================================



:Architectures: ARM64



3.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA

Parameters: 64-bit base address

Returns: -ENXIO:  Stolen time not implemented

         -EEXIST: Base address already set for this VCPU

         -EINVAL: Base address not 64 byte aligned

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



:Parameters: 64-bit base address



Returns:



	 =======  ======================================

	 -ENXIO   Stolen time not implemented

	 -EEXIST  Base address already set for this VCPU

	 -EINVAL  Base address not 64 byte aligned

	 =======  ======================================



Specifies the base address of the stolen time structure for this VCPU. The

base address must be 64 byte aligned and exist within a valid guest memory

CRA Git | Maintained and supported by SUSTech CRA and CCSE