Hi Brian,
On Wed, Jun 12, 2024 at 01:44:53PM GMT, Brian Norris wrote:
> 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>
> ---
> v2:
> * address various style, linter review comments
>
> man/man2/sched_setattr.2 | 67 +++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 66 insertions(+), 1 deletion(-)
>
> diff --git a/man/man2/sched_setattr.2 b/man/man2/sched_setattr.2
> index 0c866a786748..c3b2cc5be6f1 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,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)"
This should use .TP and .TQ as above.
> +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
With 'or', here corresponds 'is', not 'are'. For 'are' we'd need 'and',
to get a plural.
> +.IR sched_flags .
> +.IP
> +Utilization is a value in the range [0, 1024], representing the percentage of
Break after ','.
> +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
Break after ','.
> +corresponds to 0%.
> +For example, a 20% utilization task is a task running for 2ms every 10ms at
Break after ',', and after 'is'.
> +maximum frequency and is represented by a utilization value of
> +0.2 * 1024 = 205.
This should go in italics.
$ MANWIDTH=72 man man-pages | sed -n '/Expressions/,/^$/p'
Expressions, if not written on a separate indented line, should be
specified in italics. Again, the use of nonbreaking spaces may be
appropriate if the expression is inlined with normal text.
> +.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.
Please break both sentences at consistent points, since they have
symmetric wording.
> +.IP
> +A task utilization boundary can be reset by setting its field to
> +.B UINT32_MAX
> +(new in Linux 5.11).
s/new in/since/
> .P
> The
> .I flags
> @@ -368,6 +416,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
Missing bold.
Have a lovely day!
Alex
> +.B CONFIG_UCLAMP_TASK
> +support.
> +.TP
> .B EPERM
> The caller does not have appropriate privileges.
> .TP
> --
> 2.45.2.505.gda0bf45e8d-goog
>
>
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
