[Intel-gfx] [PATCH i-g-t 2/2] lib/igt_aux: Polish docs for igt_timeout

[Daniel Vetter]

Add docs, rename parameter and rename the macro to igt_do_timeout to
make it clear it works like a loop.

Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
---
 lib/igt_aux.h          | 14 ++++++++++++--
 tests/gem_close_race.c |  2 +-
 tests/gem_exec_flush.c |  4 ++--
 tests/gem_shrink.c     |  6 +++---
 4 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/lib/igt_aux.h b/lib/igt_aux.h
index f13ab0bc5604..624199ec4e4a 100644
--- a/lib/igt_aux.h
+++ b/lib/igt_aux.h
@@ -72,8 +72,18 @@ bool __igt_sigiter_continue(struct __igt_sigiter *iter, bool interrupt);
 #define igt_do_interruptible(enable) \
 	for (struct __igt_sigiter iter__={}; __igt_sigiter_continue(&iter__, (enable)); )
 
-#define igt_timeout(T) \
-	for (struct timespec t__={}; igt_seconds_elapsed(&t__) < (T); )
+/**
+ * igt_do_timeout:
+ * @timeout: timeout in seconds
+ *
+ * Convenience loop to run the provided code block in a loop until the timeout
+ * has expired. Of course when an individual execution takes too long, the
+ * actual execution time could be a lot longer.
+ *
+ * The code block will be executed at least once.
+ */
+#define igt_do_timeout(timeout) \
+	for (struct timespec t__={}; igt_seconds_elapsed(&t__) < (timeout); )
 
 void igt_exchange_int(void *array, unsigned i, unsigned j);
 void igt_permute_array(void *array, unsigned size,
diff --git a/tests/gem_close_race.c b/tests/gem_close_race.c
index 1c9707611603..72cd771abc5d 100644
--- a/tests/gem_close_race.c
+++ b/tests/gem_close_race.c
@@ -187,7 +187,7 @@ static void threads(int timeout)
 	fd = open(device, O_RDWR);
 	name.name = gem_flink(fd, gem_create(fd, OBJECT_SIZE));
 
-	igt_timeout(timeout) {
+	igt_do_timeout(timeout) {
 		crashme.fd = open(device, O_RDWR);
 
 		memset(&its, 0, sizeof(its));
diff --git a/tests/gem_exec_flush.c b/tests/gem_exec_flush.c
index f61b5b36034e..0cc791415107 100644
--- a/tests/gem_exec_flush.c
+++ b/tests/gem_exec_flush.c
@@ -196,7 +196,7 @@ static void run(int fd, unsigned ring, int nchild, int timeout,
 		}
 		munmap(ptr, 64*1024);
 
-		igt_timeout(timeout) {
+		igt_do_timeout(timeout) {
 			bool xor = false;
 			int idx = cycles++ % 1024;
 
@@ -369,7 +369,7 @@ static void batch(int fd, unsigned ring, int nchild, int timeout,
 		reloc.read_domains = I915_GEM_DOMAIN_INSTRUCTION;
 		reloc.write_domain = I915_GEM_DOMAIN_INSTRUCTION;
 
-		igt_timeout(timeout) {
+		igt_do_timeout(timeout) {
 			execbuf.batch_start_offset = 0;
 			reloc.offset = sizeof(uint32_t);
 			if (gen >= 4 && gen < 8)
diff --git a/tests/gem_shrink.c b/tests/gem_shrink.c
index eeba89edf7b5..319f5495d733 100644
--- a/tests/gem_shrink.c
+++ b/tests/gem_shrink.c
@@ -231,7 +231,7 @@ static void run_test(int nchildren, uint64_t alloc,
 	/* Background load */
 	if (flags & OOM) {
 		igt_fork(child, nchildren) {
-			igt_timeout(timeout) {
+			igt_do_timeout(timeout) {
 				int fd = drm_open_driver(DRIVER_INTEL);
 				for (int pass = 0; pass < nchildren; pass++)
 					leak(fd, alloc);
@@ -243,7 +243,7 @@ static void run_test(int nchildren, uint64_t alloc,
 	if (flags & USERPTR) {
 		igt_require(has_userptr());
 		igt_fork(child, (nchildren + 1)/2) {
-			igt_timeout(timeout) {
+			igt_do_timeout(timeout) {
 				int fd = drm_open_driver(DRIVER_INTEL);
 				for (int pass = 0; pass < nchildren; pass++)
 					userptr(fd, alloc);
@@ -255,7 +255,7 @@ static void run_test(int nchildren, uint64_t alloc,
 
 	/* Exercise major ioctls */
 	igt_fork(child, nchildren) {
-		igt_timeout(timeout) {
+		igt_do_timeout(timeout) {
 			int fd = drm_open_driver(DRIVER_INTEL);
 			for (int pass = 0; pass < nchildren; pass++)
 				func(fd, alloc);
-- 
2.8.1