tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kvm: Convert hypercalls.txt to ReST format
- Use document title and chapter markups;
- Convert tables;
- Add markups for literal blocks;
- use :field: for field descriptions;
- Add blank lines and adjust indentation
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
authored by
Mauro Carvalho Chehab
and committed by
Paolo Bonzini
5a0af480
cec0e48b
+75
-56
+73
-56
Documentation/virt/kvm/hypercalls.txt
Documentation/virt/kvm/hypercalls.rst
+73
-56
Documentation/virt/kvm/hypercalls.txt
Documentation/virt/kvm/hypercalls.rst
···
1
-
Linux KVM Hypercall:
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
2
3
===================
4
+
Linux KVM Hypercall
5
+
===================
6
+
3
7
X86:
4
8
KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall
5
9
instruction. The hypervisor can replace it with instructions that are
···
24
20
For further information on the S390 diagnose call as supported by KVM,
25
21
refer to Documentation/virt/kvm/s390-diag.txt.
26
22
27
-
PowerPC:
23
+
PowerPC:
28
24
It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers.
29
25
Return value is placed in R3.
30
26
···
38
34
the return value is placed in $2 (v0).
39
35
40
36
KVM Hypercalls Documentation
41
-
===========================
37
+
============================
38
+
42
39
The template for each hypercall is:
43
40
1. Hypercall name.
44
41
2. Architecture(s)
···
48
43
49
44
1. KVM_HC_VAPIC_POLL_IRQ
50
45
------------------------
51
-
Architecture: x86
52
-
Status: active
53
-
Purpose: Trigger guest exit so that the host can check for pending
54
-
interrupts on reentry.
46
+
47
+
:Architecture: x86
48
+
:Status: active
49
+
:Purpose: Trigger guest exit so that the host can check for pending
50
+
interrupts on reentry.
55
51
56
52
2. KVM_HC_MMU_OP
57
-
------------------------
58
-
Architecture: x86
59
-
Status: deprecated.
60
-
Purpose: Support MMU operations such as writing to PTE,
61
-
flushing TLB, release PT.
53
+
----------------
54
+
55
+
:Architecture: x86
56
+
:Status: deprecated.
57
+
:Purpose: Support MMU operations such as writing to PTE,
58
+
flushing TLB, release PT.
62
59
63
60
3. KVM_HC_FEATURES
64
-
------------------------
65
-
Architecture: PPC
66
-
Status: active
67
-
Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
68
-
used to enumerate which hypercalls are available. On PPC, either device tree
69
-
based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
70
-
mechanism (which is this hypercall) can be used.
61
+
------------------
62
+
63
+
:Architecture: PPC
64
+
:Status: active
65
+
:Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
66
+
used to enumerate which hypercalls are available. On PPC, either
67
+
device tree based lookup ( which is also what EPAPR dictates)
68
+
OR KVM specific enumeration mechanism (which is this hypercall)
69
+
can be used.
71
70
72
71
4. KVM_HC_PPC_MAP_MAGIC_PAGE
73
-
------------------------
74
-
Architecture: PPC
75
-
Status: active
76
-
Purpose: To enable communication between the hypervisor and guest there is a
77
-
shared page that contains parts of supervisor visible register state.
78
-
The guest can map this shared page to access its supervisor register through
79
-
memory using this hypercall.
72
+
----------------------------
73
+
74
+
:Architecture: PPC
75
+
:Status: active
76
+
:Purpose: To enable communication between the hypervisor and guest there is a
77
+
shared page that contains parts of supervisor visible register state.
78
+
The guest can map this shared page to access its supervisor register
79
+
through memory using this hypercall.
80
80
81
81
5. KVM_HC_KICK_CPU
82
-
------------------------
83
-
Architecture: x86
84
-
Status: active
85
-
Purpose: Hypercall used to wakeup a vcpu from HLT state
86
-
Usage example : A vcpu of a paravirtualized guest that is busywaiting in guest
87
-
kernel mode for an event to occur (ex: a spinlock to become available) can
88
-
execute HLT instruction once it has busy-waited for more than a threshold
89
-
time-interval. Execution of HLT instruction would cause the hypervisor to put
90
-
the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the
91
-
same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall,
92
-
specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0)
93
-
is used in the hypercall for future use.
82
+
------------------
83
+
84
+
:Architecture: x86
85
+
:Status: active
86
+
:Purpose: Hypercall used to wakeup a vcpu from HLT state
87
+
:Usage example:
88
+
A vcpu of a paravirtualized guest that is busywaiting in guest
89
+
kernel mode for an event to occur (ex: a spinlock to become available) can
90
+
execute HLT instruction once it has busy-waited for more than a threshold
91
+
time-interval. Execution of HLT instruction would cause the hypervisor to put
92
+
the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the
93
+
same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall,
94
+
specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0)
95
+
is used in the hypercall for future use.
94
96
95
97
96
98
6. KVM_HC_CLOCK_PAIRING
97
-
------------------------
98
-
Architecture: x86
99
-
Status: active
100
-
Purpose: Hypercall used to synchronize host and guest clocks.
99
+
-----------------------
100
+
:Architecture: x86
101
+
:Status: active
102
+
:Purpose: Hypercall used to synchronize host and guest clocks.
103
+
101
104
Usage:
102
105
103
106
a0: guest physical address where host copies
···
113
100
114
101
a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0)
115
102
is supported (corresponding to the host's CLOCK_REALTIME clock).
103
+
104
+
::
116
105
117
106
struct kvm_clock_pairing {
118
107
__s64 sec;
···
138
123
or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK.
139
124
140
125
6. KVM_HC_SEND_IPI
141
-
------------------------
142
-
Architecture: x86
143
-
Status: active
144
-
Purpose: Send IPIs to multiple vCPUs.
126
+
------------------
145
127
146
-
a0: lower part of the bitmap of destination APIC IDs
147
-
a1: higher part of the bitmap of destination APIC IDs
148
-
a2: the lowest APIC ID in bitmap
149
-
a3: APIC ICR
128
+
:Architecture: x86
129
+
:Status: active
130
+
:Purpose: Send IPIs to multiple vCPUs.
131
+
132
+
- a0: lower part of the bitmap of destination APIC IDs
133
+
- a1: higher part of the bitmap of destination APIC IDs
134
+
- a2: the lowest APIC ID in bitmap
135
+
- a3: APIC ICR
150
136
151
137
The hypercall lets a guest send multicast IPIs, with at most 128
152
138
128 destinations per hypercall in 64-bit mode and 64 vCPUs per
···
159
143
Returns the number of CPUs to which the IPIs were delivered successfully.
160
144
161
145
7. KVM_HC_SCHED_YIELD
162
-
------------------------
163
-
Architecture: x86
164
-
Status: active
165
-
Purpose: Hypercall used to yield if the IPI target vCPU is preempted
146
+
---------------------
147
+
148
+
:Architecture: x86
149
+
:Status: active
150
+
:Purpose: Hypercall used to yield if the IPI target vCPU is preempted
166
151
167
152
a0: destination APIC ID
168
153
169
-
Usage example: When sending a call-function IPI-many to vCPUs, yield if
170
-
any of the IPI target vCPUs was preempted.
154
+
:Usage example: When sending a call-function IPI-many to vCPUs, yield if
155
+
any of the IPI target vCPUs was preempted.