[RFC PATCH 8/8] docs: cgroup-v2: document io.cost ctrl=bpf option

[Tao Cui]

From: Tao Cui <cuitao@xxxxxxxxxx>

Document the "bpf" value of the ctrl key of io.cost.model and the
iocost_model_ops struct_ops it selects, in the io.cost.model section
of the cgroup v2 documentation: the registration precondition and
single-instance limit, the scalar arguments, the vtime clamp and the
delegation-to-builtin semantics of a zero return value.

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

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 8d2603751c51a..54b0574ce586c 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -2115,10 +2115,24 @@ IO Interface Files
 	are defined.
 
 	  =====		================================
-	  ctrl		"auto" or "user"
+	  ctrl		"auto", "user" or "bpf"
 	  model		The cost model in use - "linear"
 	  =====		================================
 
+	When "ctrl" is "bpf" (only available when
+	CONFIG_BLK_CGROUP_IOCOST_BPF is enabled), cost calculation for
+	the device is dispatched to the BPF program registered against
+	the iocost_model_ops struct_ops.  Writing "bpf" fails with -EINVAL
+	until such a program is registered, and at most one program can
+	be registered system-wide.  The model is called with scalar
+	arguments (operation, size, sector, cgroup cursor, css id of the
+	issuing cgroup, flags; see include/linux/blk-iocost.h for their
+	meaning) and returns a cost in vtime units, clamped by the kernel
+	to 1 second of device time per IO.  A return value of 0 delegates
+	the IO back to the builtin linear formula, so a model which only
+	handles some IO types cannot make the rest free.  Devices which
+	don't opt in keep the builtin linear model unchanged.
+
 	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