Add some kernel doc for this. We can then just reference this later when
documenting madv in the kernel.
Signed-off-by: Matthew Auld <matthew.auld@xxxxxxxxx>
Cc: Daniel Vetter <daniel@xxxxxxxx>
---
include/uapi/drm/i915_drm.h | 50 +++++++++++++++++++++++++++++++------
1 file changed, 42 insertions(+), 8 deletions(-)
diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
index e334a8b14ef2..a839085b6577 100644
--- a/include/uapi/drm/i915_drm.h
+++ b/include/uapi/drm/i915_drm.h
@@ -1492,20 +1492,54 @@ struct drm_i915_get_pipe_from_crtc_id {
__u32 pipe;
};
-#define I915_MADV_WILLNEED 0
-#define I915_MADV_DONTNEED 1
-#define __I915_MADV_PURGED 2 /* internal state */
-
+/**
+ * struct drm_i915_gem_madvise - Update the madvise hint for the object.
+ *
+ * The kernel uses this to know when it can safely discard the backing pages for
+ * an object, when under memory pressure.
+ */
struct drm_i915_gem_madvise {
- /** Handle of the buffer to change the backing store advice */
+ /**
+ * @handle: Handle of the buffer to change the backing store advice for.
+ */
__u32 handle;
- /* Advice: either the buffer will be needed again in the near future,
- * or wont be and could be discarded under memory pressure.
+ /**
+ * @madv: The madvise hint to set for the object.
+ *
+ * Supported values:
+ *
+ * I915_MADV_WILLNEED:
+ *
+ * The buffer will be needed again in the near future. By default all
+ * objects are set as I915_MADV_WILLNEED. Once the pages become
+ * dirty, the kernel is no longer allowed to simply discard the pages,
+ * and instead can only resort to swapping the pages out, if under
+ * memory pressure, where the page contents must persist when swapping
+ * the pages back in.
+ *
+ * I915_MADV_DONTNEED:
+ *
+ * The buffer wont be needed. The pages and their contents can be
+ * discarded under memory pressure.
+ *
+ * Note that if the pages were discarded then the kernel updates the
+ * internal madvise value of the object to __I915_MADV_PURGED, which
+ * effectively kills the object, since all further requests to allocate
+ * pages for the object will be rejected. At this point a new object is
+ * needed. This will be reflected in @retained.
*/
+#define I915_MADV_WILLNEED 0
+#define I915_MADV_DONTNEED 1
+#define __I915_MADV_PURGED 2 /* internal state */
__u32 madv;
- /** Whether the backing store still exists. */
+ /**
+ * @retained: Whether the backing store still exists.
+ *
+ * Set to false if the kernel purged the object and marked the object as
+ * __I915_MADV_PURGED.
+ */
__u32 retained;
};
--
2.26.3
