docs: Add user documentation about audio support

This introduces plain-text documentation about the audio test, aimed at
users who wish to setup and run the audio tests.

Given the contents of this documentation, it felt more relevant to make
it part of the tree instead of the API reference.

Signed-off-by: Paul Kocialkowski <paul.kocialkowski@linux.intel.com>
Reviewed-by: Lyude Paul <lyude@redhat.com>

1 files changed, 45 insertions, 0 deletions

diff --git a/docs/audio.txt b/docs/audio.txt
new file mode 100644
index 00000000..158ad5d1
--- /dev/null
+++ b/docs/audio.txt
@@ -0,0 +1,45 @@
+Audio Support in IGT
+====================
+
+This document provides information and instructions about audio support in IGT.
+
+Introduction
+------------
+
+The audio test is aimed at testing the audio features of display connectors,
+such as HDMI.
+
+Test setup
+----------
+
+The setup required for the audio test consists of using an HDMI-VGA adapter with
+an audio-out 3.5 mm jack to extract the audio from the HDMI interface.
+The audio-out jack is connected back to the device-under-test's line-in.
+
+Depending on the behavior of the adapter, it may be necessary to connect a
+ghost VGA dongle to it (in order to emulate a connected display) to enable the
+audio output. There are guides available detailing how to build these.
+
+When executed, the test will automatically send the test audio signal to all
+ALSA audio HDMI outputs and record from the standard ALSA capture device.
+
+Configuration
+-------------
+
+In order to deploy the test, ALSA controls have to be configured to set the
+ALSA capture source to line-in. On Intel x86 systems, this can be achieved
+with the following calls to the amixer utility:
+# amixer sset Line 31 on
+# amixer sset "Input Source" Line
+
+It is then useful to store the ALSA state permanently with the alsactl utility:
+# alsactl store
+
+These settings can be restored with the alsactl utility:
+# alsactl restore
+
+It is desirable to ensure that the alsa-restore and alsa-state systemd services
+are enabled to do this job automatically, especially in the case of an
+automated testing system:
+# systemctl enable alsa-restore
+# systemctl enable alsa-state