Utilization attributes were added in Linux v5.3 via commit a509a7cd7974
("sched/uclamp: Extend sched_setattr() to support utilization
clamping"). Borrow some documentation from there, with a bit of
editorial trimming and augmentation.
The "reset" (-1 / UINT32_MAX) behavior was added in Linux 5.11 via
commit 480a6ca2dc6e ("sched/uclamp: Allow to reset a task uclamp
constraint value").
Cc: Dietmar Eggemann <dietmar.eggemann@xxxxxxx>
Cc: Patrick Bellasi <patrick.bellasi@xxxxxxx>
Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx>
Signed-off-by: Brian Norris <briannorris@xxxxxxxxxxxx>
---
man/man2/sched_setattr.2 | 65 ++++++++++++++++++++++++++++++++++++++--
1 file changed, 63 insertions(+), 2 deletions(-)
diff --git a/man/man2/sched_setattr.2 b/man/man2/sched_setattr.2
index 5d7061bd6e3a..4b940d76de53 100644
--- a/man/man2/sched_setattr.2
+++ b/man/man2/sched_setattr.2
@@ -94,10 +94,14 @@ .SS sched_setattr()
SCHED_BATCH) */
u32 sched_priority; /* Static priority (SCHED_FIFO,
SCHED_RR) */
- /* Remaining fields are for SCHED_DEADLINE */
+ /* For SCHED_DEADLINE */
u64 sched_runtime;
u64 sched_deadline;
u64 sched_period;
+
+ /* Utilization hints */
+ u32 sched_util_min;
+ u32 sched_util_max;
};
.EE
.in
@@ -186,6 +190,20 @@ .SS sched_setattr()
On the other hand, if the process-directed signal is delivered to
a thread inside the process other than the one that had a run-time overrun,
the application has no way of knowing which thread overran.
+.TP
+.BR SCHED_FLAG_UTIL_CLAMP_MIN ", " SCHED_FLAG_UTIL_CLAMP_MAX " (since Linux 5.3)"
+These flags indicate that the
+.I
+sched_util_min
+or
+.I
+sched_util_max
+fields, respectively, are present, representing the expected minimum and
+maximum utilization of the thread.
+.IP
+The utilization attributes provide the scheduler with boundaries within which
+it should schedule the thread, potentially informing its decisions regarding
+task placement and frequency selection.
.RE
.TP
.I sched_nice
@@ -228,6 +246,33 @@ .SS sched_setattr()
.I sched_period
This field specifies the "Period" parameter for deadline scheduling.
The value is expressed in nanoseconds.
+.TP
+.IR sched_util_min ", " sched_util_max " (since Linux 5.3)"
+These fields specify the expected minimum and maximum utilization, respectively.
+They are ignored unless their corresponding
+.I SCHED_FLAG_UTIL_CLAMP_MIN
+or
+.I SCHED_FLAG_UTIL_CLAMP_MAX
+are set in
+.IR sched_flags .
+.IP
+Utilization is a value in the range [0..1024], representing the percentage of
+CPU time used by a task when running at the maximum frequency on the highest
+capacity CPU of the system.
+This is a fixed point representation, where 1024 corresponds to 100%, and 0
+corresponds to 0%.
+For example, a 20% utilization task is a task running for 2ms every 10ms at
+maximum frequency and is represented by a utilization value of
+0.2 * 1024 = 205.
+.IP
+A task with a minimum utilization value larger than 0 is more likely scheduled
+on a CPU with a capacity big enough to fit the specified value.
+A task with a maximum utilization value smaller than 1024 is more likely
+scheduled on a CPU with no more capacity than the specified value.
+.IP
+A task utilization boundary can be reset by setting its field to
+.I UINT32_MAX
+(new in Linux 5.11).
.P
The
.I flags
@@ -353,7 +398,6 @@ .SH ERRORS
.I attr.sched_flags
contains a flag other than
.BR SCHED_FLAG_RESET_ON_FORK ;
-or
.I attr.sched_priority
is invalid; or
.I attr.sched_policy
@@ -363,6 +407,23 @@ .SH ERRORS
.I attr
are invalid.
.TP
+.B EINVAL
+.I attr.sched_flags
+contains
+.B SCHED_FLAG_UTIL_CLAMP_MIN
+or
+.BR SCHED_FLAG_UTIL_CLAMP_MAX ,
+and
+.I attr.sched_util_min
+or
+.I attr.sched_util_max
+are out of bounds.
+.TP
+.B EOPNOTSUPP
+SCHED_FLAG_UTIL_CLAMP was provided, but the kernel was not built with
+.BR CONFIG_UCLAMP_TASK
+support.
+.TP
.B EPERM
The caller does not have appropriate privileges.
.TP
--
2.45.1.288.g0e0cd299f1-goog
