[RFC PATCH v7 4/4] docs: cgroup-v2: document the iocost BPF cost model attachment

[Tao Cui]

From: Tao Cui <cuitao@xxxxxxxxxx>

Document the BPF cost model attachment in the io.cost.model section
of the cgroup v2 documentation: attaching an iocost_model_ops
struct_ops to a device by its major:minor, the model=bpf readback
while attached (ctrl keeps describing the coefficients), that
detaching restores the builtin model, and that writes never select
a model.

Signed-off-by: Tao Cui <cuitao@xxxxxxxxxx>
---
 Documentation/admin-guide/cgroup-v2.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 8d2603751c51..306cc929c88d 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -2117,8 +2117,30 @@ IO Interface Files
 	  =====		================================
 	  ctrl		"auto" or "user"
 	  model		The cost model in use - "linear"
+			or "bpf" while a BPF model is
+			attached
 	  =====		================================
 
+	When CONFIG_BLK_CGROUP_IOCOST_BPF is enabled, a BPF cost model
+	can be attached to a device by loading an "iocost_model_ops"
+	struct_ops with the whole disk's major:minor in its "dev" member
+	(a partition's major:minor is rejected);
+	attaching switches the device's pricing to the model, detaching
+	the struct_ops restores the builtin linear model.  While a model
+	is attached, "model" reads back "bpf"; "ctrl" keeps describing
+	the builtin coefficients, which are inert while the model is
+	attached: coefficient writes are stored and take effect again
+	after the struct_ops is detached, and the automatic profile
+	stepping does not switch profiles.  Writing "ctrl=bpf" or
+	"model=bpf" is accepted as a no-op so a saved configuration
+	still parses, but re-attaching the model requires loading the
+	struct_ops again, not writing to this file.  Attaching
+	implicitly enables the controller if needed (disabling wbt
+	like io.cost.qos does); detaching does not disable it again,
+	and writing "enable=0" to io.cost.qos suspends the model's
+	pricing until the controller is re-enabled, while it stays
+	attached.
+
 	When "ctrl" is "auto", the kernel may change all parameters
 	dynamically.  When "ctrl" is set to "user" or any other
 	parameters are written to, "ctrl" become "user" and the
-- 
2.43.0