Re: [PATCH v2 2/2] sched_setattr.2: Document sched_util_{min,max}

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux