Documentation/schedule/sched-bwc

Chinese translated version of Documentation/00-INDEX

If you have any comment or update to the content, please contact the
original document maintainer directly.  However, if you have a problem
communicating in English you can also ask the Chinese maintainer for
help.  Contact the Chinese maintainer if this translation is outdated
or if there is a problem with the translation.

Chinese maintainer: LiuLu <541748097@qq.com>
---------------------------------------------------------------------
Documentation/00-INDEX 的中文翻译

如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
译存在问题，请联系中文版维护者。

中文版维护者： 刘璐  <541748097@qq.com>
中文版翻译者： 刘璐  <541748097@qq.com>
中文版校译者： 刘璐  <541748097@qq.com>

CFS Bandwidth Control
CFS 带宽控制
=====================


[ This document only discusses CPU bandwidth control for SCHED_NORMAL.
  这份文档仅仅讨论对于普通调度的CPU带宽控制。
  The SCHED_RT case is covered in Documentation/scheduler/sched-rt-group.txt ]
  CHED_RT 事件已经包含在 Documentation/scheduler/sched-rt-group.txt。


CFS bandwidth control is a CONFIG_FAIR_GROUP_SCHED extension which allows the
specification of the maximum CPU bandwidth available to a group or hierarchy.
CFS的带宽控制是一个CONFIG_FAIR_GROUP_SCHED的的的扩展，允许CPU的最大带宽规格的一组或层次。


The bandwidth allowed for a group is specified using a quota and period. Within
each given "period" (microseconds), a group is allowed to consume only up to
"quota" microseconds of CPU time.  When the CPU bandwidth consumption of a
group exceeds this limit (for that period), the tasks belonging to its
hierarchy will be throttled and are not allowed to run again until the next
period.
允许一组指定的带宽使用配额和周期。每个给定的“期间”（微秒）内，一组最多只允许消耗
“配额”微秒的CPU时间。当CPU的带宽消耗组大小超出该限制（在该段期间），属于其的任务
层次结构将被扼杀，且不得再次运行，直到下一个周期。


A group's unused runtime is globally tracked, being refreshed with quota units
above at each period boundary.  As threads consume this bandwidth it is
transferred to cpu-local "silos" on a demand basis.  The amount transferred
within each of these updates is tunable and described as the "slice".
A组的未使用的运行时间被全球定位跟踪时，会和配额单位在每个周期边界之前被刷新。
线程消耗带宽转移到CPU本地需求的基础上的“孤岛”。转让额度于每个这些更新是可调的，
并描述为“片状”。


Management
管理
----------
Quota and period are managed within the cpu subsystem via cgroupfs.
通过cgroupfs， 配额和周期都在CPU子系统被管理。


cpu.cfs_quota_us: the total available run-time within a period (in microseconds)
                  在每个周期内一共可适用的运行事件（微妙以内）
cpu.cfs_period_us: the length of a period (in microseconds)
                   一个周期长度（微妙以内）
cpu.stat: exports throttling statistics [explained further below]
          出口节流统计[下文进一步解释]


The default values are:
默认值：
cpu.cfs_period_us=100ms
cpu.cfs_quota=-1


A value of -1 for cpu.cfs_quota_us indicates that the group does not have any
bandwidth restriction in place, such a group is described as an unconstrained
bandwidth group.  This represents the traditional work-conserving behavior for
CFS.
cpu.cfs_quota_us的值是-1表示该组没有任何带宽限制的地方，这样的基团被描述为一个
无约束带宽组。这代表了传统的保护工作的行为是CFS。


Writing any (valid) positive value(s) will enact the specified bandwidth limit.
The minimum quota allowed for the quota or period is 1ms.  There is also an
upper bound on the period length of 1s.  Additional restrictions exist when
bandwidth limits are used in a hierarchical fashion, these are explained in
more detail below.
编写任何（有效）阳性值（s）将制定指定的带宽限制。额度或周期所允许的最低额度为1ms。
此外，还有一个上限1周期长度。存在其他限制时，带宽的限制是用于在一个分层的方式，
这些都会在更详细的说明里进行解释。


Writing any negative value to cpu.cfs_quota_us will remove the bandwidth limit
and return the group to an unconstrained state once more.
写任何负值给cpu.cfs_quota_us将删除带宽限制，并且返回该组的一次不受约束的状态。


Any updates to a group's bandwidth specification will result in it becoming
unthrottled if it is in a constrained state.
任何一组的带宽规格的更新如果是在约束状态下不，会其导致不能调整。


System wide settings
系统宽度设置
--------------------
For efficiency run-time is transferred between the global pool and CPU local
"silos" in a batch fashion.  This greatly reduces global accounting pressure
on large systems.  The amount transferred each time such an update is required
is described as the "slice".
为了提高效率，运行时间会在全局池和CPU局部“孤岛”之间被转移。这大大降低了在大型系统的
全球计算压力。调入量每次需要更新被描述为“片状”。


This is tunable via procfs:
这是通过procfs的可调：
/proc/sys/kernel/sched_cfs_bandwidth_slice_us (default=5ms)


Larger slice values will reduce transfer overheads, while smaller values allow
for more fine-grained consumption.
较大的切片值会降低传输费用，而较小的值允许为更细粒度消费。


Statistics
统计
----------
A group's bandwidth statistics are exported via 3 fields in cpu.stat.
A组的带宽统计数据通过3场cpu.stat导出。


cpu.stat:
- nr_periods: Number of enforcement intervals that have elapsed.
              执行后所经过的时间间隔数。
- nr_throttled: Number of times the group has been throttled/limited.
                这组的时间数目会被节流/限制。
- throttled_time: The total time duration (in nanoseconds) for which entities
  of the group have been throttled.
                  总的持续时间（纳秒）的实体对于该组已被扼杀。


This interface is read-only.
这个接口是只读。
Hierarchical considerations
分层考虑
---------------------------
The interface enforces that an individual entity's bandwidth is always
attainable, that is: max(c_i) <= C. However, over-subscription in the
aggregate case is explicitly allowed to enable work-conserving semantics
within a hierarchy.
接口强制执行，个别实体的带宽永远是实现的，那就是：max(c_i) <= C.然而，过度认购
在总的情况下是明确允许启用工作节约的语义在一个层次。
  e.g. \Sum (c_i) may exceed C
[ Where C is the parent's bandwidth, and c_i its children ]
[C 是父带宽，而c_i是它的子带宽]




There are two ways in which a group may become throttled:
a. it fully consumes its own quota within a period
b. a parent's quota is fully consumed within its period
其中一组有可能成为节流的方法有两种：
        a.它完全消耗自己的配额的期限内
        b.父母的配额被完全消耗其周期内


In case b) above, even though the child may have runtime remaining it will not
be allowed to until the parent's runtime is refreshed.
在b事件内，所有的，甚至是孩子的可能已经在运行时，其余的也不会
允许被刷新，直到父辈的运行。


Examples
例子
--------
1. Limit a group to 1 CPU worth of runtime.
   限制一组价值一个CPU的运行时间 


If period is 250ms and quota is also 250ms, the group will get
1 CPU worth of runtime every 250ms.
        如果周期为250ms，配额为250ms，该组每250ms将得到价值1个CPU运行时。


# echo 250000 > cpu.cfs_quota_us /* quota = 250ms */
# echo 250000 > cpu.cfs_period_us /* period = 250ms */


2. Limit a group to 2 CPUs worth of runtime on a multi-CPU machine.
   限制一组价值2个CPU在多个CPU的机器上运行。


With 500ms period and 1000ms quota, the group can get 2 CPUs worth of
runtime every 500ms.
       周期为500ms，配额为1000ms，该组每500ms可以得到价值2个CPU的运行时间


# echo 1000000 > cpu.cfs_quota_us /* quota = 1000ms */
# echo 500000 > cpu.cfs_period_us /* period = 500ms */


The larger period here allows for increased burst capacity.
       最大的周期将允许增加爆裂容量。


3. Limit a group to 20% of 1 CPU.
   限制该组是1个CPU的20%


With 50ms period, 10ms quota will be equivalent to 20% of 1 CPU.
        周期为50ms，配额为10ms，将和1个CPU的20%的运行时间相等


# echo 10000 > cpu.cfs_quota_us /* quota = 10ms */
# echo 50000 > cpu.cfs_period_us /* period = 50ms */


By using a small period here we are ensuring a consistent latency
response at the expense of burst capacity.
        在这里使用一个小的时期，我们将确信连续的潜伏期是以响应突发容量为代价的。