Re: [PATCH v5 2/2] ALSA: pcm: optimize and clarify stream sychronization ID API

[Amadeusz Sławiński <amadeuszx.slawinski@xxxxxxxxxxxxxxx>]

On 6/24/2024 3:07 PM, Jaroslav Kysela wrote:
> Optimize the memory usage in struct snd_pcm_runtime - use boolean
> value for the standard sync ID scheme.
>
> Introduce snd_pcm_set_sync_per_card function to build synchronization
> IDs.
>
> Signed-off-by: Jaroslav Kysela <perex@xxxxxxxx>
> ---

(...)

>   void snd_pcm_set_ops(struct snd_pcm * pcm, int direction,
>   		     const struct snd_pcm_ops *ops);
> -void snd_pcm_set_sync(struct snd_pcm_substream *substream);
> +void snd_pcm_set_sync_per_card(struct snd_pcm_substream *substream, struct snd_pcm_hw_params *params,
> +			       const unsigned char *id, unsigned int len);
> +/**
> + * snd_pcm_set_sync - set the PCM sync id
> + * snd_pcm_set_sync_per_card - set the PCM sync id with card number

Above doc line seems like mistake in this place? This function is 
documented below ;)

> + * @substream: the pcm substream
> + *
> + * Use the default PCM sync identifier for the specific card.
> + */
> +static inline void snd_pcm_set_sync(struct snd_pcm_substream *substream)
> +{
> +	substream->runtime->sync_flag = true;
> +}
>   int snd_pcm_lib_ioctl(struct snd_pcm_substream *substream,
>   		      unsigned int cmd, void *arg);
>   void snd_pcm_period_elapsed_under_stream_lock(struct snd_pcm_substream *substream);
> diff --git a/sound/core/pcm_lib.c b/sound/core/pcm_lib.c
> index a6d59ee9eb52..8d1a24a2c43d 100644
> --- a/sound/core/pcm_lib.c
> +++ b/sound/core/pcm_lib.c
> @@ -516,19 +516,37 @@ void snd_pcm_set_ops(struct snd_pcm *pcm, int direction,
>   EXPORT_SYMBOL(snd_pcm_set_ops);
>   
>   /**
> - * snd_pcm_set_sync - set the PCM sync id
> + * snd_pcm_set_sync_per_card - set the PCM sync id with card number

Here ^

>    * @substream: the pcm substream
> + * @params: modified hardware parameters
> + * @id: identifier (max 12 bytes)
> + * @len: identifier length (max 12 bytes)
>    *
> - * Sets the PCM sync identifier for the card.
> + * Sets the PCM sync identifier for the card with zero padding.
> + *
> + * User space or any user should use this 16-byte identifier for a comparison only
> + * to check if two IDs are similar or different. Special case is the identifier
> + * containing only zeros. Interpretation for this combination is - empty (not set).
> + * The contents of the identifier should not be interpreted in any other way.
> + *
> + * The synchronization ID must be unique per clock source (usually one sound card,
> + * but multiple soundcard may use one PCM word clock source which means that they
> + * are fully synchronized).
> + *
> + * This routine composes this ID using card number in first four bytes and
> + * 12-byte additional ID. When other ID composition is used (e.g. for multiple
> + * sound cards), make sure that the composition does not clash with this
> + * composition scheme.
>    */