Documentation/virt/guest-halt-polling.rst

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