[igt-dev] [PATCH i-g-t] tests/kms_hdmi_inject: document how the test works

[Simon Ser]

It's not immediately obvious what injection and ELDs are, and what is tested.

This commit adds a few comments to help readers understand this test. In case
the test breaks, this could help.

Signed-off-by: Simon Ser <simon.ser at intel.com>
---

Suggestions wrt. more things to add and rewords are welcome!

I also noticed that there were already functions to generate audio-capable
EDIDs in IGT. Future work includes:

- Unifying kmstest_edid_add_audio and igt_edid (same for 4k helpers)
- Make the injection tests work on DisplayPort
- Test more EDIDs (e.g. more formats/sample sizes combinations)
- Also run tests with the same EDIDs with the Chamelium

 tests/kms_hdmi_inject.c | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/tests/kms_hdmi_inject.c b/tests/kms_hdmi_inject.c
index 699bad5b73e2..a24061042c20 100644
--- a/tests/kms_hdmi_inject.c
+++ b/tests/kms_hdmi_inject.c
@@ -30,6 +30,22 @@

 IGT_TEST_DESCRIPTION("Tests 4K and audio HDMI injection.");

+/**
+ * This collection of tests performs EDID and status injection tests. Injection
+ * forces a given EDID and status on a connector. The kernel will parse the
+ * forced EDID and we will check whether correct metadata is exposed to
+ * userspace.
+ *
+ * Currently, this can be used to test:
+ *
+ * - 4K modes exposed via KMS
+ * - Audio capabilities of the monitor exposed via ALSA. EDID-Like Data (ELD)
+ *   entries in /proc/asound are verified.
+ *
+ * Injection is performed on a disconnected connector.
+ */
+
+/** get_connector: get the first disconnected HDMI connector */
 static drmModeConnector *
 get_connector(int drm_fd, drmModeRes *res)
 {
@@ -118,6 +134,7 @@ hdmi_inject_4k(int drm_fd, drmModeConnector *connector)
 	free(edid);
 }

+/** eld_entry_is_igt: checks whether an ELD entry is mapped to the IGT EDID */
 static bool
 eld_entry_is_igt(const char* path)
 {
@@ -154,6 +171,8 @@ eld_entry_is_igt(const char* path)
 	return false;
 }

+/** eld_is_valid: check whether ALSA has detected the audio-capable IGT EDID by
+ * parsing ELD entries */
 static bool
 eld_is_valid(void)
 {
--
2.21.0