4sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget./translations/zh_CN/scheduler/sched-util-clampmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/zh_TW/scheduler/sched-util-clampmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/it_IT/scheduler/sched-util-clampmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/ja_JP/scheduler/sched-util-clampmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/ko_KR/scheduler/sched-util-clampmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/sp_SP/scheduler/sched-util-clampmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhH/var/lib/git/docbuild/linux/Documentation/scheduler/sched-util-clamp.rsthKubhsection)}(hhh](htitle)}(hUtilization Clampingh]hUtilization Clamping}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h1. Introductionh]h1. Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hUtilization clamping, also known as util clamp or uclamp, is a scheduler feature that allows user space to help in managing the performance requirement of tasks. It was introduced in v5.3 release. The CGroup support was merged in v5.4.h]hUtilization clamping, also known as util clamp or uclamp, is a scheduler feature that allows user space to help in managing the performance requirement of tasks. It was introduced in v5.3 release. The CGroup support was merged in v5.4.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hX$Uclamp is a hinting mechanism that allows the scheduler to understand the performance requirements and restrictions of the tasks, thus it helps the scheduler to make a better decision. And when schedutil cpufreq governor is used, util clamp will influence the CPU frequency selection as well.h]hX$Uclamp is a hinting mechanism that allows the scheduler to understand the performance requirements and restrictions of the tasks, thus it helps the scheduler to make a better decision. And when schedutil cpufreq governor is used, util clamp will influence the CPU frequency selection as well.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXSince the scheduler and schedutil are both driven by PELT (util_avg) signals, util clamp acts on that to achieve its goal by clamping the signal to a certain point; hence the name. That is, by clamping utilization we are making the system run at a certain performance point.h]hXSince the scheduler and schedutil are both driven by PELT (util_avg) signals, util clamp acts on that to achieve its goal by clamping the signal to a certain point; hence the name. That is, by clamping utilization we are making the system run at a certain performance point.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hThe right way to view util clamp is as a mechanism to make request or hint on performance constraints. It consists of two tunables:h]hThe right way to view util clamp is as a mechanism to make request or hint on performance constraints. It consists of two tunables:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh block_quote)}(hT* UCLAMP_MIN, which sets the lower bound. * UCLAMP_MAX, which sets the upper bound. h]h bullet_list)}(hhh](h list_item)}(h'UCLAMP_MIN, which sets the lower bound.h]h)}(hj#h]h'UCLAMP_MIN, which sets the lower bound.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj!ubah}(h]h ]h"]h$]h&]uh1jhjubj )}(h(UCLAMP_MAX, which sets the upper bound. h]h)}(h'UCLAMP_MAX, which sets the upper bound.h]h'UCLAMP_MAX, which sets the upper bound.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj8ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]bullet*uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhhhhubh)}(hThese two bounds will ensure a task will operate within this performance range of the system. UCLAMP_MIN implies boosting a task, while UCLAMP_MAX implies capping a task.h]hThese two bounds will ensure a task will operate within this performance range of the system. UCLAMP_MIN implies boosting a task, while UCLAMP_MAX implies capping a task.}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXOne can tell the system (scheduler) that some tasks require a minimum performance point to operate at to deliver the desired user experience. Or one can tell the system that some tasks should be restricted from consuming too much resources and should not go above a specific performance point. Viewing the uclamp values as performance points rather than utilization is a better abstraction from user space point of view.h]hXOne can tell the system (scheduler) that some tasks require a minimum performance point to operate at to deliver the desired user experience. Or one can tell the system that some tasks should be restricted from consuming too much resources and should not go above a specific performance point. Viewing the uclamp values as performance points rather than utilization is a better abstraction from user space point of view.}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hhhhubh)}(hX~As an example, a game can use util clamp to form a feedback loop with its perceived Frames Per Second (FPS). It can dynamically increase the minimum performance point required by its display pipeline to ensure no frame is dropped. It can also dynamically 'prime' up these tasks if it knows in the coming few hundred milliseconds a computationally intensive scene is about to happen.h]hXAs an example, a game can use util clamp to form a feedback loop with its perceived Frames Per Second (FPS). It can dynamically increase the minimum performance point required by its display pipeline to ensure no frame is dropped. It can also dynamically ‘prime’ up these tasks if it knows in the coming few hundred milliseconds a computationally intensive scene is about to happen.}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK*hhhhubh)}(hOn mobile hardware where the capability of the devices varies a lot, this dynamic feedback loop offers a great flexibility to ensure best user experience given the capabilities of any system.h]hOn mobile hardware where the capability of the devices varies a lot, this dynamic feedback loop offers a great flexibility to ensure best user experience given the capabilities of any system.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hhhhubh)}(hOf course a static configuration is possible too. The exact usage will depend on the system, application and the desired outcome.h]hOf course a static configuration is possible too. The exact usage will depend on the system, application and the desired outcome.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hhhhubh)}(hXVAnother example is in Android where tasks are classified as background, foreground, top-app, etc. Util clamp can be used to constrain how much resources background tasks are consuming by capping the performance point they can run at. This constraint helps reserve resources for important tasks, like the ones belonging to the currently active app (top-app group). Beside this helps in limiting how much power they consume. This can be more obvious in heterogeneous systems (e.g. Arm big.LITTLE); the constraint will help bias the background tasks to stay on the little cores which will ensure that:h]hXVAnother example is in Android where tasks are classified as background, foreground, top-app, etc. Util clamp can be used to constrain how much resources background tasks are consuming by capping the performance point they can run at. This constraint helps reserve resources for important tasks, like the ones belonging to the currently active app (top-app group). Beside this helps in limiting how much power they consume. This can be more obvious in heterogeneous systems (e.g. Arm big.LITTLE); the constraint will help bias the background tasks to stay on the little cores which will ensure that:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK8hhhhubj)}(hX1. The big cores are free to run top-app tasks immediately. top-app tasks are the tasks the user is currently interacting with, hence the most important tasks in the system. 2. They don't run on a power hungry core and drain battery even if they are CPU intensive tasks. h]henumerated_list)}(hhh](j )}(hThe big cores are free to run top-app tasks immediately. top-app tasks are the tasks the user is currently interacting with, hence the most important tasks in the system.h]h)}(hThe big cores are free to run top-app tasks immediately. top-app tasks are the tasks the user is currently interacting with, hence the most important tasks in the system.h]hThe big cores are free to run top-app tasks immediately. top-app tasks are the tasks the user is currently interacting with, hence the most important tasks in the system.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKAhjubah}(h]h ]h"]h$]h&]uh1jhjubj )}(h^They don't run on a power hungry core and drain battery even if they are CPU intensive tasks. h]h)}(h]They don't run on a power hungry core and drain battery even if they are CPU intensive tasks.h]h_They don’t run on a power hungry core and drain battery even if they are CPU intensive tasks.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhjubah}(h]h ]h"]h$]h&]uh1jhhhKAhhhhubhnote)}(hY**little cores**: CPUs with capacity < 1024 **big cores**: CPUs with capacity = 1024h]hdefinition_list)}(hhh](hdefinition_list_item)}(h,**little cores**: CPUs with capacity < 1024 h](hterm)}(h**little cores**:h](hstrong)}(h**little cores**h]h little cores}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1j hhhKIhj ubh definition)}(hhh]h)}(hCPUs with capacity < 1024h]hCPUs with capacity < 1024}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKIhj/ubah}(h]h ]h"]h$]h&]uh1j-hj ubeh}(h]h ]h"]h$]h&]uh1jhhhKIhjubj)}(h(**big cores**: CPUs with capacity = 1024h](j)}(h**big cores**:h](j)}(h **big cores**h]h big cores}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jhjPubh:}(hjPhhhNhNubeh}(h]h ]h"]h$]h&]uh1j hhhKKhjLubj.)}(hhh]h)}(hCPUs with capacity = 1024h]hCPUs with capacity = 1024}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhjlubah}(h]h ]h"]h$]h&]uh1j-hjLubeh}(h]h ]h"]h$]h&]uh1jhhhKKhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhhhhhNhNubh)}(hBy making these uclamp performance requests, or rather hints, user space can ensure system resources are used optimally to deliver the best possible user experience.h]hBy making these uclamp performance requests, or rather hints, user space can ensure system resources are used optimally to deliver the best possible user experience.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhhhhubh)}(h~Another use case is to help with **overcoming the ramp up latency inherit in how scheduler utilization signal is calculated**.h](h!Another use case is to help with }(hjhhhNhNubj)}(h\**overcoming the ramp up latency inherit in how scheduler utilization signal is calculated**h]hXovercoming the ramp up latency inherit in how scheduler utilization signal is calculated}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKRhhhhubh)}(hXOn the other hand, a busy task for instance that requires to run at maximum performance point will suffer a delay of ~200ms (PELT HALFIFE = 32ms) for the scheduler to realize that. This is known to affect workloads like gaming on mobile devices where frames will drop due to slow response time to select the higher frequency required for the tasks to finish their work in time. Setting UCLAMP_MIN=1024 will ensure such tasks will always see the highest performance level when they start running.h]hXOn the other hand, a busy task for instance that requires to run at maximum performance point will suffer a delay of ~200ms (PELT HALFIFE = 32ms) for the scheduler to realize that. This is known to affect workloads like gaming on mobile devices where frames will drop due to slow response time to select the higher frequency required for the tasks to finish their work in time. Setting UCLAMP_MIN=1024 will ensure such tasks will always see the highest performance level when they start running.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKUhhhhubh)}(hThe overall visible effect goes beyond better perceived user experience/performance and stretches to help achieve a better overall performance/watt if used effectively.h]hThe overall visible effect goes beyond better perceived user experience/performance and stretches to help achieve a better overall performance/watt if used effectively.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hhhhubh)}(hUser space can form a feedback loop with the thermal subsystem too to ensure the device doesn't heat up to the point where it will throttle.h]hUser space can form a feedback loop with the thermal subsystem too to ensure the device doesn’t heat up to the point where it will throttle.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKahhhhubh)}(hGBoth SCHED_NORMAL/OTHER and SCHED_FIFO/RR honour uclamp requests/hints.h]hGBoth SCHED_NORMAL/OTHER and SCHED_FIFO/RR honour uclamp requests/hints.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKdhhhhubh)}(hIn the SCHED_FIFO/RR case, uclamp gives the option to run RT tasks at any performance point rather than being tied to MAX frequency all the time. Which can be useful on general purpose systems that run on battery powered devices.h]hIn the SCHED_FIFO/RR case, uclamp gives the option to run RT tasks at any performance point rather than being tied to MAX frequency all the time. Which can be useful on general purpose systems that run on battery powered devices.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKfhhhhubh)}(hNote that by design RT tasks don't have per-task PELT signal and must always run at a constant frequency to combat undeterministic DVFS rampup delays.h]hNote that by design RT tasks don’t have per-task PELT signal and must always run at a constant frequency to combat undeterministic DVFS rampup delays.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhhhhubh)}(hXNote that using schedutil always implies a single delay to modify the frequency when an RT task wakes up. This cost is unchanged by using uclamp. Uclamp only helps picking what frequency to request instead of schedutil always requesting MAX for all RT tasks.h]hXNote that using schedutil always implies a single delay to modify the frequency when an RT task wakes up. This cost is unchanged by using uclamp. Uclamp only helps picking what frequency to request instead of schedutil always requesting MAX for all RT tasks.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKmhhhhubh)}(hSee :ref:`section 3.4 ` for default values and :ref:`3.4.1 ` on how to change RT tasks default value.h](hSee }(hj%hhhNhNubh)}(h*:ref:`section 3.4 `h]hinline)}(hj/h]h section 3.4}(hj3hhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1j1hj-ubah}(h]h ]h"]h$]h&]refdocscheduler/sched-util-clamp refdomainj>reftyperef refexplicitrefwarn reftargetuclamp-default-valuesuh1hhhhKrhj%ubh for default values and }(hj%hhhNhNubh)}(h.:ref:`3.4.1 `h]j2)}(hjXh]h3.4.1}(hjZhhhNhNubah}(h]h ](j=stdstd-refeh"]h$]h&]uh1j1hjVubah}(h]h ]h"]h$]h&]refdocjJ refdomainjdreftyperef refexplicitrefwarnjPsched-util-clamp-min-rt-defaultuh1hhhhKrhj%ubh) on how to change RT tasks default value.}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKrhhhhubeh}(h] introductionah ]h"]1. introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h 2. Designh]h 2. Design}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKwubh)}(hUtil clamp is a property of every task in the system. It sets the boundaries of its utilization signal; acting as a bias mechanism that influences certain decisions within the scheduler.h]hUtil clamp is a property of every task in the system. It sets the boundaries of its utilization signal; acting as a bias mechanism that influences certain decisions within the scheduler.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKyhjhhubh)}(hX)The actual utilization signal of a task is never clamped in reality. If you inspect PELT signals at any point of time you should continue to see them as they are intact. Clamping happens only when needed, e.g: when a task wakes up and the scheduler needs to select a suitable CPU for it to run on.h]hX)The actual utilization signal of a task is never clamped in reality. If you inspect PELT signals at any point of time you should continue to see them as they are intact. Clamping happens only when needed, e.g: when a task wakes up and the scheduler needs to select a suitable CPU for it to run on.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hjhhubh)}(hXcSince the goal of util clamp is to allow requesting a minimum and maximum performance point for a task to run on, it must be able to influence the frequency selection as well as task placement to be most effective. Both of which have implications on the utilization value at CPU runqueue (rq for short) level, which brings us to the main design challenge.h]hXcSince the goal of util clamp is to allow requesting a minimum and maximum performance point for a task to run on, it must be able to influence the frequency selection as well as task placement to be most effective. Both of which have implications on the utilization value at CPU runqueue (rq for short) level, which brings us to the main design challenge.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX?When a task wakes up on an rq, the utilization signal of the rq will be affected by the uclamp settings of all the tasks enqueued on it. For example if a task requests to run at UTIL_MIN = 512, then the util signal of the rq needs to respect to this request as well as all other requests from all of the enqueued tasks.h]hX?When a task wakes up on an rq, the utilization signal of the rq will be affected by the uclamp settings of all the tasks enqueued on it. For example if a task requests to run at UTIL_MIN = 512, then the util signal of the rq needs to respect to this request as well as all other requests from all of the enqueued tasks.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX9To be able to aggregate the util clamp value of all the tasks attached to the rq, uclamp must do some housekeeping at every enqueue/dequeue, which is the scheduler hot path. Hence care must be taken since any slow down will have significant impact on a lot of use cases and could hinder its usability in practice.h]hX9To be able to aggregate the util clamp value of all the tasks attached to the rq, uclamp must do some housekeeping at every enqueue/dequeue, which is the scheduler hot path. Hence care must be taken since any slow down will have significant impact on a lot of use cases and could hinder its usability in practice.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe way this is handled is by dividing the utilization range into buckets (struct uclamp_bucket) which allows us to reduce the search space from every task on the rq to only a subset of tasks on the top-most bucket.h]hThe way this is handled is by dividing the utilization range into buckets (struct uclamp_bucket) which allows us to reduce the search space from every task on the rq to only a subset of tasks on the top-most bucket.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hWhen a task is enqueued, the counter in the matching bucket is incremented, and on dequeue it is decremented. This makes keeping track of the effective uclamp value at rq level a lot easier.h]hWhen a task is enqueued, the counter in the matching bucket is incremented, and on dequeue it is decremented. This makes keeping track of the effective uclamp value at rq level a lot easier.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hAs tasks are enqueued and dequeued, we keep track of the current effective uclamp value of the rq. See :ref:`section 2.1 ` for details on how this works.h](hgAs tasks are enqueued and dequeued, we keep track of the current effective uclamp value of the rq. See }(hjhhhNhNubh)}(h#:ref:`section 2.1 `h]j2)}(hjh]h section 2.1}(hjhhhNhNubah}(h]h ](j=stdstd-refeh"]h$]h&]uh1j1hjubah}(h]h ]h"]h$]h&]refdocjJ refdomainjreftyperef refexplicitrefwarnjPuclamp-bucketsuh1hhhhKhjubh for details on how this works.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hLater at any path that wants to identify the effective uclamp value of the rq, it will simply need to read this effective uclamp value of the rq at that exact moment of time it needs to take a decision.h]hLater at any path that wants to identify the effective uclamp value of the rq, it will simply need to read this effective uclamp value of the rq at that exact moment of time it needs to take a decision.}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXFor task placement case, only Energy Aware and Capacity Aware Scheduling (EAS/CAS) make use of uclamp for now, which implies that it is applied on heterogeneous systems only. When a task wakes up, the scheduler will look at the current effective uclamp value of every rq and compare it with the potential new value if the task were to be enqueued there. Favoring the rq that will end up with the most energy efficient combination.h]hXFor task placement case, only Energy Aware and Capacity Aware Scheduling (EAS/CAS) make use of uclamp for now, which implies that it is applied on heterogeneous systems only. When a task wakes up, the scheduler will look at the current effective uclamp value of every rq and compare it with the potential new value if the task were to be enqueued there. Favoring the rq that will end up with the most energy efficient combination.}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXSimilarly in schedutil, when it needs to make a frequency update it will look at the current effective uclamp value of the rq which is influenced by the set of tasks currently enqueued there and select the appropriate frequency that will satisfy constraints from requests.h]hXSimilarly in schedutil, when it needs to make a frequency update it will look at the current effective uclamp value of the rq which is influenced by the set of tasks currently enqueued there and select the appropriate frequency that will satisfy constraints from requests.}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXOther paths like setting overutilization state (which effectively disables EAS) make use of uclamp as well. Such cases are considered necessary housekeeping to allow the 2 main use cases above and will not be covered in detail here as they could change with implementation details.h]hXOther paths like setting overutilization state (which effectively disables EAS) make use of uclamp as well. Such cases are considered necessary housekeeping to allow the 2 main use cases above and will not be covered in detail here as they could change with implementation details.}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubhtarget)}(h.. _uclamp-buckets:h]h}(h]h ]h"]h$]h&]refiduclamp-bucketsuh1jehKhjhhhhubh)}(hhh](h)}(h 2.1. Bucketsh]h 2.1. Buckets}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjshhhhhKubh literal_block)}(hX [struct rq] (bottom) (top) 0 1024 | | +-----------+-----------+-----------+---- ----+-----------+ | Bucket 0 | Bucket 1 | Bucket 2 | ... | Bucket N | +-----------+-----------+-----------+---- ----+-----------+ : : : +- p0 +- p3 +- p4 : : +- p1 +- p5 : +- p2h]hX [struct rq] (bottom) (top) 0 1024 | | +-----------+-----------+-----------+---- ----+-----------+ | Bucket 0 | Bucket 1 | Bucket 2 | ... | Bucket N | +-----------+-----------+-----------+---- ----+-----------+ : : : +- p0 +- p3 +- p4 : : +- p1 +- p5 : +- p2}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjshhubj)}(haThe diagram above is an illustration rather than a true depiction of the internal data structure.h]h)}(haThe diagram above is an illustration rather than a true depiction of the internal data structure.h]haThe diagram above is an illustration rather than a true depiction of the internal data structure.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjshhhhhNubh)}(hXTo reduce the search space when trying to decide the effective uclamp value of an rq as tasks are enqueued/dequeued, the whole utilization range is divided into N buckets where N is configured at compile time by setting CONFIG_UCLAMP_BUCKETS_COUNT. By default it is set to 5.h]hXTo reduce the search space when trying to decide the effective uclamp value of an rq as tasks are enqueued/dequeued, the whole utilization range is divided into N buckets where N is configured at compile time by setting CONFIG_UCLAMP_BUCKETS_COUNT. By default it is set to 5.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubh)}(hJThe rq has a bucket for each uclamp_id tunables: [UCLAMP_MIN, UCLAMP_MAX].h]hJThe rq has a bucket for each uclamp_id tunables: [UCLAMP_MIN, UCLAMP_MAX].}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubh)}(hThe range of each bucket is 1024/N. For example, for the default value of 5 there will be 5 buckets, each of which will cover the following range:h]hThe range of each bucket is 1024/N. For example, for the default value of 5 there will be 5 buckets, each of which will cover the following range:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubj)}(hDELTA = round_closest(1024/5) = 204.8 = 205 Bucket 0: [0:204] Bucket 1: [205:409] Bucket 2: [410:614] Bucket 3: [615:819] Bucket 4: [820:1024]h]hDELTA = round_closest(1024/5) = 204.8 = 205 Bucket 0: [0:204] Bucket 1: [205:409] Bucket 2: [410:614] Bucket 3: [615:819] Bucket 4: [820:1024]}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjshhubh)}(h/When a task p with following tunable parametersh]h/When a task p with following tunable parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubj)}(h8p->uclamp[UCLAMP_MIN] = 300 p->uclamp[UCLAMP_MAX] = 1024h]h8p->uclamp[UCLAMP_MIN] = 300 p->uclamp[UCLAMP_MAX] = 1024}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjshhubh)}(his enqueued into the rq, bucket 1 will be incremented for UCLAMP_MIN and bucket 4 will be incremented for UCLAMP_MAX to reflect the fact the rq has a task in this range.h]his enqueued into the rq, bucket 1 will be incremented for UCLAMP_MIN and bucket 4 will be incremented for UCLAMP_MAX to reflect the fact the rq has a task in this range.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubh)}(hQThe rq then keeps track of its current effective uclamp value for each uclamp_id.h]hQThe rq then keeps track of its current effective uclamp value for each uclamp_id.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubh)}(h3When a task p is enqueued, the rq value changes to:h]h3When a task p is enqueued, the rq value changes to:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubj)}(h// update bucket logic goes here rq->uclamp[UCLAMP_MIN] = max(rq->uclamp[UCLAMP_MIN], p->uclamp[UCLAMP_MIN]) // repeat for UCLAMP_MAXh]h// update bucket logic goes here rq->uclamp[UCLAMP_MIN] = max(rq->uclamp[UCLAMP_MIN], p->uclamp[UCLAMP_MIN]) // repeat for UCLAMP_MAX}hj*sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjshhubh)}(h6Similarly, when p is dequeued the rq value changes to:h]h6Similarly, when p is dequeued the rq value changes to:}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubj)}(hx// update bucket logic goes here rq->uclamp[UCLAMP_MIN] = search_top_bucket_for_highest_value() // repeat for UCLAMP_MAXh]hx// update bucket logic goes here rq->uclamp[UCLAMP_MIN] = search_top_bucket_for_highest_value() // repeat for UCLAMP_MAX}hjFsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjshhubh)}(hWhen all buckets are empty, the rq uclamp values are reset to system defaults. See :ref:`section 3.4 ` for details on default values.h](hSWhen all buckets are empty, the rq uclamp values are reset to system defaults. See }(hjThhhNhNubh)}(h*:ref:`section 3.4 `h]j2)}(hj^h]h section 3.4}(hj`hhhNhNubah}(h]h ](j=stdstd-refeh"]h$]h&]uh1j1hj\ubah}(h]h ]h"]h$]h&]refdocjJ refdomainjjreftyperef refexplicitrefwarnjPuclamp-default-valuesuh1hhhhMhjTubh for details on default values.}(hjThhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjshhubeh}(h](bucketsjreh ]h"]( 2.1. bucketsuclamp-bucketseh$]h&]uh1hhjhhhhhKexpect_referenced_by_name}jjgsexpect_referenced_by_id}jrjgsubh)}(hhh](h)}(h2.2. Max aggregationh]h2.2. Max aggregation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM ubh)}(hcUtil clamp is tuned to honour the request for the task that requires the highest performance point.h]hcUtil clamp is tuned to honour the request for the task that requires the highest performance point.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hWhen multiple tasks are attached to the same rq, then util clamp must make sure the task that needs the highest performance point gets it even if there's another task that doesn't need it or is disallowed from reaching this point.h]hWhen multiple tasks are attached to the same rq, then util clamp must make sure the task that needs the highest performance point gets it even if there’s another task that doesn’t need it or is disallowed from reaching this point.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hUFor example, if there are multiple tasks attached to an rq with the following values:h]hUFor example, if there are multiple tasks attached to an rq with the following values:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(htp0->uclamp[UCLAMP_MIN] = 300 p0->uclamp[UCLAMP_MAX] = 900 p1->uclamp[UCLAMP_MIN] = 500 p1->uclamp[UCLAMP_MAX] = 500h]htp0->uclamp[UCLAMP_MIN] = 300 p0->uclamp[UCLAMP_MAX] = 900 p1->uclamp[UCLAMP_MIN] = 500 p1->uclamp[UCLAMP_MAX] = 500}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubh)}(h`then assuming both p0 and p1 are enqueued to the same rq, both UCLAMP_MIN and UCLAMP_MAX become:h]h`then assuming both p0 and p1 are enqueued to the same rq, both UCLAMP_MIN and UCLAMP_MAX become:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hYrq->uclamp[UCLAMP_MIN] = max(300, 500) = 500 rq->uclamp[UCLAMP_MAX] = max(900, 500) = 900h]hYrq->uclamp[UCLAMP_MIN] = max(300, 500) = 500 rq->uclamp[UCLAMP_MAX] = max(900, 500) = 900}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhM"hjhhubh)}(hAs we shall see in :ref:`section 5.1 `, this max aggregation is the cause of one of limitations when using util clamp, in particular for UCLAMP_MAX hint when user space would like to save power.h](hAs we shall see in }(hjhhhNhNubh)}(h(:ref:`section 5.1 `h]j2)}(hjh]h section 5.1}(hjhhhNhNubah}(h]h ](j=stdstd-refeh"]h$]h&]uh1j1hjubah}(h]h ]h"]h$]h&]refdocjJ refdomainjreftyperef refexplicitrefwarnjPuclamp-capping-failuh1hhhhM%hjubh, this max aggregation is the cause of one of limitations when using util clamp, in particular for UCLAMP_MAX hint when user space would like to save power.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM%hjhhubeh}(h]max-aggregationah ]h"]2.2. max aggregationah$]h&]uh1hhjhhhhhM ubh)}(hhh](h)}(h2.3. Hierarchical aggregationh]h2.3. Hierarchical aggregation}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj2hhhhhM*ubh)}(hAs stated earlier, util clamp is a property of every task in the system. But the actual applied (effective) value can be influenced by more than just the request made by the task or another actor on its behalf (middleware library).h]hAs stated earlier, util clamp is a property of every task in the system. But the actual applied (effective) value can be influenced by more than just the request made by the task or another actor on its behalf (middleware library).}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hj2hhubh)}(hDThe effective util clamp value of any task is restricted as follows:h]hDThe effective util clamp value of any task is restricted as follows:}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hj2hhubj)}(h1. By the uclamp settings defined by the cgroup CPU controller it is attached to, if any. 2. The restricted value in (1) is then further restricted by the system wide uclamp settings. h]j)}(hhh](j )}(hVBy the uclamp settings defined by the cgroup CPU controller it is attached to, if any.h]h)}(hVBy the uclamp settings defined by the cgroup CPU controller it is attached to, if any.h]hVBy the uclamp settings defined by the cgroup CPU controller it is attached to, if any.}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hjfubah}(h]h ]h"]h$]h&]uh1jhjcubj )}(h[The restricted value in (1) is then further restricted by the system wide uclamp settings. h]h)}(hZThe restricted value in (1) is then further restricted by the system wide uclamp settings.h]hZThe restricted value in (1) is then further restricted by the system wide uclamp settings.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hj~ubah}(h]h ]h"]h$]h&]uh1jhjcubeh}(h]h ]h"]h$]h&]jjjhjjuh1jhj_ubah}(h]h ]h"]h$]h&]uh1jhhhM2hj2hhubh)}(h^:ref:`Section 3 ` discusses the interfaces and will expand further on that.h](h)}(h$:ref:`Section 3 `h]j2)}(hjh]h Section 3}(hjhhhNhNubah}(h]h ](j=stdstd-refeh"]h$]h&]uh1j1hjubah}(h]h ]h"]h$]h&]refdocjJ refdomainjreftyperef refexplicitrefwarnjPuclamp-interfacesuh1hhhhM7hjubh: discusses the interfaces and will expand further on that.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM7hj2hhubh)}(hFor now suffice to say that if a task makes a request, its actual effective value will have to adhere to some restrictions imposed by cgroup and system wide settings.h]hFor now suffice to say that if a task makes a request, its actual effective value will have to adhere to some restrictions imposed by cgroup and system wide settings.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM:hj2hhubh)}(hXThe system will still accept the request even if effectively will be beyond the constraints, but as soon as the task moves to a different cgroup or a sysadmin modifies the system settings, the request will be satisfied only if it is within new constraints.h]hXThe system will still accept the request even if effectively will be beyond the constraints, but as soon as the task moves to a different cgroup or a sysadmin modifies the system settings, the request will be satisfied only if it is within new constraints.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM>hj2hhubh)}(hIn other words, this aggregation will not cause an error when a task changes its uclamp values, but rather the system may not be able to satisfy requests based on those factors.h]hIn other words, this aggregation will not cause an error when a task changes its uclamp values, but rather the system may not be able to satisfy requests based on those factors.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChj2hhubeh}(h]hierarchical-aggregationah ]h"]2.3. hierarchical aggregationah$]h&]uh1hhjhhhhhM*ubh)}(hhh](h)}(h 2.4. Rangeh]h 2.4. Range}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMHubh)}(h@Uclamp performance request has the range of 0 to 1024 inclusive.h]h@Uclamp performance request has the range of 0 to 1024 inclusive.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjhhubh)}(hFor cgroup interface percentage is used (that is 0 to 100 inclusive). Just like other cgroup interfaces, you can use 'max' instead of 100.h]hFor cgroup interface percentage is used (that is 0 to 100 inclusive). Just like other cgroup interfaces, you can use ‘max’ instead of 100.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjhhubjf)}(h.. _uclamp-interfaces:h]h}(h]h ]h"]h$]h&]jquclamp-interfacesuh1jehMOhjhhhhubeh}(h]rangeah ]h"] 2.4. rangeah$]h&]uh1hhjhhhhhMHubeh}(h]designah ]h"] 2. designah$]h&]uh1hhhhhhhhKwubh)}(hhh](h)}(h 3. Interfacesh]h 3. Interfaces}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhMRubh)}(hhh](h)}(h3.1. Per task interfaceh]h3.1. Per task interface}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj[hhhhhMUubh)}(h>sched_setattr() syscall was extended to accept two new fields:h]h>sched_setattr() syscall was extended to accept two new fields:}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMWhj[hhubj)}(hhh](j )}(hsched_util_min: requests the minimum performance point the system should run at when this task is running. Or lower performance bound.h]h)}(hsched_util_min: requests the minimum performance point the system should run at when this task is running. Or lower performance bound.h]hsched_util_min: requests the minimum performance point the system should run at when this task is running. Or lower performance bound.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMYhj}ubah}(h]h ]h"]h$]h&]uh1jhjzhhhhhNubj )}(hsched_util_max: requests the maximum performance point the system should run at when this task is running. Or upper performance bound. h]h)}(hsched_util_max: requests the maximum performance point the system should run at when this task is running. Or upper performance bound.h]hsched_util_max: requests the maximum performance point the system should run at when this task is running. Or upper performance bound.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM[hjubah}(h]h ]h"]h$]h&]uh1jhjzhhhhhNubeh}(h]h ]h"]h$]h&]jVjWuh1jhhhMYhj[hhubh)}(hLFor example, the following scenario have 40% to 80% utilization constraints:h]hLFor example, the following scenario have 40% to 80% utilization constraints:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hj[hhubj)}(hEattr->sched_util_min = 40% * 1024; attr->sched_util_max = 80% * 1024;h]hEattr->sched_util_min = 40% * 1024; attr->sched_util_max = 80% * 1024;}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMbhj[hhubh)}(hWhen task @p is running, **the scheduler should try its best to ensure it starts at 40% performance level**. If the task runs for a long enough time so that its actual utilization goes above 80%, the utilization, or performance level, will be capped.h](hWhen task @p is running, }(hjhhhNhNubj)}(hR**the scheduler should try its best to ensure it starts at 40% performance level**h]hNthe scheduler should try its best to ensure it starts at 40% performance level}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. If the task runs for a long enough time so that its actual utilization goes above 80%, the utilization, or performance level, will be capped.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMehj[hhubh)}(hPThe special value -1 is used to reset the uclamp settings to the system default.h]hPThe special value -1 is used to reset the uclamp settings to the system default.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMjhj[hhubh)}(hX9Note that resetting the uclamp value to system default using -1 is not the same as manually setting uclamp value to system default. This distinction is important because as we shall see in system interfaces, the default value for RT could be changed. SCHED_NORMAL/OTHER might gain similar knobs too in the future.h]hX9Note that resetting the uclamp value to system default using -1 is not the same as manually setting uclamp value to system default. This distinction is important because as we shall see in system interfaces, the default value for RT could be changed. SCHED_NORMAL/OTHER might gain similar knobs too in the future.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMmhj[hhubeh}(h]per-task-interfaceah ]h"]3.1. per task interfaceah$]h&]uh1hhjJhhhhhMUubh)}(hhh](h)}(h3.2. cgroup interfaceh]h3.2. cgroup interface}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMtubh)}(hAThere are two uclamp related values in the CPU cgroup controller:h]hAThere are two uclamp related values in the CPU cgroup controller:}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMvhjhhubj)}(hhh](j )}(hcpu.uclamp.minh]h)}(hj7h]hcpu.uclamp.min}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMxhj5ubah}(h]h ]h"]h$]h&]uh1jhj2hhhhhNubj )}(hcpu.uclamp.max h]h)}(hcpu.uclamp.maxh]hcpu.uclamp.max}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMyhjLubah}(h]h ]h"]h$]h&]uh1jhj2hhhhhNubeh}(h]h ]h"]h$]h&]jVjWuh1jhhhMxhjhhubh)}(h[When a task is attached to a CPU controller, its uclamp values will be impacted as follows:h]h[When a task is attached to a CPU controller, its uclamp values will be impacted as follows:}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM{hjhhubj)}(hhh](j )}(hXGcpu.uclamp.min is a protection as described in :ref:`section 3-3 of cgroup v2 documentation `. If a task uclamp_min value is lower than cpu.uclamp.min, then the task will inherit the cgroup cpu.uclamp.min value. In a cgroup hierarchy, effective cpu.uclamp.min is the max of (child, parent). h](h)}(hcpu.uclamp.min is a protection as described in :ref:`section 3-3 of cgroup v2 documentation `.h](h/cpu.uclamp.min is a protection as described in }(hjhhhNhNubh)}(hP:ref:`section 3-3 of cgroup v2 documentation `h]j2)}(hjh]h§ion 3-3 of cgroup v2 documentation}(hjhhhNhNubah}(h]h ](j=stdstd-refeh"]h$]h&]uh1j1hjubah}(h]h ]h"]h$]h&]refdocjJ refdomainjreftyperef refexplicitrefwarnjP cgroupv2-protections-distributoruh1hhhhM~hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM~hj{ubh)}(htIf a task uclamp_min value is lower than cpu.uclamp.min, then the task will inherit the cgroup cpu.uclamp.min value.h]htIf a task uclamp_min value is lower than cpu.uclamp.min, then the task will inherit the cgroup cpu.uclamp.min value.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj{ubh)}(hNIn a cgroup hierarchy, effective cpu.uclamp.min is the max of (child, parent).h]hNIn a cgroup hierarchy, effective cpu.uclamp.min is the max of (child, parent).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj{ubeh}(h]h ]h"]h$]h&]uh1jhjxhhhhhNubj )}(hX>cpu.uclamp.max is a limit as described in :ref:`section 3-2 of cgroup v2 documentation `. If a task uclamp_max value is higher than cpu.uclamp.max, then the task will inherit the cgroup cpu.uclamp.max value. In a cgroup hierarchy, effective cpu.uclamp.max is the min of (child, parent). h](h)}(hvcpu.uclamp.max is a limit as described in :ref:`section 3-2 of cgroup v2 documentation `.h](h*cpu.uclamp.max is a limit as described in }(hjhhhNhNubh)}(hK:ref:`section 3-2 of cgroup v2 documentation `h]j2)}(hjh]h§ion 3-2 of cgroup v2 documentation}(hjhhhNhNubah}(h]h ](j=stdstd-refeh"]h$]h&]uh1j1hjubah}(h]h ]h"]h$]h&]refdocjJ refdomainjreftyperef refexplicitrefwarnjPcgroupv2-limits-distributoruh1hhhhMhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(huIf a task uclamp_max value is higher than cpu.uclamp.max, then the task will inherit the cgroup cpu.uclamp.max value.h]huIf a task uclamp_max value is higher than cpu.uclamp.max, then the task will inherit the cgroup cpu.uclamp.max value.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(hNIn a cgroup hierarchy, effective cpu.uclamp.max is the min of (child, parent).h]hNIn a cgroup hierarchy, effective cpu.uclamp.max is the min of (child, parent).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubeh}(h]h ]h"]h$]h&]uh1jhjxhhhhhNubeh}(h]h ]h"]h$]h&]jVjWuh1jhhhM~hjhhubh)}(h(For example, given following parameters:h]h(For example, given following parameters:}(hj1 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hX=p0->uclamp[UCLAMP_MIN] = // system default; p0->uclamp[UCLAMP_MAX] = // system default; p1->uclamp[UCLAMP_MIN] = 40% * 1024; p1->uclamp[UCLAMP_MAX] = 50% * 1024; cgroup0->cpu.uclamp.min = 20% * 1024; cgroup0->cpu.uclamp.max = 60% * 1024; cgroup1->cpu.uclamp.min = 60% * 1024; cgroup1->cpu.uclamp.max = 100% * 1024;h]hX=p0->uclamp[UCLAMP_MIN] = // system default; p0->uclamp[UCLAMP_MAX] = // system default; p1->uclamp[UCLAMP_MIN] = 40% * 1024; p1->uclamp[UCLAMP_MAX] = 50% * 1024; cgroup0->cpu.uclamp.min = 20% * 1024; cgroup0->cpu.uclamp.max = 60% * 1024; cgroup1->cpu.uclamp.min = 60% * 1024; cgroup1->cpu.uclamp.max = 100% * 1024;}hj? sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubh)}(h:when p0 and p1 are attached to cgroup0, the values become:h]h:when p0 and p1 are attached to cgroup0, the values become:}(hjM hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hp0->uclamp[UCLAMP_MIN] = cgroup0->cpu.uclamp.min = 20% * 1024; p0->uclamp[UCLAMP_MAX] = cgroup0->cpu.uclamp.max = 60% * 1024; p1->uclamp[UCLAMP_MIN] = 40% * 1024; // intact p1->uclamp[UCLAMP_MAX] = 50% * 1024; // intacth]hp0->uclamp[UCLAMP_MIN] = cgroup0->cpu.uclamp.min = 20% * 1024; p0->uclamp[UCLAMP_MAX] = cgroup0->cpu.uclamp.max = 60% * 1024; p1->uclamp[UCLAMP_MIN] = 40% * 1024; // intact p1->uclamp[UCLAMP_MAX] = 50% * 1024; // intact}hj[ sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubh)}(h=when p0 and p1 are attached to cgroup1, these instead become:h]h=when p0 and p1 are attached to cgroup1, these instead become:}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hp0->uclamp[UCLAMP_MIN] = cgroup1->cpu.uclamp.min = 60% * 1024; p0->uclamp[UCLAMP_MAX] = cgroup1->cpu.uclamp.max = 100% * 1024; p1->uclamp[UCLAMP_MIN] = cgroup1->cpu.uclamp.min = 60% * 1024; p1->uclamp[UCLAMP_MAX] = 50% * 1024; // intacth]hp0->uclamp[UCLAMP_MIN] = cgroup1->cpu.uclamp.min = 60% * 1024; p0->uclamp[UCLAMP_MAX] = cgroup1->cpu.uclamp.max = 100% * 1024; p1->uclamp[UCLAMP_MIN] = cgroup1->cpu.uclamp.min = 60% * 1024; p1->uclamp[UCLAMP_MAX] = 50% * 1024; // intact}hjw sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubh)}(h{Note that cgroup interfaces allows cpu.uclamp.max value to be lower than cpu.uclamp.min. Other interfaces don't allow that.h]h}Note that cgroup interfaces allows cpu.uclamp.max value to be lower than cpu.uclamp.min. Other interfaces don’t allow that.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]cgroup-interfaceah ]h"]3.2. cgroup interfaceah$]h&]uh1hhjJhhhhhMtubh)}(hhh]h)}(h3.3. System interfaceh]h3.3. System interface}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubah}(h]system-interfaceah ]h"]3.3. system interfaceah$]h&]uh1hhjJhhhhhMubh)}(hhh](h)}(h3.3.1 sched_util_clamp_minh]h3.3.1 sched_util_clamp_min}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hX$System wide limit of allowed UCLAMP_MIN range. By default it is set to 1024, which means that permitted effective UCLAMP_MIN range for tasks is [0:1024]. By changing it to 512 for example the range reduces to [0:512]. This is useful to restrict how much boosting tasks are allowed to acquire.h]hX$System wide limit of allowed UCLAMP_MIN range. By default it is set to 1024, which means that permitted effective UCLAMP_MIN range for tasks is [0:1024]. By changing it to 512 for example the range reduces to [0:512]. This is useful to restrict how much boosting tasks are allowed to acquire.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hRequests from tasks to go above this knob value will still succeed, but they won't be satisfied until it is more than p->uclamp[UCLAMP_MIN].h]hRequests from tasks to go above this knob value will still succeed, but they won’t be satisfied until it is more than p->uclamp[UCLAMP_MIN].}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h@The value must be smaller than or equal to sched_util_clamp_max.h]h@The value must be smaller than or equal to sched_util_clamp_max.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]sched-util-clamp-minah ]h"]3.3.1 sched_util_clamp_minah$]h&]uh1hhjJhhhhhMubh)}(hhh](h)}(h3.3.2 sched_util_clamp_maxh]h3.3.2 sched_util_clamp_max}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hSystem wide limit of allowed UCLAMP_MAX range. By default it is set to 1024, which means that permitted effective UCLAMP_MAX range for tasks is [0:1024].h]hSystem wide limit of allowed UCLAMP_MAX range. By default it is set to 1024, which means that permitted effective UCLAMP_MAX range for tasks is [0:1024].}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hBy changing it to 512 for example the effective allowed range reduces to [0:512]. This means is that no task can run above 512, which implies that all rqs are restricted too. IOW, the whole system is capped to half its performance capacity.h]hBy changing it to 512 for example the effective allowed range reduces to [0:512]. This means is that no task can run above 512, which implies that all rqs are restricted too. IOW, the whole system is capped to half its performance capacity.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hXThis is useful to restrict the overall maximum performance point of the system. For example, it can be handy to limit performance when running low on battery or when the system wants to limit access to more energy hungry performance levels when it's in idle state or screen is off.h]hXThis is useful to restrict the overall maximum performance point of the system. For example, it can be handy to limit performance when running low on battery or when the system wants to limit access to more energy hungry performance levels when it’s in idle state or screen is off.}(hj$ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hRequests from tasks to go above this knob value will still succeed, but they won't be satisfied until it is more than p->uclamp[UCLAMP_MAX].h]hRequests from tasks to go above this knob value will still succeed, but they won’t be satisfied until it is more than p->uclamp[UCLAMP_MAX].}(hj2 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h@The value must be greater than or equal to sched_util_clamp_min.h]h@The value must be greater than or equal to sched_util_clamp_min.}(hj@ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubjf)}(h.. _uclamp-default-values:h]h}(h]h ]h"]h$]h&]jquclamp-default-valuesuh1jehMhj hhhhubeh}(h]sched-util-clamp-maxah ]h"]3.3.2 sched_util_clamp_maxah$]h&]uh1hhjJhhhhhMubh)}(hhh](h)}(h3.4. Default valuesh]h3.4. Default values}(hjd hhhNhNubah}(h]h ]h"]h$]h&]uh1hhja hhhhhMubh)}(hABy default all SCHED_NORMAL/SCHED_OTHER tasks are initialized to:h]hABy default all SCHED_NORMAL/SCHED_OTHER tasks are initialized to:}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhja hhubj)}(h@p_fair->uclamp[UCLAMP_MIN] = 0 p_fair->uclamp[UCLAMP_MAX] = 1024h]h@p_fair->uclamp[UCLAMP_MIN] = 0 p_fair->uclamp[UCLAMP_MAX] = 1024}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhja hhubh)}(hThat is, by default they're boosted to run at the maximum performance point of changed at boot or runtime. No argument was made yet as to why we should provide this, but can be added in the future.h]hThat is, by default they’re boosted to run at the maximum performance point of changed at boot or runtime. No argument was made yet as to why we should provide this, but can be added in the future.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhja hhubh)}(hFor SCHED_FIFO/SCHED_RR tasks:h]hFor SCHED_FIFO/SCHED_RR tasks:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhja hhubj)}(h?p_rt->uclamp[UCLAMP_MIN] = 1024 p_rt->uclamp[UCLAMP_MAX] = 1024h]h?p_rt->uclamp[UCLAMP_MIN] = 1024 p_rt->uclamp[UCLAMP_MAX] = 1024}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhja hhubh)}(hThat is by default they're boosted to run at the maximum performance point of the system which retains the historical behavior of the RT tasks.h]hThat is by default they’re boosted to run at the maximum performance point of the system which retains the historical behavior of the RT tasks.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhja hhubh)}(hcRT tasks default uclamp_min value can be modified at boot or runtime via sysctl. See below section.h]hcRT tasks default uclamp_min value can be modified at boot or runtime via sysctl. See below section.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhja hhubjf)}(h$.. _sched-util-clamp-min-rt-default:h]h}(h]h ]h"]h$]h&]jqsched-util-clamp-min-rt-defaultuh1jehMhja hhhhubeh}(h](default-valuesjX eh ]h"](3.4. default valuesuclamp-default-valueseh$]h&]uh1hhjJhhhhhMj}j jN sj}jX jN subh)}(hhh](h)}(h%3.4.1 sched_util_clamp_min_rt_defaulth]h%3.4.1 sched_util_clamp_min_rt_default}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hXRunning RT tasks at maximum performance point is expensive on battery powered devices and not necessary. To allow system developer to offer good performance guarantees for these tasks without pushing it all the way to maximum performance point, this sysctl knob allows tuning the best boost value to address the system requirement without burning power running at maximum performance point all the time.h]hXRunning RT tasks at maximum performance point is expensive on battery powered devices and not necessary. To allow system developer to offer good performance guarantees for these tasks without pushing it all the way to maximum performance point, this sysctl knob allows tuning the best boost value to address the system requirement without burning power running at maximum performance point all the time.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hApplication developer are encouraged to use the per task util clamp interface to ensure they are performance and power aware. Ideally this knob should be set to 0 by system designers and leave the task of managing performance requirements to the apps.h]hApplication developer are encouraged to use the per task util clamp interface to ensure they are performance and power aware. Ideally this knob should be set to 0 by system designers and leave the task of managing performance requirements to the apps.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h](j id1eh ]h"](%3.4.1 sched_util_clamp_min_rt_defaultsched-util-clamp-min-rt-defaulteh$]h&]uh1hhjJhhhhhMj}j j sj}j j subeh}(h]( interfacesj9eh ]h"]( 3. interfacesuclamp-interfaceseh$]h&]uh1hhhhhhhhMRj}j( j/sj}j9j/subh)}(hhh](h)}(h4. How to use util clamph]h4. How to use util clamp}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj- hhhhhM ubh)}(hX(Util clamp promotes the concept of user space assisted power and performance management. At the scheduler level there is no info required to make the best decision. However, with util clamp user space can hint to the scheduler to make better decision about task placement and frequency selection.h]hX(Util clamp promotes the concept of user space assisted power and performance management. At the scheduler level there is no info required to make the best decision. However, with util clamp user space can hint to the scheduler to make better decision about task placement and frequency selection.}(hj> hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj- hhubh)}(hX Best results are achieved by not making any assumptions about the system the application is running on and to use it in conjunction with a feedback loop to dynamically monitor and adjust. Ultimately this will allow for a better user experience at a better perf/watt.h]hX Best results are achieved by not making any assumptions about the system the application is running on and to use it in conjunction with a feedback loop to dynamically monitor and adjust. Ultimately this will allow for a better user experience at a better perf/watt.}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj- hhubh)}(hXFor some systems and use cases, static setup will help to achieve good results. Portability will be a problem in this case. How much work one can do at 100, 200 or 1024 is different for each system. Unless there's a specific target system, static setup should be avoided.h]hXFor some systems and use cases, static setup will help to achieve good results. Portability will be a problem in this case. How much work one can do at 100, 200 or 1024 is different for each system. Unless there’s a specific target system, static setup should be avoided.}(hjZ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj- hhubh)}(hThere are enough possibilities to create a whole framework based on util clamp or self contained app that makes use of it directly.h]hThere are enough possibilities to create a whole framework based on util clamp or self contained app that makes use of it directly.}(hjh hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj- hhubh)}(hhh](h)}(h54.1. Boost important and DVFS-latency-sensitive tasks^h]h54.1. Boost important and DVFS-latency-sensitive tasks}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjv hhhhhM ubh)}(hXcA GUI task might not be busy to warrant driving the frequency high when it wakes up. However, it requires to finish its work within a specific time window to deliver the desired user experience. The right frequency it requires at wakeup will be system dependent. On some underpowered systems it will be high, on other overpowered ones it will be low or 0.h]hXcA GUI task might not be busy to warrant driving the frequency high when it wakes up. However, it requires to finish its work within a specific time window to deliver the desired user experience. The right frequency it requires at wakeup will be system dependent. On some underpowered systems it will be high, on other overpowered ones it will be low or 0.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hjv hhubh)}(hX6This task can increase its UCLAMP_MIN value every time it misses the deadline to ensure on next wake up it runs at a higher performance point. It should try to approach the lowest UCLAMP_MIN value that allows to meet its deadline on any particular system to achieve the best possible perf/watt for that system.h]hX6This task can increase its UCLAMP_MIN value every time it misses the deadline to ensure on next wake up it runs at a higher performance point. It should try to approach the lowest UCLAMP_MIN value that allows to meet its deadline on any particular system to achieve the best possible perf/watt for that system.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hjv hhubh)}(hUOn heterogeneous systems, it might be important for this task to run on a faster CPU.h]hUOn heterogeneous systems, it might be important for this task to run on a faster CPU.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hjv hhubh)}(h**Generally it is advised to perceive the input as performance level or point which will imply both task placement and frequency selection**.h](j)}(h**Generally it is advised to perceive the input as performance level or point which will imply both task placement and frequency selection**h]hGenerally it is advised to perceive the input as performance level or point which will imply both task placement and frequency selection}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM0hjv hhubeh}(h]0boost-important-and-dvfs-latency-sensitive-tasksah ]h"]54.1. boost important and dvfs-latency-sensitive tasksah$]h&]uh1hhj- hhhhhM ubh)}(hhh](h)}(h4.2. Cap background tasksh]h4.2. Cap background tasks}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM4ubh)}(hLike explained for Android case in the introduction. Any app can lower UCLAMP_MAX for some background tasks that don't care about performance but could end up being busy and consume unnecessary system resources on the system.h]hLike explained for Android case in the introduction. Any app can lower UCLAMP_MAX for some background tasks that don’t care about performance but could end up being busy and consume unnecessary system resources on the system.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hj hhubeh}(h]cap-background-tasksah ]h"]4.2. cap background tasksah$]h&]uh1hhj- hhhhhM4ubh)}(hhh](h)}(h4.3. Powersave modeh]h4.3. Powersave mode}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM;ubh)}(hsched_util_clamp_max system wide interface can be used to limit all tasks from operating at the higher performance points which are usually energy inefficient.h]hsched_util_clamp_max system wide interface can be used to limit all tasks from operating at the higher performance points which are usually energy inefficient.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM=hj hhubh)}(hThis is not unique to uclamp as one can achieve the same by reducing max frequency of the cpufreq governor. It can be considered a more convenient alternative interface.h]hThis is not unique to uclamp as one can achieve the same by reducing max frequency of the cpufreq governor. It can be considered a more convenient alternative interface.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj hhubeh}(h]powersave-modeah ]h"]4.3. powersave modeah$]h&]uh1hhj- hhhhhM;ubh)}(hhh](h)}(h$4.4. Per-app performance restrictionh]h$4.4. Per-app performance restriction}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj1 hhhhhMFubh)}(hMiddleware/Utility can provide the user an option to set UCLAMP_MIN/MAX for an app every time it is executed to guarantee a minimum performance point and/or limit it from draining system power at the cost of reduced performance for these apps.h]hMiddleware/Utility can provide the user an option to set UCLAMP_MIN/MAX for an app every time it is executed to guarantee a minimum performance point and/or limit it from draining system power at the cost of reduced performance for these apps.}(hjB hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhj1 hhubh)}(hIf you want to prevent your laptop from heating up while on the go from compiling the kernel and happy to sacrifice performance to save power, but still would like to keep your browser performance intact, uclamp makes it possible.h]hIf you want to prevent your laptop from heating up while on the go from compiling the kernel and happy to sacrifice performance to save power, but still would like to keep your browser performance intact, uclamp makes it possible.}(hjP hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMMhj1 hhubeh}(h]per-app-performance-restrictionah ]h"]$4.4. per-app performance restrictionah$]h&]uh1hhj- hhhhhMFubeh}(h]how-to-use-util-clampah ]h"]4. how to use util clampah$]h&]uh1hhhhhhhhM ubh)}(hhh](h)}(h5. Limitationsh]h5. Limitations}(hjq hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjn hhhhhMSubjf)}(h.. _uclamp-capping-fail:h]h}(h]h ]h"]h$]h&]jquclamp-capping-failuh1jehMUhjn hhhhubh)}(hhh](h)}(hE5.1. Capping frequency with uclamp_max fails under certain conditionsh]hE5.1. Capping frequency with uclamp_max fails under certain conditions}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMXubh)}(h#If task p0 is capped to run at 512:h]h#If task p0 is capped to run at 512:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhj hhubj)}(hp0->uclamp[UCLAMP_MAX] = 512h]hp0->uclamp[UCLAMP_MAX] = 512}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhM^hj hhubh)}(hKand it shares the rq with p1 which is free to run at any performance point:h]hKand it shares the rq with p1 which is free to run at any performance point:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM`hj hhubj)}(hp1->uclamp[UCLAMP_MAX] = 1024h]hp1->uclamp[UCLAMP_MAX] = 1024}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMdhj hhubh)}(hRthen due to max aggregation the rq will be allowed to reach max performance point:h]hRthen due to max aggregation the rq will be allowed to reach max performance point:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMfhj hhubj)}(h.rq->uclamp[UCLAMP_MAX] = max(512, 1024) = 1024h]h.rq->uclamp[UCLAMP_MAX] = max(512, 1024) = 1024}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMkhj hhubh)}(hAssuming both p0 and p1 have UCLAMP_MIN = 0, then the frequency selection for the rq will depend on the actual utilization value of the tasks.h]hAssuming both p0 and p1 have UCLAMP_MIN = 0, then the frequency selection for the rq will depend on the actual utilization value of the tasks.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMmhj hhubh)}(hXIf p1 is a small task but p0 is a CPU intensive task, then due to the fact that both are running at the same rq, p1 will cause the frequency capping to be left from the rq although p1, which is allowed to run at any performance point, doesn't actually need to run at that frequency.h]hXIf p1 is a small task but p0 is a CPU intensive task, then due to the fact that both are running at the same rq, p1 will cause the frequency capping to be left from the rq although p1, which is allowed to run at any performance point, doesn’t actually need to run at that frequency.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMphj hhubeh}(h](@capping-frequency-with-uclamp-max-fails-under-certain-conditionsj eh ]h"](E5.1. capping frequency with uclamp_max fails under certain conditionsuclamp-capping-faileh$]h&]uh1hhjn hhhhhMXj}j j sj}j j subh)}(hhh](h)}(h05.2. UCLAMP_MAX can break PELT (util_avg) signalh]h05.2. UCLAMP_MAX can break PELT (util_avg) signal}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMvubh)}(hXUPELT assumes that frequency will always increase as the signals grow to ensure there's always some idle time on the CPU. But with UCLAMP_MAX, this frequency increase will be prevented which can lead to no idle time in some circumstances. When there's no idle time, a task will stuck in a busy loop, which would result in util_avg being 1024.h]hXYPELT assumes that frequency will always increase as the signals grow to ensure there’s always some idle time on the CPU. But with UCLAMP_MAX, this frequency increase will be prevented which can lead to no idle time in some circumstances. When there’s no idle time, a task will stuck in a busy loop, which would result in util_avg being 1024.}(hj' hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMxhj hhubh)}(hCombing with issue described below, this can lead to unwanted frequency spikes when severely capped tasks share the rq with a small non capped task.h]hCombing with issue described below, this can lead to unwanted frequency spikes when severely capped tasks share the rq with a small non capped task.}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM~hj hhubh)}(h$As an example if task p, which have:h]h$As an example if task p, which have:}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h-p0->util_avg = 300 p0->uclamp[UCLAMP_MAX] = 0h]h-p0->util_avg = 300 p0->uclamp[UCLAMP_MAX] = 0}hjQ sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(hwakes up on an idle CPU, then it will run at min frequency (Fmin) this CPU is capable of. The max CPU frequency (Fmax) matters here as well, since it designates the shortest computational time to finish the task's work on this CPU.h]hwakes up on an idle CPU, then it will run at min frequency (Fmin) this CPU is capable of. The max CPU frequency (Fmax) matters here as well, since it designates the shortest computational time to finish the task’s work on this CPU.}(hj_ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hrq->uclamp[UCLAMP_MAX] = 0h]hrq->uclamp[UCLAMP_MAX] = 0}hjm sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(h;If the ratio of Fmax/Fmin is 3, then maximum value will be:h]h;If the ratio of Fmax/Fmin is 3, then maximum value will be:}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h300 * (Fmax/Fmin) = 900h]h300 * (Fmax/Fmin) = 900}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(hX which indicates the CPU will still see idle time since 900 is < 1024. The _actual_ util_avg will not be 900 though, but somewhere between 300 and 900. As long as there's idle time, p->util_avg updates will be off by a some margin, but not proportional to Fmax/Fmin.h]hX which indicates the CPU will still see idle time since 900 is < 1024. The _actual_ util_avg will not be 900 though, but somewhere between 300 and 900. As long as there’s idle time, p->util_avg updates will be off by a some margin, but not proportional to Fmax/Fmin.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h p0->util_avg = 300 + small_errorh]h p0->util_avg = 300 + small_error}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(h>Now if the ratio of Fmax/Fmin is 4, the maximum value becomes:h]h>Now if the ratio of Fmax/Fmin is 4, the maximum value becomes:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h300 * (Fmax/Fmin) = 1200h]h300 * (Fmax/Fmin) = 1200}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(hwhich is higher than 1024 and indicates that the CPU has no idle time. When this happens, then the _actual_ util_avg will become:h]hwhich is higher than 1024 and indicates that the CPU has no idle time. When this happens, then the _actual_ util_avg will become:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hp0->util_avg = 1024h]hp0->util_avg = 1024}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(h,If task p1 wakes up on this CPU, which have:h]h,If task p1 wakes up on this CPU, which have:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h0p1->util_avg = 200 p1->uclamp[UCLAMP_MAX] = 1024h]h0p1->util_avg = 200 p1->uclamp[UCLAMP_MAX] = 1024}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(hthen the effective UCLAMP_MAX for the CPU will be 1024 according to max aggregation rule. But since the capped p0 task was running and throttled severely, then the rq->util_avg will be:h]hthen the effective UCLAMP_MAX for the CPU will be 1024 according to max aggregation rule. But since the capped p0 task was running and throttled severely, then the rq->util_avg will be:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hYp0->util_avg = 1024 p1->util_avg = 200 rq->util_avg = 1024 rq->uclamp[UCLAMP_MAX] = 1024h]hYp0->util_avg = 1024 p1->util_avg = 200 rq->util_avg = 1024 rq->uclamp[UCLAMP_MAX] = 1024}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(hKHence lead to a frequency spike since if p0 wasn't throttled we should get:h]hMHence lead to a frequency spike since if p0 wasn’t throttled we should get:}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h9p0->util_avg = 300 p1->util_avg = 200 rq->util_avg = 500h]h9p0->util_avg = 300 p1->util_avg = 200 rq->util_avg = 500}hj1sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(hNand run somewhere near mid performance point of that CPU, not the Fmax we get.h]hNand run somewhere near mid performance point of that CPU, not the Fmax we get.}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h])uclamp-max-can-break-pelt-util-avg-signalah ]h"]05.2. uclamp_max can break pelt (util_avg) signalah$]h&]uh1hhjn hhhhhMvubh)}(hhh](h)}(h#5.3. Schedutil response time issuesh]h#5.3. Schedutil response time issues}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjUhhhhhMubh)}(h schedutil has three limitations:h]h schedutil has three limitations:}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjUhhubj)}(hX_1. Hardware takes non-zero time to respond to any frequency change request. On some platforms can be in the order of few ms. 2. Non fast-switch systems require a worker deadline thread to wake up and perform the frequency change, which adds measurable overhead. 3. schedutil rate_limit_us drops any requests during this rate_limit_us window. h]j)}(hhh](j )}(hyHardware takes non-zero time to respond to any frequency change request. On some platforms can be in the order of few ms.h]h)}(hyHardware takes non-zero time to respond to any frequency change request. On some platforms can be in the order of few ms.h]hyHardware takes non-zero time to respond to any frequency change request. On some platforms can be in the order of few ms.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj{ubah}(h]h ]h"]h$]h&]uh1jhjxubj )}(hNon fast-switch systems require a worker deadline thread to wake up and perform the frequency change, which adds measurable overhead.h]h)}(hNon fast-switch systems require a worker deadline thread to wake up and perform the frequency change, which adds measurable overhead.h]hNon fast-switch systems require a worker deadline thread to wake up and perform the frequency change, which adds measurable overhead.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjxubj )}(hMschedutil rate_limit_us drops any requests during this rate_limit_us window. h]h)}(hLschedutil rate_limit_us drops any requests during this rate_limit_us window.h]hLschedutil rate_limit_us drops any requests during this rate_limit_us window.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjxubeh}(h]h ]h"]h$]h&]jjjhjjuh1jhjtubah}(h]h ]h"]h$]h&]uh1jhhhMhjUhhubh)}(hIf a relatively small task is doing critical job and requires a certain performance point when it wakes up and starts running, then all these limitations will prevent it from getting what it wants in the time scale it expects.h]hIf a relatively small task is doing critical job and requires a certain performance point when it wakes up and starts running, then all these limitations will prevent it from getting what it wants in the time scale it expects.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjUhhubh)}(hThis limitation is not only impactful when using uclamp, but will be more prevalent as we no longer gradually ramp up or down. We could easily be jumping between frequencies depending on the order tasks wake up, and their respective uclamp values.h]hThis limitation is not only impactful when using uclamp, but will be more prevalent as we no longer gradually ramp up or down. We could easily be jumping between frequencies depending on the order tasks wake up, and their respective uclamp values.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjUhhubh)}(hSWe regard that as a limitation of the capabilities of the underlying system itself.h]hSWe regard that as a limitation of the capabilities of the underlying system itself.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjUhhubh)}(hThere is room to improve the behavior of schedutil rate_limit_us, but not much to be done for 1 or 2. They are considered hard limitations of the system.h]hThere is room to improve the behavior of schedutil rate_limit_us, but not much to be done for 1 or 2. They are considered hard limitations of the system.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjUhhubeh}(h]schedutil-response-time-issuesah ]h"]#5.3. schedutil response time issuesah$]h&]uh1hhjn hhhhhMubeh}(h] limitationsah ]h"]5. limitationsah$]h&]uh1hhhhhhhhMSubeh}(h]utilization-clampingah ]h"]utilization clampingah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjBerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}(jr]jgaj9]j/ajX ]jN aj ]j aj ]j aunameids}(jjjjjGjDjjrjjj/j,jjj?j<j( j9j' j$ jj j j j j j j j^ j[ j jX j j j j j j jk jh j j j j j. j+ jc j` jjj j j j jRjOj j u nametypes}(jjjGjjj/jj?j( j' jj j j j^ j j j j jk j j j. jc jj j jRj uh}(jhjhjDjjrjsjjsj,jjj2j<jj9jJj$ jJj j[j jj j j j j[ j jX ja j ja j j j j jh j- j jv j j j+ j j` j1 jjn j j j j jOj j jUu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jPKsRparse_messages]transform_messages](hsystem_message)}(hhh]h)}(hhh]h4Hyperlink target "uclamp-buckets" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKuh1jubj)}(hhh]h)}(hhh]h7Hyperlink target "uclamp-interfaces" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejsourcehlineMOuh1jubj)}(hhh]h)}(hhh]h;Hyperlink target "uclamp-default-values" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejsourcehlineMuh1jubj)}(hhh]h)}(hhh]hEHyperlink target "sched-util-clamp-min-rt-default" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejsourcehlineMuh1jubj)}(hhh]h)}(hhh]h9Hyperlink target "uclamp-capping-fail" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejsourcehlineMUuh1jube transformerN include_log] decorationNhhub.