[PATCH] docs: cgroup-v2: fix stale "io" controller introduction

[PATCH] docs: cgroup-v2: fix stale "io" controller introduction

[Zhe Liu]

The introductory paragraph for the IO controller still states that
weight based distribution is "available only if cfq-iosched is in use"
and that "neither scheme is available for blk-mq devices".  This text
dates from when the cgroup v2 documentation was first written (2015)
and was correct at the time, but is no longer accurate:

  * cfq-iosched was removed in v4.12;
  * blk-mq is now the only block I/O path, and both the absolute limit
    scheme (io.max via blk-throttle) and the weight based scheme
    (io.weight via iocost, or io.bfq.weight under BFQ) work on it;
  * latency based protection (iolatency) and I/O priority (ioprio)
    controllers have since been added.

The rest of the section already documents io.weight, io.max,
io.cost.{qos,model}, io.latency and io.prio.class correctly, so the
introduction is the only part that contradicts them.  Rewrite it to
reflect the current state.

Signed-off-by: Zhe Liu <liuzhe1@kylinos.cn>
---
 Documentation/admin-guide/cgroup-v2.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index aed195a71cbf..0fbc7c963807 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1984,9 +1984,13 @@ IO
 
 The "io" controller regulates the distribution of IO resources.  This
 controller implements both weight based and absolute bandwidth or IOPS
-limit distribution; however, weight based distribution is available
-only if cfq-iosched is in use and neither scheme is available for
-blk-mq devices.
+limit distribution.  Absolute BPS and IOPS limits are enforced by
+blk-throttle and apply to all devices, while weight based proportional
+distribution is provided by the iocost cost model controller
+(CONFIG_BLK_CGROUP_IOCOST) and, when the BFQ I/O scheduler is in use
+for a device, by BFQ's own cgroup support.  Latency-based protection
+(CONFIG_BLK_CGROUP_IOLATENCY) and I/O priority assignment
+(CONFIG_BLK_CGROUP_IOPRIO) are also available.
 
 
 IO Interface Files
-- 
2.25.1

Re: [PATCH] docs: cgroup-v2: fix stale "io" controller introduction

[Tao Cui]

在 2026/8/10 14:35, Zhe Liu 写道:
> The introductory paragraph for the IO controller still states that
> weight based distribution is "available only if cfq-iosched is in use"
> and that "neither scheme is available for blk-mq devices".  This text
> dates from when the cgroup v2 documentation was first written (2015)
> and was correct at the time, but is no longer accurate:
> 
>   * cfq-iosched was removed in v4.12;
>   * blk-mq is now the only block I/O path, and both the absolute limit
>     scheme (io.max via blk-throttle) and the weight based scheme
>     (io.weight via iocost, or io.bfq.weight under BFQ) work on it;
>   * latency based protection (iolatency) and I/O priority (ioprio)
>     controllers have since been added.
> 
cfq-iosched was removed in v5.0, not v4.12 (f382fb0bcef4, "block:
remove legacy IO schedulers"). v4.12 only added the blk-mq schedulers;
cfq-iosched.c stayed until v5.0.

Otherwise looks good.

Reviewed-by: Tao Cui <cuitao@kylinos.cn>
> The rest of the section already documents io.weight, io.max,
> io.cost.{qos,model}, io.latency and io.prio.class correctly, so the
> introduction is the only part that contradicts them.  Rewrite it to
> reflect the current state.
> 
> Signed-off-by: Zhe Liu <liuzhe1@kylinos.cn>
> ---
>  Documentation/admin-guide/cgroup-v2.rst | 10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index aed195a71cbf..0fbc7c963807 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst
> @@ -1984,9 +1984,13 @@ IO
>  
>  The "io" controller regulates the distribution of IO resources.  This
>  controller implements both weight based and absolute bandwidth or IOPS
> -limit distribution; however, weight based distribution is available
> -only if cfq-iosched is in use and neither scheme is available for
> -blk-mq devices.
> +limit distribution.  Absolute BPS and IOPS limits are enforced by
> +blk-throttle and apply to all devices, while weight based proportional
> +distribution is provided by the iocost cost model controller
> +(CONFIG_BLK_CGROUP_IOCOST) and, when the BFQ I/O scheduler is in use
> +for a device, by BFQ's own cgroup support.  Latency-based protection
> +(CONFIG_BLK_CGROUP_IOLATENCY) and I/O priority assignment
> +(CONFIG_BLK_CGROUP_IOPRIO) are also available.
>  
>  
>  IO Interface Files

Re: [PATCH] docs: cgroup-v2: fix stale "io" controller introduction

[Tejun Heo]

Applied to cgroup/for-7.3 with the cfq removal version in the
description corrected to v5.0 as pointed out by Tao and his Reviewed-by
added.

Thanks.

--
tejun