1 ================== 1 ==================
2 Guest halt polling 2 Guest halt polling
3 ================== 3 ==================
4 4
5 The cpuidle_haltpoll driver, with the haltpoll 5 The cpuidle_haltpoll driver, with the haltpoll governor, allows
6 the guest vcpus to poll for a specified amount 6 the guest vcpus to poll for a specified amount of time before
7 halting. 7 halting.
8 8
9 This provides the following benefits to host s 9 This provides the following benefits to host side polling:
10 10
11 1) The POLL flag is set while polling 11 1) The POLL flag is set while polling is performed, which allows
12 a remote vCPU to avoid sending an I 12 a remote vCPU to avoid sending an IPI (and the associated
13 cost of handling the IPI) when perf 13 cost of handling the IPI) when performing a wakeup.
14 14
15 2) The VM-exit cost can be avoided. 15 2) The VM-exit cost can be avoided.
16 16
17 The downside of guest side polling is that pol 17 The downside of guest side polling is that polling is performed
18 even with other runnable tasks in the host. 18 even with other runnable tasks in the host.
19 19
20 The basic logic as follows: A global value, gu 20 The basic logic as follows: A global value, guest_halt_poll_ns,
21 is configured by the user, indicating the maxi 21 is configured by the user, indicating the maximum amount of
22 time polling is allowed. This value is fixed. 22 time polling is allowed. This value is fixed.
23 23
24 Each vcpu has an adjustable guest_halt_poll_ns 24 Each vcpu has an adjustable guest_halt_poll_ns
25 ("per-cpu guest_halt_poll_ns"), which is adjus 25 ("per-cpu guest_halt_poll_ns"), which is adjusted by the algorithm
26 in response to events (explained below). 26 in response to events (explained below).
27 27
28 Module Parameters 28 Module Parameters
29 ================= 29 =================
30 30
31 The haltpoll governor has 5 tunable module par 31 The haltpoll governor has 5 tunable module parameters:
32 32
33 1) guest_halt_poll_ns: 33 1) guest_halt_poll_ns:
34 34
35 Maximum amount of time, in nanoseconds, that p 35 Maximum amount of time, in nanoseconds, that polling is
36 performed before halting. 36 performed before halting.
37 37
38 Default: 200000 38 Default: 200000
39 39
40 2) guest_halt_poll_shrink: 40 2) guest_halt_poll_shrink:
41 41
42 Division factor used to shrink per-cpu guest_h 42 Division factor used to shrink per-cpu guest_halt_poll_ns when
43 wakeup event occurs after the global guest_hal 43 wakeup event occurs after the global guest_halt_poll_ns.
44 44
45 Default: 2 45 Default: 2
46 46
47 3) guest_halt_poll_grow: 47 3) guest_halt_poll_grow:
48 48
49 Multiplication factor used to grow per-cpu gue 49 Multiplication factor used to grow per-cpu guest_halt_poll_ns
50 when event occurs after per-cpu guest_halt_pol 50 when event occurs after per-cpu guest_halt_poll_ns
51 but before global guest_halt_poll_ns. 51 but before global guest_halt_poll_ns.
52 52
53 Default: 2 53 Default: 2
54 54
55 4) guest_halt_poll_grow_start: 55 4) guest_halt_poll_grow_start:
56 56
57 The per-cpu guest_halt_poll_ns eventually reac 57 The per-cpu guest_halt_poll_ns eventually reaches zero
58 in case of an idle system. This value sets the 58 in case of an idle system. This value sets the initial
59 per-cpu guest_halt_poll_ns when growing. This 59 per-cpu guest_halt_poll_ns when growing. This can
60 be increased from 10000, to avoid misses durin 60 be increased from 10000, to avoid misses during the initial
61 growth stage: 61 growth stage:
62 62
63 10k, 20k, 40k, ... (example assumes guest_halt 63 10k, 20k, 40k, ... (example assumes guest_halt_poll_grow=2).
64 64
65 Default: 50000 65 Default: 50000
66 66
67 5) guest_halt_poll_allow_shrink: 67 5) guest_halt_poll_allow_shrink:
68 68
69 Bool parameter which allows shrinking. Set to 69 Bool parameter which allows shrinking. Set to N
70 to avoid it (per-cpu guest_halt_poll_ns will r 70 to avoid it (per-cpu guest_halt_poll_ns will remain
71 high once achieves global guest_halt_poll_ns v 71 high once achieves global guest_halt_poll_ns value).
72 72
73 Default: Y 73 Default: Y
74 74
75 The module parameters can be set from the sysf !! 75 The module parameters can be set from the debugfs files in::
76 76
77 /sys/module/haltpoll/parameters/ 77 /sys/module/haltpoll/parameters/
78 78
79 Further Notes 79 Further Notes
80 ============= 80 =============
81 81
82 - Care should be taken when setting the guest_ 82 - Care should be taken when setting the guest_halt_poll_ns parameter as a
83 large value has the potential to drive the c 83 large value has the potential to drive the cpu usage to 100% on a machine
84 which would be almost entirely idle otherwis 84 which would be almost entirely idle otherwise.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.