From: Tao Cui <cui.tao@linux.dev>
To: tj@kernel.org, josef@toxicopanda.com, axboe@kernel.dk,
ast@kernel.org, alexei.starovoitov@gmail.com
Cc: cgroups@vger.kernel.org, linux-block@vger.kernel.org,
linux-kernel@vger.kernel.org, bpf@vger.kernel.org,
andrii@kernel.org, eddyz87@gmail.com, daniel@iogearbox.net,
linux-kselftest@vger.kernel.org, cui.tao@linux.dev,
cuitao@kylinos.cn, ameryhung@gmail.com
Subject: [RFC PATCH v14 4/4] docs: cgroup-v2: document the iocost BPF cost model attachment
Date: Wed, 18 Nov 2026 21:10:29 +0800 [thread overview]
Message-ID: <20261118131029.797007-5-cui.tao@linux.dev> (raw)
In-Reply-To: <20261118131029.797007-1-cui.tao@linux.dev>
From: Tao Cui <cuitao@kylinos.cn>
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 <tj@kernel.org>
Signed-off-by: Tao Cui <cuitao@kylinos.cn>
---
Documentation/admin-guide/cgroup-v2.rst | 55 +++++++++++++++++++++----
1 file changed, 47 insertions(+), 8 deletions(-)
diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 9e3c67b02ae2..a3c402f03ae9 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,50 @@ 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). The loader supplies
+ "dev" when the map is created and it cannot be changed
+ afterward. 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, with
+ -EINVAL if the model fails its attach-time validation, with
+ -EOPNOTSUPP if dev names a partition or a device without a
+ multiqueue queue, and with -ENODEV if dev does not name an
+ existing device or if the device has gone away. Updating the
+ link to a different model is not supported and fails with
+ -EINVAL or -EOPNOTSUPP; switching models requires detaching
+ first. 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's per-IO pricing;
+ the completion-time sizing of their requests still uses the
+ attached model's transfer coefficients.
+
+ 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 +2163,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
next prev parent reply other threads:[~2026-11-18 13:11 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-18 13:10 [RFC PATCH v14 0/4] blk-iocost: BPF struct_ops cost model Tao Cui
2026-11-18 13:10 ` [RFC PATCH v14 1/4] blk-iocost: add BPF struct_ops cost model support Tao Cui
2026-11-18 13:10 ` [RFC PATCH v14 2/4] blk-iocost: add iocost_ioc_tick tracepoint for per-period device summary Tao Cui
2026-11-18 13:10 ` [RFC PATCH v14 3/4] selftests/bpf: add iocost cost model test Tao Cui
2026-11-18 13:10 ` Tao Cui [this message]
2026-11-18 13:17 ` [RFC PATCH v14 0/4] blk-iocost: BPF struct_ops cost model Tao Cui
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261118131029.797007-5-cui.tao@linux.dev \
--to=cui.tao@linux.dev \
--cc=alexei.starovoitov@gmail.com \
--cc=ameryhung@gmail.com \
--cc=andrii@kernel.org \
--cc=ast@kernel.org \
--cc=axboe@kernel.dk \
--cc=bpf@vger.kernel.org \
--cc=cgroups@vger.kernel.org \
--cc=cuitao@kylinos.cn \
--cc=daniel@iogearbox.net \
--cc=eddyz87@gmail.com \
--cc=josef@toxicopanda.com \
--cc=linux-block@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=tj@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox