[PATCH v2 17/17] drm/xe/svm: Document how xe keeps drm_pagemap references

["Thomas Hellström" <thomas.hellstrom@linux.intel.com>]

As an aid to understanding the lifetime of the drm_pagemaps used
by the xe driver, document how the xe driver keeps the
drm_pagemap references.

Suggested-by: Matthew Brost <matthew.brost@intel.com>
Signed-off-by: Thomas Hellström <thomas.hellstrom@linux.intel.com>
---
 drivers/gpu/drm/xe/xe_svm.c | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/drivers/gpu/drm/xe/xe_svm.c b/drivers/gpu/drm/xe/xe_svm.c
index 56bb3896b89a..c1d6eb2f97d1 100644
--- a/drivers/gpu/drm/xe/xe_svm.c
+++ b/drivers/gpu/drm/xe/xe_svm.c
@@ -28,6 +28,28 @@
 #define XE_PEER_PAGEMAP ((void *)0ul)
 #define XE_PEER_VM ((void *)1ul)
 
+/**
+ * DOC: drm_pagemap reference-counting in xe:
+ *
+ * In addition to the drm_pagemap internal reference counting by
+ * its zone device data, the xe driver holds the following
+ * long-time references:
+ *
+ * - struct xe_pagemap:
+ *      The xe_pagemap struct derives from struct drm_pagemap and
+ *      uses its reference count.
+ * - SVM-enabled VMs:
+ *      SVM-enabled VMs look up and keeps a reference to all
+ *      xe_pagemaps on the same device.
+ * - VMAs:
+ *      vmas keep a reference on the drm_pagemap indicated by a gpu_madvise()
+ *      call.
+ *
+ * In addition, all drm_pagemap or xe_pagemap pointers where lifetime cannot
+ * be guaranteed by a vma reference under the vm lock should keep a reference.
+ * That includes the range->pages.dpagemap pointer.
+ */
+
 static int xe_svm_get_pagemaps(struct xe_vm *vm);
 
 void *xe_svm_private_page_owner(struct xe_vm *vm, bool force_smem)
-- 
2.51.1