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@intel.com Cc: Daniel Vetter daniel@ffwll.ch --- 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; };