负载跟踪之（四）：uclamp

The Linux scheduler tracks a "utilization" signal for each scheduling entity

(SE), e.g. tasks, to know how much CPU time they use. This signal allows the

scheduler to know how "big" a task is and, in principle, it can support

advanced task placement strategies by selecting the best CPU to run a task.

Some of these strategies are represented by the Energy Aware Scheduler [1].

When the schedutil cpufreq governor is in use, the utilization signal allows

the Linux scheduler also to drive frequency selection. The CPU utilization

signal, which represents the aggregated utilization of tasks scheduled on that

CPU, is used to select the frequency which best fits the workload generated by

the tasks.

However, the current translation of utilization values into a frequency

selection is pretty simple: we just go to max for RT tasks or to the minimum

frequency which can accommodate the utilization of DL+FAIR tasks.

Instead, utilization is of limited usage for tasks placement since its value

alone is not enough to properly describe what the _expected_ power/performance

behaviors of each task really is from a userspace standpoint.

In general, for both RT and FAIR tasks we can aim at better tasks placement and

frequency selection policies if we take hints coming from user-space into

consideration.

Utilization clamping is a mechanism which allows to "clamp" (i.e. filter) the

utilization generated by RT and FAIR tasks within a range defined from

user-space. The clamped utilization value can then be used, for example, to

enforce a minimum and/or maximum frequency depending on which tasks are

currently active on a CPU.

The main use-cases for utilization clamping are:

- boosting: better interactive response for small tasks which

are affecting the user experience.

Consider for example the case of a small control thread for an external

accelerator (e.g. GPU, DSP, other devices). In this case, from the task

utilization the scheduler does not have a complete view of what the task

requirements are and, if it's a small utilization task, it keep selecting a

more energy efficient CPU, with smaller capacity and lower frequency, thus

affecting the overall time required to complete task activations.

- capping: increase energy efficiency for background tasks not directly

affecting the user experience.

Since running on a lower capacity CPU at a lower frequency is in general

more energy efficient, when the completion time is not a main goal, then

capping the utilization considered for certain (maybe big) tasks can have

positive effects, both on energy consumption and thermal headroom.

Moreover, this feature allows also to make RT tasks more energy

friendly on mobile systems, where running them on high capacity CPUs and at

the maximum frequency is not strictly required.

From these two use-cases, it's worth to notice that frequency selection

biasing, introduced by patches 9 and 10 of this series, is just one possible

usage of utilization clamping. Another compelling extension of utilization

clamping is in helping the scheduler on tasks placement decisions.

Utilization is (also) a task specific property which is used by the scheduler

to know how much CPU bandwidth a task requires, at least as long as there is

idle time.

Thus, the utilization clamp values, defined either per-task or per-taskgroup,

can be used to represent tasks to the scheduler as being bigger (or smaller)

than what they really are.

Utilization clamping thus ultimately enables interesting additional

optimizations, especially on asymmetric capacity systems like Arm

big.LITTLE and DynamIQ CPUs, where:

- boosting: small/foreground tasks are preferably scheduled on

higher-capacity CPUs where, despite being less energy efficient, they are

expected to complete faster.

- capping: big/background tasks are preferably scheduled on low-capacity CPUs

where, being more energy efficient, they can still run but save power and

thermal headroom for more important tasks.

This additional usage of utilization clamping is not presented in this series

but it's an integral part of the EAS feature set, where [1] is one of its main

components. A solution similar to utilization clamping, namely SchedTune, is

already used on Android kernels to bias both 'frequency selection' and 'task

placement'.

This series provides the foundation bits to add similar features to mainline

while focusing, for the time being, just on schedutil integration.

[1] https://lore.kernel.org/lkml/20181016101513.26919-1-quentin.perret@arm.com/

Tasks without a user-defined clamp value are considered not clamped

and by default their utilization can have any value in the

[0..SCHED_CAPACITY_SCALE] range.

Tasks with a user-defined clamp value are allowed to request any value

in that range, and the required clamp is unconditionally enforced.

However, a "System Management Software" could be interested in limiting

the range of clamp values allowed for all tasks.

Add a privileged interface to define a system default configuration via:

/proc/sys/kernel/sched_uclamp_util_{min,max}

which works as an unconditional clamp range restriction for all tasks.

With the default configuration, the full SCHED_CAPACITY_SCALE range of

values is allowed for each clamp index. Otherwise, the task-specific

clamp is capped by the corresponding system default value.

Do that by tracking, for each task, the "effective" clamp value and

bucket the task has been refcounted in at enqueue time. This

allows to lazy aggregate "requested" and "system default" values at

enqueue time and simplifies refcounting updates at dequeue time.

The cached bucket ids are used to avoid (relatively) more expensive

integer divisions every time a task is enqueued.

An active flag is used to report when the "effective" value is valid and

thus the task is actually refcounted in the corresponding rq's bucket.

a) 设置uclamp_default[]，这是system维度的uclamp值，所有uclamp值必须小于该值

b) 设置根组的root_task_group->uclamp_req[]值

/proc/sys/kernel/sched_util_clamp_min

/proc/sys/kernel/sched_util_clamp_max

a) 设置到系统中所有rt线程的p->uclamp_req[UCLAMP_MIN]

/proc/sys/kernel/sched_util_clamp_min_rt_default

#ifdef CONFIG_UCLAMP_TASK

    {

        .procname    = "sched_util_clamp_min",

        .data        = &sysctl_sched_uclamp_util_min,

        .maxlen        = sizeof(unsigned int),

        .mode        = 0644,

        .proc_handler    = sysctl_sched_uclamp_handler,

    },

    {

        .procname    = "sched_util_clamp_max",

        .data        = &sysctl_sched_uclamp_util_max,

        .maxlen        = sizeof(unsigned int),

        .mode        = 0644,

        .proc_handler    = sysctl_sched_uclamp_handler,

    },

    {

        .procname    = "sched_util_clamp_min_rt_default",

        .data        = &sysctl_sched_uclamp_util_min_rt_default,

        .maxlen        = sizeof(unsigned int),

        .mode        = 0644,

        .proc_handler    = sysctl_sched_uclamp_handler,

    },

#endif

/* Max allowed minimum utilization */

//所有task的uclamp_min都不能超过这个值

unsigned int sysctl_sched_uclamp_util_min = SCHED_CAPACITY_SCALE;

/* Max allowed maximum utilization */

unsigned int sysctl_sched_uclamp_util_max = SCHED_CAPACITY_SCALE;

/*

* By default RT tasks run at the maximum performance point/capacity of the

* system. Uclamp enforces this by always setting UCLAMP_MIN of RT tasks to

* SCHED_CAPACITY_SCALE.

*

* This knob allows admins to change the default behavior when uclamp is being

* used. In battery powered devices, particularly, running at the maximum

* capacity and frequency will increase energy consumption and shorten the

* battery life.

*

* This knob only affects RT tasks that their uclamp_se->user_defined == false.

*

* This knob will not override the system default sched_util_clamp_min defined

* above.

*/

//控制系统中所有rt任务的最小uclamp值

unsigned int sysctl_sched_uclamp_util_min_rt_default = SCHED_CAPACITY_SCALE;

/* All clamps are required to be less or equal than these values */

//system维度的uclamp值，所有uclamp，不管是uclamp_min还是uclamp_max，都必须小于该值

static struct uclamp_se uclamp_default[UCLAMP_CNT];

int sysctl_sched_uclamp_handler(

            struct ctl_table *table,

            int write,

            void *buffer,

            size_t *lenp,

            loff_t *ppos)

{

    bool update_root_tg = false;

    int old_min, old_max, old_min_rt;

    int result;

    mutex_lock(&uclamp_mutex);

    //1.先记录旧的值

    old_min = sysctl_sched_uclamp_util_min;

    old_max = sysctl_sched_uclamp_util_max;

    old_min_rt = sysctl_sched_uclamp_util_min_rt_default;

    //2.下面接口返回后，上面的三个全局变量就已经被用户空间修改了

    result = proc_dointvec(table, write, buffer, lenp, ppos);

    if (result)

        goto undo;

    if (!write)

        goto done;

    //3.检查用户空间设置的值是否合理，不合理的话则还是使用旧的值

    if (sysctl_sched_uclamp_util_min > sysctl_sched_uclamp_util_max ||

     sysctl_sched_uclamp_util_max > SCHED_CAPACITY_SCALE ||

     sysctl_sched_uclamp_util_min_rt_default > SCHED_CAPACITY_SCALE) {

        result = -EINVAL;

        goto undo;

    }

    //4.下面检测用户空间修改了那个值

    // sysctl_sched_uclamp_util_[min|max]分别设置到

    // 全局数组uclamp_default[UCLAMP_MIN|MAX]中去

    // 下面传入的参数为false标记这个uclamp值并不是来源于用户空间的系统调用

    if (old_min != sysctl_sched_uclamp_util_min) {

        uclamp_se_set(&uclamp_default[UCLAMP_MIN], sysctl_sched_uclamp_util_min, false);

        update_root_tg = true;

    }

    if (old_max != sysctl_sched_uclamp_util_max) {

        uclamp_se_set(&uclamp_default[UCLAMP_MAX], sysctl_sched_uclamp_util_max, false);

        update_root_tg = true;

    }

    //4.只要系统维度的uclamp发生变化，就执行下面操作

    // 完成对group和task维度的uclamp进行更新

    if (update_root_tg) {

        //4.1 在enqueue/dequeue时用于计算CPU的clamp值时进行判断

        static_branch_enable(&sched_uclamp_used);

        //4.2 设置到全局变量root_task_group

        uclamp_update_root_tg();

    }

    //5.如果修改的是sysctl_sched_uclamp_util_min_rt_default

    if (old_min_rt != sysctl_sched_uclamp_util_min_rt_default) {

        static_branch_enable(&sched_uclamp_used);

        //5.1 设置到系统中所有rt线程的p->uclamp_req[UCLAMP_MIN]

        uclamp_sync_util_min_rt_default();

    }

    /*

     * We update all RUNNABLE tasks only when task groups are in use.

     * Otherwise, keep it simple and do just a lazy update at each next

     * task enqueue time.

     */

    goto done;

undo:

    sysctl_sched_uclamp_util_min = old_min;

    sysctl_sched_uclamp_util_max = old_max;

    sysctl_sched_uclamp_util_min_rt_default = old_min_rt;

done:

    mutex_unlock(&uclamp_mutex);

    return result;

}

static void uclamp_update_root_tg(void)

{

    struct task_group *tg = &root_task_group;

    //1.根组的uclamp信息和system维度的uclamp信息相等

    uclamp_se_set(&tg->uclamp_req[UCLAMP_MIN], sysctl_sched_uclamp_util_min, false);

    uclamp_se_set(&tg->uclamp_req[UCLAMP_MAX], sysctl_sched_uclamp_util_max, false);

    //2.一个group的uclamp信息发生了变化，需要完成下面三个工作

    // a) 更新这个group下的子group的uclamp信息

    // b) 更新这个group下的task的uclamp信息，包括子group中的task

    // c) 更新这些task所属的rq的uclamp信息，即rq->uclamp[clamp_id]

    rcu_read_lock();

    cpu_util_update_eff(&root_task_group.css);

    rcu_read_unlock();

}

struct task_group {

    ...

#ifdef CONFIG_UCLAMP_TASK_GROUP

    /* The two decimal precision [%] value requested from user-space */

    //用户空间通过/dev/cpuctl/<group>/cpu.uclamp.[min|max]节点设置的值对应的百分比

    unsigned int uclamp_pct[UCLAMP_CNT];

    /* Clamp values requested for a task group */

    //用户空间通过/dev/cpuctl/<group>/cpu.uclamp.[min|max]节点设置的值对应的util值

    struct uclamp_se
uclamp_req[UCLAMP_CNT];

    /* Effective clamp values used for a task group */

    //有效的uclamp值

    struct uclamp_se
uclamp[UCLAMP_CNT];

    /* Latency-sensitive flag used for a task group */

    //下面成员只在AOSP中有

    unsigned int latency_sensitive;

#endif

};

/*

* Integer 10^N with a given N exponent by casting to integer the literal "1eN"

* C expression. Since there is no way to convert a macro argument (N) into a

* character constant, use two levels of macros.

*/

//上面的宏解释了为什么要使用两级宏，将宏的参数转化为字符常量

//POW10(N)表示10^N

#define _POW10(exp) ((unsigned int)1e##exp)

#define POW10(exp) _POW10(exp)

struct uclamp_request {

    //2表示两位小数

#define UCLAMP_PERCENT_SHIFT    2

#define UCLAMP_PERCENT_SCALE    (100 * POW10(UCLAMP_PERCENT_SHIFT))

    //用户空间的百分比，例如87.95%，该值就是8795

    s64 percent;

    //上面百分比对应的util值大小

    u64 util;

    int ret;

};

更新task_group中的uclamp_req[]和uclamp_pct[]

/dev/cpuctl/<group>/cpu.uclamp.min

/dev/cpuctl/<group>/cpu.uclamp.max

更新task_group中的latency_sensitive

/dev/cpuctl/<group>/cpu.uclamp.latency_sensitive

static struct cftype cpu_legacy_files[] = {

    ...

#ifdef CONFIG_UCLAMP_TASK_GROUP

    {

        .name = "uclamp.min",

        .flags = CFTYPE_NOT_ON_ROOT,

        .seq_show = cpu_uclamp_min_show,

        .write = cpu_uclamp_min_write,

    },

    {

        .name = "uclamp.max",

        .flags = CFTYPE_NOT_ON_ROOT,

        .seq_show = cpu_uclamp_max_show,

        .write = cpu_uclamp_max_write,

    },

    {

        .name = "uclamp.latency_sensitive",                    //只有AOSP中会存在该节点

        .flags = CFTYPE_NOT_ON_ROOT,

        .read_u64 = cpu_uclamp_ls_read_u64,

        .write_u64 = cpu_uclamp_ls_write_u64,

    },

#endif

    ...

};

static ssize_t cpu_uclamp_min_write(

            struct kernfs_open_file *of,

            char *buf, size_t nbytes,

            loff_t off)

{

    return cpu_uclamp_write(of, buf, nbytes, off, UCLAMP_MIN);

}

static ssize_t cpu_uclamp_max_write(

            struct kernfs_open_file *of,

            char *buf, size_t nbytes,

            loff_t off)

{

    return cpu_uclamp_write(of, buf, nbytes, off, UCLAMP_MAX);

}

static ssize_t cpu_uclamp_write(

            struct kernfs_open_file *of,

            char *buf,

            size_t nbytes, loff_t off,

            enum uclamp_id clamp_id)            //标记是写min还是max

{

    struct uclamp_request req;

    struct task_group *tg;

    //1.解析用户空间的输入

    // 得到百分比，并计算得到对应的util值

    req = capacity_from_percent(buf);

    if (req.ret)

        return req.ret;

    //2.使能

    static_branch_enable(&sched_uclamp_used);

    mutex_lock(&uclamp_mutex);

    rcu_read_lock();

    //3.得到是从哪个组的节点下写下来的

    tg = css_tg(of_css(of));

    //4.更新task_group->uclamp_req值，注意，这里传入的参数为false

    if (tg->uclamp_req[clamp_id].value != req.util)

        uclamp_se_set(&tg->uclamp_req[clamp_id], req.util, false);

    /*

     * Because of not recoverable conversion rounding we keep track of the

     * exact requested value

     */

    //5.更新task_group中记录的uclamp_pct值

    tg->uclamp_pct[clamp_id] = req.percent;

    /* Update effective clamps to track the most restrictive value */

    //6.更新这个group的有效uclamp值

    cpu_util_update_eff(of_css(of));

    rcu_read_unlock();

    mutex_unlock(&uclamp_mutex);

    return nbytes;

}

static inline struct uclamp_request capacity_from_percent(char *buf)

{

    //1.100%对应1024，下面的值也是用户空间输入"max"时对应的值

    struct uclamp_request req = {

        .percent = UCLAMP_PERCENT_SCALE,                //10000，表示100%

        .util = SCHED_CAPACITY_SCALE,                    //1024

        .ret = 0,

    };

    //2.去除前面的空格

    buf = strim(buf);

    //3.如果输入的不是字符串max，则进入该分支，解析用户空间输入的小数

    if (strcmp(buf, "max")) {

        //4.将输入的字符串转化为整形值保存在percent里面

        req.ret = cgroup_parse_float(buf, UCLAMP_PERCENT_SHIFT, &req.percent);

        if (req.ret)

            return req;

        //5.对用户空间的输入的百分比进行有效性检查

        if ((u64)req.percent > UCLAMP_PERCENT_SCALE) {

            req.ret = -ERANGE;

            return req;

        }

        //6.这里计算得到百分比对应的util值，100%对应的是1024

        // 这里的计算是真他娘的巧妙啊

        req.util = req.percent << SCHED_CAPACITY_SHIFT;

        req.util = DIV_ROUND_CLOSEST_ULL(req.util, UCLAMP_PERCENT_SCALE);

    }

    return req;

}

/**

* cgroup_parse_float - parse a floating number

* @input: input string

* @dec_shift: number of decimal digits to shift

* @v: output

*

* Parse a decimal floating point number in @input and store the result in

* @v with decimal point right shifted @dec_shift times. For example, if

* @input is "12.3456" and @dec_shift is 3, *@v will be set to 12345.

* Returns 0 on success, -errno otherwise.

*

* There's nothing cgroup specific about this function except that it's

* currently the only user.

*/

int cgroup_parse_float(

            const char *input,                    //要解析的字符串

            unsigned dec_shift,                //小数点移位的个数

            s64 *v)                                //解析后得到的浮点数

{

    s64 whole, frac = 0;

    int fstart = 0, fend = 0, flen;

    if (!sscanf(input, "%lld.%n%lld%n", &whole, &fstart, &frac, &fend))

        return -EINVAL;

    if (frac < 0)

        return -EINVAL;

    flen = fend > fstart ? fend - fstart : 0;

    if (flen < dec_shift)

        frac *= power_of_ten(dec_shift - flen);

    else

        frac = DIV_ROUND_CLOSEST_ULL(frac, power_of_ten(flen - dec_shift));

    *v = whole * power_of_ten(dec_shift) + frac;

    return 0;

}

static int cpu_uclamp_min_show(struct seq_file *sf, void *v)

{

    cpu_uclamp_print(sf, UCLAMP_MIN);

    return 0;

}

static int cpu_uclamp_max_show(struct seq_file *sf, void *v)

{

    cpu_uclamp_print(sf, UCLAMP_MAX);

    return 0;

}

static inline void cpu_uclamp_print(

            struct seq_file *sf,

            enum uclamp_id clamp_id)            //标记要显示min还是max

{

    struct task_group *tg;

    u64 util_clamp;

    u64 percent;

    u32 rem;

    rcu_read_lock();

    //1.获取要读取哪个group中的节点

    tg = css_tg(seq_css(sf));

    //2.获取这个group中的值

    util_clamp = tg->uclamp_req[clamp_id].value;

    rcu_read_unlock();

    //3.如果uclamp达到最大值1024，直接显示max

    if (util_clamp == SCHED_CAPACITY_SCALE) {

        seq_puts(sf, "max\n");

        return;

    }

    //4.否则按照task_group中的百分比来计算返回的值

    percent = tg->uclamp_pct[clamp_id];

    percent = div_u64_rem(percent, POW10(UCLAMP_PERCENT_SHIFT), &rem);

    seq_printf(sf, "%llu.%0*u\n", percent, UCLAMP_PERCENT_SHIFT, rem);

}

static int cpu_uclamp_ls_write_u64(

            struct cgroup_subsys_state *css,

            struct cftype *cftype,

            u64 ls)

{

    struct task_group *tg;

    if (ls > 1)

        return -EINVAL;

    //直接将用户空间的值写入task_group->latency_sensitive

    tg = css_tg(css);

    tg->latency_sensitive = (unsigned int) ls;

    return 0;

}

static u64 cpu_uclamp_ls_read_u64(

            struct cgroup_subsys_state *css, struct cftype *cft)

{

    struct task_group *tg = css_tg(css);

    //读取task_group->latency_sensitive

    return (u64) tg->latency_sensitive;

}

#define SCHEDTUNE_TOPAPP_CPUCTL_BOOST_PATH "/dev/cpuctl/top-app/cpu.uclamp.min"

int DecisionDriver::setSchedtuneBoost(int index, int boost)

{

    char path[64], buf[128];

    if (index >= SCHEDTUNE_BG_MAX_INDEX)

        return -1;

    if (isFileExist(SCHEDTUNE_TOPAPP_CPUCTL_BOOST_PATH)) {

        DEBUG("set cpuctl enter");

        snprintf(path, sizeof(path), SCHEDTUNE_TOPAPP_CPUCTL_BOOST_PATH);

    } else if (index < 0)     // FIXME: only support top_app boostgroup

        snprintf(path, sizeof(path), SCHEDTUNE_TOPAPP_BOOST_PATH);

    else

        snprintf(path, sizeof(path), "/dev/stune/fb%d/schedtune.boost", index);

    if (mFpBoost == NULL) {

        mFpBoost = fopen(path, "w");

        if (mFpBoost == NULL) {

            ERROR("fopen %s failed.(%s)", path, strerror(errno));

            return -1;

        }

    }

    if (fseek(mFpBoost, 0, SEEK_SET) < 0) {

        ERROR("fseek failed.(%s)\n", strerror(errno));

        fclose(mFpBoost);

        mFpBoost = NULL;

        return -1;

    }

    snprintf(buf, sizeof(buf), "%d", boost);

    if (fwrite(buf, sizeof(char), strlen(buf), mFpBoost) == 0) {

        ERROR("fwrite failed.(%s)\n", strerror(errno));

        fclose(mFpBoost);

        mFpBoost = NULL;

        return -1;

    }

    fflush(mFpBoost);

    DEBUG("set schedtune boost %d", boost);

    return 0;

}

static constexpr char* uclampLatencySensitivePath = \

            "/dev/cpuctl/foreground/cpu.uclamp.latency_sensitive";

Return<void> OrmsHalService::ormsWriteUclampLatencySensitive(const hidl_string& stingValue)

{

    int fd = open(uclampLatencySensitivePath, O_WRONLY);

    if (fd < 0) {

        ALOGE("open %s failed(%s)", uclampLatencySensitivePath, strerror(errno));

        return Void();

    }

    ALOGD("OrmsHalService write file %s - %s.",

                uclampLatencySensitivePath, stingValue.c_str());

    ssize_t len = write(fd, stingValue.c_str(), stingValue.size());

    if (len <= 0) {

        ALOGE("write file %s failed.(%s)", uclampLatencySensitivePath, strerror(errno));

    }

    close(fd);

    return Void();

}

static void cpu_util_update_eff(

            struct cgroup_subsys_state *css)            //要更新哪个group

{

    struct cgroup_subsys_state *top_css = css;

    struct uclamp_se *uc_parent = NULL;

    struct uclamp_se *uc_se = NULL;

    unsigned int eff[UCLAMP_CNT];

    enum uclamp_id clamp_id;

    unsigned int clamps;

    lockdep_assert_held(&uclamp_mutex);

    SCHED_WARN_ON(!rcu_read_lock_held());

    //遍历这个cgroup下的所有子group

    css_for_each_descendant_pre(css, top_css) {

        //1.第一步：计算子group受父group钳位后的uclamp值

        uc_parent = css_tg(css)->parent

            ? css_tg(css)->parent->uclamp : NULL;

        //1.1 不管是uclamp_min还是uclamp_max，子group的

        // 有效uclamp值一定小于父group的uclamp值，为啥捏？？？

        for_each_clamp_id(clamp_id) {

            /* Assume effective clamps matches requested clamps */

            eff[clamp_id] = css_tg(css)->uclamp_req[clamp_id].value;

            /* Cap effective clamps with parent's effective clamps */

            if (uc_parent &&

             eff[clamp_id] > uc_parent[clamp_id].value) {

                eff[clamp_id] = uc_parent[clamp_id].value;

            }

        }

        /* Ensure protection is always capped by limit */

        //1.2 因为上面都是取最小值，所以有可能算出来的min要大于max，在这里做处理

        eff[UCLAMP_MIN] = min(eff[UCLAMP_MIN], eff[UCLAMP_MAX]);

        /* Propagate most restrictive effective clamps */

        //1.3 将受父group钳位后的新的uclamp值更新进这个group->uclamp里面

        // 相等则不用更新，不相等则更新

        clamps = 0x0;

        uc_se = css_tg(css)->uclamp;

        for_each_clamp_id(clamp_id) {

            if (eff[clamp_id] == uc_se[clamp_id].value)

                continue;

            uc_se[clamp_id].value = eff[clamp_id];

            uc_se[clamp_id].bucket_id = uclamp_bucket_id(eff[clamp_id]);

            clamps |= (0x1 << clamp_id);

        }

        //1.4只有在这个group的uclamp_min和uclamp_max全都没用发生

        // 变化时，才执行下面的操作，获取最左侧的cgroup，暂不分析

        if (!clamps) {

            css = css_rightmost_descendant(css);

            continue;

        }

        /* Immediately update descendants RUNNABLE tasks */

        //2.第二步：遍历这个cgroup下的所有task，完成下面工作：

        // a) 更新task的有效uclamp信息，即task->uclamp[]

        // b) 更新这些task所属的rq的uclamp信息，即rq->uclamp[clamp_id]

        uclamp_update_active_tasks(css);

    }

}

static inline void uclamp_update_active_tasks(

            struct cgroup_subsys_state *css)

{

    struct css_task_iter it;

    struct task_struct *p;

    //遍历这个group中的所有task，挨个设置

    css_task_iter_start(css, 0, &it);

    while ((p = css_task_iter_next(&it)))

        uclamp_update_active(p);

    css_task_iter_end(&it);

}

static inline void uclamp_update_active(struct task_struct *p)

{

    enum uclamp_id clamp_id;

    struct rq_flags rf;

    struct rq *rq;

    /*

     * Lock the task and the rq where the task is (or was) queued.

     *

     * We might lock the (previous) rq of a !RUNNABLE task, but that's the

     * price to pay to safely serialize util_{min,max} updates with

     * enqueues, dequeues and migration operations.

     * This is the same locking schema used by __set_cpus_allowed_ptr().

     */

    rq = task_rq_lock(p, &rf);

    /*

     * Setting the clamp bucket is serialized by task_rq_lock().

     * If the task is not yet RUNNABLE and its task_struct is not

     * affecting a valid clamp bucket, the next time it's enqueued,

     * it will already see the updated clamp bucket value.

     */

    //前面我们说过：group下的所有task的uclamp值，都不得大于这个父group的uclamp值

    //这个group的uclamp信息已经被保存在task_group->uclamp结构中，下面依次执行

    //uclamp_rq_dec_id和uclamp_rq_inc_id，在uclamp_rq_inc_id -> uclamp_eff_get中，

    //group的uclamp信息最终在uclamp_eff_value中被作用在task上

    //如果这个task已经在rq链表上，则手动执行下面dec和inc操作，使uclamp信息立刻生效，

    //如果不在链表上（active为false），则不需要执行，更新工作留到这个task下一次enqueue时完成

    for_each_clamp_id(clamp_id) {

        if (p->uclamp[clamp_id].active) {

            uclamp_rq_dec_id(rq, p, clamp_id);

            uclamp_rq_inc_id(rq, p, clamp_id);

        }

    }

    task_rq_unlock(rq, p, &rf);

}

/proc/<pid>/task/<tid>/sched

void proc_sched_show_task(

            struct task_struct *p,

            struct pid_namespace *ns,

            struct seq_file *m)

{

    ...

#ifdef CONFIG_UCLAMP_TASK

    __PS("uclamp.min", p->uclamp_req[UCLAMP_MIN].value);

    __PS("uclamp.max", p->uclamp_req[UCLAMP_MAX].value);

    __PS("effective uclamp.min", uclamp_eff_value(p, UCLAMP_MIN));

    __PS("effective uclamp.max", uclamp_eff_value(p, UCLAMP_MAX));

#endif

    ...

}

struct task_struct {

    ...

#ifdef CONFIG_UCLAMP_TASK

    /*

     * Clamp values requested for a scheduling entity.

     * Must be updated with task_rq_lock() held.

     */

    //用户空间请求的clamp值，通过sched_setattr系统调用设置

    struct uclamp_se        uclamp_req[UCLAMP_CNT];

    /*

     * Effective clamp values used for a scheduling entity.

     * Must be updated with task_rq_lock() held.

     */

    //这个task最终生效的uclamp信息，也就是是受system和cgroup两个

    //维度共同钳制后的值，在enqueue的时候更新，详见uclamp_rq_inc_id

    struct uclamp_se        uclamp[UCLAMP_CNT];

#endif

    ...

}

/*

* Utilization clamp for a scheduling entity

* @value:            clamp value "assigned" to a se

* @bucket_id:        bucket index corresponding to the "assigned" value

* @active:        the se is currently refcounted in a rq's bucket

* @user_defined:    the requested clamp value comes from user-space

*

* The bucket_id is the index of the clamp bucket matching the clamp value

* which is pre-computed and stored to avoid expensive integer divisions from

* the fast path.

*

* The active bit is set whenever a task has got an "effective" value assigned,

* which can be different from the clamp value "requested" from user-space.

* This allows to know a task is refcounted in the rq's bucket corresponding

* to the "effective" bucket_id.

*

* The user_defined bit is set whenever a task has got a task-specific clamp

* value requested from userspace, i.e. the system defaults apply to this task

* just as a restriction. This allows to relax default clamps when a less

* restrictive task-specific value has been requested, thus allowing to

* implement a "nice" semantic. For example, a task running with a 20%

* default boost can still drop its own boosting to 0%.

*/

struct uclamp_se {

    //用来记录这个task的uclamp_[min|max]值，最大值为1024，占11个bit

    unsigned int value        : bits_per(SCHED_CAPACITY_SCALE);

    //标记这个task的uclamp_[min|max]值落在rq的bucket的那个桶里面

    unsigned int bucket_id        : bits_per(UCLAMP_BUCKETS);

    //标记这个task对应的uclamp_se是否已经被规划进rq的bucket中

    //enqueue此task时写1，dequeue此task时写0，线程刚fork的时候写0

    unsigned int active        : 1;

    //标记这个task的clamp值是否是来源于用户空间的系统调用

    //如果是来源于system和cgroup维度，设置为0

    //如果是来源于用户空间的系统调用，设置为1

    unsigned int user_defined : 1;

};

/*

* Utilization clamp constraints.

* @UCLAMP_MIN:    Minimum utilization

* @UCLAMP_MAX:    Maximum utilization

* @UCLAMP_CNT:    Utilization clamp constraints count

*/

enum uclamp_id {

    UCLAMP_MIN = 0,

    UCLAMP_MAX,

    UCLAMP_CNT

};

int sched_setattr(pid_t pid, struct sched_attr *attr, unsigned int flags);

/*

* Extended scheduling parameters data structure.

*

* This is needed because the original struct sched_param can not be

* altered without introducing ABI issues with legacy applications

* (e.g., in sched_getparam()).

*

* However, the possibility of specifying more than just a priority for

* the tasks may be useful for a wide variety of application fields, e.g.,

* multimedia, streaming, automation and control, and many others.

*

* This variant (sched_attr) allows to define additional attributes to

* improve the scheduler knowledge about task requirements.

*

* Scheduling Class Attributes

* ===========================

*

* A subset of sched_attr attributes specifies the

* scheduling policy and relative POSIX attributes:

*

* @size                size of the structure, for fwd/bwd compat.

*

* @sched_policy        task's scheduling policy

* @sched_nice        task's nice value (SCHED_NORMAL/BATCH)

* @sched_priority    task's static priority (SCHED_FIFO/RR)

*

* Certain more advanced scheduling features can be controlled by a

* predefined set of flags via the attribute:

*

* @sched_flags    for customizing the scheduler behaviour

*

* Sporadic Time-Constrained Task Attributes

* =========================================

*

* A subset of sched_attr attributes allows to describe a so-called

* sporadic time-constrained task.

*

* In such a model a task is specified by:

* - the activation period or minimum instance inter-arrival time;

* - the maximum (or average, depending on the actual scheduling

* discipline) computation time of all instances, a.k.a. runtime;

* - the deadline (relative to the actual activation time) of each

* instance.

* Very briefly, a periodic (sporadic) task asks for the execution of

* some specific computation --which is typically called an instance--

* (at most) every period. Moreover, each instance typically lasts no more

* than the runtime and must be completed by time instant t equal to

* the instance activation time + the deadline.

*

* This is reflected by the following fields of the sched_attr structure:

*

* @sched_deadline    representative of the task's deadline

* @sched_runtime        representative of the task's runtime

* @sched_period        representative of the task's period

*

* Given this task model, there are a multiplicity of scheduling algorithms

* and policies, that can be used to ensure all the tasks will make their

* timing constraints.

*

* As of now, the SCHED_DEADLINE policy (sched_dl scheduling class) is the

* only user of this new interface. More information about the algorithm

* available in the scheduling class file or in Documentation/.

*

* Task Utilization Attributes

* ===========================

*

* A subset of sched_attr attributes allows to specify the utilization

* expected for a task. These attributes allow to inform the scheduler about

* the utilization boundaries within which it should schedule the task. These

* boundaries are valuable hints to support scheduler decisions on both task

* placement and frequency selection.

*

* @sched_util_min    represents the minimum utilization

* @sched_util_max    represents the maximum utilization

*

* Utilization is a value in the range [0..SCHED_CAPACITY_SCALE]. It

* represents the percentage of CPU time used by a task when running at the

* maximum frequency on the highest capacity CPU of the system. For example, a

* 20% utilization task is a task running for 2ms every 10ms at maximum

* frequency.

*

* A task with a min utilization value bigger than 0 is more likely scheduled

* on a CPU with a capacity big enough to fit the specified value.

* A task with a max utilization value smaller than 1024 is more likely

* scheduled on a CPU with no more capacity than the specified value.

*/

struct sched_attr {

    //该数据结构的大小

    __u32 size;

    //指定调度策略，可取值为：

    //#define SCHED_NORMAL        0

    //#define SCHED_FIFO            1

    //#define SCHED_RR                2

    //#define SCHED_BATCH            3

    //#define SCHED_IDLE            5

    //#define SCHED_DEADLINE        6

    __u32 sched_policy;

    //给调度器使用的一些flag，可取值如下

    //#define SCHED_FLAG_RESET_ON_FORK    0x01

    //#define SCHED_FLAG_RECLAIM        0x02

    //#define SCHED_FLAG_DL_OVERRUN        0x04

    //#define SCHED_FLAG_KEEP_POLICY        0x08

    //#define SCHED_FLAG_KEEP_PARAMS        0x10

    //#define SCHED_FLAG_UTIL_CLAMP_MIN    0x20

    //#define SCHED_FLAG_UTIL_CLAMP_MAX    0x40

    __u64 sched_flags;

    /* SCHED_NORMAL, SCHED_BATCH */

    __s32 sched_nice;                        //指定nice值

    /* SCHED_FIFO, SCHED_RR */

    __u32 sched_priority;                    //指定优先级

    /* SCHED_DEADLINE */

    __u64 sched_runtime;

    __u64 sched_deadline;

    __u64 sched_period;

    /* Utilization hints */

    __u32 sched_util_min;                    //uclamp相关

    __u32 sched_util_max;

};

/**

* sys_sched_setattr - same as above, but with extended sched_attr

* @pid: the pid in question.

* @uattr: structure containing the extended parameters.

* @flags: for future extension.

*/

SYSCALL_DEFINE3(sched_setattr,

            pid_t, pid,

            struct sched_attr __user *, uattr,

            unsigned int, flags)

{

    struct sched_attr attr;

    struct task_struct *p;

    int retval;

    //1.参数有效性判断

    if (!uattr || pid < 0 || flags)

        return -EINVAL;

    //2.获取用户空间的attr数据

    retval = sched_copy_attr(uattr, &attr);

    if (retval)

        return retval;

    //3.参数有效性判断：调度策略

    if ((int)attr.sched_policy < 0)

        return -EINVAL;

    //4.sched_flags参数处理

    if (attr.sched_flags & SCHED_FLAG_KEEP_POLICY)

        attr.sched_policy = SETPARAM_POLICY;

    //6.由pid找到对应的task结构

    rcu_read_lock();

    retval = -ESRCH;

    p = find_process_by_pid(pid);

    if (likely(p))

        get_task_struct(p);

    rcu_read_unlock();

    //7.设置用户空间的attr

    if (likely(p)) {

        retval = sched_setattr(p, &attr);

        put_task_struct(p);

    }

    return retval;

}

/*

* Mimics kernel/events/core.c perf_copy_attr().

*/

static int sched_copy_attr(struct sched_attr __user *uattr, struct sched_attr *attr)

{

    u32 size;

    int ret;

    /* Zero the full structure, so that a short copy will be nice: */

    memset(attr, 0, sizeof(*attr));

    //1.先从用户空间的uattr中拷贝出size信息

    ret = get_user(size, &uattr->size);

    if (ret)

        return ret;

    /* ABI compatibility quirk: */

    //2.校验size

    if (!size)

        size = SCHED_ATTR_SIZE_VER0;

    if (size < SCHED_ATTR_SIZE_VER0 || size > PAGE_SIZE)

        goto err_size;

    //3.拷贝用户空间的attr信息

    ret = copy_struct_from_user(attr, sizeof(*attr), uattr, size);

    if (ret) {

        if (ret == -E2BIG)

            goto err_size;

        return ret;

    }

    //4.参数校验，当支持SCHED_FLAG_UTIL_CLAMP时，这个数据结构的大小必定为56

    if ((attr->sched_flags & SCHED_FLAG_UTIL_CLAMP) &&

     size < SCHED_ATTR_SIZE_VER1)

        return -EINVAL;

    /*

     * XXX: Do we want to be lenient like existing syscalls; or do we want

     * to be strict and return an error on out-of-bounds values?

     */

    //5.nice值的范围为[-20, 19]

    attr->sched_nice = clamp(attr->sched_nice, MIN_NICE, MAX_NICE);

    return 0;

err_size:

    put_user(sizeof(*attr), &uattr->size);

    return -E2BIG;

}

#define SCHED_ATTR_SIZE_VER0        48        /* sizeof first published struct */

#define SCHED_ATTR_SIZE_VER1        56        /* add: util_{min,max} */

int sched_setattr(struct task_struct *p, const struct sched_attr *attr)

{

    return __sched_setscheduler(p, attr, true, true);

}

static int __sched_setscheduler(struct task_struct *p,

                const struct sched_attr *attr,

                bool user, bool pi)

{

    ...

    /* Update task specific "requested" clamps */

    //1.参数有效性判断

    if (attr->sched_flags & SCHED_FLAG_UTIL_CLAMP) {

        retval = uclamp_validate(p, attr);

        if (retval)

            return retval;

    }

    ...

    /*

     * If not changing anything there's no need to proceed further,

     * but store a possible modification of reset_on_fork.

     */

    //2.下面几种情况会跳转到change标签，才会执行到__setscheduler_uclamp

    if (unlikely(policy == p->policy)) {

        //2.1 cfs线程修改了优先级

        if (fair_policy(policy) && attr->sched_nice != task_nice(p))

            goto change;

        //2.2 rt线程修改了优先级

        if (rt_policy(policy) && attr->sched_priority != p->rt_priority)

            goto change;

        //2.3 dl类线程修改了参数

        if (dl_policy(policy) && dl_param_changed(p, attr))

            goto change;

        //2.4 线程修改了uclamp信息

        if (attr->sched_flags & SCHED_FLAG_UTIL_CLAMP)

            goto change;

        p->sched_reset_on_fork = reset_on_fork;

        retval = 0;

        goto unlock;

    }

change:

    ...

    //3.设置uclamp值生效

    __setscheduler_uclamp(p, attr);

unlock:

    ...

}

static int uclamp_validate(

            struct task_struct *p,

            const struct sched_attr *attr)

{

    //1.先读取这个task的旧的uclamp值

    unsigned int lower_bound = p->uclamp_req[UCLAMP_MIN].value;

    unsigned int upper_bound = p->uclamp_req[UCLAMP_MAX].value;

    //2.从用户空间获取新的值

    if (attr->sched_flags & SCHED_FLAG_UTIL_CLAMP_MIN)

        lower_bound = attr->sched_util_min;

    if (attr->sched_flags & SCHED_FLAG_UTIL_CLAMP_MAX)

        upper_bound = attr->sched_util_max;

    //3.有效性判断

    if (lower_bound > upper_bound)

        return -EINVAL;

    if (upper_bound > SCHED_CAPACITY_SCALE)

        return -EINVAL;

    /*

     * We have valid uclamp attributes; make sure uclamp is enabled.

     *

     * We need to do that here, because enabling static branches is a

     * blocking operation which obviously cannot be done while holding

     * scheduler locks.

     */

    static_branch_enable(&sched_uclamp_used);

    return 0;

}

static void __setscheduler_uclamp(

            struct task_struct *p,

            const struct sched_attr *attr)

{

    enum uclamp_id clamp_id;

    /*

     * On scheduling class change, reset to default clamps for tasks

     * without a task-specific value.

     */

    //1.先恢复默认的uclamp信息

    // 如果这个task的uclamp信息是用户空间通过系统调用主动设置下来的，

    // 则保留，毕竟只有用户自己最了解自己的程序。否则，我们在这里将这个

    // task的uclamp信息恢复成默认值，即uclamp_min为0，uclamp_max为1024

    for_each_clamp_id(clamp_id) {

        struct uclamp_se *uc_se = &p->uclamp_req[clamp_id];

        /* Keep using defined clamps across class changes */

        //1.1 如果这个task的uclamp值是用户通过系统调用主动设置下来的，则保留

        if (uc_se->user_defined)

            continue;

        /*

         * RT by default have a 100% boost value that could be modified

         * at runtime.

         */

        //1.2 rt和cfs线程的默认uclamp值是不同的

        if (unlikely(rt_task(p) && clamp_id == UCLAMP_MIN))

            //1.2.1 rt线程的UCLAMP_MIN值需要拉满

            // 这个是为了rt运行时能够获得更高的性能

            __uclamp_update_util_min_rt_default(p);

        else {

            //1.2.2 对于普通的cft线程和rt的UCLAMP_MAX，通过uclamp_none设置默认值

            // uclamp_none表示没有钳位时的uclamp值，此时mix为0，max为1024

            uclamp_se_set(uc_se, uclamp_none(clamp_id), false);

        }

    }

    //2.如果没有设置该标记位，则表示用户空间并没有通过sched_setattr系统调用

    // 设置task的uclamp值，也就不需要执行下面的逻辑了，则直接退出

    if (likely(!(attr->sched_flags & SCHED_FLAG_UTIL_CLAMP)))

        return;

    //3.下面根据用户空间指定的flag，设置线程的uclamp_req值

    // 注意：

    // a) 这里并不是更新task的有效uclamp，而是task->uclamp_req

    // 这个task的有效uclamp在enqueue的时候更新，详见uclamp_rq_inc_id

    // b) 这里在调用函数时，传入的user_defined参数为true，

    // 表示这个uclamp是来源于用户空间的系统调用

    if (attr->sched_flags & SCHED_FLAG_UTIL_CLAMP_MIN) {

        uclamp_se_set(&p->uclamp_req[UCLAMP_MIN], attr->sched_util_min, true);

    }

    if (attr->sched_flags & SCHED_FLAG_UTIL_CLAMP_MAX) {

        uclamp_se_set(&p->uclamp_req[UCLAMP_MAX], attr->sched_util_max, true);

    }

}

#define SCHED_FLAG_UTIL_CLAMP            \

            (SCHED_FLAG_UTIL_CLAMP_MIN | SCHED_FLAG_UTIL_CLAMP_MAX)

#define for_each_clamp_id(clamp_id) \

    for ((clamp_id) = 0; (clamp_id) < UCLAMP_CNT; (clamp_id)++)

static inline void uclamp_se_set(

                struct uclamp_se *uc_se,

                unsigned int value,                //要设置的uclamp值，实际就是util值

                bool user_defined)                    //标记这个值是都是来源于用户空间的系统调用

{

    //1.uclamp值

    uc_se->value = value;

    //2.得到对应的桶编号

    uc_se->bucket_id = uclamp_bucket_id(value);

    //3.标记这个uclamp值是否来源于用户空间，只有task维度

    // 的uclamp信息才是通过用户空间系统调用设置下来的

    uc_se->user_defined = user_defined;

}

#define SCHED_FLAG_UTIL_CLAMP            \

        (SCHED_FLAG_UTIL_CLAMP_MIN | SCHED_FLAG_UTIL_CLAMP_MAX)

status_t SurfaceFlinger::setSchedAttr(bool enabled)

{

    static const unsigned int kUclampMin =

            base::GetUintProperty<unsigned int>("ro.surface_flinger.uclamp.min", 0U);

    //1.uclamp.min set to 0 (default), skip setting

    if (!kUclampMin)

        return NO_ERROR;

    //2.Currently, there is no wrapper in bionic: b/183240349.

    struct sched_attr {

        uint32_t size;

        uint32_t sched_policy;

        uint64_t sched_flags;

        int32_t sched_nice;

        uint32_t sched_priority;

        uint64_t sched_runtime;

        uint64_t sched_deadline;

        uint64_t sched_period;

        uint32_t sched_util_min;

        uint32_t sched_util_max;

    };

    //3.参数初始化，设置task的min和max

    sched_attr attr = {};

    attr.size = sizeof(attr);

    attr.sched_flags = (SCHED_FLAG_KEEP_ALL | SCHED_FLAG_UTIL_CLAMP);

    attr.sched_util_min = enabled ? kUclampMin : 0;

    attr.sched_util_max = 1024;

    //4.执行系统调用

    if (syscall(__NR_sched_setattr, 0, &attr, 0))

        return -errno;

    return NO_ERROR;

}

static inline unsigned long uclamp_task_util(struct task_struct *p)

{

    return clamp(task_util_est(p),

         uclamp_eff_value(p, UCLAMP_MIN),

         uclamp_eff_value(p, UCLAMP_MAX));

}

unsigned long uclamp_eff_value(struct task_struct *p, enum uclamp_id clamp_id)

{

    struct uclamp_se uc_eff;

    /* Task currently refcounted: use back-annotated (effective) value */

    //1.这个task的有效uclamp信息记录在task->uclamp中，在task执行enqueue

    // 的时候更新，如果这个task已经被添加进rq的某个桶中（这个task已经在rq上，

    // 已经执行过enqueue操作），那么task->uclamp中记录的就是有效的uclamp信

    // 息，否则就需要通过下面的uclamp_eff_get重新计算

    if (p->uclamp[clamp_id].active)

        return (unsigned long)p->uclamp[clamp_id].value;

    //2.代码走到这里，表示这个task并没有加到这个rq上，也就是说不是处于RUNNABLE

    // 状态，此时这个task的有效uclamp可能很久没有更新了，调用下面函数获取当前这

    // 个task的有效uclamp值

    uc_eff = uclamp_eff_get(p, clamp_id);

    return (unsigned long)uc_eff.value;

}

/*

* The effective clamp bucket index of a task depends on, by increasing

* priority:

* - the task specific clamp value, when explicitly requested from userspace

* - the task group effective clamp value, for tasks not either in the root

* group or in an autogroup

* - the system default clamp value, defined by the sysadmin

*/

static inline struct uclamp_se uclamp_eff_get(

            struct task_struct *p,

            enum uclamp_id clamp_id)

{

    //1.返回task的uclamp受group的uclamp钳位后的值

    struct uclamp_se uc_req = uclamp_tg_restrict(p, clamp_id);

    //2.获取system维度的uclamp信息，记录在全局变量uclamp_default[]中

    // 该全局变量可通过/proc/sys/kernel/sched_util_clamp_[min|max]设置的

    struct uclamp_se uc_max = uclamp_default[clamp_id];

    /* System default restrictions always apply */

    //3.注意：

    // 在计算受system维度的钳位值时，不管是uclamp_min还是uclamp_max，

    // 均取最小值，也就是说系统中任何task的uclamp值，不管是uclamp_min

    // 还是uclamp_max，都不会超过system维度的uclamp_min和uclamp_max的值

    if (unlikely(uc_req.value > uc_max.value))

        return uc_max;

    return uc_req;

}

static inline struct uclamp_se uclamp_tg_restrict(

            struct task_struct *p,

            enum uclamp_id clamp_id)

{

    /* Copy by value as we could modify it */

    //1.先获取task的uclamp_req值，uclamp_req来源于用户空间的系统调用，不是最终有效的uclamp

    struct uclamp_se uc_req = p->uclamp_req[clamp_id];

#ifdef CONFIG_UCLAMP_TASK_GROUP

    unsigned int tg_min, tg_max, value;

    /*

     * Tasks in autogroups or root task group will be

     * restricted by system defaults.

     */

    //2.由上面的注释可知，如果这个task位于autogroup或者在根组，

    // 则这个task的uclamp值只受system层约束，因此就直接返回

    // autogroup表示根据线程的特性，决定将task放到哪个group中

    if (task_group_is_autogroup(task_group(p)))

        return uc_req;

    if (task_group(p) == &root_task_group)

        return uc_req;

    //3.获取这个task所在group的钳位值

    tg_min = task_group(p)->uclamp[UCLAMP_MIN].value;

    tg_max = task_group(p)->uclamp[UCLAMP_MAX].value;

    //4.干他

    // 一个task的uclamp值（不管是min还是max），都不能超出其所在group限定的uclamp范围

    value = uc_req.value;

    value = clamp(value, tg_min, tg_max);

    //5.返回的这个uclamp是搜task和group维度共同影响的uclamp

    // 注意：此时只是记录在局部变量中，还没有设置进task的uclamp里面

    uclamp_se_set(&uc_req, value, false);

#endif

    return uc_req;

}

static void uclamp_sync_util_min_rt_default(void)

{

    struct task_struct *g, *p;

    /*

     * copy_process()            sysctl_uclamp

     *                     uclamp_min_rt = X;

     * write_lock(&tasklist_lock)         read_lock(&tasklist_lock)

     * // link thread             smp_mb__after_spinlock()

     * write_unlock(&tasklist_lock)     read_unlock(&tasklist_lock);

     * sched_post_fork()             for_each_process_thread()

     * __uclamp_sync_rt()         __uclamp_sync_rt()

     *

     * Ensures that either sched_post_fork() will observe the new

     * uclamp_min_rt or for_each_process_thread() will observe the new

     * task.

     */

    read_lock(&tasklist_lock);

    smp_mb__after_spinlock();

    read_unlock(&tasklist_lock);

    //遍历系统中的每一个进程的每一个线程

    rcu_read_lock();

    for_each_process_thread(g, p)

        uclamp_update_util_min_rt_default(p);

    rcu_read_unlock();

}

/* Careful: this is a double loop, 'break' won't work as expected. */

#define for_each_process_thread(p, t)    \

    for_each_process(p) for_each_thread(p, t)

static void uclamp_update_util_min_rt_default(struct task_struct *p)

{

    struct rq_flags rf;

    struct rq *rq;

    //1.只设置rt线程，不是rt直接返回

    if (!rt_task(p))

        return;

    /* Protect updates to p->uclamp_* */

    rq = task_rq_lock(p, &rf);

    __uclamp_update_util_min_rt_default(p);

    task_rq_unlock(rq, p, &rf);

}

static void __uclamp_update_util_min_rt_default(struct task_struct *p)

{

    unsigned int default_util_min;

    struct uclamp_se *uc_se;

    lockdep_assert_held(&p->pi_lock);

    //1.注意：

    // 设置的是uclamp_req，不是有效的uclamp，有效uclamp在enqueue的时候更新

    uc_se = &p->uclamp_req[UCLAMP_MIN];

    /* Only sync if user didn't override the default */

    //2.如果这个rt线程的uclamp值是用户通过系统调用设置下来的，则跳过

    // 注意：用户空间系统调用设置下来的比system维度的权限更高

    if (uc_se->user_defined)

        return;

    //3.否则将rt线程的uclamp_min值拉倒最大，下面这个全局变量也是都用户

    // 空间控制的，表示系统中所有的rt线程的uclamp_min的值应该设置多大，

    // 默认是1024

    // 之所以要将rt线程uclamp_min拉倒最大值1024，主要是处于对性能的

    // 考虑，高的util是可以将频率拉满，并且选核时可能上大核

    default_util_min = sysctl_sched_uclamp_util_min_rt_default;

    uclamp_se_set(uc_se, default_util_min, false);

}

static inline unsigned int uclamp_bucket_id(unsigned int clamp_value)

{

    //默认分20个桶，将1024均分到[0, 19]，两个宏分别为 51, 20

    return min_t(unsigned int, clamp_value / UCLAMP_BUCKET_DELTA, UCLAMP_BUCKETS - 1);

}

/* Integer rounded range for each bucket */

#define UCLAMP_BUCKET_DELTA DIV_ROUND_CLOSEST(SCHED_CAPACITY_SCALE, UCLAMP_BUCKETS)

/* Number of utilization clamp buckets (shorter alias) */

#define UCLAMP_BUCKETS CONFIG_UCLAMP_BUCKETS_COUNT

Utilization clamping allows to clamp the CPU's utilization within a

[util_min, util_max] range, depending on the set of RUNNABLE tasks on

that CPU. Each task references two "clamp buckets" defining its minimum

and maximum (util_{min,max}) utilization "clamp values". A CPU's clamp

bucket is active if there is at least one RUNNABLE tasks enqueued on

that CPU and refcounting that bucket.

When a task is {en,de}queued {on,from} a rq, the set of active clamp

buckets on that CPU can change. If the set of active clamp buckets

changes for a CPU a new "aggregated" clamp value is computed for that

CPU. This is because each clamp bucket enforces a different utilization

clamp value.

Clamp values are always MAX aggregated for both util_min and util_max.

This ensures that no task can affect the performance of other

co-scheduled tasks which are more boosted (i.e. with higher util_min

clamp) or less capped (i.e. with higher util_max clamp).

A tasks has:

task_struct::uclamp[clamp_id]::bucket_id

to track the "bucket index" of the CPU's clamp bucket it refcounts while

enqueued, for each clamp index (clamp_id).

A runqueue has:

rq::uclamp[clamp_id]::bucket[bucket_id].tasks

to track how many RUNNABLE tasks on that CPU refcount each

clamp bucket (bucket_id) of a clamp index (clamp_id).

It also has a:

rq::uclamp[clamp_id]::bucket[bucket_id].value

to track the clamp value of each clamp bucket (bucket_id) of a clamp

index (clamp_id).

The rq::uclamp::bucket[clamp_id][] array is scanned every time it's

needed to find a new MAX aggregated clamp value for a clamp_id. This

operation is required only when it's dequeued the last task of a clamp

bucket tracking the current MAX aggregated clamp value. In this case,

the CPU is either entering IDLE or going to schedule a less boosted or

more clamped task.

The expected number of different clamp values configured at build time

is small enough to fit the full unordered array into a single cache

line, for configurations of up to 7 buckets.

Add to struct rq the basic data structures required to refcount the

number of RUNNABLE tasks for each clamp bucket. Add also the max

aggregation required to update the rq's clamp value at each

enqueue/dequeue event.

Use a simple linear mapping of clamp values into clamp buckets.

Pre-compute and cache bucket_id to avoid integer divisions at

enqueue/dequeue time.

struct rq {

    ...

#ifdef CONFIG_UCLAMP_TASK

    /* Utilization clamp values based on CPU's RUNNABLE tasks */

    //两组uclamp，分别对应min和max

    struct uclamp_rq
uclamp[UCLAMP_CNT] ____cacheline_aligned;

    //目前只有UCLAMP_FLAG_IDLE这一个标记，用于标记当前cpu是不是idle状态

    unsigned int uclamp_flags;

#define UCLAMP_FLAG_IDLE 0x01

#endif

    ...

};

/*

* struct uclamp_rq - rq's utilization clamp

* @value: currently active clamp values for a rq

* @bucket: utilization clamp buckets affecting a rq

*

* Keep track of RUNNABLE tasks on a rq to aggregate their clamp values.

* A clamp value is affecting a rq when there is at least one task RUNNABLE

* (or actually running) with that value.

*

* There are up to UCLAMP_CNT possible different clamp values, currently there

* are only two: minimum utilization and maximum utilization.

*

* All utilization clamping values are MAX aggregated, since:

* - for util_min: we want to run the CPU at least at the max of the minimum

* utilization required by its currently RUNNABLE tasks.

* - for util_max: we want to allow the CPU to run up to the max of the

* maximum utilization allowed by its currently RUNNABLE tasks.

*

* Since on each system we expect only a limited number of different

* utilization clamp values (UCLAMP_BUCKETS), use a simple array to track

* the metrics required to compute all the per-rq utilization clamp values.

*/

struct uclamp_rq {

    //当前rq生效的clamp值

    unsigned int value;

    //每个cpu上有两个桶，分别是min和max

    struct uclamp_bucket bucket[UCLAMP_BUCKETS];

};

/*

* struct uclamp_bucket - Utilization clamp bucket

* @value: utilization clamp value for tasks on this clamp bucket

* @tasks: number of RUNNABLE tasks on this clamp bucket

*

* Keep track of how many tasks are RUNNABLE for a given utilization

* clamp value.

*/

struct uclamp_bucket {

    //value表示此bucket中所有task生效clamp的最大值

    //实际上就是enqueue到rq上的线程，也就是runnable的线程

    unsigned long value : bits_per(SCHED_CAPACITY_SCALE);

    //记录当前bucket内有多少个task

    unsigned long tasks : BITS_PER_LONG - bits_per(SCHED_CAPACITY_SCALE);

};

/**

* bits_per - calculate the number of bits required for the argument

* @n: parameter

*

* This is constant-capable and can be used for compile time

* initializations, e.g bitfields.

*

* The first few values calculated by this routine:

* bf(0) = 1

* bf(1) = 1

* bf(2) = 2

* bf(3) = 2

* bf(4) = 3

* ... and so on.

*/

#define bits_per(n)                \

(                        \

    __builtin_constant_p(n) ? (        \

        ((n) == 0 || (n) == 1)        \

            ? 1 : ilog2(n) + 1    \

    ) :                    \

    __bits_per(n)                \

)

struct sched_class {

#ifdef CONFIG_UCLAMP_TASK

    //标记这个调度类是否使能了uclamp机制，cfs和rt调度类默认是使能的

    int uclamp_enabled;

#endif

    ...

}

static inline void uclamp_rq_inc(

            struct rq *rq,

            struct task_struct *p)            //要enqueue到上面rq上的task

{

    enum uclamp_id clamp_id;

    /*

     * Avoid any overhead until uclamp is actually used by the userspace.

     *

     * The condition is constructed such that a NOP is generated when

     * sched_uclamp_used is disabled.

     */

    //1.由上面的注释可知，static_key可以避免用户空间的任何开销，直到该

    // 功能被真正的使能，当uclamp被禁用时，下面的语句实际上就是一句NOP

    // 好牛逼的样子，下次一定出一篇文章好好研究研究

    if (!static_branch_unlikely(&sched_uclamp_used))

        return;

    //2.目前cfs和rt调度类默认都是使能了该标记的

    if (unlikely(!p->sched_class->uclamp_enabled))

        return;

    //3.遍历每一个uclamp，执行加操作

    for_each_clamp_id(clamp_id)

        uclamp_rq_inc_id(rq, p, clamp_id);

    /* Reset clamp idle holding when there is one RUNNABLE task */

    //4.UCLAMP_FLAG_IDLE标记这个cpu当前是不是处于idle状态，也就是这个

    // cpu对应的rq上是不是没有任何task。上面刚enqueue一个task上来，

    // 这个cpu也就不再是idle了，如果设置了该标记，则取消

    if (rq->uclamp_flags & UCLAMP_FLAG_IDLE)

        rq->uclamp_flags &= ~UCLAMP_FLAG_IDLE;

}

/*

* When a task is enqueued on a rq, the clamp bucket currently defined by the

* task's uclamp::bucket_id is refcounted on that rq. This also immediately

* updates the rq's clamp value if required.

*

* Tasks can have a task-specific value requested from user-space, track

* within each bucket the maximum value for tasks refcounted in it.

* This "local max aggregation" allows to track the exact "requested" value

* for each bucket when all its RUNNABLE tasks require the same clamp.

*/

static inline void uclamp_rq_inc_id(

            struct rq *rq,

            struct task_struct *p,            //要enqueue到上面rq上的task

            enum uclamp_id clamp_id)            //标记min还是max

{

    struct uclamp_rq *uc_rq = &rq->uclamp[clamp_id];

    struct uclamp_se *uc_se = &p->uclamp[clamp_id];

    struct uclamp_bucket *bucket;

    lockdep_assert_held(&rq->lock);

    /* Update task effective clamp */

    //1.在enqueue的时候更新这个task的有效uclamp值，即task->uclamp

    // 这个task的有效uclamp，是uclamp_req受group和system共同嵌制后的值

    p->uclamp[clamp_id] = uclamp_eff_get(p, clamp_id);

    //2.根据这个task最终有效的uclamp信息，将这个task规划进rq对应的桶中

    bucket = &uc_rq->bucket[uc_se->bucket_id];

    bucket->tasks++;

    uc_se->active = true;

    //3.通过UCLAMP_FLAG_IDLE标记，判断rq是否是刚从idle中退出，如果刚刚退出idle，

    // 说明rq上当前只有这一个task，则设置rq->uclamp[clamp_id].value为这个刚

    // enqueue进来的task的有效uclamp值，即p->uclamp[clamp_id]

    uclamp_idle_reset(rq, clamp_id, uc_se->value);

    /*

     * Local max aggregation: rq buckets always track the max

     * "requested" clamp value of its RUNNABLE tasks.

     */

    //4.注意：

    // 一个bucket的value，是这个bucket中所有task的uclamp值的

    // 最大值（不管是uclamp_min还是uclamp_max都是最大值），这也

    // 是上面为什么说，uclamp小的task将会受益于uclamp大的task

    if (bucket->tasks == 1 || uc_se->value > bucket->value)

        bucket->value = uc_se->value;

    //5.注意：

    // 这里修改了rq->uclamp[clamp_id].value，这个值始终记录着这个

    // cpu上所有task中uclamp的最大值（不管是uclamp_min还是uclamp_max

    // 都是取最大值），这个在后面uclamp_rq_util_with中计算cpu的util

    // 的时候，这个cpu上所有uclamp较低的task，都将受益于这个uclamp

    // 最高的task，例如这个cpu上有一个任务的uclamp_min值设置为1024，

    // 那么在获取cpu的util值的时候会得到1024，拿他去调频将会把cpu的

    // 频率拉满，这可能会对功耗造成影响

    if (uc_se->value > READ_ONCE(uc_rq->value))

        WRITE_ONCE(uc_rq->value, uc_se->value);

}

static inline void uclamp_idle_reset(

            struct rq *rq,                        //这个task刚被enqueue到那个cpu上

            enum uclamp_id clamp_id,

            unsigned int clamp_value)            //刚enqueue上来的task对应的uclamp值

{

    /* Reset max-clamp retention only on idle exit */

    //1.如果在这个task的uclamp被规划进来之前，这个cpu是处于idle

    // 状态，也就是这个刚enqueue进来的task是这个rq上第一个task，

    // 此时将这个task的uclamp赋值给rq->uclamp[clamp_id].value，

    // 因为老子是第一个task，否则直接返回

    if (!(rq->uclamp_flags & UCLAMP_FLAG_IDLE))

        return;

    //2.代码走到这里，表示这个rq之前还是处于idle状态，但是刚queue上来

    // 一个task后，这个rq便从idle状态中退出，此时这个rq上也只有

    // 这么一个task，此时这个rq的uclamp就是这个task的uclamp信息

    WRITE_ONCE(rq->uclamp[clamp_id].value, clamp_value);

}

static inline void uclamp_rq_dec(struct rq *rq, struct task_struct *p)

{

    enum uclamp_id clamp_id;

    /*

     * Avoid any overhead until uclamp is actually used by the userspace.

     *

     * The condition is constructed such that a NOP is generated when

     * sched_uclamp_used is disabled.

     */

    //1.超级牛逼的static_key

    if (!static_branch_unlikely(&sched_uclamp_used))

        return;

    //2.cfs和rt默认是使能的

    if (unlikely(!p->sched_class->uclamp_enabled))

        return;

    //3.依次设置min和max

    for_each_clamp_id(clamp_id)

        uclamp_rq_dec_id(rq, p, clamp_id);

}

/*

* When a task is dequeued from a rq, the clamp bucket refcounted by the task

* is released. If this is the last task reference counting the rq's max

* active clamp value, then the rq's clamp value is updated.

*

* Both refcounted tasks and rq's cached clamp values are expected to be

* always valid. If it's detected they are not, as defensive programming,

* enforce the expected state and warn.

*/

static inline void uclamp_rq_dec_id(

            struct rq *rq,

            struct task_struct *p,                //要从上面rq中dequeue的task

            enum uclamp_id clamp_id)                //要dequeue的task对应的uclamp

{

    struct uclamp_rq *uc_rq = &rq->uclamp[clamp_id];

    struct uclamp_se *uc_se = &p->uclamp[clamp_id];

    struct uclamp_bucket *bucket;

    unsigned int bkt_clamp;

    unsigned int rq_clamp;

    lockdep_assert_held(&rq->lock);