[PATCH] sched/documentation: elaborate on uclamp limitations

[Hongyan Xia]

The story in 5.2 about util_avg abruptly jumping from 300 when
Fmax/Fmin == 3 to 1024 when Fmax/Fmin == 4 hides some details about how
clock_pelt works behind the scenes. Explicitly mention it to make it
easier for readers to follow.

Signed-off-by: Hongyan Xia <hongyan.xia2@xxxxxxx>
Cc: Qais Yousef <qyousef@xxxxxxxxxxx>
Cc: Vincent Guittot <vincent.guittot@xxxxxxxxxx>
---
 Documentation/scheduler/sched-util-clamp.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/scheduler/sched-util-clamp.rst b/Documentation/scheduler/sched-util-clamp.rst
index 74d5b7c6431d..524df07bceba 100644
--- a/Documentation/scheduler/sched-util-clamp.rst
+++ b/Documentation/scheduler/sched-util-clamp.rst
@@ -669,6 +669,19 @@ but not proportional to Fmax/Fmin.
 
         p0->util_avg = 300 + small_error
 
+The reason why util_avg is around 300 even though it runs for 900 at Fmin is:
+Although running at Fmin reduces the rate of rq_clock_pelt() to 1/3 thus
+accumulates util_sum at 1/3 of the rate at Fmax, the clock period
+(rq_clock_pelt() now minus previous rq_clock_pelt()) in:
+
+::
+
+        util_sum / clock period = util_avg
+
+does not shrink to 1/3, since rq->clock_pelt is periodically synchronized with
+rq->clock_task as long as there's idle time. As a result, we get util_avg of
+about 300, not 900.
+
 Now if the ratio of Fmax/Fmin is 4, the maximum value becomes:
 
 ::
@@ -682,6 +695,10 @@ this happens, then the _actual_ util_avg will become:
 
         p0->util_avg = 1024
 
+This is because rq->clock_pelt is no longer synchronized with the task clock.
+The clock period therefore is proportionally shrunk by the same ratio of
+(Fmax/Fmin), giving us a maximal util_avg of 1024.
+
 If task p1 wakes up on this CPU, which have:
 
 ::
-- 
2.34.1