1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 Paravirtualized time support for arm64 3 Paravirtualized time support for arm64
4 ====================================== 4 ======================================
5 5
6 Arm specification DEN0057/A defines a standard 6 Arm specification DEN0057/A defines a standard for paravirtualised time
7 support for AArch64 guests: 7 support for AArch64 guests:
8 8
9 https://developer.arm.com/docs/den0057/a 9 https://developer.arm.com/docs/den0057/a
10 10
11 KVM/arm64 implements the stolen time part of t 11 KVM/arm64 implements the stolen time part of this specification by providing
12 some hypervisor service calls to support a par 12 some hypervisor service calls to support a paravirtualized guest obtaining a
13 view of the amount of time stolen from its exe 13 view of the amount of time stolen from its execution.
14 14
15 Two new SMCCC compatible hypercalls are define 15 Two new SMCCC compatible hypercalls are defined:
16 16
17 * PV_TIME_FEATURES: 0xC5000020 17 * PV_TIME_FEATURES: 0xC5000020
18 * PV_TIME_ST: 0xC5000021 18 * PV_TIME_ST: 0xC5000021
19 19
20 These are only available in the SMC64/HVC64 ca 20 These are only available in the SMC64/HVC64 calling convention as
21 paravirtualized time is not available to 32 bi 21 paravirtualized time is not available to 32 bit Arm guests. The existence of
22 the PV_TIME_FEATURES hypercall should be probe 22 the PV_TIME_FEATURES hypercall should be probed using the SMCCC 1.1
23 ARCH_FEATURES mechanism before calling it. 23 ARCH_FEATURES mechanism before calling it.
24 24
25 PV_TIME_FEATURES 25 PV_TIME_FEATURES
26 26
27 ============= ======== ================ 27 ============= ======== =================================================
28 Function ID: (uint32) 0xC5000020 28 Function ID: (uint32) 0xC5000020
29 PV_call_id: (uint32) The function to 29 PV_call_id: (uint32) The function to query for support.
30 Currently only P 30 Currently only PV_TIME_ST is supported.
31 Return value: (int64) NOT_SUPPORTED (- 31 Return value: (int64) NOT_SUPPORTED (-1) or SUCCESS (0) if the relevant
32 PV-time feature 32 PV-time feature is supported by the hypervisor.
33 ============= ======== ================ 33 ============= ======== =================================================
34 34
35 PV_TIME_ST 35 PV_TIME_ST
36 36
37 ============= ======== ================ 37 ============= ======== ==============================================
38 Function ID: (uint32) 0xC5000021 38 Function ID: (uint32) 0xC5000021
39 Return value: (int64) IPA of the stole 39 Return value: (int64) IPA of the stolen time data structure for this
40 VCPU. On failure 40 VCPU. On failure:
41 NOT_SUPPORTED (- 41 NOT_SUPPORTED (-1)
42 ============= ======== ================ 42 ============= ======== ==============================================
43 43
44 The IPA returned by PV_TIME_ST should be mappe 44 The IPA returned by PV_TIME_ST should be mapped by the guest as normal memory
45 with inner and outer write back caching attrib 45 with inner and outer write back caching attributes, in the inner shareable
46 domain. A total of 16 bytes from the IPA retur 46 domain. A total of 16 bytes from the IPA returned are guaranteed to be
47 meaningfully filled by the hypervisor (see str 47 meaningfully filled by the hypervisor (see structure below).
48 48
49 PV_TIME_ST returns the structure for the calli 49 PV_TIME_ST returns the structure for the calling VCPU.
50 50
51 Stolen Time 51 Stolen Time
52 ----------- 52 -----------
53 53
54 The structure pointed to by the PV_TIME_ST hyp 54 The structure pointed to by the PV_TIME_ST hypercall is as follows:
55 55
56 +-------------+-------------+-------------+--- 56 +-------------+-------------+-------------+----------------------------+
57 | Field | Byte Length | Byte Offset | De 57 | Field | Byte Length | Byte Offset | Description |
58 +=============+=============+=============+=== 58 +=============+=============+=============+============================+
59 | Revision | 4 | 0 | Mu 59 | Revision | 4 | 0 | Must be 0 for version 1.0 |
60 +-------------+-------------+-------------+--- 60 +-------------+-------------+-------------+----------------------------+
61 | Attributes | 4 | 4 | Mu 61 | Attributes | 4 | 4 | Must be 0 |
62 +-------------+-------------+-------------+--- 62 +-------------+-------------+-------------+----------------------------+
63 | Stolen time | 8 | 8 | St 63 | Stolen time | 8 | 8 | Stolen time in unsigned |
64 | | | | na 64 | | | | nanoseconds indicating how |
65 | | | | mu 65 | | | | much time this VCPU thread |
66 | | | | wa 66 | | | | was involuntarily not |
67 | | | | ru 67 | | | | running on a physical CPU. |
68 +-------------+-------------+-------------+--- 68 +-------------+-------------+-------------+----------------------------+
69 69
70 All values in the structure are stored little- 70 All values in the structure are stored little-endian.
71 71
72 The structure will be updated by the hyperviso 72 The structure will be updated by the hypervisor prior to scheduling a VCPU. It
73 will be present within a reserved region of th 73 will be present within a reserved region of the normal memory given to the
74 guest. The guest should not attempt to write i 74 guest. The guest should not attempt to write into this memory. There is a
75 structure per VCPU of the guest. 75 structure per VCPU of the guest.
76 76
77 It is advisable that one or more 64k pages are 77 It is advisable that one or more 64k pages are set aside for the purpose of
78 these structures and not used for other purpos 78 these structures and not used for other purposes, this enables the guest to map
79 the region using 64k pages and avoids conflict 79 the region using 64k pages and avoids conflicting attributes with other memory.
80 80
81 For the user space interface see 81 For the user space interface see
82 :ref:`Documentation/virt/kvm/devices/vcpu.rst 82 :ref:`Documentation/virt/kvm/devices/vcpu.rst <kvm_arm_vcpu_pvtime_ctrl>`.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.