diff options
| -rw-r--r-- | lib/drmtest.c | 51 | ||||
| -rw-r--r-- | lib/drmtest.h | 26 |
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 */ |