From: Tao Cui 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), the builtin model coming back on detach, and ctrl writes never selecting a model. Suggested-by: Tejun Heo Signed-off-by: Tao Cui --- Documentation/admin-guide/cgroup-v2.rst | 45 ++++++++++++++++++++----- 1 file changed, 37 insertions(+), 8 deletions(-) diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 9e3c67b02ae2..0965645b1286 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -2056,8 +2056,9 @@ IO Interface Files currently implements "io.weight" proportional control. Lines are keyed by $MAJ:$MIN device numbers and not ordered. The line for a given device is populated on the first write for - the device on "io.cost.qos" or "io.cost.model". The following - nested keys are defined. + the device on "io.cost.qos" or "io.cost.model", or when a BPF + cost model is attached to it. The following nested keys are + defined. ====== ===================================== enable Weight-based control enable @@ -2111,13 +2112,40 @@ IO Interface Files implements "io.weight" proportional control. Lines are keyed by $MAJ:$MIN device numbers and not ordered. The line for a given device is populated on the first write for the device on - "io.cost.qos" or "io.cost.model". The following nested keys - are defined. + "io.cost.qos" or "io.cost.model", or when a BPF cost model is + attached to it. The following nested keys are defined. - ===== ================================ + ===== ========================================== ctrl "auto" or "user" - model The cost model in use - "linear" - ===== ================================ + model The cost model in use - "linear" or "bpf" + ===== ========================================== + + When BPF cost model support is available, a BPF cost model + can be bound to a device by attaching an + "iocost_model_ops" struct_ops carrying the whole disk's + major:minor as encoded by makedev(3) in its "dev" member (a + partition's major:minor is rejected). Attaching creates the + controller if needed, like + an io.cost.model write does, switches the device's pricing to + the model and populates the device's line in this file and in + "io.cost.qos" if it did not exist yet. Attaching fails with + -EBUSY if the device already has a model attached. The + attached model prices IOs only while the controller is + enabled through "io.cost.qos"; attaching does not enable it. + IOs issued directly by the root cgroup bypass the model. + + While a model is attached, "model" selects between it and the + builtin model: "model=bpf" switches to the attached model and + "model=linear" switches back to the builtin model, and neither + detaches the struct_ops. + + Detaching removes the model, after which "model=bpf" + fails and the device prices with the builtin model again. + Device removal ejects the attached model as well, while the + struct_ops link remains until userspace destroys it. "ctrl" + accepts only "auto" and "user" and never selects a model. It + keeps describing the builtin coefficients, which take effect + again when switched back. When "ctrl" is "auto", the kernel may change all parameters dynamically. When "ctrl" is set to "user" or any other @@ -2125,7 +2153,8 @@ IO Interface Files automatic changes are disabled. When "model" is "linear", the following model parameters are - defined. + defined. They remain readable and writable while "model" is + "bpf". ============= ======================================== [r|w]bps The maximum sequential IO throughput -- 2.53.0