[PATCH AUTOSEL 6.18] docs: update the unmount propagation rule

[PATCH AUTOSEL 6.18] docs: update the unmount propagation rule

[Sasha Levin]

From: Christian Brauner <brauner@kernel.org>

[ Upstream commit 3f5dc09141a7bfe286620a6869d1d70ffe32d6b8 ]

Section 5f still describes the rule propagate_umount() used before
commit f0d0ba19985d ("Rewrite of propagate_umount()"). It states that a
mount that receives the unmount by propagation is left alone as soon as
it has any submount. That's not true anymore.

A propagated unmount unmounts a mount with sub-mounts as long as every
sub-mount gets unmounted together with it. This is the case when the
sub-mounts are unmounted by the same propagation. Only a sub-mount that
cannot be unmounted keeps its parent mounted.

The section also only describes a single mount without sub-mounts. But
lazy unmounts take a tree and every mount of the tree propagates its
unmount from its parent mount.

Link: https://patch.msgid.link/20260923-work-mount-fixes-v1-8-f424cf8d3242@kernel.org
Signed-off-by: Christian Brauner (Amutable) <brauner@kernel.org>
Signed-off-by: Sasha Levin <sashal@kernel.org>
---

LLM Generated explanations, may be completely bogus:

This is a documentation-only correction of stale unmount-propagation
text. The local tree is **6.18.57** (`v6.18.57-155-gcdf239ca885b2`). The
rewrite it documents is already in that tree, so the question is whether
this docs update belongs here.

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

Step 1.1: PARSE THE SUBJECT LINE
Record: **[docs]** **[update]** Update the unmount propagation rule in
shared-subtree documentation.

Step 1.2: PARSE ALL COMMIT MESSAGE TAGS
Record:
- Link: `https://patch.msgid.link/20260923-work-mount-
  fixes-v1-8-f424cf8d3242@kernel.org`
- Signed-off-by: Christian Brauner (Amutable) \<brauner@kernel.org\>
- No Fixes:, Reported-by:, Tested-by:, Reviewed-by:, Acked-by:, or Cc:
  stable on this patch itself
- Cover letter of the same series (`[PATCH 0/8] mount: a few gnarly
  fixes`) did Cc stable; this 8/8 docs patch did not
- Ignore pipeline tags: `[Upstream commit 3f5dc09141a7…]`, `Signed-off-
  by: Sasha Levin`

Step 1.3: ANALYZE THE COMMIT BODY TEXT
Record:
- **Bug:** Section 5f of `sharedsubtree.rst` still describes pre-rewrite
  `propagate_umount()`: a receiver with any sub-mount is left mounted.
- **Symptom:** Documentation disagrees with current kernel behavior. A
  propagated unmount may take a mount that has children if those
  children are also unmounted by the same propagation. Only a child that
  cannot be unmounted keeps its parent.
- **Also missing:** Lazy `MNT_DETACH` unmounts a tree; every mount in
  that tree propagates from its own parent.
- **Version info:** Behavior changed in `f0d0ba19985d` (“Rewrite of
  propagate_umount()”).
- **Root cause:** Overview docs were not updated when
  `propagate_umount()` was rewritten.

Step 1.4: DETECT HIDDEN BUG FIXES
Record: Not a hidden runtime fix. It is an explicit documentation
correction of obsolete unmount semantics. No code, locking, or error-
path change.

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

Step 2.1: INVENTORY THE CHANGES
Record:
- File: `Documentation/filesystems/sharedsubtree.rst` (+14 / −6)
- One section: “f) Unmount semantics”
- Scope: single-file documentation, surgical

Step 2.2: UNDERSTAND THE CODE FLOW CHANGE
Record:
- Before: receivers at dentry `b` are unmounted only if they have no
  sub-mounts. Any child on C2/C3 blocks that receiver; C1 with sub-
  mounts fails the whole umount.
- After: receivers are unmounted if every mount below them is also
  unmounted. A child unmounted by the same propagation does not pin its
  parent. Adds lazy-umount tree propagation and a pointer to
  `Documentation/filesystems/propagate_umount.txt`.
- Path affected: documentation of umount/propagation semantics only.

Step 2.3: IDENTIFY THE BUG MECHANISM
Record:
- Category: documentation correctness (obsolete comment/docs)
- Mechanism: overview text still described the old “any sub-mount blocks
  the receiver” rule. Code after `f0d0ba19985d` unmounts a receiver when
  remaining children are themselves candidates (`trim_one()` / non-
  shifting set).

Step 2.4: ASSESS THE FIX QUALITY
Record:
- Obviously correct relative to this tree’s `propagate_umount()` and
  `propagate_umount.txt`
- Minimal; no unrelated edits
- Regression risk: none (no executable code)
- Red flags: none

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

Step 3.1: BLAME THE CHANGED LINES
Record:
- Original unmount-semantics prose: `9cfcceea8f7e8f` (Ram Pai,
  2005-11-07, `Documentation/sharedsubtree.txt`)
- ReST conversion/formatting: Bagas Sanjaya, 2025-08 (`a8886b42d57b8`,
  `b293fd55a1b89`)
- Behavior change that made the text wrong: `f0d0ba19985d` (Al Viro,
  2025-06-29, ~v6.17)
- That rewrite **is** an ancestor of this 6.18.y tree

Step 3.2: FOLLOW THE FIXES: TAG
Record: No Fixes: tag. Expected. The related behavioral commit is
`f0d0ba19985d`, already in `v6.18.57`.

Step 3.3: CHECK FILE HISTORY FOR RELATED CHANGES
Record:
- Recent `sharedsubtree.rst` work is formatting/ReST, not semantics
- Precise rules already live in
  `Documentation/filesystems/propagate_umount.txt` (added by the
  rewrite)
- Standalone: patch 8/8 of Brauner’s “mount: a few gnarly fixes”; this
  hunk does not depend on patches 1–7

Step 3.4: CHECK THE AUTHOR'S OTHER COMMITS
Record:
- Author is VFS maintainer (`FILESYSTEMS (VFS and infrastructure)` in
  MAINTAINERS)
- Same series includes real umount/mount bugfixes (busy propagated
  umount, unbindable copy, etc.)
- This patch is the docs companion, not one of those code fixes

Step 3.5: CHECK FOR DEPENDENT/PREREQUISITE COMMITS
Record:
- Depends only on the rewrite already present here, and on
  `propagate_umount.txt`, which exists at `v6.18.57`
- Can apply standalone. No new helpers or struct changes.

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

Step 4.1: FIND THE ORIGINAL PATCH DISCUSSION
Record:
- `b4 dig -c 3f5dc09141a7…` matched patch-id `0b2df883901084c2…`
- Lore URL: https://patch.msgid.link/20260923-work-mount-
  fixes-v1-8-f424cf8d3242@kernel.org
- Series: v1 only (`[PATCH 8/8] docs: update the unmount propagation
  rule`), 2026-09-23
- Cover letter: `[PATCH 0/8] mount: a few gnarly fixes`
- Direct replies in the saved thread are about patch 5/8 (`fs: don't
  silently unmount busy mounts`), not this docs patch
- No NAK, no reviewer concern, no stable nomination on 8/8 itself
- WebFetch of lore.kernel.org returned 403; thread recovered via `b4 dig
  -m`

Step 4.2: CHECK WHO REVIEWED THE PATCH
Record (`b4 dig -w`):
- Recipients: Christian Brauner, linux-fsdevel, Linus Torvalds,
  Alexander Viro, Jan Kara
- Right maintainers/lists. No extra Reviewed-by on 8/8. Brauner is both
  author and VFS maintainer.

Step 4.3: SEARCH FOR THE BUG REPORT
Record: No user/syzbot report for the docs. The body is the author’s
observation that section 5f lagged the rewrite. Severity is
documentation inaccuracy, not a crash.

Step 4.4: CHECK FOR RELATED PATCHES AND SERIES
Record:
- Series of 8: unbindable copy, MOVE_MOUNT_SET_GROUP, busy propagated
  umount, migrating-task ref, plus selftests, plus this docs update
- 8/8 does not implement those fixes; it only restates
  `propagate_umount()` after the 2025 rewrite
- Self-contained

Step 4.5: CHECK STABLE MAILING LIST HISTORY
Record:
- Cover letter Cc’d `stable@vger.kernel.org`
- Patches 1/8 and 5/8 had explicit `Cc: stable` in the body; 8/8 did not
- Direct lore.kernel.org/stable search was blocked (bot challenge). No
  additional stable-thread evidence beyond the series headers.

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

Step 5.1: IDENTIFY KEY FUNCTIONS IN THE DIFF
Record: None. Documentation only. Semcode tools are not available.

Step 5.2: TRACE CALLERS
Record: N/A for the diff. Documented behavior is implemented by
`propagate_umount()` in `fs/pnode.c`, called from `fs/namespace.c`
(`umount_tree` / `do_umount` path).

Step 5.3: TRACE CALLEES
Record: `propagate_umount()` gathers candidates, `trim_one()` /
`trim_ancestors()` enforce the non-shifting set, `handle_locked()`
enforces locked-mount (non-revealing) rules. That matches “unmount a
parent if every child is also unmounted; a child that cannot be
unmounted keeps the parent.”

Step 5.4: FOLLOW THE CALL CHAIN
Record: Reachable from `umount(2)` / `umount2(MNT_DETACH)` on
shared/slave mounts. Common container/namespace path. The **patch**
itself is not on that path; it only describes it.

Step 5.5: SEARCH FOR SIMILAR PATTERNS
Record: Detailed rules already in
`Documentation/filesystems/propagate_umount.txt`. This change makes the
overview consistent with that file instead of contradicting it.

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

Step 6.1: DOES THE BUGGY CODE EXIST IN THIS TREE?
Record:
- Local tree: VERSION 6.18.57 (`v6.18.57-155-gcdf239ca885b2`)
- Stale section 5f is present at
  `v6.18.57:Documentation/filesystems/sharedsubtree.rst` (identical to
  the candidate’s pre-image)
- Rewrite `f0d0ba19985d` **is** in `v6.18.57`
- So this tree’s kernel already uses the new rule, while the overview
  still documents the old one
- Bug introduced (as a docs mismatch) when the rewrite landed (~v6.17),
  i.e. before this 6.18 branch

Step 6.2: CHECK FOR BACKPORT COMPLICATIONS
Record: Clean apply. `diff` of `v6.18.57` vs the candidate pre-image is
empty (both 994 lines). Context matches.

Step 6.3: CHECK IF RELATED FIXES ARE ALREADY HERE
Record:
- Precise notes (`propagate_umount.txt`) already here
- Related code fix `bf2c8dec26fb7` (“fs: don't silently unmount busy
  mounts”) is already in `v6.18.57`; that does not replace this overview
  correction
- No earlier equivalent rewrite of section 5f

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

Step 7.1: IDENTIFY THE SUBSYSTEM AND ITS CRITICALITY
Record:
- Subsystem: VFS / mount namespace documentation
  (`Documentation/filesystems/`)
- Documents CORE mount/umount propagation used by containers
- The change itself is docs, not core code
- Criticality of the **text**: IMPORTANT for people who rely on shared-
  subtree docs; runtime criticality: none

Step 7.2: ASSESS SUBSYSTEM ACTIVITY
Record: Mount/namespace code is actively maintained (Brauner/Viro).
`sharedsubtree.rst` itself is old and mostly formatting churn; the
semantics gap dates to the 2025 rewrite.

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

Step 8.1: DETERMINE WHO IS AFFECTED
Record: Anyone reading shared-subtree unmount docs (container/namespace
users and developers). No runtime user population is changed.

Step 8.2: DETERMINE THE TRIGGER CONDITIONS
Record: Not a runtime trigger. The mismatch is visible whenever someone
reads section 5f and compares it to `umount` on shared mounts with
nested children.

Step 8.3: DETERMINE THE FAILURE MODE SEVERITY
Record:
- Failure mode: incorrect documentation of `umount(2)` propagation
- Userspace that trusts the old “any child blocks the receiver” rule can
  mis-predict which mounts disappear
- Accurate rules already exist in `propagate_umount.txt`
- Severity: **LOW** for runtime; **MEDIUM** as a docs bug about user-
  visible mount semantics

Step 8.4: CALCULATE RISK-BENEFIT RATIO
Record:
- Benefit: overview matches this tree’s actual `propagate_umount()`;
  avoids a documented lie about umount
- Risk: none (14 insertions / 6 deletions, docs only)
- Ratio: favorable — small, zero-risk correction of obsolete docs for
  behavior that is already here

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

Step 9.1: COMPILE THE EVIDENCE

FOR:
- Section 5f is factually wrong in this 6.18.y tree because
  `f0d0ba19985d` is present
- Stable exception for documentation/comment fixes applies
- Small, contained, maintainer-authored
- Applies cleanly to `v6.18.57`
- Points at `propagate_umount.txt`, which already exists here
- Zero runtime regression risk

AGAINST:
- No crash, UAF, deadlock, corruption, or security fix
- This patch was not itself Cc’d to stable (1/8 and 5/8 were)
- Precise behavior is already documented in `propagate_umount.txt`
- No user report of the docs bug

UNRESOLVED:
- lore.kernel.org HTTP fetch returned 403; thread was recovered with `b4
  dig`
- Could not search lore.kernel.org/stable beyond a bot wall
- No Reviewed-by on 8/8 (unverified whether silent acks existed off-
  thread)

Step 9.2: APPLY THE STABLE RULES CHECKLIST
1. Obviously correct and tested? **PASS** — text matches
   `propagate_umount()` / `propagate_umount.txt` in this tree
2. Fixes a real bug that affects users? **PASS** — obsolete description
   of user-visible umount semantics (not a runtime bug)
3. Important issue (crash, security, corruption, deadlock)? **FAIL** as
   a runtime issue; **PASS** under the documentation exception
4. Small and contained? **PASS** — +14/−6, one rst file
5. No new features or APIs? **PASS**
6. Can apply to the local tree? **PASS** — context at `v6.18.57` is
   identical

Step 9.3: CHECK FOR EXCEPTION CATEGORIES
Record: **Documentation fix** — correcting obsolete comments/docs. Zero
runtime risk.

Step 9.4: MAKE YOUR DECISION
The rewrite this documents is already in 6.18.y, the overview is still
wrong, and the patch is a tiny docs-only correction that applies
cleanly. That is exactly the documentation exception. It should be
backported to this tree.

Verification:
- [Phase 1] Parsed subject/tags: docs update; Link to patch 8/8 of work-
  mount-fixes; no Fixes/Reported-by/Cc:stable on this patch
- [Phase 1] Cover letter Cc’d stable; patches 1/8 and 5/8 had `Cc:
  stable` in the body; 8/8 did not
- [Phase 2] Diff: `Documentation/filesystems/sharedsubtree.rst` +14/−6;
  section 5f only
- [Phase 3] `git describe HEAD` / Makefile: 6.18.57
- [Phase 3] `git merge-base --is-ancestor f0d0ba19985d v6.18.57`:
  rewrite is in this tree
- [Phase 3] Blame: original text Ram Pai 2005; stale vs rewrite 2025-06
- [Phase 3] `git show
  v6.18.57:Documentation/filesystems/sharedsubtree.rst`: old “any sub-
  mounts” wording still present
- [Phase 4] `b4 dig -c 3f5dc09141a7`:
  https://patch.msgid.link/20260923-work-mount-
  fixes-v1-8-f424cf8d3242@kernel.org
- [Phase 4] `b4 dig -a`: v1 only, series of 8
- [Phase 4] `b4 dig -w`: vfs maintainers + linux-fsdevel
- [Phase 4] mbox: no NAK on 8/8; discussion was about 5/8
- [Phase 4] WebFetch lore: 403; UNVERIFIED beyond b4 mbox
- [Phase 5] Semcode unavailable; `propagate_umount()`/`trim_one()` in
  `fs/pnode.c` match the new wording
- [Phase 6] File at v6.18.57 identical to candidate pre-image (994
  lines, empty diff) — clean apply
- [Phase 6] `propagate_umount.txt` exists at v6.18.57
- [Phase 7] Author is VFS maintainer in MAINTAINERS
- [Phase 8] Failure mode: stale umount-propagation docs; severity LOW
  runtime / docs exception
- UNVERIFIED: stable-list discussion beyond series headers

This is a small, obviously correct documentation fix for mount-namespace
behavior that this tree already implements. Risk is zero.

**YES**

 Documentation/filesystems/sharedsubtree.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst
index 8b7dc91590837..8bae6d9a7e047 100644
--- a/Documentation/filesystems/sharedsubtree.rst
+++ b/Documentation/filesystems/sharedsubtree.rst
@@ -564,8 +564,8 @@ f) Unmount semantics
    where 'A' is a mount mounted on mount 'B' at dentry 'b'.
 
    If mount 'B' is shared, then all most-recently-mounted mounts at dentry
-   'b' on mounts that receive propagation from mount 'B' and does not have
-   sub-mounts within them are unmounted.
+   'b' on mounts that receive propagation from mount 'B' are unmounted as
+   well, if every mount below them is also unmounted.
 
    Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to
    each other.
@@ -584,10 +584,18 @@ f) Unmount semantics
 
    So all 'C1', 'C2' and 'C3' should be unmounted.
 
-   If any of 'C2' or 'C3' has some child mounts, then that mount is not
-   unmounted, but all other mounts are unmounted. However if 'C1' is told
-   to be unmounted and 'C1' has some sub-mounts, the umount operation is
-   failed entirely.
+   If any of 'C2' or 'C3' has a child mount that cannot be unmounted
+   then that mount is not unmounted. But all other mounts are unmounted.
+   A child mount that is itself unmounted by the same unmount
+   propagation does not keep its parent mounted. However if 'C1' is
+   supposed to be unmounted and 'C1' has some sub-mounts, the unmount
+   fails.
+
+   A lazy umount (MNT_DETACH) takes a whole tree. Every mount of the
+   tree then propagates its unmount from its own parent as described
+   above, so the mounts that receive propagation lose the corresponding
+   trees as well. Documentation/filesystems/propagate_umount.txt has the
+   precise rules, including the ones for locked mounts.
 
 g) Clone Namespace
 
-- 
2.53.0

[PATCH AUTOSEL 6.18-5.10] docs: block: fix dead http link in blk-mq.rst

[Sasha Levin]

From: Jenson Johnathon Reggentin <mail@jregg.de>

[ Upstream commit b40a680ea4efe4ef2addada63e304a94d19500d1 ]

The current link http://kernel.dk/blk-mq.pdf leads to a 404 error page.
https://www.kernel.dk/blk-mq.pdf leads to the correct document.

v2 to add the missing www. prefix in the actual file change.

Signed-off-by: Jenson Johnathon Reggentin <mail@jregg.de>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260819192422.42189-1-mail@jregg.de>
Signed-off-by: Sasha Levin <sashal@kernel.org>
---

LLM Generated explanations, may be completely bogus:

I have the tree identity, the dead URL in-tree, review history, and a
clean apply. Next I’ll finish call-site and stable-rule checks, then
give the backport verdict.

---

## PHASE 1: COMMIT MESSAGE FORENSICS

Step 1.1: PARSE THE SUBJECT LINE
Record: `[docs: block:]` `[fix]` `[dead HTTP link in blk-mq.rst]` —
documentation URL correction in the block multi-queue overview.

Step 1.2: PARSE ALL COMMIT MESSAGE TAGS
Record:
- Signed-off-by: Jenson Johnathon Reggentin `<mail@jregg.de>` (author)
- Acked-by: Randy Dunlap `<rdunlap@infradead.org>` (docs reviewer)
- Signed-off-by: Jonathan Corbet `<corbet@lwn.net>` (docs maintainer,
  applied it)
- Message-ID: `<20260819192422.42189-1-mail@jregg.de>` (v2 submission)
- No Fixes: tag (expected)
- No Reported-by / Tested-by / Reviewed-by on the committed form (v1 had
  Reviewed-by: Md Haris Iqbal; that tag was not carried to v2)
- No Cc: stable (expected; not a negative)
- Ignore any pipeline “Upstream commit” / “Signed-off-by: Sasha Levin”
  markers if present

Step 1.3: ANALYZE THE COMMIT BODY TEXT
Record:
- Bug: `http://kernel.dk/blk-mq.pdf` in the “Further reading” section
  returns 404.
- Symptom: readers of blk-mq documentation cannot open the canonical
  blk-mq paper.
- Fix: switch to `https://www.kernel.dk/blk-mq.pdf`.
- v2 note: v1 used `https://kernel.dk/blk-mq.pdf` (missing `www.`),
  which still 404’d / had a bad cert; v2 adds `www.`.
- No kernel version range given; no crash/trace.

Step 1.4: DETECT HIDDEN BUG FIXES
Record: Not a hidden runtime fix. It is exactly what it says: a
documentation hyperlink correction. Not a leak/race/UAF disguised as
cleanup.

---

## PHASE 2: DIFF ANALYSIS

Step 2.1: INVENTORY THE CHANGES
Record:
- File: `Documentation/block/blk-mq.rst` — 1 line changed (`-1/+1`)
- Functions: none
- Scope: single-file, surgical documentation edit

Step 2.2: UNDERSTAND THE CODE FLOW CHANGE
Record:
- Before: RST link target `http://kernel.dk/blk-mq.pdf`
- After: RST link target `https://www.kernel.dk/blk-mq.pdf`
- Path affected: documentation “Further reading” only; no execution path

Step 2.3: IDENTIFY THE BUG MECHANISM
Record: Not a memory-safety/locking/refcount bug. Category:
documentation correctness (dead external URL). Mechanism: site now
requires HTTPS + `www.` hostname.

Step 2.4: ASSESS THE FIX QUALITY
Record:
- Obviously correct once v2 uses the working URL.
- Minimal; no unrelated edits.
- Regression risk: none at runtime. Residual risk is only that the
  remote host could move again (same class of risk as any external
  link).
- v1 was wrong (Randy Dunlap reported continued 404 / bad SSL);
  committed v2 addresses that.

Verified live:
- `http://kernel.dk/blk-mq.pdf` → 404
- `https://www.kernel.dk/blk-mq.pdf` → PDF retrieved (51.5 KB)

---

## PHASE 3: GIT HISTORY INVESTIGATION

Step 3.1: BLAME THE CHANGED LINES
Record:
- Introduced in `46e906144c3f4b` (“docs: block: Create blk-mq
  documentation”, André Almeida, 2020-06-19)
- First appeared: `v5.9-rc1` (`git describe --contains` →
  `v5.9-rc1~150^2~141`)
- Present in this tree for the entire 6.12 lifetime

Step 3.2: FOLLOW THE FIXES: TAG
Record: No Fixes: tag. The introducing commit is the original
documentation add, not a later regression in C code.

Step 3.3: CHECK FILE HISTORY FOR RELATED CHANGES
Record (this tree, `-- Documentation/block/blk-mq.rst`):
- `41bd33df4e180` docs: correct places → place
- `c19430eec84f7` Fix small typo
- `2bc602cb0e0d9` correct drive → driver
- `8ac867340bd8c` / `9303c9d5e9883` Sphinx `:c:type` cleanup
- `46e906144c3f4b` create the file
No later URL rewrite in this checkout. Standalone; not patch X/Y of a
functional series.

Step 3.4: CHECK THE AUTHOR'S OTHER COMMITS
Record: `git log --author="Jenson Johnathon Reggentin"` /
`mail@jregg.de` on this tree: no hits. One-off docs contributor, not the
block maintainer. Applied by Jonathan Corbet; Acked-by Randy Dunlap.

Step 3.5: CHECK FOR DEPENDENT/PREREQUISITE COMMITS
Record: No new helpers, structs, or APIs. The hunk matches the current
file byte-for-byte. Can apply standalone.

---

## PHASE 4: MAILING LIST AND EXTERNAL RESEARCH

Step 4.1: FIND THE ORIGINAL PATCH DISCUSSION
Record:
- `b4 mbox 20260819192422.42189-1-mail@jregg.de` saved 12-message thread
  (lore HTTP 403 from WebFetch; b4 succeeded).
- v1: `https://kernel.dk/blk-mq.pdf` (no www)
- v2 (applied): `https://www.kernel.dk/blk-mq.pdf`
- Randy Dunlap: v1 still 404 + invalid SSL; confirmed `www.` works;
  Acked-by on v2; asked changelog-after-`---` nit
- Haris Iqbal: Reviewed-by on v1; spotted missing `www.`
- Jonathan Corbet: asked for a version that actually works; applied v2
  (“Applied, thanks.”)
- No NAK. No reviewer asked for Cc: stable.
- Included in Corbet’s `[GIT PULL] Documentation stragglers for 7.3`
  (`docs-7.3-2`), described as late-arriving docs fixes, not a stable-
  critical runtime fix.
- Syzbot CI skipped both versions: “AI determined the patch has no
  functional impact”

Step 4.2: CHECK WHO REVIEWED THE PATCH
Record (syzbot CI Cc + thread):
- To/Cc: Jens Axboe, Jonathan Corbet, linux-block, linux-doc
- Reviewers who spoke: Randy Dunlap (ack), Md Haris Iqbal (v1 r-b),
  Jonathan Corbet (applied)
- Block maintainer was copied; no Axboe reply in the 12-message thread

Step 4.3: SEARCH FOR THE BUG REPORT
Record: No bugzilla/syzbot crash. Author observed a 404. Confirmed
independently in this analysis.

Step 4.4: CHECK FOR RELATED PATCHES AND SERIES
Record: Standalone. v1→v2 only to correct the hostname. No sibling
functional patches required.

Step 4.5: CHECK STABLE MAILING LIST HISTORY
Record: lore.kernel.org/stable WebFetch returned 403. UNVERIFIED that
stable@ discussed this specific URL. No evidence in the docs thread of a
stable nomination or of a reason to exclude it.

---

## PHASE 5: CODE SEMANTIC ANALYSIS

Step 5.1: KEY FUNCTIONS
Record: None. Only an RST hyperlink.

Step 5.2: TRACE CALLERS
Record: N/A — not callable kernel code. Consumers are humans (and Sphinx
HTML on kernel.org / distro doc packages).

Step 5.3: TRACE CALLEES
Record: N/A.

Step 5.4: FOLLOW THE CALL CHAIN
Record: Not reachable from syscalls. User impact is documentation-only.
kernel.org `v6.12` HTML is built from this tree, so the 404 is user-
visible for people reading 6.12 docs.

Step 5.5: SEARCH FOR SIMILAR PATTERNS
Record: `kernel.dk/blk-mq` appears only in `Documentation/block/blk-
mq.rst` in this tree. Other `kernel.dk` hits are emails/copyrights, not
this PDF.

---

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

Step 6.1: DOES THE BUGGY CODE EXIST IN THIS TREE?
Record:
- `git describe HEAD` → `p-6.12-3-gc504cf0baa3d8`
- `make kernelversion` / Makefile → **6.12.111**, branch `pending-6.12`
- Line 142 of `Documentation/block/blk-mq.rst` still has
  `http://kernel.dk/blk-mq.pdf`
- `git merge-base --is-ancestor 46e906144c3f4b HEAD` → yes
- Bug introduced v5.9-rc1 (2020); present here

Step 6.2: CHECK FOR BACKPORT COMPLICATIONS
Record: Surrounding hunk is identical to the patch context. Expected
apply: **clean**. `git log v6.12..HEAD -- Documentation/block/blk-
mq.rst` is empty (no conflicting stable edits).

Step 6.3: CHECK IF RELATED FIXES ARE ALREADY HERE
Record: Replacement URL not present. No alternate rewrite of this link.
Comparable docs-link backports **do** exist after v6.12 in this tree,
e.g.:
- `b23111ec50d86` `docs: hwmon: fix link to g762 devicetree binding`
- `a7f28636da6f9` `docs: media: update location of the media patches`
  (explicit Cc: stable)

---

## PHASE 7: SUBSYSTEM AND MAINTAINER CONTEXT

Step 7.1: SUBSYSTEM AND CRITICALITY
Record:
- Subsystem: Documentation for the block layer (`Documentation/block/`,
  MAINTAINERS: BLOCK LAYER, Jens Axboe; docs tree via Corbet)
- Criticality of **blk-mq itself**: IMPORTANT (common block I/O)
- Criticality of **this change**: documentation-only, not the I/O path

Step 7.2: SUBSYSTEM ACTIVITY
Record: `Documentation/block/` is mature; this file’s last change in-
tree is a 2023 typo fix. The URL has been wrong/stale for years; the
site layout change is what made `http://kernel.dk/...` a hard 404.

---

## PHASE 8: IMPACT AND RISK ASSESSMENT

Step 8.1: WHO IS AFFECTED
Record: Anyone reading in-tree or generated blk-mq docs (developers,
distro doc packages, kernel.org HTML for 6.12). Not a
runtime/driver/config population.

Step 8.2: TRIGGER CONDITIONS
Record: Opening the “Further reading” PDF link. Common for people
studying blk-mq; never triggered by unprivileged syscalls. Not a race.

Step 8.3: FAILURE MODE SEVERITY
Record:
- Failure: HTTP 404 / cannot open the referenced paper
- Severity: **LOW** (incorrect documentation, no crash/corruption/hang)
- No kernel oops, leak, or security effect

Step 8.4: RISK-BENEFIT RATIO
Record:
- Benefit: working further-reading link in 6.12 docs; small but real for
  doc users
- Risk: **very low** (one RST URL; no code, locks, APIs)
- Ratio: favorable *if* documentation corrections are in scope; not a
  stability win

---

## PHASE 9: FINAL SYNTHESIS

Step 9.1: COMPILE THE EVIDENCE

FOR backporting:
- Dead link is real (404 verified); replacement URL works
- One-line, obviously correct v2 after review
- Docs maintainer applied it; Randy Dunlap Acked-by
- Buggy line exists in this 6.12.111 tree since v5.9; applies cleanly
- User-facing exception: documentation/comment fixes with zero runtime
  regression
- This same 6.12 tree already took other documentation link-location
  fixes

AGAINST backporting:
- Not a crash, deadlock, corruption, UAF, or security bug
- Official rule 3 (“important issue”) is not met in the runtime sense
- No functional kernel impact (syzbot CI skipped it for that reason)
- No Cc: stable; landed as docs-7.3 stragglers, not a hotfix
- Stable rules also discourage purely trivial edits; this is adjacent to
  that class
- Benefit is only to documentation readers, not production uptime

UNRESOLVED:
- Could not fetch lore.kernel.org or lore stable search via WebFetch
  (403); thread recovered via b4
- Commit SHA is not in this checkout’s `master` (that tip is ~7.2; patch
  went in docs-7.3-2)

Step 9.2: STABLE RULES CHECKLIST
1. Obviously correct and tested? **PASS** — v2 URL verified; Acked-by +
   maintainer apply
2. Fixes a real bug that affects users? **PASS** — 404 in
   shipped/generated docs, not a runtime bug
3. Important issue (crash, security, corruption, deadlock)? **FAIL** as
   runtime severity; **LOW** doc defect only
4. Small and contained? **PASS** — 1 line, one file
5. No new features or APIs? **PASS**
6. Can apply to the local tree? **PASS** — context identical, URL still
   old

Step 9.3: EXCEPTION CATEGORIES
Record: **Documentation fix** (incorrect/obsolete external link). That
exception is why a LOW-severity, zero-runtime patch can still be
appropriate for this tree.

Step 9.4: DECISION
The change does not stabilize running 6.12 systems, but it is a
contained, verified correction of documentation this tree still ships,
with no regression surface and with precedent for similar doc-link
backports here. That matches the documentation exception, not a “new
feature” or refactor.

What it solves for stable users: kernel.org / distro HTML for 6.12
currently points “Further reading” at a 404; after backport it points at
Jens Axboe’s actual blk-mq PDF.

Risk vs benefit: negligible risk, modest doc benefit. No dependencies or
backport rework.

---

## Verification
- [Phase 1] Tags: author SOB, Randy Dunlap Acked-by, Jonathan Corbet
  SOB, Message-ID v2; no Fixes/Reported-by/Cc-stable
- [Phase 2] Diff: single RST URL `http://kernel.dk/blk-mq.pdf` →
  `https://www.kernel.dk/blk-mq.pdf`
- [Phase 2] WebFetch: old URL 404; new URL returns the PDF
- [Phase 3] `git blame` line 142: `46e906144c3f4b` (2020); `git describe
  --contains` → v5.9-rc1
- [Phase 3] `git merge-base --is-ancestor 46e906144c3f4b HEAD` succeeded
- [Phase 3] Author has no other commits in this tree; file history is
  typo/Sphinx-only
- [Phase 4] `b4 mbox`: 12-message v1/v2 thread; Randy caught v1 404/SSL;
  Corbet applied v2
- [Phase 4] LKML pull: included in Documentation stragglers for 7.3
- [Phase 4] Syzbot CI: skipped, no functional impact
- [Phase 4] UNVERIFIED: lore.kernel.org/stable search (HTTP 403)
- [Phase 5] No functions/callers; only docs consumers
- [Phase 6] `git describe HEAD` = p-6.12-3-gc504cf0baa3d8; kernelversion
  6.12.111; dead URL still at blk-mq.rst:142
- [Phase 6] Apply would be clean; no post-v6.12 edits to this file
- [Phase 6] Precedent: `docs: hwmon: fix link to g762...` and `docs:
  media: update location...` already in this 6.12 tree
- [Phase 8] Failure mode: documentation 404, severity LOW; runtime risk
  none

**YES**

 Documentation/block/blk-mq.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst
index fc06761b6ea90..2798761efe0d6 100644
--- a/Documentation/block/blk-mq.rst
+++ b/Documentation/block/blk-mq.rst
@@ -139,7 +139,7 @@ completed.
 Further reading
 ---------------
 
-- `Linux Block IO: Introducing Multi-queue SSD Access on Multi-core Systems <http://kernel.dk/blk-mq.pdf>`_
+- `Linux Block IO: Introducing Multi-queue SSD Access on Multi-core Systems <https://www.kernel.dk/blk-mq.pdf>`_
 
 - `NOOP scheduler <https://en.wikipedia.org/wiki/Noop_scheduler>`_
 
-- 
2.53.0

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

[Sasha Levin]

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