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

[Sasha Levin <sashal@kernel.org>]

From: Zhe Liu <liuzhe1@kylinos.cn>

[ Upstream commit 3345c7248a9e2a91cb9e2477c29af16881706f4f ]

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 v5.0;
  * 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>
Reviewed-by: Tao Cui <cuitao@kylinos.cn>
Signed-off-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Sasha Levin <sashal@kernel.org>
---

LLM Generated explanations, may be completely bogus:

I have enough to decide: this is a docs-only correction of text that is
already wrong in 6.12, and the rewrite matches features this tree
actually ships.

===============================================================
PHASE 1: COMMIT MESSAGE FORENSICS
===============================================================

Step 1.1: PARSE THE SUBJECT LINE
Record: [docs / cgroup-v2] [fix] [rewrite the stale IO controller
introduction so it no longer claims CFQ-only weights and no blk-mq
support]

Step 1.2: PARSE ALL COMMIT MESSAGE TAGS
Record:
- Signed-off-by: Zhe Liu <liuzhe1@kylinos.cn> (author)
- Reviewed-by: Tao Cui <cuitao@kylinos.cn>
- Signed-off-by: Tejun Heo <tj@kernel.org> (cgroup maintainer; applied
  the patch)
- No Fixes: tag (expected)
- No Reported-by / Tested-by / Link / Cc: stable
- Ignore any pipeline-added Sasha Levin SOB / "[Upstream commit ...]"
  markers; they are not evidence of selection

Notable pattern: maintainer SOB plus a Reviewed-by; single standalone
patch, not a series.

Step 1.3: ANALYZE THE COMMIT BODY TEXT
Record:
- [Bug] Admin-guide intro for the cgroup v2 "io" controller still says
  weight-based control needs cfq-iosched and that neither weight nor
  limits work on blk-mq.
- [Symptom] Operators reading the intro are told IO control does not
  work on modern (blk-mq-only) kernels, which contradicts the rest of
  the same document.
- [Version info] Text written in 2015; cfq-iosched removed in v5.0; blk-
  mq is now the only block path.
- [Root cause] Documentation was never updated after CFQ removal and
  after iocost / iolatency / ioprio / BFQ cgroup support landed. The
  rest of the section already documents io.weight, io.max,
  io.cost.{qos,model}, io.latency, and io.prio.class.

Step 1.4: DETECT HIDDEN BUG FIXES
Record: Not a hidden runtime bug. It is an explicit documentation
correction of obsolete, contradictory admin-guide text. No leak/race/UAF
disguised as cleanup.

===============================================================
PHASE 2: DIFF ANALYSIS - LINE BY LINE
===============================================================

Step 2.1: INVENTORY THE CHANGES
Record:
- File: `Documentation/admin-guide/cgroup-v2.rst` (+7 / -3, 10 lines
  with context)
- Functions modified: none (prose only)
- Scope: single-file surgical documentation rewrite of one introductory
  paragraph

Step 2.2: UNDERSTAND THE CODE FLOW CHANGE
Record:
- Before: "weight based distribution is available only if cfq-iosched is
  in use and neither scheme is available for blk-mq devices."
- After: Absolute BPS/IOPS limits via blk-throttle on all devices;
  proportional weight via iocost (`CONFIG_BLK_CGROUP_IOCOST`) and BFQ
  (`io.bfq.weight` when BFQ is the device scheduler); also iolatency
  (`CONFIG_BLK_CGROUP_IOLATENCY`) and ioprio
  (`CONFIG_BLK_CGROUP_IOPRIO`).
- Path affected: documentation readers only; no kernel execution path.

Step 2.3: IDENTIFY THE BUG MECHANISM
Record: [Logic / correctness in documentation] The intro describes
2015-era CFQ/legacy-request_fn constraints that do not exist in this
tree. Not a memory-safety, locking, or refcount bug.

Step 2.4: ASSESS THE FIX QUALITY
Record:
- Obviously correct relative to this tree: CFQ is gone, blk-mq is the
  I/O path, and the named configs/files exist.
- Minimal: one paragraph, no unrelated edits.
- Regression risk: none at runtime. Residual docs risk is only if the
  new sentence were wrong; it matches `block/Kconfig`,
  `block/Kconfig.iosched`, and the later IO sections of the same file.
  `io.bfq.weight` is documented in `Documentation/block/bfq-
  iosched.rst`, not in the cgroup-v2 interface-file list; that is
  consistent with the intro pointing at BFQ's own cgroup support.

===============================================================
PHASE 3: GIT HISTORY INVESTIGATION
===============================================================

Step 3.1: BLAME THE CHANGED LINES
Record: Stale paragraph introduced by `6c2920926b10e8` ("cgroup: replace
unified-hierarchy.txt with a proper cgroup v2 documentation", Tejun Heo,
2015-11-16). Present since cgroup v2 docs were written. Converted to rST
by `633b11bee40c37` (2017) without changing that claim. `git merge-base
--is-ancestor 6c2920926b10e8 HEAD` succeeded.

Step 3.2: FOLLOW THE FIXES: TAG
Record: No Fixes: tag. Not applicable. The "bug" is long-lived stale
documentation, not a later functional regression.

Step 3.3: CHECK FILE HISTORY FOR RELATED CHANGES
Record: Recent `cgroup-v2.rst` changes in this tree are unrelated
(writeback folio conversion, mm/zswap docs, cgroup-for-6.12 merge). No
prerequisite refactor of the IO intro. Standalone one-patch change (b4:
v1 only, not patch X/Y).

Step 3.4: CHECK THE AUTHOR'S OTHER COMMITS
Record: Zhe Liu has this one commit on `origin/master` for this file.
Tejun Heo (cgroup maintainer) applied it. Tao Cui reviewed and corrected
the CFQ-removal version in the commit message from v4.12 to v5.0.

Step 3.5: CHECK FOR DEPENDENT/PREREQUISITE COMMITS
Record: No code-structure dependencies. The rewrite only names
controllers/configs that already exist in 6.12 (`BLK_CGROUP_IOCOST`,
`BLK_CGROUP_IOLATENCY`, `BLK_CGROUP_IOPRIO`, `BFQ_GROUP_IOSCHED`,
`BLK_DEV_THROTTLING`). Can apply standalone. `git show 3345c7248a9e2 |
git apply --check` succeeded at offset -172 lines.

===============================================================
PHASE 4: MAILING LIST AND EXTERNAL RESEARCH
===============================================================

Step 4.1: FIND THE ORIGINAL PATCH DISCUSSION
Record:
- Commit: `3345c7248a9e2a91cb9e2477c29af16881706f4f` (not an ancestor of
  this HEAD; `git merge-base --is-ancestor` exit 1)
- b4 dig:
  https://patch.msgid.link/20260810063535.327765-1-liuzhe1@kylinos.cn
- Single v1 series; no v2/v3. Tejun applied v1 after fixing the CFQ
  version in the changelog.
- Reviewer feedback: Tao Cui, "cfq-iosched was removed in v5.0, not
  v4.12 (f382fb0bcef4)". Otherwise "looks good." Reviewed-by added.
- Tejun: "Applied to cgroup/for-7.3 with the cfq removal version in the
  description corrected to v5.0"
- No NAK, no stable nomination in the thread
- Included in the v7.3 cgroup pull (`[GIT PULL] cgroup: Changes for
  v7.3`)
- Later `origin/master` text of this paragraph is unchanged; no follow-
  up rewrite

Step 4.2: CHECK WHO REVIEWED THE PATCH
Record (b4 dig -w): To/Cc included tj@kernel.org, hannes@cmpxchg.org,
mkoutny@suse.com, corbet@lwn.net, skhan@linuxfoundation.org, cgroups@,
linux-doc@, linux-kernel@. Those are the cgroup maintainers plus linux-
doc. Applied by Tejun Heo.

Step 4.3: SEARCH FOR THE BUG REPORT
Record: No Reported-by, bugzilla, or syzbot. Author noticed the intro
contradicting the rest of the same document. Severity from a reporter's
perspective: documentation accuracy, not a crash.

Step 4.4: CHECK FOR RELATED PATCHES AND SERIES
Record: Standalone. Later cgroup-v2 doc commits on `origin/master`
(misc.events, io.latency rotational, io.pressure, etc.) do not touch
this paragraph and are not prerequisites.

Step 4.5: CHECK STABLE MAILING LIST HISTORY
Record: lore.kernel.org/stable WebFetch returned HTTP 403. UNVERIFIED
whether anyone already requested or rejected this on stable@. No
evidence from b4 or lkml mirrors of a stable discussion.

===============================================================
PHASE 5: CODE SEMANTIC ANALYSIS
===============================================================

Step 5.1: IDENTIFY KEY FUNCTIONS IN THE DIFF
Record: None. Documentation only.

Step 5.2: TRACE CALLERS
Record: N/A — no functions. Impact surface is readers of the cgroup v2
admin guide (container/cgroup operators), not a call graph.

Step 5.3: TRACE CALLEES
Record: N/A.

Step 5.4: FOLLOW THE CALL CHAIN
Record: N/A for kernel reachability. The misleading text is in the
primary user-facing cgroup v2 document. Userspace does not "trigger" a
bug; operators can be misled about whether io.max / io.weight work.

Step 5.5: SEARCH FOR SIMILAR PATTERNS
Record: `cfq-iosched` in this tree's docs remains only in this stale
intro (plus an unrelated historical RCU lockdep-splat example).
`init/Kconfig` BLK_CGROUP help still mentions CFQ; that is a separate
stale-help issue, not part of this patch.

===============================================================
PHASE 6: CROSS-REFERENCING AGAINST THE LOCAL TREE
===============================================================

Step 6.1: DOES THE BUGGY CODE EXIST IN THIS TREE?
Record: Yes. Local tree is **6.12.111** (`pending-6.12`, `git describe
HEAD` = p-6.12-3-gc504cf0baa3d8). Stale text is at `Documentation/admin-
guide/cgroup-v2.rst` lines 1834–1838. Features the rewrite describes are
present:
- CFQ source `block/cfq-iosched.c` absent; removed by `f382fb0bcef4`
  (ancestor of HEAD)
- iocost: `block/blk-iocost.c`, `CONFIG_BLK_CGROUP_IOCOST`
  (`7caa47151ab2e`, ancestor)
- iolatency: `block/blk-iolatency.c` (`d70675121546c`, ancestor)
- ioprio: `block/blk-ioprio.c` (`556910e39249d`, ancestor)
- blk-throttle: `CONFIG_BLK_DEV_THROTTLING`
- BFQ cgroup: `CONFIG_BFQ_GROUP_IOSCHED`, `io.bfq.weight` in
  `Documentation/block/bfq-iosched.rst`
- Same file already documents io.cost.*, io.weight, io.max, io.latency,
  io.prio.class

Step 6.2: CHECK FOR BACKPORT COMPLICATIONS
Record: Clean apply with hunk offset -172 (upstream intro at ~1988; this
tree at ~1833). Surrounding Memory Ownership / IO Interface Files
context matches. Difficulty: clean apply.

Step 6.3: CHECK IF RELATED FIXES ARE ALREADY HERE
Record: `git log --grep='stale "io" controller'` and `--grep='cfq-
iosched'` on this file: empty. No equivalent fix in this checkout. `git
merge-base --is-ancestor 3345c7248a9e2 HEAD` failed.

===============================================================
PHASE 7: SUBSYSTEM AND MAINTAINER CONTEXT
===============================================================

Step 7.1: IDENTIFY THE SUBSYSTEM AND ITS CRITICALITY
Record: [Documentation / cgroup v2 admin-guide] Criticality: IMPORTANT
for operators (the user-facing contract for cgroup IO), PERIPHERAL for
kernel runtime (no code change). MAINTAINERS: CONTROL GROUP, Tejun Heo
et al., file `Documentation/admin-guide/cgroup-v2.rst`.

Step 7.2: ASSESS SUBSYSTEM ACTIVITY
Record: cgroup-v2.rst still receives interface-doc updates. The IO intro
itself has been untouched since 2015. Mature, long-stale paragraph
rather than a bug in brand-new code.

===============================================================
PHASE 8: IMPACT AND RISK ASSESSMENT
===============================================================

Step 8.1: DETERMINE WHO IS AFFECTED
Record: Anyone reading the cgroup v2 IO intro on 6.12 (container hosts,
systemd/cgroup users, Kubernetes node kernels). Not a
runtime/config/platform subset. No kernel code path changes.

Step 8.2: DETERMINE THE TRIGGER CONDITIONS
Record: Reading the admin guide. Common for operators enabling IO
control. Not a race; not triggerable as a crash by unprivileged users.

Step 8.3: DETERMINE THE FAILURE MODE SEVERITY
Record: [Failure mode] Contradictory, obsolete documentation: claims IO
weight/limits do not work on blk-mq, i.e. on essentially all 6.12 block
devices. [Severity] LOW as kernel runtime; the rest of the same chapter
already describes working interfaces. The harm is misleading operators,
not oops/corruption/deadlock.

Step 8.4: CALCULATE RISK-BENEFIT RATIO
Record:
- Benefit: medium for documentation accuracy of a widely used
  controller; the intro currently tells 6.12 users the opposite of
  reality.
- Risk: very low (docs-only, 7 insertions / 3 deletions, apply-check
  clean).
- Ratio: high benefit-to-risk for a documentation exception; no runtime
  regression vector.

===============================================================
PHASE 9: FINAL SYNTHESIS
===============================================================

Step 9.1: COMPILE THE EVIDENCE
FOR:
- Stale intro is present in this 6.12 tree and is factually false here
  (CFQ gone since v5.0; blk-mq-only; iocost/iolatency/ioprio/BFQ all
  present).
- Same document already documents the working interfaces; the intro is
  the part that contradicts them.
- Small, obviously correct, maintainer-applied (Tejun Heo), Reviewed-by
  Tao Cui.
- Applies cleanly.
- Zero runtime risk.
- Documentation/comment fixes are an allowed stable exception.
- This pending-6.12 tree already carries other `docs:` backports under
  `Documentation/admin-guide/`.

AGAINST:
- Not a crash, UAF, deadlock, corruption, or security hole.
- No user report / syzbot / Cc: stable (absence of Cc: stable is
  expected and not a negative).
- Later sections already describe the real interfaces, so a careful
  reader can recover.
- `stable-kernel-rules.rst` also says no trivial-without-benefit
  changes; this is more than spelling, but it is still docs-only.

UNRESOLVED:
- lore.kernel.org/stable search HTTP 403; no confirmed stable@ thread.

Step 9.2: APPLY THE STABLE RULES CHECKLIST
1. Obviously correct and tested? **PASS** — matches Kconfig and the rest
   of the same document; reviewed and applied by the cgroup maintainer.
2. Fixes a real bug that affects users? **PASS** (documentation bug) —
   the intro is wrong for every 6.12 blk-mq system.
3. Important issue (crash, security, corruption, deadlock)? **FAIL** as
   a runtime severity; **PASS** under the documentation exception
   (incorrect admin-guide, not a spelling nit).
4. Small and contained? **PASS** — 10 lines, one file.
5. No new features or APIs? **PASS** — describes existing 6.12
   interfaces only.
6. Can apply to the local tree? **PASS** — `git apply --check`
   succeeded.

Step 9.3: CHECK FOR EXCEPTION CATEGORIES
Record: **Documentation fix** (incorrect/obsolete admin-guide text).
That exception applies. Not a device-ID, quirk, DT, or build fix.

Step 9.4: MAKE YOUR DECISION
This should be backported to **this** 6.12 tree. The buggy paragraph is
here, the features the new text describes are here, the patch applies,
and runtime risk is zero. Stable rules allow documentation corrections
of incorrect material; this is not a feature add and not a whitespace
cleanup.

What it solves for stable users: the cgroup v2 admin guide currently
says weight-based IO control needs CFQ and that neither weights nor
limits work on blk-mq. On 6.12 that is false for all block devices and
contradicts io.max / io.weight / iocost / iolatency / ioprio in the same
file.

Risk vs benefit: documentation-only, surgical, maintainer-acked; benefit
is correcting the primary operator document for a common container
feature.

Concerns: none on apply or prerequisites. Not a crash-class fix;
accepted because it is a contained docs correction of still-present
stale text.

Verification:
- [Phase 1] Parsed tags: SOB Zhe Liu, Reviewed-by Tao Cui, SOB Tejun
  Heo; no Fixes/Reported-by/Cc: stable
- [Phase 1] Body: stale 2015 CFQ/blk-mq claims; cfq removed v5.0
- [Phase 2] Diff: `Documentation/admin-guide/cgroup-v2.rst` +7/-3, IO
  intro only
- [Phase 3] `git describe HEAD` / `make kernelversion`:
  p-6.12-3-gc504cf0baa3d8, 6.12.111, branch pending-6.12
- [Phase 3] `git blame`: stale lines from `6c2920926b10e8` (2015);
  ancestor of HEAD
- [Phase 3] `git merge-base --is-ancestor 3345c7248a9e2 HEAD`: not in
  this tree
- [Phase 3] CFQ removal `f382fb0bcef4` is ancestor; no `block/cfq-
  iosched.c`
- [Phase 3] iocost `7caa47151ab2e`, iolatency `d70675121546c`, ioprio
  `556910e39249d` are ancestors
- [Phase 3] `git apply --check` of 3345c7248a9e2: hunk succeeded at 1833
  (offset -172)
- [Phase 4] b4 dig -c 3345c7248a9e2: msgid
  20260810063535.327765-1-liuzhe1@kylinos.cn
- [Phase 4] b4 dig -a: v1 only
- [Phase 4] b4 dig -w: cgroup maintainers + linux-doc on the original
  To/Cc
- [Phase 4] lkml/openwall: Tao Cui v5.0 correction; Tejun applied to
  cgroup/for-7.3; no NAK
- [Phase 4] origin/master still has the rewritten paragraph; no later
  rewrite
- [Phase 4] lore.kernel.org/stable: HTTP 403, UNVERIFIED
- [Phase 5] No functions/callers; docs-only
- [Phase 6] Stale text at lines 1834–1838 of this tree's cgroup-v2.rst;
  io.cost/io.weight/io.max/io.latency/io.prio.class already documented
  below
- [Phase 6] `CONFIG_BLK_CGROUP_IOCOST`, `IOLATENCY`, `IOPRIO`,
  `BFQ_GROUP_IOSCHED`, `BLK_DEV_THROTTLING` exist in this tree
- [Phase 7] MAINTAINERS CONTROL GROUP: Tejun Heo; file listed
- [Phase 8] Failure mode: misleading admin-guide, severity LOW runtime /
  docs exception
- UNVERIFIED: whether this SHA was already discussed on stable@

**YES**

 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 edcd125d6992f..a62505e55dd07 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1959,9 +1959,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.53.0