Skip to contentSkip to conversation

lib: add the ability to include a description with a test

PATCH Superseded Thomas Wood 3 participants 7 messages Oct 28, 2014 – Nov 3, 2014

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/4 lib: add the ability to include a description with a test

---
 lib/igt_core.c | 19 ++++++++++++++++---
 lib/igt_core.h |  3 +++
 2 files changed, 19 insertions(+), 3 deletions(-)
lib/igt_core.c +16 -3
index e3d5fb0..3861121 100644
@@ -223,6 +223,7 @@ bool test_child;
 enum {
  OPT_LIST_SUBTESTS,
  OPT_RUN_SUBTEST,
+ OPT_DESCRIPTION,
  OPT_DEBUG,
  OPT_HELP = 'h'
 };
@@ -360,6 +361,12 @@ static void common_exit_handler(int sig)
 	assert(sig != 0 || igt_exit_called);
 }
 
+static void print_test_description(void)
+{
+	if (&__igt_test_description)
+		printf("%s\n", __igt_test_description);
+}
+
 static void print_version(void)
 {
 	struct utsname uts;
@@ -380,11 +387,12 @@ static void print_usage(const char *help_str, bool output_on_stderr)
 {
 	FILE *f = output_on_stderr ? stderr : stdout;
 
-	fprintf(f, "Usage: %s [OPTIONS]\n"
-		   "  --list-subtests\n"
+	fprintf(f, "Usage: %s [OPTIONS]\n", command_str);
+	fprintf(f, "  --list-subtests\n"
 		   "  --run-subtest <pattern>\n"
 		   "  --debug\n"
-		   "  --help\n", command_str);
+		   "  --help-description\n"
+		   "  --help\n");
 	if (help_str)
 		fprintf(f, "%s\n", help_str);
 }
@@ -413,6 +421,7 @@ static int common_init(int argc, char **argv,
 	static struct option long_options[] = {
 		{"list-subtests", 0, 0, OPT_LIST_SUBTESTS},
 		{"run-subtest", 1, 0, OPT_RUN_SUBTEST},
+		{"help-description", 0, 0, OPT_DESCRIPTION},
 		{"debug", 0, 0, OPT_DEBUG},
 		{"help", 0, 0, OPT_HELP},
 		{0, 0, 0, 0}
@@ -510,6 +519,10 @@ static int common_init(int argc, char **argv,
 			if (!list_subtests)
 				run_single_subtest = strdup(optarg);
 			break;
+		case OPT_DESCRIPTION:
+			print_test_description();
+			ret = -1;
+			goto out;
 		case OPT_HELP:
 			print_usage(help_str, false);
 			ret = -1;
lib/igt_core.h +3 -0
index b8f6702..98b8951 100644
@@ -38,6 +38,9 @@
 #include <stdarg.h>
 #include <getopt.h>
 
+extern const char* __igt_test_description __attribute__((weak));
+#define IGT_TEST_DESCRIPTION(a) const char* __igt_test_description = a;
+
 /**
  * IGT_EXIT_TIMEOUT:
  *
Signature · 6 lines
2.1.0

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#1 lore raw

PATCH 2/4 docs: add some test descriptions

---
 tests/core_getclient.c      |  5 ++---
 tests/core_getstats.c       |  3 +++
 tests/core_getversion.c     |  6 +++---
 tests/kms_3d.c              |  2 ++
 tests/kms_cursor_crc.c      |  8 ++++++++
 tests/kms_fbc_crc.c         |  5 +++++
 tests/kms_fence_pin_leak.c  |  2 ++
 tests/kms_flip_event_leak.c | 12 ++++++------
 8 files changed, 31 insertions(+), 12 deletions(-)
tests/core_getclient.c +2 -3
index ed46e51..92bf3e7 100644
@@ -32,9 +32,8 @@
 
 #include "drmtest.h"
 
-/**
- * Checks DRM_IOCTL_GET_CLIENT.
- */
+IGT_TEST_DESCRIPTION("Tests the DRM_IOCTL_GET_CLIENT ioctl.")
+
 igt_simple_main
 {
 	int fd, ret;
tests/core_getstats.c +3 -0
index 1e2c565..52a2d20 100644
@@ -40,6 +40,9 @@
  * I don't care too much about the actual contents, just that the kernel
  * doesn't crash.
  */
+
+IGT_TEST_DESCRIPTION("Tests the DRM_IOCTL_GET_STATS ioctl.");
+
 igt_simple_main
 {
 	int fd, ret;
tests/core_getversion.c +3 -3
index 7058c89..30132e4 100644
@@ -29,9 +29,9 @@
 #include <sys/ioctl.h>
 #include "drmtest.h"
 
-/**
- * Checks DRM_IOCTL_GET_VERSION and libdrm's drmGetVersion() interface to it.
- */
+IGT_TEST_DESCRIPTION("Tests the DRM_IOCTL_GET_VERSION ioctl and libdrm's "
+		     "drmGetVersion() interface to it.");
+
 igt_simple_main
 {
 	int fd;
tests/kms_3d.c +2 -0
index 4ecb90d..6c8ab33 100644
@@ -27,6 +27,8 @@
 #include "drmtest.h"
 #include "igt_edid.h"
 
+IGT_TEST_DESCRIPTION("Tests 3D mode setting.")
+
 igt_simple_main
 {
 	int drm_fd;
tests/kms_cursor_crc.c +8 -0
index 87b4f64..5772ed4 100644
@@ -34,6 +34,14 @@
 #include "intel_chipset.h"
 #include "igt_aux.h"
 
+IGT_TEST_DESCRIPTION(
+   "Use the display CRC support to validate cursor plane functionality. "
+   "The test will position the cursor plane either fully onscreen, "
+   "partially onscreen, or fully offscreen, using either a fully opaque "
+   "or fully transparent surface. In each case it then reads the PF CRC "
+   "and compares it with the CRC value obtained when the cursor plane "
+   "was disabled.");
+
 #ifndef DRM_CAP_CURSOR_WIDTH
 #define DRM_CAP_CURSOR_WIDTH 0x8
 #endif
tests/kms_fbc_crc.c +5 -0
index e1e8e97..43e68bd 100644
@@ -34,6 +34,11 @@
 #include "intel_batchbuffer.h"
 #include "ioctl_wrappers.h"
 
+IGT_TEST_DESCRIPTION(
+   "Performs various write operations to the scanout buffer while FBC is "
+   "enabled. CRC checks will be used to make sure the modifications to scanout "
+   "buffer are detected.");
+
 enum test_mode {
 	TEST_PAGE_FLIP,
 	TEST_MMAP_CPU,
tests/kms_fence_pin_leak.c +2 -0
index 5610ad8..6b032b0 100644
@@ -35,6 +35,8 @@
 #include "intel_chipset.h"
 #include "igt_aux.h"
 
+IGT_TEST_DESCRIPTION("Exercises full ppgtt fence pin_count leak in the kernel.")
+
 typedef struct {
 	int drm_fd;
 	uint32_t devid;
tests/kms_flip_event_leak.c +6 -6
index 0b45471..d30874d 100644
@@ -39,12 +39,12 @@ typedef struct {
 	igt_display_t display;
 } data_t;
 
-/*
- * This test tries to provoke the kernel to leak a pending page flip event
- * when the fd is closed before the flip has completed. The test itself won't
- * fail even if the kernel leaks the event, but the resulting dmesg WARN
- * will cause piglit to report a failure.
- */
+IGT_TEST_DESCRIPTION(
+    "This test tries to provoke the kernel into leaking a pending page flip "
+    "event when the fd is closed before the flip has completed. The test "
+    "itself won't fail even if the kernel leaks the event, but the resulting "
+    "dmesg WARN will indicate a failure.")
+
 static bool test(data_t *data, enum pipe pipe, igt_output_t *output)
 {
 	igt_plane_t *primary;
Signature · 6 lines
2.1.0

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#2 lore raw

PATCH 3/4 Build the docs directory last

In reply to Thomas Wood

Ensure that other components are built before generating the documentation.

---
 Makefile.am | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Makefile.am +1 -1
index 1dacb17..0c799d2 100644
@@ -21,7 +21,7 @@
 
 ACLOCAL_AMFLAGS = ${ACLOCAL_FLAGS} -I m4
 
-SUBDIRS = docs lib man tools scripts benchmarks demos overlay
+SUBDIRS = lib man tools scripts benchmarks demos overlay docs
 
 if BUILD_ASSEMBLER
 SUBDIRS += assembler
Signature · 6 lines
2.1.0

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#3 lore raw

PATCH 4/4 doc: include descriptions for the test programs

In reply to Thomas Wood
---
 docs/reference/intel-gpu-tools/Makefile.am         | 20 ++++++-
 .../intel-gpu-tools/igt_test_programs.xml.header   | 65 ++++++++++++++++++++++
 .../intel-gpu-tools/intel-gpu-tools-docs.xml       |  1 +
 3 files changed, 84 insertions(+), 2 deletions(-)
 create mode 100644 docs/reference/intel-gpu-tools/igt_test_programs.xml.header
docs/reference/intel-gpu-tools/Makefile.am +18 -2
index 3368e3e..bd02f5f 100644
@@ -1,5 +1,21 @@
 ## Process this file with automake to produce Makefile.in
 
+#noinst_PROGRAMS=igt-test-scan
+#
+#AM_CFLAGS="-DTESTDIR=\"$(abs_top_srcdir)/tests\""
+
+igt_test_programs.xml:
+	cat igt_test_programs.xml.header > $@; \
+	for test in `cat $(top_builddir)/tests/single-tests.txt $(top_builddir)/tests/multi-tests.txt`; do \
+		if [ "$$test" = "TESTLIST" -o "$$test" = "END" ]; then \
+			continue; \
+		fi; \
+		echo "<refsect2 id=\"$$test\"><title>$$test</title><para>" >> $@;\
+		./$(top_srcdir)/tests/$$test --help-description >> $@; \
+		echo "</para></refsect2>" >> $@; \
+	done; \
+	echo "</refsect1></refentry>" >> $@;
+
 # We require automake 1.6 at least.
 AUTOMAKE_OPTIONS = 1.6
 
@@ -68,12 +84,12 @@ HTML_IMAGES=
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=
+content_files=igt_test_programs.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
 # e.g. expand_content_files=running.sgml
-expand_content_files=
+expand_content_files=igt_test_programs.xml
 
 # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
 # Only needed if you are using gtkdoc-scangobj to dynamically query widget
docs/reference/intel-gpu-tools/igt_test_programs.xml.header new file +65 -0

65 lines not on this page · raw message

docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml +1 -0
index 3d9caf8..07ced05 100644
@@ -25,6 +25,7 @@
     <xi:include href="xml/intel_batchbuffer.xml"/>
     <xi:include href="xml/intel_chipset.xml"/>
     <xi:include href="xml/intel_io.xml"/>
+    <xi:include href="xml/igt_test_programs.xml"/>
     <xi:include href="xml/igt_edid.xml"/>
 
   </chapter>
Signature · 6 lines
2.1.0

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#4 lore raw
In reply to Thomas Wood

lib/igt_core.h line 42

Quoted 2 lines · Thomas Wood
lib/igt_core.h +2 -0
+extern const char* __igt_test_description __attribute__((weak));
+#define IGT_TEST_DESCRIPTION(a) const char* __igt_test_description = a;

It's usual to omit the ';' here to have the macro invokation always finish with a ';' (your next patch mixes both).

Signature · 5 lines
Damien
_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#5 lore raw
Quoted 6 lines · Damien Lespiau

lib/igt_core.h line 42

Quoted 2 lines · Thomas Wood
lib/igt_core.h +2 -0
+extern const char* __igt_test_description __attribute__((weak));
+#define IGT_TEST_DESCRIPTION(a) const char* __igt_test_description = a;

It's usual to omit the ';' here to have the macro invokation always finish with a ';' (your next patch mixes both).

Since you need to go through them all anyway small style bikeshed, but I think the multi-line arguments to macros look funny. What about

#define IGT_TEST_DESCPIPTION const char * __igt_test_description

and use them like

IGT_TEST_DESCRIPTION =
"blbl"
"blbl";

Imo slightly easier on the eyes ;-)

Otherwise this looks like a good start. So either way pls push after addressing Damien's feedback.
-Daniel

Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#6 lore raw
Quoted 11 lines · Daniel Vetter
Quoted 6 lines · Damien Lespiau

lib/igt_core.h line 42

Quoted 2 lines · Thomas Wood
lib/igt_core.h +2 -0
+extern const char* __igt_test_description __attribute__((weak));
+#define IGT_TEST_DESCRIPTION(a) const char* __igt_test_description = a;

It's usual to omit the ';' here to have the macro invokation always finish with a ';' (your next patch mixes both).

Since you need to go through them all anyway small style bikeshed, but I think the multi-line arguments to macros look funny. What about

Quoted 7 lines

#define IGT_TEST_DESCPIPTION const char * __igt_test_description

and use them like

IGT_TEST_DESCRIPTION =
"blbl"
"blbl";

The macro was originally going to include some extra parameters with more details. It may still be useful to add them at some point (perhaps a shorter summary line or some basic requirements).

Quoted 5 lines

Imo slightly easier on the eyes ;-)

Otherwise this looks like a good start. So either way pls push after addressing Damien's feedback.

The v2 of this series includes Damien's feedback, as well as some other fixes.

Quoted 5 lines

-Daniel
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx