[PATCH 4/4] uapi/drm/i915: Update the placement list impact on obj residency

[Ramalingam C <ramalingam.c@intel.com>]

Object created with list of memory classes as placement preferences, can
be backed with any memory class of the list as per kernel's migration
policy for the memory contrain situation. Userspace won't be notified of
the memory residency change at this scenario.

And also Flat-CCS compression is supported only on objects of
I915_MEMORY_CLASS_DEVICE. When the Flat-CCS compressed objects migrates
out of I915_MEMORY_CLASS_DEVICE, due to memory constrain, content will
be decompressed without notifying the userpsace.

Record these details in Kernel documentation.

Signed-off-by: Ramalingam C <ramalingam.c@intel.com>
---
 include/uapi/drm/i915_drm.h | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
index 35ca528803fd..8b25dd6a157a 100644
--- a/include/uapi/drm/i915_drm.h
+++ b/include/uapi/drm/i915_drm.h
@@ -3393,6 +3393,20 @@ struct drm_i915_gem_create_ext {
  * At which point we get the object handle in &drm_i915_gem_create_ext.handle,
  * along with the final object size in &drm_i915_gem_create_ext.size, which
  * should account for any rounding up, if required.
+ *
+ * If an object is created with list of memory classes as their placement
+ * preference, kernel could use one of the memory class as the backing storage
+ * based on the memory availability. At memory pressure kernel could migrate the
+ * objects content from one memory class to another, given in the placement list.
+ *
+ * With placement preference list, userpace can't be sure about the object's memory
+ * residence.
+ *
+ * Flat-CCS compression is supported only for objects of I915_MEMORY_CLASS_DEVICE.
+ * If the object has other placement preferences, and if the content is
+ * migrated (by kernel due to memory constrain) to a memory class which is other
+ * than I915_MEMORY_CLASS_DEVICE, object content will be decompressed by kernel.
+ * Userpace will be ignorant of this Flat-CCS state change.
  */
 struct drm_i915_gem_create_ext_memory_regions {
 	/** @base: Extension link. See struct i915_user_extension. */
-- 
2.20.1