Skip to contentSkip to conversation

Subtest documentation

PATCH Superseded Petri Latvala 2 participants 7 messages Aug 10, 2017 Library code

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

v3 cover Subtest documentation

New ever-growing series with some fixes and additions.

Petri Latvala (5):
Add support for subtest-specific documentation
README: Describe the subtest documentation command line flags
docs: Include subtest documentation
testdisplay: Handle subtest documentation flags igt_command_line.sh: Test subtest documentation flag handling

 README                                     |   5 +
 docs/reference/intel-gpu-tools/Makefile.am |   6 ++
 lib/igt_aux.c                              |   8 +-
 lib/igt_core.c                             | 148 +++++++++++++++++++++++------
 lib/igt_core.h                             |   6 +-
 tests/igt_command_line.sh                  |  12 ++-
 tests/testdisplay.c                        |   2 +
 7 files changed, 151 insertions(+), 36 deletions(-)
Signature · 6 lines
2.9.3

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

PATCH v3 1/5 Add support for subtest-specific documentation

The current documentation for tests is limited to a single string per test binary. This patch adds support for documenting individual subtests.

The syntax for subtest documentation is:

igt_document_subtest("Frob knobs to see if one of the "
"crossbeams will go out of skew on the " "treadle.\n");
igt_subtest("knob-frobbing-askew")

     test_frob();

or with a format string:

  for_example_loop(e) {
    igt_document_subtest_f("Frob %s to see if one of the "
                           "crossbeams will go out of skew on the "
                           "treadle.\n", e->readable_name);
    igt_subtest_f("%s-frob-askew", e->name)
      test_frob(e);
  }

The documentation cannot be extracted from just comments, because associating them with the correct subtest name will then require doing pattern matching in the documentation generator, for subtests where the name is generated at runtime using igt_subtest_f.

v2: Rebase, change function name in commit message to match code

v3: Fix current documentation string tracking, add missing va_end (Vinay)

---
 lib/igt_aux.c  |   8 ++--
 lib/igt_core.c | 148 +++++++++++++++++++++++++++++++++++++++++++++------------
 lib/igt_core.h |   6 ++-
 3 files changed, 127 insertions(+), 35 deletions(-)
lib/igt_aux.c +4 -4
index f428f15..d56f41f 100644
@@ -311,7 +311,7 @@ static void sig_handler(int i)
  */
 void igt_fork_signal_helper(void)
 {
-	if (igt_only_list_subtests())
+	if (igt_only_collect_data())
 		return;
 
 	/* We pick SIGCONT as it is a "safe" signal - if we send SIGCONT to
@@ -344,7 +344,7 @@ void igt_fork_signal_helper(void)
  */
 void igt_stop_signal_helper(void)
 {
-	if (igt_only_list_subtests())
+	if (igt_only_collect_data())
 		return;
 
 	igt_stop_helper(&signal_helper);
@@ -375,7 +375,7 @@ static void __attribute__((noreturn)) shrink_helper_process(int fd, pid_t pid)
  */
 void igt_fork_shrink_helper(int drm_fd)
 {
-	assert(!igt_only_list_subtests());
+	assert(!igt_only_collect_data());
 	igt_require(igt_drop_caches_has(drm_fd, DROP_SHRINK_ALL));
 	igt_fork_helper(&shrink_helper)
 		shrink_helper_process(drm_fd, getppid());
@@ -473,7 +473,7 @@ void igt_stop_hang_detector(void)
 #else
 void igt_fork_hang_detector(int fd)
 {
-	if (igt_only_list_subtests())
+	if (igt_only_collect_data())
 		return;
 }
 
lib/igt_core.c +118 -30

282 lines not on this page · raw message

lib/igt_core.h +5 -1
index 1619a9d..275e467 100644
@@ -197,8 +197,12 @@ bool __igt_run_subtest(const char *subtest_name);
 #define igt_subtest_f(f...) \
 	__igt_subtest_f(igt_tokencat(__tmpchar, __LINE__), f)
 
+void igt_document_subtest(const char *documentation);
+__attribute__((format(printf, 1, 2)))
+void igt_document_subtest_f(const char *documentation, ...);
+
 const char *igt_subtest_name(void);
-bool igt_only_list_subtests(void);
+bool igt_only_collect_data(void);
 
 void __igt_subtest_group_save(int *);
 void __igt_subtest_group_restore(int);
Signature · 6 lines
2.9.3

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

PATCH v3 2/5 README: Describe the subtest documentation command line flags

In reply to Petri Latvala
---
 README | 5 +++++
 1 file changed, 5 insertions(+)
README +5 -0
index d1ea952..5b6cb00 100644
@@ -32,6 +32,11 @@ tests/
 	be run. Some tests have futher options and these are detailed by using
 	the --help option.
 
+	Tests with subtests will print a documentation string (if any)
+	with the --document-subtest option. The option
+	--document-all-subtests will print the subtest documentation
+	for all subtests that have it.
+
 	The test suite can be run using the run-tests.sh script available in
 	the scripts directory. Piglit is used to run the tests and can either
 	be installed from your distribution (if available), or can be
Signature · 6 lines
2.9.3

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

PATCH v3 3/5 docs: Include subtest documentation

In reply to Petri Latvala

A simple and naive format: Double newline denotes paragraph change, otherwise insert subtest documentation into the generated docs as-is.

---

Still not sure whether <para> inside <simplelist><member> is kosher.

docs/reference/intel-gpu-tools/Makefile.am | 6 ++++++

 1 file changed, 6 insertions(+)
docs/reference/intel-gpu-tools/Makefile.am +6 -0
index ee1e900..2407e37 100644
@@ -56,6 +56,12 @@ xml/igt_test_programs_%_description.xml: $(TESTLISTS)
 				for subtest in $$subtest_list; do \
 					echo "<member>" >> $@; \
 					echo "$$subtest" | perl -pe 's/\b$(KEYWORDS)\b/<acronym>\1<\/acronym>/g' >> $@; \
+					subtest_doc=`./$$testprog --document-subtest $$subtest`; \
+					if [ -n "$$subtest_doc" ]; then \
+						echo "<para><![CDATA[" >> $@; \
+						echo "$$subtest_doc" | sed ':a;N;$$!ba;s,\n\n,]]></para><para><![CDATA[,g'>> $@; \
+						echo "]]></para>" >> $@; \
+					fi; \
 					echo "</member>" >> $@; \
 				done; \
 				echo "</simplelist>" >> $@; \
Signature · 6 lines
2.9.3

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

PATCH v3 4/5 testdisplay: Handle subtest documentation flags

In reply to Petri Latvala

testdisplay has no subtests so hook them to existing subtest handling.

---

TODO: Make testdisplay use igt_simple_init_parse_opts...

tests/testdisplay.c | 2 ++

 1 file changed, 2 insertions(+)
tests/testdisplay.c +2 -0
index f2a41fa..85b118f 100644
@@ -623,6 +623,8 @@ int main(int argc, char **argv)
 	struct option long_opts[] = {
 		{"list-subtests", 0, 0, SUBTEST_OPTS},
 		{"run-subtest", 1, 0, SUBTEST_OPTS},
+		{"document-all-subtests", 0, 0, SUBTEST_OPTS},
+		{"document-subtest", 1, 0, SUBTEST_OPTS},
 		{"help-description", 0, 0, HELP_DESCRIPTION},
 		{"help", 0, 0, 'h'},
 		{"yb", 0, 0, Yb_OPT},
Signature · 6 lines
2.9.3

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

PATCH v3 5/5 igt_command_line.sh: Test subtest documentation flag handling

In reply to Petri Latvala
---
 tests/igt_command_line.sh | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)
tests/igt_command_line.sh +11 -1
index 7f80fc8..b3a794c 100755
@@ -102,7 +102,17 @@ for test in $TESTLIST; do
 		fi
 	fi
 
+	# check --document-all-subtests handling
+	echo "  Checking subtest documentation..."
+	DOCS=`./$test --document-all-subtests`
+	RET=$?
+
+	if [ $RET -ne 0 -a $RET -ne 79 ]; then
+		fail $test
+	fi
+
 	# check invalid subtest handling
 	echo "  Checking invalid subtest handling..."
-	./$test --run-subtest invalid-subtest > /dev/null 2>&1 && fail $test
+	./$test --run-subtest invalid-subtest > /dev/null 2>&1 && fail "$test --run-subtest invalid"
+	./$test --document-subtest invalid-subtest > /dev/null 2>&1 && fail "$test --document-subtest invalid"
 done
Signature · 6 lines
2.9.3

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

✗ Fi.CI.BAT: failure for Subtest documentation

In reply to Petri Latvala
== Series Details ==

== Series Details ==

Series: Subtest documentation
URL : https://patchwork.freedesktop.org/series/28605/
State : failure

== Summary ==

IGT patchset tested on top of latest successful build c129026622accef6f54c0cfb0dc55e930cfa60b5 igt: add syncobj_basic.

with latest DRM-Tip kernel build CI_DRM_2942
2d0288b5b28c drm-tip: 2017y-08m-09d-18h-09m-54s UTC integration manifest

Test drv_hangman:

        Subgroup error-state-basic:
                pass       -> INCOMPLETE (fi-bxt-j4205)
Test gem_busy:
        Subgroup basic-busy-default:
                pass       -> INCOMPLETE (fi-ilk-650)
                pass       -> INCOMPLETE (fi-snb-2520m)
                pass       -> INCOMPLETE (fi-snb-2600)
                pass       -> INCOMPLETE (fi-ivb-3520m)
                pass       -> INCOMPLETE (fi-ivb-3770)
                pass       -> INCOMPLETE (fi-byt-j1900)
                pass       -> INCOMPLETE (fi-hsw-4770)
                pass       -> INCOMPLETE (fi-hsw-4770r)
                pass       -> INCOMPLETE (fi-bdw-5557u)
                pass       -> INCOMPLETE (fi-bdw-gvtdvm)
                pass       -> INCOMPLETE (fi-bsw-n3050)
                pass       -> INCOMPLETE (fi-skl-6260u)
                pass       -> INCOMPLETE (fi-skl-6700k)
                pass       -> INCOMPLETE (fi-skl-6770hq)
                pass       -> INCOMPLETE (fi-skl-gvtdvm)
                pass       -> INCOMPLETE (fi-skl-x1585l)
                pass       -> INCOMPLETE (fi-kbl-7500u)
                pass       -> INCOMPLETE (fi-kbl-7560u)
                pass       -> INCOMPLETE (fi-kbl-r)
                pass       -> INCOMPLETE (fi-glk-2a)
Test gem_close_race:
        Subgroup basic-process:
                pass       -> INCOMPLETE (fi-blb-e6850)
                pass       -> INCOMPLETE (fi-pnv-d510)
fi-bdw-5557u     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-bdw-gvtdvm    total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-blb-e6850     total:12   pass:11   dwarn:0   dfail:0   fail:0   skip:0  
fi-bsw-n3050     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-bxt-j4205     total:6    pass:5    dwarn:0   dfail:0   fail:0   skip:0  
fi-byt-j1900     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-glk-2a        total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-hsw-4770      total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-hsw-4770r     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-ilk-650       total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-ivb-3520m     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-ivb-3770      total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-kbl-7500u     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-kbl-7560u     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-kbl-r         total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-pnv-d510      total:12   pass:11   dwarn:0   dfail:0   fail:0   skip:0  
fi-skl-6260u     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-skl-6700k     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-skl-6770hq    total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-skl-gvtdvm    total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-skl-x1585l    total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-snb-2520m     total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  
fi-snb-2600      total:10   pass:9    dwarn:0   dfail:0   fail:0   skip:0  

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_51/
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx