[RFC PATCH 9/9] drm/i915/gt: Document CCS mode load balancing

[Andi Shyti]

Add documentation for how to set the static CCS load balancing.

Signed-off-by: Andi Shyti <andi.shyti at linux.intel.com>
---
 Documentation/gpu/i915.rst                  |  3 ++
 drivers/gpu/drm/i915/gt/intel_gt_ccs_mode.c | 56 +++++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index ad59ae579237..7e4f0d5a4cec 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -341,6 +341,9 @@ for execution also include a list of all locations within buffers that
 refer to GPU-addresses so that the kernel can edit the buffer correctly.
 This process is dubbed relocation.
 
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_sysfs.c
+   :doc: CCS load balancing
+
 Locking Guidelines
 ------------------
 
diff --git a/drivers/gpu/drm/i915/gt/intel_gt_ccs_mode.c b/drivers/gpu/drm/i915/gt/intel_gt_ccs_mode.c
index 7773a04981a4..2babd91d4c0e 100644
--- a/drivers/gpu/drm/i915/gt/intel_gt_ccs_mode.c
+++ b/drivers/gpu/drm/i915/gt/intel_gt_ccs_mode.c
@@ -165,6 +165,62 @@ static ssize_t num_cslices_show(struct device *dev,
 }
 static DEVICE_ATTR_RO(num_cslices);
 
+/**
+ * DOC: CCS Load Balancing
+ *
+ * CCS load balancing involves distributing the commands submitted to the
+ * compute engine across the various CCS slices.
+ *
+ * The initial design was aimed at automatic load balancing, but it was found
+ * that static load balancing performed better. Static load balancing allows
+ * users to set the desired balancing mode, also referred to as "CCS mode." This
+ * approach enables users to determine how the CCS workload is distributed
+ * among the slices.
+ *
+ * The possible modes for CCS balancing depend on the total number of slices,
+ * which currently does not exceed 4, and applies to DG2 and ATS-M platforms.
+ * (PVC also has more than 1 CCS engine, but the mode is set through an
+ * execbuffer setting.)
+ *
+ * Given a maximum mode of 4, the CCS mode can be set to 1, 2, or 4. Each mode
+ * corresponds to the number of CCS engines exposed to userspace, and the load
+ * is balanced as follows:
+ *
+ * CCS mode 1:
+ *   - slices 0, 1, 2, 3: ccs0
+ *
+ * CCS mode 2:
+ *   - slice 0, 2: ccs0
+ *   - slice 1, 3: ccs1
+ *
+ * CCS mode 4:
+ *   - slice 0: ccs0
+ *   - slice 1: ccs1
+ *   - slice 2: ccs2
+ *   - slice 3: ccs3
+ *
+ * At boot time, the default mode set is '1'.
+ *
+ * Two interfaces are generated for the CCS engine:
+ *
+ * - ccs_mode: This read-write interface, generated only for DG2 and ATSM,
+ *   shows the current CCS mode when read and sets the CCS mode when written to.
+ *
+ *   Setting the CCS mode is only possible when no one is using i915, i.e.,
+ *   when no client is keeping the interface open. This is to ensure a
+ *   consistent engine topology view among different clients and to guarantee
+ *   that no task is impacted by a runtime CCS mode change.
+ *
+ *   Writing to this interface can fail, returning the following error codes:
+ *
+ *   - -EINVAL for attempting to set an invalid mode: when the mode is '0',
+ *     exceeds the number of available slices, or is not a power of 2.
+ *
+ *   - -EBUSY when other clients are attached to i915.
+ *
+ * - num_cslices, read-only: Shows the maximum number of slices and,
+ *   consequently, the highest mode that can be set.
+ */
 static ssize_t ccs_mode_show(struct device *dev,
 			     struct device_attribute *attr, char *buff)
 {
-- 
2.45.2