lib/drmtest: api documentation

Also rename the arguments of do_ioctl a bit for better clarity.

I haven't figured out a way to reference other section headers, hence
the links to igt_core and intel_batchbuffer are a bit fragile
unfortunately. It gets the job done though.

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

2 files changed, 71 insertions, 6 deletions

diff --git a/lib/drmtest.c b/lib/drmtest.c
index 8bb64f0c..d48af9c8 100644
--- a/lib/drmtest.c
+++ b/lib/drmtest.c
@@ -58,8 +58,20 @@
 #include "intel_reg.h"
 #include "ioctl_wrappers.h"
 
-/* This file contains a bunch of wrapper functions to directly use gem ioctls.
- * Mostly useful to write kernel tests. */
+/**
+ * SECTION:drmtest
+ * @short_description: Base library for drm tests and tools
+ * @title: drmtest
+ * @include: drmtest.h
+ *
+ * This library contains the basic support for writing tests, with the most
+ * important part being the helper function to open drm device nodes.
+ *
+ * But there's also a bit of other assorted stuff here.
+ *
+ * Note that this library's header pulls in the [i-g-t core](intel-gpu-tools-i-g-t-core.html)
+ * and [batchbuffer](intel-gpu-tools-intel-batchbuffer.html) libraries as depencies.
+ */
 
 static int
 is_intel(int fd)
@@ -77,7 +89,18 @@ is_intel(int fd)
 }
 
 #define LOCAL_I915_EXEC_VEBOX	(4 << 0)
-/* Ensure the gpu is idle by launching a nop execbuf and stalling for it. */
+/**
+ * gem_quiescent_gpu:
+ * @fd: open i915 drm file descriptor
+ *
+ * Ensure the gpu is idle by launching a nop execbuf and stalling for it. This
+ * is automatically run when opening a drm device node and is also installed as
+ * an exit handler to have the best assurance that the test is run in a pristine
+ * and controlled environment.
+ *
+ * This function simply allows tests to make additional calls in-between, if so
+ * desired.
+ */
 void gem_quiescent_gpu(int fd)
 {
 	uint32_t batch[2] = {MI_BATCH_BUFFER_END, 0};
@@ -134,9 +157,11 @@ void gem_quiescent_gpu(int fd)
 /**
  * drm_get_card:
  *
- * Get an intel card number for use in /dev or /sys
+ * Get an i915 drm card index number for use in /dev or /sys. The minor index of
+ * the legacy node is returned, not of the control or render node.
  *
- * Returns: -1 on error
+ * Returns:
+ * The i915 drm index or -1 on error
  */
 int drm_get_card(void)
 {
@@ -242,6 +267,14 @@ static void quiescent_gpu_at_exit_render(int sig)
 	at_exit_drm_render_fd = -1;
 }
 
+/**
+ * drm_open_any:
+ *
+ * Open an i915 drm legacy device node.
+ *
+ * Returns:
+ * The i915 drm file descriptor or -1 on error
+ */
 int drm_open_any(void)
 {
 	static int open_count;
@@ -259,6 +292,14 @@ int drm_open_any(void)
 	return fd;
 }
 
+/**
+ * drm_open_any:
+ *
+ * Open an i915 drm render device node.
+ *
+ * Returns:
+ * The i915 drm file descriptor or -1 on error
+ */
 int drm_open_any_render(void)
 {
 	static int open_count;
diff --git a/lib/drmtest.h b/lib/drmtest.h
index 631627cc..fdf98c62 100644
--- a/lib/drmtest.h
+++ b/lib/drmtest.h
@@ -48,6 +48,12 @@ static inline void *mmap64(void *addr, size_t length, int prot, int flags,
 #endif
 #endif
 
+/**
+ * ARRAY_SIZE:
+ * @arr: static array
+ *
+ * Macro to compute the size of the static array @arr.
+ */
 #define ARRAY_SIZE(arr) (sizeof(arr)/sizeof(arr[0]))
 
 int drm_get_card(void);
@@ -56,7 +62,25 @@ int drm_open_any_render(void);
 
 void gem_quiescent_gpu(int fd);
 
+/**
+ * do_or_die:
+ * @x: command
+ *
+ * Simple macro to execute x and check that it's return value is 0. Presumes
+ * that in any failure case the return value is non-zero and a precise error is
+ * logged into errno. Uses igt_assert() internally.
+ */
 #define do_or_die(x) igt_assert((x) == 0)
-#define do_ioctl(fd, ptr, sz) igt_assert(drmIoctl((fd), (ptr), (sz)) == 0)
+
+/**
+ * do_ioctl:
+ * @fd: open i915 drm file descriptor
+ * @ioc: ioctl op definition from drm headers
+ * @ioc_data: data pointer for the ioctl operation
+ *
+ * This macro wraps drmIoctl() and uses igt_assert to check that it has been
+ * successfully executed.
+ */
+#define do_ioctl(fd, ioc, ioc_data) igt_assert(drmIoctl((fd), (ioc), (ioc_data)) == 0)
 
 #endif /* DRMTEST_H */