ALSA: hda: document state machine for hdac_streams

The code in this library is far from self-explanatory, hopefully this
state diagram reverse-engineered from the code will help others
understand the expected transitions.

Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Reviewed-by: Bard Liao <yung-chuan.liao@linux.intel.com>
Reviewed-by: Péter Ujfalusi <peter.ujfalusi@linux.intel.com>
Reviewed-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>
Link: https://lore.kernel.org/r/20220919121041.43463-3-pierre-louis.bossart@linux.intel.com
Signed-off-by: Takashi Iwai <tiwai@suse.de>

diff --git a/sound/hda/hdac_stream.c b/sound/hda/hdac_stream.c
index 2dbde3d..2e98f5f 100644 (file)
--- a/sound/hda/hdac_stream.c
+++ b/sound/hda/hdac_stream.c
@@ -13,6 +13,39 @@
 #include <sound/hda_register.h>
 #include "trace.h"
 
+/*
+ * the hdac_stream library is intended to be used with the following
+ * transitions. The states are not formally defined in the code but loosely
+ * inspired by boolean variables. Note that the 'prepared' field is not used
+ * in this library but by the callers during the hw_params/prepare transitions
+ *
+ *                        |
+ *     stream_init()      |
+ *                        v
+ *                     +--+-------+
+ *                     |  unused  |
+ *                     +--+----+--+
+ *                        |    ^
+ *     stream_assign()    |    |    stream_release()
+ *                        v    |
+ *                     +--+----+--+
+ *                     |  opened  |
+ *                     +--+----+--+
+ *                        |    ^
+ *     stream_reset()     |    |
+ *     stream_setup()     |    |    stream_cleanup()
+ *                        v    |
+ *                     +--+----+--+
+ *                     | prepared |
+ *                     +--+----+--+
+ *                        |    ^
+ *     stream_start()     |    |    stream_stop()
+ *                        v    |
+ *                     +--+----+--+
+ *                     |  running |
+ *                     +----------+
+ */
+
 /**
  * snd_hdac_get_stream_stripe_ctl - get stripe control value
  * @bus: HD-audio core bus