Skip to contentSkip to conversation

ALSA: compress: Document stream states and fix gaplless SM

PATCH Superseded Vinod Koul 3 participants 12 messages Jun 19, 2020 – Jun 22, 2020

Subsystems (3)

v1 of 5 Superseded Latest is v5 →

lore
Share & tools
lore

Vinod Koul

author maintainer
#0 lore raw

cover ALSA: compress: Document stream states and fix gaplless SM

Srini found issue with gapless implementation which prompted to look deeper into SM for compressed stream.

So documenting SM was first step, so first two patches add that. Last patch fixes the issue by keeping track on partial_drain and then moving state to 'running' in snd_compr_drain_notify() for partial_drain case on success. While at it, noticed snd_compr_drain_notify() is lockless state change, so fixed that as well.

I have tested this on Dragon board RB3, compressed audio works out of the box on that platform and Srini will send driver and fcplay patches for gapless soon.

Vinod Koul (3):
ALSA: compress: document the compress audio state machine
ALSA: compress: document the compress gapless audio state machine
ALSA: compress: fix partial_drain completion state

 .../sound/designs/compress-offload.rst        | 84 +++++++++++++++++++
 include/sound/compress_driver.h               | 12 ++-
 sound/core/compress_offload.c                 |  4 +
 3 files changed, 99 insertions(+), 1 deletion(-)
Signature · 1 line
2.26.2
author maintainer
#1 lore raw

PATCH 1/3 ALSA: compress: document the compress audio state machine

So we had some discussions of the stream states, so I thought it is a good idea to document the state transitions, so add it documentation

---
 .../sound/designs/compress-offload.rst        | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)
Documentation/sound/designs/compress-offload.rst +52 -0
index ad4bfbdacc83..7292717c43bf 100644
@@ -151,6 +151,58 @@ Modifications include:
 - Addition of encoding options when required (derived from OpenMAX IL)
 - Addition of rateControlSupported (missing in OpenMAX AL)
 
+State Machine
+=============
+
+The compressed audio stream state machine is described below ::
+
+                                        +----------+
+                                        |          |
+                                        |   OPEN   |
+                                        |          |
+                                        +----------+
+                                             |
+                                             |
+                                             | compr_set_params()
+                                             |
+                                             V
+                                        +----------+
+                compr_drain_notify()    |          |
+              +------------------------>|   SETUP  |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_write()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              |                         |  PREPARE |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_start()
+              |                              |
+              |                              V
+        +----------+                    +----------+     compr_pause()      +----------+
+        |          |                    |          |----------------------->|          |
+        |  DRAIN   |<-------------------|  RUNNING |                        |  PAUSE   |
+        |          |                    |          |<-----------------------|          |
+        +----------+                    +----------+     compr_resume()     +----------+
+              |                              |
+              |                              |
+              |                              | compr_free()
+              |                              |
+              |                              V
+              |                         +----------+
+              |     compr_free()        |          |
+              +------------------------>|          |
+                                        |   STOP   |
+                                        |          |
+                                        +----------+
+
 
 Gapless Playback
 ================
Signature · 1 line
2.26.2
Reviewed-by on v1 1/3
#2 lore raw

Re: [PATCH 1/3] ALSA: compress: document the compress audio state machine

Quoted 5 lines · Vinod Koul

So we had some discussions of the stream states, so I thought it is a good idea to document the state transitions, so add it documentation

---

Thanks Vinod for doing this,
Makes things much clear on the state-machine side!

Quoted 67 lines
  .../sound/designs/compress-offload.rst        | 52 +++++++++++++++++++
  1 file changed, 52 insertions(+)
Documentation/sound/designs/compress-offload.rst +52 -0
index ad4bfbdacc83..7292717c43bf 100644
@@ -151,6 +151,58 @@ Modifications include:
  - Addition of encoding options when required (derived from OpenMAX IL)
  - Addition of rateControlSupported (missing in OpenMAX AL)
 
+State Machine
+=============
+
+The compressed audio stream state machine is described below ::
+
+                                        +----------+
+                                        |          |
+                                        |   OPEN   |
+                                        |          |
+                                        +----------+
+                                             |
+                                             |
+                                             | compr_set_params()
+                                             |
+                                             V
+                                        +----------+
+                compr_drain_notify()    |          |
+              +------------------------>|   SETUP  |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_write()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              |                         |  PREPARE |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_start()
+              |                              |
+              |                              V
+        +----------+                    +----------+     compr_pause()      +----------+
+        |          |                    |          |----------------------->|          |
+        |  DRAIN   |<-------------------|  RUNNING |                        |  PAUSE   |
+        |          |                    |          |<-----------------------|          |
+        +----------+                    +----------+     compr_resume()     +----------+
+              |                              |
+              |                              |
+              |                              | compr_free()
+              |                              |
+              |                              V
+              |                         +----------+
+              |     compr_free()        |          |
+              +------------------------>|          |
+                                        |   STOP   |
+                                        |          |
+                                        +----------+
+
 
  Gapless Playback
  ================
#3 lore raw

Re: [PATCH 1/3] ALSA: compress: document the compress audio state machine

In reply to Vinod Koul
Quoted 38 lines
Documentation/sound/designs/compress-offload.rst +37 -0
+
+                                        +----------+
+                                        |          |
+                                        |   OPEN   |
+                                        |          |
+                                        +----------+
+                                             |
+                                             |
+                                             | compr_set_params()
+                                             |
+                                             V
+                                        +----------+
+                compr_drain_notify()    |          |
+              +------------------------>|   SETUP  |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_write()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              |                         |  PREPARE |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_start()
+              |                              |
+              |                              V
+        +----------+                    +----------+     compr_pause()      +----------+
+        |          |                    |          |----------------------->|          |
+        |  DRAIN   |<-------------------|  RUNNING |                        |  PAUSE   |
+        |          |                    |          |<-----------------------|          |
+        +----------+                    +----------+     compr_resume()     +----------+
+              |                              |

Documentation/sound/designs/compress-offload.rst Modifications include: · line 204

Quoted 10 lines
Documentation/sound/designs/compress-offload.rst +10 -0
+              |                              |
+              |                              | compr_free()
+              |                              |
+              |                              V
+              |                         +----------+
+              |     compr_free()        |          |
+              +------------------------>|          |
+                                        |   STOP   |
+                                        |          |
+                                        +----------+

The STOP state doesn't seem quite right to me, sorry.

the direction of the DRAIN-STOP comp_free() arrow seems wrong? Of if it is correct, then something's missing to exit the STOP state so that the stream can be opened again.

author maintainer
#4 lore raw

Re: [PATCH 1/3] ALSA: compress: document the compress audio state machine

HI Pierre,

Quoted 50 lines · Pierre-Louis Bossart
Quoted 38 lines
Documentation/sound/designs/compress-offload.rst +37 -0
+
+                                        +----------+
+                                        |          |
+                                        |   OPEN   |
+                                        |          |
+                                        +----------+
+                                             |
+                                             |
+                                             | compr_set_params()
+                                             |
+                                             V
+                                        +----------+
+                compr_drain_notify()    |          |
+              +------------------------>|   SETUP  |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_write()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              |                         |  PREPARE |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_start()
+              |                              |
+              |                              V
+        +----------+                    +----------+     compr_pause()      +----------+
+        |          |                    |          |----------------------->|          |
+        |  DRAIN   |<-------------------|  RUNNING |                        |  PAUSE   |
+        |          |                    |          |<-----------------------|          |
+        +----------+                    +----------+     compr_resume()     +----------+
+              |                              |

Documentation/sound/designs/compress-offload.rst Modifications include: · line 204

Quoted 10 lines
Documentation/sound/designs/compress-offload.rst +10 -0
+              |                              |
+              |                              | compr_free()
+              |                              |
+              |                              V
+              |                         +----------+
+              |     compr_free()        |          |
+              +------------------------>|          |
+                                        |   STOP   |
+                                        |          |
+                                        +----------+
Quoted 1 line

The STOP state doesn't seem quite right to me, sorry.

We should call it free, Will update

Quoted 3 lines

the direction of the DRAIN-STOP comp_free() arrow seems wrong? Of if it is correct, then something's missing to exit the STOP state so that the stream can be opened again.

Once stream is freed, it can't be opened again.

But we have trigger stop which is not comprehended here, I will add compr_stop() above which would transition to SETUP state. And a stopped stream can be freed up as well, so one more transition from SETUP to FREE.

Thanks for reviewing

Signature · 1 line
~Vinod
author maintainer
#5 lore raw

PATCH 2/3 ALSA: compress: document the compress gapless audio state machine

In reply to Vinod Koul

Also documented the galpess transitions. Please note that these are not really stream states, but show how the stream steps in gapless mode

---
 .../sound/designs/compress-offload.rst        | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)
Documentation/sound/designs/compress-offload.rst +32 -0
index 7292717c43bf..3e241530e173 100644
@@ -251,6 +251,38 @@ Sequence flow for gapless would be:
 
 (note: order for partial_drain and write for next track can be reversed as well)
 
+Gapless Playback SM
+===================
+
+For Gapless, we move from running state to partial drain and back, along
+with setting of meta_data and signalling for next track ::
+
+
+                                        +----------+
+                compr_drain_notify()    |          |
+              +------------------------>|  RUNNING |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_next_track()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              |                         |NEXT_TRACK|
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_partial_drain()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              +------------------------ | PARTIAL_ |
+                                        |  DRAIN   |
+                                        +----------+
 
 Not supported
 =============
Signature · 1 line
2.26.2
#6 lore raw

Re: [PATCH 2/3] ALSA: compress: document the compress gapless audio state machine

Quoted 20 lines
Documentation/sound/designs/compress-offload.rst +19 -0
+For Gapless, we move from running state to partial drain and back, along
+with setting of meta_data and signalling for next track ::
+
+
+                                        +----------+
+                compr_drain_notify()    |          |
+              +------------------------>|  RUNNING |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_next_track()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              |                         |NEXT_TRACK|
+              |                         |          |
+              |                         +----------+

Documentation/sound/designs/compress-offload.rst Sequence flow for gapless would be: · line 285

Quoted 10 lines
Documentation/sound/designs/compress-offload.rst +10 -0
+              |                              |
+              |                              |
+              |                              | compr_partial_drain()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              +------------------------ | PARTIAL_ |
+                                        |  DRAIN   |
+                                        +----------+

May I suggest having a single state machine, not a big one and an additional partial one. It would help explain why in one case compr_drain_notify() triggers a transition to RUNNING while in the other one it goes to SETUP.

I realize it's more complicated to edit but it'd be easier on reviewers/users.

author maintainer
#7 lore raw

Re: [PATCH 2/3] ALSA: compress: document the compress gapless audio state machine

Quoted 35 lines · Pierre-Louis Bossart
Quoted 20 lines
Documentation/sound/designs/compress-offload.rst +19 -0
+For Gapless, we move from running state to partial drain and back, along
+with setting of meta_data and signalling for next track ::
+
+
+                                        +----------+
+                compr_drain_notify()    |          |
+              +------------------------>|  RUNNING |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_next_track()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              |                         |NEXT_TRACK|
+              |                         |          |
+              |                         +----------+

Documentation/sound/designs/compress-offload.rst Sequence flow for gapless would be: · line 285

Quoted 10 lines
Documentation/sound/designs/compress-offload.rst +10 -0
+              |                              |
+              |                              |
+              |                              | compr_partial_drain()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              +------------------------ | PARTIAL_ |
+                                        |  DRAIN   |
+                                        +----------+

May I suggest having a single state machine, not a big one and an additional partial one. It would help explain why in one case compr_drain_notify() triggers a transition to RUNNING while in the other one it goes to SETUP.

Quoted 2 lines

I realize it's more complicated to edit but it'd be easier on reviewers/users.

Ell adding stop and transitions would really make it complicated and gapless is a bit different handling and it looks cleaner this way IMO, so lets stick to this. Feel free to create one if you are up for it.

Signature · 1 line
~Vinod
#8 lore raw

Re: [PATCH 2/3] ALSA: compress: document the compress gapless audio state machine

Quoted 36 lines · Vinod Koul
Quoted 35 lines · Pierre-Louis Bossart
Quoted 20 lines
Documentation/sound/designs/compress-offload.rst +19 -0
+For Gapless, we move from running state to partial drain and back, along
+with setting of meta_data and signalling for next track ::
+
+
+                                        +----------+
+                compr_drain_notify()    |          |
+              +------------------------>|  RUNNING |
+              |                         |          |
+              |                         +----------+
+              |                              |
+              |                              |
+              |                              | compr_next_track()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              |                         |NEXT_TRACK|
+              |                         |          |
+              |                         +----------+

Documentation/sound/designs/compress-offload.rst Sequence flow for gapless would be: · line 285

Quoted 10 lines
Documentation/sound/designs/compress-offload.rst +10 -0
+              |                              |
+              |                              |
+              |                              | compr_partial_drain()
+              |                              |
+              |                              V
+              |                         +----------+
+              |                         |          |
+              +------------------------ | PARTIAL_ |
+                                        |  DRAIN   |
+                                        +----------+

May I suggest having a single state machine, not a big one and an additional partial one. It would help explain why in one case compr_drain_notify() triggers a transition to RUNNING while in the other one it goes to SETUP.

Quoted 6 lines
Quoted 2 lines

I realize it's more complicated to edit but it'd be easier on reviewers/users.

Ell adding stop and transitions would really make it complicated and gapless is a bit different handling and it looks cleaner this way IMO, so lets stick to this. Feel free to create one if you are up for it.

if you don't want to change the visuals then please add a paragraph explaining the different uses of compr_drain_notify().

author maintainer
#9 lore raw

PATCH 3/3 ALSA: compress: fix partial_drain completion state

In reply to Vinod Koul

On partial_drain completion we should be in SNDRV_PCM_STATE_RUNNING state, so set that for partially draining streams in snd_compr_drain_notify() and use a flag for partially draining streams

While at it, add locks for stream state change in
snd_compr_drain_notify() as well.

Fixes f44f2a5417b2 ("ALSA: compress: fix drain calls blocking other compress functions (v6)")
---
 include/sound/compress_driver.h | 12 +++++++++++-
 sound/core/compress_offload.c   |  4 ++++
 2 files changed, 15 insertions(+), 1 deletion(-)
include/sound/compress_driver.h +11 -1
index 3df8d8c90191..93a5897201ea 100644
@@ -66,6 +66,7 @@ struct snd_compr_runtime {
  * @direction: stream direction, playback/recording
  * @metadata_set: metadata set flag, true when set
  * @next_track: has userspace signal next track transition, true when set
+ * @partial_drain: undergoing partial_drain for stream, true when set
  * @private_data: pointer to DSP private data
  * @dma_buffer: allocated buffer if any
  */
@@ -78,6 +79,7 @@ struct snd_compr_stream {
 	enum snd_compr_direction direction;
 	bool metadata_set;
 	bool next_track;
+	bool partial_drain;
 	void *private_data;
 	struct snd_dma_buffer dma_buffer;
 };
@@ -187,7 +189,15 @@ static inline void snd_compr_drain_notify(struct snd_compr_stream *stream)
 	if (snd_BUG_ON(!stream))
 		return;
 
-	stream->runtime->state = SNDRV_PCM_STATE_SETUP;
+	mutex_lock(&stream->device->lock);
+	/* for partial_drain case we are back to running state on success */
+	if (stream->partial_drain) {
+		stream->runtime->state = SNDRV_PCM_STATE_RUNNING;
+		stream->partial_drain = false; /* clear this flag as well */
+	} else {
+		stream->runtime->state = SNDRV_PCM_STATE_SETUP;
+	}
+	mutex_unlock(&stream->device->lock);
 
 	wake_up(&stream->runtime->sleep);
 }
sound/core/compress_offload.c +4 -0
index e618580feac4..1c4b2cf450a0 100644
@@ -803,6 +803,9 @@ static int snd_compr_stop(struct snd_compr_stream *stream)
 
 	retval = stream->ops->trigger(stream, SNDRV_PCM_TRIGGER_STOP);
 	if (!retval) {
+		/* clear flags and stop any drain wait */
+		stream->partial_drain = false;
+		stream->metadata_set = false;
 		snd_compr_drain_notify(stream);
 		stream->runtime->total_bytes_available = 0;
 		stream->runtime->total_bytes_transferred = 0;
@@ -960,6 +963,7 @@ static int snd_compr_partial_drain(struct snd_compr_stream *stream)
 	if (stream->next_track == false)
 		return -EPERM;
 
+	stream->partial_drain = true;
 	retval = stream->ops->trigger(stream, SND_COMPR_TRIGGER_PARTIAL_DRAIN);
 	if (retval) {
 		pr_debug("Partial drain returned failure\n");
Signature · 1 line
2.26.2
Reviewed-by Tested-by on v1 3/3
#10 lore raw

Re: [PATCH 3/3] ALSA: compress: fix partial_drain completion state

Quoted 11 lines · Vinod Koul

On partial_drain completion we should be in SNDRV_PCM_STATE_RUNNING state, so set that for partially draining streams in snd_compr_drain_notify() and use a flag for partially draining streams

While at it, add locks for stream state change in
snd_compr_drain_notify() as well.

Fixes f44f2a5417b2 ("ALSA: compress: fix drain calls blocking other compress functions (v6)")

---

Quoted 64 lines
  include/sound/compress_driver.h | 12 +++++++++++-
  sound/core/compress_offload.c   |  4 ++++
  2 files changed, 15 insertions(+), 1 deletion(-)
include/sound/compress_driver.h +11 -1
index 3df8d8c90191..93a5897201ea 100644
@@ -66,6 +66,7 @@ struct snd_compr_runtime {
   * @direction: stream direction, playback/recording
   * @metadata_set: metadata set flag, true when set
   * @next_track: has userspace signal next track transition, true when set
+ * @partial_drain: undergoing partial_drain for stream, true when set
   * @private_data: pointer to DSP private data
   * @dma_buffer: allocated buffer if any
   */
@@ -78,6 +79,7 @@ struct snd_compr_stream {
  	enum snd_compr_direction direction;
  	bool metadata_set;
  	bool next_track;
+	bool partial_drain;
  	void *private_data;
  	struct snd_dma_buffer dma_buffer;
  };
@@ -187,7 +189,15 @@ static inline void snd_compr_drain_notify(struct snd_compr_stream *stream)
  	if (snd_BUG_ON(!stream))
  		return;
 
-	stream->runtime->state = SNDRV_PCM_STATE_SETUP;
+	mutex_lock(&stream->device->lock);
+	/* for partial_drain case we are back to running state on success */
+	if (stream->partial_drain) {
+		stream->runtime->state = SNDRV_PCM_STATE_RUNNING;
+		stream->partial_drain = false; /* clear this flag as well */
+	} else {
+		stream->runtime->state = SNDRV_PCM_STATE_SETUP;
+	}
+	mutex_unlock(&stream->device->lock);
 
  	wake_up(&stream->runtime->sleep);
  }
sound/core/compress_offload.c +4 -0
index e618580feac4..1c4b2cf450a0 100644
@@ -803,6 +803,9 @@ static int snd_compr_stop(struct snd_compr_stream *stream)
 
  	retval = stream->ops->trigger(stream, SNDRV_PCM_TRIGGER_STOP);
  	if (!retval) {
+		/* clear flags and stop any drain wait */
+		stream->partial_drain = false;
+		stream->metadata_set = false;
  		snd_compr_drain_notify(stream);
  		stream->runtime->total_bytes_available = 0;
  		stream->runtime->total_bytes_transferred = 0;
@@ -960,6 +963,7 @@ static int snd_compr_partial_drain(struct snd_compr_stream *stream)
  	if (stream->next_track == false)
  		return -EPERM;
 
+	stream->partial_drain = true;
  	retval = stream->ops->trigger(stream, SND_COMPR_TRIGGER_PARTIAL_DRAIN);
  	if (retval) {
  		pr_debug("Partial drain returned failure\n");
author maintainer
#11 lore raw

Re: [PATCH 3/3] ALSA: compress: fix partial_drain completion state

Quoted 10 lines · Srinivas Kandagatla
Quoted 7 lines · Vinod Koul

On partial_drain completion we should be in SNDRV_PCM_STATE_RUNNING state, so set that for partially draining streams in snd_compr_drain_notify() and use a flag for partially draining streams

While at it, add locks for stream state change in
snd_compr_drain_notify() as well.

Quoted 7 lines
Quoted 4 lines
Fixes f44f2a5417b2 ("ALSA: compress: fix drain calls blocking other compress functions (v6)")

---

Thanks for testing Srini

Signature · 1 line
~Vinod