1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===========================
4 The KVM halt polling system
5 ===========================
6
7 The KVM halt polling system provides a feature
8 of a guest can, under some circumstances, be r
9 for some time period after the guest has elect
10 That is, when a guest vcpu has ceded, or in th
11 vcpus of a single vcore have ceded, the host k
12 before giving up the cpu to the scheduler in o
13
14 Polling provides a latency advantage in cases
15 very quickly by at least saving us a trip thro
16 the order of a few micro-seconds, although per
17 dependent. In the event that no wakeup source
18 interval or some other task on the runqueue is
19 invoked. Thus halt polling is especially usefu
20 wakeup periods where the time spent halt polli
21 savings of not invoking the scheduler are dist
22
23 The generic halt polling code is implemented i
24
25 virt/kvm/kvm_main.c: kvm_vcpu_block()
26
27 The powerpc kvm-hv specific case is implemente
28
29 arch/powerpc/kvm/book3s_hv.c: kvmppc_v
30
31 Halt Polling Interval
32 =====================
33
34 The maximum time for which to poll before invo
35 as the halt polling interval, is increased and
36 effectiveness of the polling in an attempt to
37 This value is stored in either the vcpu struct
38
39 kvm_vcpu->halt_poll_ns
40
41 or in the case of powerpc kvm-hv, in the vcore
42
43 kvmppc_vcore->halt_poll_ns
44
45 Thus this is a per vcpu (or vcore) value.
46
47 During polling if a wakeup source is received
48 the interval is left unchanged. In the event t
49 received during the polling interval (and thus
50 two options, either the polling interval and t
51 the global max polling interval (see module pa
52 time was greater than the global max polling i
53
54 In the event that both the polling interval an
55 the global max polling interval then the polli
56 the hope that next time during the longer poll
57 will be received while the host is polling and
58 received. The polling interval is grown in the
59 is multiplied by the module parameters halt_po
60 halt_poll_ns_grow_start.
61
62 In the event that the total block time was gre
63 interval then the host will never poll for lon
64 max) to wakeup during the polling interval so
65 to avoid pointless polling. The polling interv
66 shrink_halt_poll_ns() and is divided by the mo
67 halt_poll_ns_shrink, or set to 0 iff halt_poll
68
69 It is worth noting that this adjustment proces
70 steady state polling interval but will only re
71 which come at an approximately constant rate,
72 adjustment of the polling interval.
73
74 [0] total block time:
75 the time between when th
76 invoked and a wakeup sou
77 whether the scheduler is
78
79 Module Parameters
80 =================
81
82 The kvm module has 4 tunable module parameters
83 interval, the initial value (to grow from 0),
84 interval is grown and shrunk. These variables
85 include/linux/kvm_host.h and as module paramet
86 arch/powerpc/kvm/book3s_hv.c in the powerpc kv
87
88 +-----------------------+---------------------
89 |Module Parameter | Description
90 +-----------------------+---------------------
91 |halt_poll_ns | The global max polli
92 | | interval which defin
93 | | the ceiling value of
94 | | polling interval for
95 | | each vcpu.
96 +-----------------------+---------------------
97 |halt_poll_ns_grow | The value by which t
98 | | halt polling interva
99 | | multiplied in the
100 | | grow_halt_poll_ns()
101 | | function.
102 +-----------------------+---------------------
103 |halt_poll_ns_grow_start| The initial value to
104 | | to from zero in the
105 | | grow_halt_poll_ns()
106 | | function.
107 +-----------------------+---------------------
108 |halt_poll_ns_shrink | The value by which t
109 | | halt polling interva
110 | | divided in the
111 | | shrink_halt_poll_ns(
112 | | function.
113 +-----------------------+---------------------
114
115 These module parameters can be set from the sy
116
117 /sys/module/kvm/parameters/
118
119 Note: these module parameters are system-wide
120 be tuned on a per vm basis.
121
122 Any changes to these parameters will be picked
123 next time they halt, with the notable exceptio
124 (see next section).
125
126 KVM_CAP_HALT_POLL
127 =================
128
129 KVM_CAP_HALT_POLL is a VM capability that allo
130 on a per-VM basis. VMs using KVM_CAP_HALT_POLL
131 still obey halt_poll_ns_grow, halt_poll_ns_gro
132
133 See Documentation/virt/kvm/api.rst for more in
134
135 Further Notes
136 =============
137
138 - Care should be taken when setting the halt_p
139 has the potential to drive the cpu usage to
140 entirely idle otherwise. This is because eve
141 little work is done and which are quite far
142 global max polling interval (halt_poll_ns) t
143 entire block time and thus cpu utilisation w
144
145 - Halt polling essentially presents a trade-of
146 the module parameters should be used to tune
147 essentially converted to host kernel time wi
148 entering the guest.
149
150 - Halt polling will only be conducted by the h
151 that cpu, otherwise the polling will cease i
152 allow that other task to run. Thus this does
153 of the cpu.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.