[PATCH v2 4/4] docs: block: document prio_enable and prio_aging_expire in deadline-iosched

[Ye Bin <yebin@huaweicloud.com>]

From: Ye Bin <yebin10@huawei.com>

The mq-deadline scheduler exposes two sysfs tunables, prio_enable and
prio_aging_expire, that control its I/O priority (RT/BE/IDLE) support,
but neither was described in the deadline-iosched documentation.

Add sections covering:

  - prio_enable: enables/disables RT/BE/IDLE distinction; when disabled
    all requests fall into the best-effort bucket and the priority aging
    path is bypassed.  Switching the value drains in-flight I/O (queue
    freeze and quiesce) to avoid priority inversion during the transition.
    Also available as a module parameter.

  - prio_aging_expire: the time after which a waiting best-effort or idle
    request may be dispatched despite pending real-time requests, to
    prevent indefinite starvation.  Defaults to 10000 ms; only effective
    when prio_enable is on and at least two priority buckets are
    populated.  Zero and negative values are rejected with -EINVAL to
    avoid the "now - 0 == now" priority inversion.

Signed-off-by: Ye Bin <yebin10@huawei.com>
---
 Documentation/block/deadline-iosched.rst | 32 ++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/Documentation/block/deadline-iosched.rst b/Documentation/block/deadline-iosched.rst
index 9f5c5a4c370e..ffa88cbf2951 100644
--- a/Documentation/block/deadline-iosched.rst
+++ b/Documentation/block/deadline-iosched.rst
@@ -69,4 +69,36 @@ that comes at basically 0 cost we leave that on. We simply disable the
 rbtree front sector lookup when the io scheduler merge function is called.
 
 
+prio_enable	(bool)
+----------------------
+
+Whether to enable I/O priority support that distinguishes real-time (RT),
+best-effort (BE) and idle requests.  When enabled (the default), requests are
+filed into separate per-priority buckets and dispatched in priority order: lower
+priority requests are deferred while any higher priority requests are pending,
+subject to the prio_aging_expire aging mechanism described below.  When disabled,
+every request is filed in the best-effort bucket, the priority aging path is
+bypassed, and the scheduler dispatches from that single bucket.  This lets
+systems that do not want RT/BE/IDLE distinction opt out of the extra overhead.
+Switching the value drains all in-flight I/O (queue freeze and quiesce) to avoid
+priority inversion during the transition.  This parameter can also be set at
+module load time via the prio_enable module parameter.
+
+
+prio_aging_expire	(in ms)
+------------------------------
+
+To prevent lower priority requests from being starved indefinitely by a steady
+stream of higher priority requests, the deadline scheduler ages pending
+requests.  prio_aging_expire is the time after which a best-effort or idle
+request that has been waiting longer than this threshold may be dispatched even
+though real-time requests are still pending.  The default is 10000 ms (10 s).
+
+This parameter only takes effect when prio_enable is enabled and there are
+requests queued in at least two distinct priority buckets.  The value must be
+positive: zero or negative values are rejected with -EINVAL, since a value of
+zero would dispatch best-effort and idle requests ahead of pending real-time
+requests through "now - 0 == now", a classic priority inversion.
+
+
 Nov 11 2002, Jens Axboe <jens.axboe@oracle.com>
-- 
2.34.1