[PATCH 3/4] drm/i915/gt: Extend doc on Flat-CCS obj eviction

[Ramalingam C]

Capture the eviction details for Flat-CCS capable lmem only objects and
lmem objects with smem residency. This also captures the impact of
eviction on  object's memory residency and Flat-CCS compression
state.

Signed-off-by: Ramalingam C <ramalingam.c at intel.com>
---
 drivers/gpu/drm/i915/gt/intel_migrate.c | 36 ++++++++++++++++++-------
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/drivers/gpu/drm/i915/gt/intel_migrate.c b/drivers/gpu/drm/i915/gt/intel_migrate.c
index 463a6a14b5f9..9d0d18950e76 100644
--- a/drivers/gpu/drm/i915/gt/intel_migrate.c
+++ b/drivers/gpu/drm/i915/gt/intel_migrate.c
@@ -485,16 +485,34 @@ static bool wa_1209644611_applies(int ver, u32 size)
  * And CCS data can be copied in and out of CCS region through
  * XY_CTRL_SURF_COPY_BLT. CPU can't access the CCS data directly.
  *
- * When we exhaust the lmem, if the object's placements support smem, then we can
- * directly decompress the compressed lmem object into smem and start using it
- * from smem itself.
+ * when we exhaust the lmem, we need to handle two types of flat-ccs capable
+ * objects for its eviction.
+ *   1) lmem only objects
+ *   2) lmem objects with smem residency option
  *
- * But when we need to swapout the compressed lmem object into a smem region
- * though objects' placement doesn't support smem, then we copy the lmem content
- * as it is into smem region along with ccs data (using XY_CTRL_SURF_COPY_BLT).
- * When the object is referred, lmem content will be swaped in along with
- * restoration of the CCS data (using XY_CTRL_SURF_COPY_BLT) at corresponding
- * location.
+ * 1) lmem only objects:
+ *
+ * lmem backing memory can be temporarily evicted to smem, along with the
+ * auxiliary CCS state, where it can be potentially swapped-out at a later point,
+ * if required. If userspace later touches the evicted pages, then we always move
+ * the backing memory back to lmem, which includes restoring the saved CCS state,
+ * and potentially performing any required swap-in.
+ *
+ * In this scenario, objects' backing memory class and Flat-CCS state doesn't
+ * change.
+ *
+ * 2) lmem objects with smem residency option
+ *
+ * Lmem object with smem region in it's placement list, will be migrated into
+ * smem  by decompressing the content. I915 doesn't handle this kind of
+ * migration for Flat-CCS compressed objects yet.
+ *
+ * In this scenario, objects' backing memory class and Flat-CCS state changed,
+ * and userspace is not aware of it.
+ *
+ * In summary, when a userspace wants to be sure about the objects memory
+ * residency and flat-ccs compression state, then placement list can't have
+ * the lmem and smem together. Instead, object has to be lmem resident only.
  */
 
 static inline u32 *i915_flush_dw(u32 *cmd, u32 flags)
-- 
2.20.1