sched/cahce: Document cache aware scheduling

This series adds the documentation for cache aware scheduling (CONFIG_SCHED_CACHE) and fixes the migration decision tables in the comment above can_migrate_llc().

Patch 1 adds Documentation/scheduler/sched-cache.rst, written in the same style as sched-energy.rst. It explains the operation principles of the scheduler and describes the debugfs tunables with tuning guidance.

Patch 2 fixes the example tables in the comment above can_migrate_llc(). Several cells did not match what the function computes with the default thresholds. The tables now use 45% instead of 40% so they also show the imb_pct hysteresis. This is a comment-only change and is tagged for stable so the comment matches the code in v7.2.y and v7.3.y.

Tim Chen (2):
Documentation/scheduler: Add cache aware scheduling documentation sched/cache: Fix decision matrix comment above can_migrate_llc()

 Documentation/scheduler/index.rst       |   1 +
 Documentation/scheduler/sched-cache.rst | 554 ++++++++++++++++++++++++
 kernel/sched/fair.c                     |  14 +-
 3 files changed, 562 insertions(+), 7 deletions(-)
 create mode 100644 Documentation/scheduler/sched-cache.rst

2.32.0

Add Documentation/scheduler/sched-cache.rst to describe cache aware scheduling (CONFIG_SCHED_CACHE).

The document explains how the scheduler tracks LLC occupancy per cache group, how the preferred LLC is chosen and withdrawn, how the load balancer is biased toward the preferred LLC, and which safety valves let generic load balancing take over. It also describes the debugfs tunables under /sys/kernel/debug/sched/llc_balancing/ and gives tuning guidance.

The migration decision tables in the document are derived from the logic of can_migrate_llc(), fits_llc_capacity() and util_greater().

---
 Documentation/scheduler/index.rst       |   1 +
 Documentation/scheduler/sched-cache.rst | 554 ++++++++++++++++++++++++
 2 files changed, 555 insertions(+)
 create mode 100644 Documentation/scheduler/sched-cache.rst

index 791178ac8bec..67cf466a169b 100644
@@ -16,6 +16,7 @@ Scheduler
     sched-domains
     sched-capacity
     sched-energy
+    sched-cache
     schedutil
     sched-util-clamp
     sched-nice-design

2.32.0

The example tables in the comment did not match what the function computes with the default thresholds. The imbalance test is a ratio, so 50% is noticeably busier than 40% (25% above), and several cells were wrong: 40%->60% toward the preferred LLC is forbidden, 50%->30% out of the preferred LLC is allowed, and 60%->40% out is allowed.

Use 45% instead of 40% so the tables also illustrate the imb_pct hysteresis, and recompute every cell from the code.

---
 kernel/sched/fair.c | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

index cfc982205b98..5770ae37d1dc 100644
@@ -10837,20 +10837,20 @@ static __maybe_unused bool get_llc_stats(int cpu, unsigned long *util,
  * 1. moving towards the preferred LLC, dst is the preferred
  *    LLC, src is not.
  *
- * src \ dst      30%  40%  50%  60%
- * 30%            Y    Y    Y    N
- * 40%            Y    Y    Y    Y
+ * src \ dst      30%  45%  50%  60%
+ * 30%            Y    Y    N    N
+ * 45%            Y    Y    Y    N
  * 50%            Y    Y    G    G
  * 60%            Y    Y    G    G
  *
  * 2. moving out of the preferred LLC, src is the preferred
  *    LLC, dst is not:
  *
- * src \ dst      30%  40%  50%  60%
+ * src \ dst      30%  45%  50%  60%
  * 30%            N    N    N    N
- * 40%            N    N    N    N
- * 50%            N    N    G    G
- * 60%            Y    N    G    G
+ * 45%            N    N    N    N
+ * 50%            Y    N    G    G
+ * 60%            Y    Y    G    G
  *
  * src :      src_util
  * dst :      dst_util

2.32.0