* Updated title capitalization for consistency * Fixed acronym capitalization (e.g. CPU, vCPU) * Added usage of hypenated compoud adjective (e.g. host-side polling, where host-side is modifying polling) * Added missing verb "as" in "basic logic is as follows" * Added missing articl "an" in "guest_halt_poll_ns when an event occurs" * Fixed parameter definition in 4, all previous examples started with descibing the parameter in the first sentence followed by additional notes * Replaced C-terminology Bool in favor of formal form Boolean * Cleaned up phrasing in "Further Notes" section for clarity Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@xxxxxxxxx> --- Documentation/virt/guest-halt-polling.rst | 47 +++++++++++------------ 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/Documentation/virt/guest-halt-polling.rst b/Documentation/virt/guest-halt-polling.rst index 922291ddc40c..3e4e9d4099c5 100644 --- a/Documentation/virt/guest-halt-polling.rst +++ b/Documentation/virt/guest-halt-polling.rst @@ -1,12 +1,12 @@ ================== -Guest halt polling +Guest Halt Polling ================== -The cpuidle_haltpoll driver, with the haltpoll governor, allows -the guest vcpus to poll for a specified amount of time before +The cpuidle_haltpoll driver, along with the haltpoll governor, allows +the guest vCPUs to poll for a specified amount of time before halting. -This provides the following benefits to host side polling: +This provides the following benefits to host-side polling: 1) The POLL flag is set while polling is performed, which allows a remote vCPU to avoid sending an IPI (and the associated @@ -14,15 +14,15 @@ This provides the following benefits to host side polling: 2) The VM-exit cost can be avoided. -The downside of guest side polling is that polling is performed -even with other runnable tasks in the host. +The downside of guest-side polling is that polling is performed +even when other tasks are runnable on the host. -The basic logic as follows: A global value, guest_halt_poll_ns, +The basic logic is as follows: A global value, guest_halt_poll_ns, is configured by the user, indicating the maximum amount of time polling is allowed. This value is fixed. -Each vcpu has an adjustable guest_halt_poll_ns -("per-cpu guest_halt_poll_ns"), which is adjusted by the algorithm +Each vCPU has an adjustable guest_halt_poll_ns +("per-CPU guest_halt_poll_ns"), which is adjusted by the algorithm in response to events (explained below). Module Parameters @@ -39,26 +39,25 @@ Default: 200000 2) guest_halt_poll_shrink: -Division factor used to shrink per-cpu guest_halt_poll_ns when -wakeup event occurs after the global guest_halt_poll_ns. +Division factor used to shrink per-CPU guest_halt_poll_ns when +a wakeup event occurs after the global guest_halt_poll_ns. Default: 2 3) guest_halt_poll_grow: -Multiplication factor used to grow per-cpu guest_halt_poll_ns -when event occurs after per-cpu guest_halt_poll_ns +Multiplication factor used to grow per-CPU guest_halt_poll_ns +when an event occurs after per-CPU guest_halt_poll_ns but before global guest_halt_poll_ns. Default: 2 4) guest_halt_poll_grow_start: -The per-cpu guest_halt_poll_ns eventually reaches zero -in case of an idle system. This value sets the initial -per-cpu guest_halt_poll_ns when growing. This can -be increased from 10000, to avoid misses during the initial -growth stage: +The initial per-CPU guest_halt_poll_ns when growing. The per-CPU +guest_halt_poll_ns eventually reaches zero in case of an idle +system. This can be increased from 10000, to avoid misses +during the initial growth stage: 10k, 20k, 40k, ... (example assumes guest_halt_poll_grow=2). @@ -66,9 +65,9 @@ Default: 50000 5) guest_halt_poll_allow_shrink: -Bool parameter which allows shrinking. Set to N -to avoid it (per-cpu guest_halt_poll_ns will remain -high once achieves global guest_halt_poll_ns value). +Boolean parameter which allows shrinking. Set to N +to avoid it (per-CPU guest_halt_poll_ns will remain +high once it achieves global guest_halt_poll_ns value). Default: Y @@ -79,6 +78,6 @@ The module parameters can be set from the sysfs files in:: Further Notes ============= -- Care should be taken when setting the guest_halt_poll_ns parameter as a - large value has the potential to drive the cpu usage to 100% on a machine - which would be almost entirely idle otherwise. +- Care should be taken when setting the guest_halt_poll_ns parameter to a + large value, as this can potentially drive the CPU usage to 100% on an + otherwise mostly idle machine. -- 2.43.0