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>
---
v3:
* more grammar, formatting fixes
* drop patch 1 / semi-unrelated content which was already applied
v2:
* address various style, linter review comments
man/man2/sched_setattr.2 | 72 +++++++++++++++++++++++++++++++++++++++-
1 file changed, 71 insertions(+), 1 deletion(-)
diff --git a/man/man2/sched_setattr.2 b/man/man2/sched_setattr.2
index 0c866a786748..aa27dee79dce 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,23 @@ .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
+.B SCHED_FLAG_UTIL_CLAMP_MIN
+.TQ
+.BR SCHED_FLAG_UTIL_CLAMP_MAX " (both 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 +249,37 @@ .SS sched_setattr()
.I sched_period
This field specifies the "Period" parameter for deadline scheduling.
The value is expressed in nanoseconds.
+.TP
+.I sched_util_min
+.TQ
+.IR sched_util_max " (both since Linux 5.3)"
+These fields specify the expected minimum and maximum utilization, respectively.
+They are ignored unless their corresponding
+.B SCHED_FLAG_UTIL_CLAMP_MIN
+or
+.B SCHED_FLAG_UTIL_CLAMP_MAX
+is 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
+.IR 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
+.B UINT32_MAX
+(since Linux 5.11).
.P
The
.I flags
@@ -368,6 +420,24 @@ .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
+.B SCHED_FLAG_UTIL_CLAMP
+was provided, but the kernel was not built with
+.B CONFIG_UCLAMP_TASK
+support.
+.TP
.B EPERM
The caller does not have appropriate privileges.
.TP
--
2.45.2.627.g7a2c4fd464-goog
