Commit 6a745848 authored by Steven Price's avatar Steven Price Committed by Marc Zyngier
Browse files

KVM: arm64: Document PV-time interface 



Introduce a paravirtualization interface for KVM/arm64 based on the
"Arm Paravirtualized Time for Arm-Base Systems" specification DEN 0057A.

This only adds the details about "Stolen Time" as the details of "Live
Physical Time" have not been fully agreed.

User space can specify a reserved area of memory for the guest and
inform KVM to populate the memory with information on time that the host
kernel has stolen from the guest.

A hypercall interface is provided for the guest to interrogate the
hypervisor's support for this interface and the location of the shared
memory structures.

Signed-off-by: default avatarSteven Price <steven.price@arm.com>
Signed-off-by: default avatarMarc Zyngier <maz@kernel.org>
parent dcac930e

Documentation/virt/kvm/arm/pvtime.rst

0 → 100644
+80 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



Paravirtualized time support for arm64

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



Arm specification DEN0057/A defines a standard for paravirtualised time

support for AArch64 guests:



https://developer.arm.com/docs/den0057/a



KVM/arm64 implements the stolen time part of this specification by providing

some hypervisor service calls to support a paravirtualized guest obtaining a

view of the amount of time stolen from its execution.



Two new SMCCC compatible hypercalls are defined:



* PV_TIME_FEATURES: 0xC5000020

* PV_TIME_ST:       0xC5000021



These are only available in the SMC64/HVC64 calling convention as

paravirtualized time is not available to 32 bit Arm guests. The existence of

the PV_FEATURES hypercall should be probed using the SMCCC 1.1 ARCH_FEATURES

mechanism before calling it.



PV_TIME_FEATURES

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

    Function ID:  (uint32)    0xC5000020

    PV_call_id:   (uint32)    The function to query for support.

                              Currently only PV_TIME_ST is supported.

    Return value: (int64)     NOT_SUPPORTED (-1) or SUCCESS (0) if the relevant

                              PV-time feature is supported by the hypervisor.

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



PV_TIME_ST

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

    Function ID:  (uint32)    0xC5000021

    Return value: (int64)     IPA of the stolen time data structure for this

                              VCPU. On failure:

                              NOT_SUPPORTED (-1)

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



The IPA returned by PV_TIME_ST should be mapped by the guest as normal memory

with inner and outer write back caching attributes, in the inner shareable

domain. A total of 16 bytes from the IPA returned are guaranteed to be

meaningfully filled by the hypervisor (see structure below).



PV_TIME_ST returns the structure for the calling VCPU.



Stolen Time

-----------



The structure pointed to by the PV_TIME_ST hypercall is as follows:



+-------------+-------------+-------------+----------------------------+

| Field       | Byte Length | Byte Offset | Description                |

+=============+=============+=============+============================+

| Revision    |      4      |      0      | Must be 0 for version 1.0  |

+-------------+-------------+-------------+----------------------------+

| Attributes  |      4      |      4      | Must be 0                  |

+-------------+-------------+-------------+----------------------------+

| Stolen time |      8      |      8      | Stolen time in unsigned    |

|             |             |             | nanoseconds indicating how |

|             |             |             | much time this VCPU thread |

|             |             |             | was involuntarily not      |

|             |             |             | running on a physical CPU. |

+-------------+-------------+-------------+----------------------------+



All values in the structure are stored little-endian.



The structure will be updated by the hypervisor prior to scheduling a VCPU. It

will be present within a reserved region of the normal memory given to the

guest. The guest should not attempt to write into this memory. There is a

structure per VCPU of the guest.



It is advisable that one or more 64k pages are set aside for the purpose of

these structures and not used for other purposes, this enables the guest to map

the region using 64k pages and avoids conflicting attributes with other memory.



For the user space interface see Documentation/virt/kvm/devices/vcpu.txt

section "3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL".

Documentation/virt/kvm/devices/vcpu.txt

+14 −0
Original line number Diff line number Diff line
@@ -60,3 +60,17 @@ time to use the number provided for a given timer, overwriting any previously 
configured values on other VCPUs.  Userspace should configure the interrupt

numbers on at least one VCPU after creating all VCPUs and before running any

VCPUs.



3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL

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



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

region. See Documentation/virt/kvm/arm/pvtime.txt for more information

including the layout of the stolen time structure.

CRA Git | Maintained and supported by SUSTech CRA and CCSE