[PATCH 0/2] alsa-lib: -ENODATA documentation

[PATCH 0/2] alsa-lib: -ENODATA documentation

[Kai Vehmanen]

Hello all,

here's patch to document -ENODATA error as a PCM error code.
We have recently merged patches to SOF firmware to use
this error code:
  https://github.com/thesofproject/sof/pull/2918

Some additional background on the use-case:
  https://github.com/thesofproject/sof/issues/2564

In thread "Functionality of pcm_notify in snd-aloop?"
https://mailman.alsa-project.org/pipermail/alsa-devel/2020-April/166974.html

.. we discussed the possibility for ALSA to provide a mechanism
for application to wait for the condition to change, but at least
for the currently known usages, the synchronization responsibility
will be in user-space (UCM file will describe the PCM dependencies).
Anyways, this is orthogonal to documenting -ENODATA, so sending
this now.

Kai Vehmanen (2):
  pcm: add documentation for -ENODATA error code
  pcm: fix spelling in documentation for -EBADFD

 src/pcm/pcm.c | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

-- 
2.26.2

[PATCH 1/2] pcm: add documentation for -ENODATA error code

[Kai Vehmanen]

This error code can be used e.g. with echo reference PCM devices
(the SND_USE_CASE_MOD_ECHO_REF UCM token).

Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>
---
 src/pcm/pcm.c | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index 1064044c9812..488a8dd0493d 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -292,6 +292,14 @@ This error can happen when device is physically removed (for example
 some hotplug devices like USB or PCMCIA, CardBus or ExpressCard
 can be removed on the fly).
 
+\par -ENODATA
+
+This error can happen if the device data transfer is dependent on
+an external condition and that condition is not met. For example,
+PCM device for echo reference as described by SND_USE_CASE_MOD_ECHO_REF
+UCM token, may return -ENODATA if the linked playback stream has not been
+started.
+
 \section pcm_params Managing parameters
 
 The ALSA PCM device uses two groups of PCM related parameters. The hardware
-- 
2.26.2

[PATCH 2/2] pcm: fix spelling in documentation for -EBADFD

[Kai Vehmanen]

Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>
---
 src/pcm/pcm.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index 488a8dd0493d..79322b4eab0d 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -284,7 +284,7 @@ supports resume and the snd_pcm_prepare() call can be ommited.
 \par -EBADFD
 
 This error means that the device is in a bad state. It means that
-the handskahe between application and alsa-lib is corrupted.
+the handshake between application and alsa-lib is corrupted.
 
 \par -ENOTTY, -ENODEV
 
-- 
2.26.2

Re: [PATCH 0/2] alsa-lib: -ENODATA documentation

[Jaroslav Kysela]

Dne 29. 05. 20 v 14:28 Kai Vehmanen napsal(a):
> Hello all,
> 
> here's patch to document -ENODATA error as a PCM error code.
> We have recently merged patches to SOF firmware to use
> this error code:
>    https://github.com/thesofproject/sof/pull/2918
> 
> Some additional background on the use-case:
>    https://github.com/thesofproject/sof/issues/2564
> 
> In thread "Functionality of pcm_notify in snd-aloop?"
> https://mailman.alsa-project.org/pipermail/alsa-devel/2020-April/166974.html
> 
> .. we discussed the possibility for ALSA to provide a mechanism
> for application to wait for the condition to change, but at least
> for the currently known usages, the synchronization responsibility
> will be in user-space (UCM file will describe the PCM dependencies).
> Anyways, this is orthogonal to documenting -ENODATA, so sending
> this now.
> 
> Kai Vehmanen (2):
>    pcm: add documentation for -ENODATA error code
>    pcm: fix spelling in documentation for -EBADFD
> 
>   src/pcm/pcm.c | 10 +++++++++-
>   1 file changed, 9 insertions(+), 1 deletion(-)
> 

I applied those two patches, and added a short description that there is
no recovery mechanism and an event mechanism to notify the link availability 
at the moment.

https://github.com/alsa-project/alsa-lib/commit/f3597737defe495f9c618b12507c9528c0ade1ee

						Jaroslav

-- 
Jaroslav Kysela <perex@perex.cz>
Linux Sound Maintainer; ALSA Project; Red Hat, Inc.