alsa_settings: Add README.md

Add README.md documentation for SOF test ALSA settings.

Signed-off-by: Dmitrii Golovanov <dmitrii.golovanov@intel.com>

Author: golowanow

alsa_settings/README.md

@@ -0,0 +1,73 @@
+# ALSA settings
+
+SOF test case execution requires certain DSP and mixer configurations being set
+on the DUT (Device Under Test). An important part of this configuration is the
+signal levels adjusted to the hardware setup which runs the tests, including its
+codec and loopback devices.
+
+The `./alsa_settings/` directory contains custom ALSA configurations which
+are currently applied at the SOF CI pipeline's hardware platforms.
+
+
+## How it works
+
+When a test case calls `set_alsa()` function, its task is to apply the DUT's
+default ALSA configuration file as the baseline to ensure the expected ALSA
+settings are active the same way as after the DUT's reboot, so to avoid
+after-effects possible from the previous test's execution - either it was
+success, or failure, or any other unexpected change due to the DUT's power
+reset, the test case error, manual re-configuration, etc.
+
+After `alsactl init` and `alsa restore` calls by `set_alsa()` function,
+two optional custom settings are applied in the following order (assuming
+the DUT belongs to a `PLATFORM` hardware configuration, and the configuration
+files are in `./alsa_settings/` directory):
+
+    1. `PLATFORM.state` - an ALSA driver state file in `alsactl` format.
+
+    2. `PLATFROM.sh` - a shell script to configure the ALSA driver parameters,
+       e.g. calling `amixer` tool.
+
+The custom state should be compatible with the platform's default state.
+
+Currently, the custom settings include all these default ALSA settings the SOF
+tests are expecting at the appropriate DUT.
+In the future most of them should be moved to the DUT's default config
+out of the test case scope, so only the test-specific settings will remain here.
+
+It is important to avoid linking configuration files to 'reuse' them for
+different HW configurations: the `.state` files have platform specific control
+id's, whereas `amixer` refers to the sound card control by its name.
+
+For some platforms their USB audio card settings are also included in
+the configuration files: it is needed to adjust loopback volume levels on the DUT.
+
+
+## DUT host configuration
+
+The DUT host should NOT run `alsa-state.service`.
+
+The `alsa-restore.service` shoudl work only in 'restore' mode (on start) -
+the 'store' mode (on shutdown) should be OFF to keep the default ALSA driver
+settings not changed.
+
+It is NOT allowed to change the DUT's default state with `alsactl store` unless
+it is a special part of the test case, or a DUT recovery procedure.
+
+For more details see [ALSA and systemd](https://wiki.archlinux.org/title/Advanced_Linux_Sound_Architecture#ALSA_and_systemd)
+
+
+## How to create a custom .state file
+
+1. Check contents of the DUT's default ALSA driver configuration `asound.state`.
+   Usually, it is in `/var/lib/alsa/`, and under control of `alsa-restore.service`,
+   or `alsa-state.service`. Make sure you have a backup copy of this file:
+   the ALSA `.service`-s are in charge of keeping your current custom ALSA settings
+   as the DUT's default, so it might unexpectedly affect your DUT normal operations,
+   unless it is your goal.
+
+2. Copy the controls you need to change with the new values into the appropriate
+   platform's `PLATFORM.state` file in `./alsa_settings/`, or create a shell script
+   `PLATFORM.sh` there with the appropriate `amixer` calls.
+   Both these methods can be applied simultaneously.
+