[PATCH] drm/ttm: Add a comment for the FAULT_FLAG_ALLOW_RETRY implementation

[Thomas Hellström (VMware)]

From: Thomas Hellstrom <thellstrom at vmware.com>

The FAULT_FLAG_ALLOW_RETRY semantics is tricky and appears poorly
documented. Add a comment to the TTM fault() implementation to avoid
future confusion.

Cc: Christian Koenig <christian.koenig at vmware.com>
Signed-off-by: Thomas Hellstrom <thellstrom at vmware.com>
---
 drivers/gpu/drm/ttm/ttm_bo_vm.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/drivers/gpu/drm/ttm/ttm_bo_vm.c b/drivers/gpu/drm/ttm/ttm_bo_vm.c
index a61a35e57d1c..e93b1ad7828f 100644
--- a/drivers/gpu/drm/ttm/ttm_bo_vm.c
+++ b/drivers/gpu/drm/ttm/ttm_bo_vm.c
@@ -125,6 +125,17 @@ static vm_fault_t ttm_bo_vm_fault(struct vm_fault *vmf)
 		&bdev->man[bo->mem.mem_type];
 	struct vm_area_struct cvma;
 
+	/*
+	 * FAULT_FLAG_ALLOW_RETRY indicates that the caller would like to avoid
+	 * IO waits with the mmap_sem held. With FAULT_FLAG_RETRY_NOWAIT,
+	 * the caller would like an early return with VM_FAULT_RETRY and the
+	 * mmap_sem held.
+	 * If FAULT_FLAG_RETRY_NOWAIT is not set, then we should drop the
+	 * mmap_sem, perform the wait and return VM_FAULT_RETRY without
+	 * holding it. We implement this for sleeping bo reservations
+	 * where the reservation holder may be waiting for fences, and for
+	 * fence waits.
+	 */
 	if (unlikely(!dma_resv_trylock(bo->base.resv))) {
 		if (vmf->flags & FAULT_FLAG_ALLOW_RETRY) {
 			if (!(vmf->flags & FAULT_FLAG_RETRY_NOWAIT)) {
-- 
2.20.1