[alsa-devel] [alsa-lib][PATCH 1/2] ctl: deprecate APIs of dimension information

[Takashi Iwai]

On Sat, 04 Nov 2017 03:24:25 +0100,
Takashi Sakamoto wrote:
> 
> In ALSA control interface of asound.h, 'struct snd_ctl_elem_info' has
> 'dimen' member to deliver information for multi-dimensional array, however
> there's no common way to handle the member. As a result, drivers can
> force userspace applications to handle the information by inconsistent
> ways.

Well, the text is slightly misleading.
Actually the API itself wasn't bad and you can implement it
consistently.  But practically seen, we haven't got *any* driver using
the feature in the correct way for over decades.  The only user was
echoaudio drivers but it was obviously wrong.  So, judging from the
situation, keeping this doesn't make much sense -- that's the reason
for dropping.


> This issue was reported by a commit 51db452df07b ('Revert "ALSA: echoaudio:
> purge contradictions between dimension matrix members and total number of
> members"') to Linux kernel. As a result of discussion at Linux
> miniconference 2017, usage of 'dimen' member of 'struct snd_ctl_elem_info'
> is going to be deprecated for future removal.
> 
> This commit deprecates some APIs related to the dimension information. They
> are planned to be removed in a development period for Linux kernel v4.21.

IMO, the version to deprecate the feature may depend on LTS kernel
version.  4.21 looks OK, but we may shift it.


thanks,

Takashi

> 
> Signed-off-by: Takashi Sakamoto <o-takashi at sakamocchi.jp>
> ---
>  src/control/control.c | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/src/control/control.c b/src/control/control.c
> index 6439b294..88828f54 100644
> --- a/src/control/control.c
> +++ b/src/control/control.c
> @@ -2503,6 +2503,10 @@ const char *snd_ctl_elem_info_get_item_name(const snd_ctl_elem_info_t *obj)
>   * \brief Get count of dimensions for given element
>   * \param obj CTL element id/info
>   * \return zero value if no dimensions are defined, otherwise positive value with count of dimensions
> + *
> + * \deprecated	Since 1.1.5
> + * #snd_ctl_elem_info_get_dimensions is deprecated without any replacement,
> + * under a decision to drop corresponding kernel ABI at Linux v4.21.
>   */
>  #ifndef DOXYGEN
>  int INTERNAL(snd_ctl_elem_info_get_dimensions)(const snd_ctl_elem_info_t *obj)
> @@ -2525,6 +2529,10 @@ use_default_symbol_version(__snd_ctl_elem_info_get_dimensions, snd_ctl_elem_info
>   * \param obj CTL element id/info
>   * \param idx The dimension index
>   * \return zero value if no dimension width is defined, otherwise positive value with with of specified dimension
> + *
> + * \deprecated	Since 1.1.5
> + * #snd_ctl_elem_info_get_dimension is deprecated without any replacement,
> + * under a decision to drop corresponding kernel ABI at Linux v4.21.
>   */
>  #ifndef DOXYGEN
>  int INTERNAL(snd_ctl_elem_info_get_dimension)(const snd_ctl_elem_info_t *obj, unsigned int idx)
> @@ -2553,6 +2561,10 @@ use_default_symbol_version(__snd_ctl_elem_info_get_dimension, snd_ctl_elem_info_
>   *
>   * \par Compatibility:
>   * This function is added in version 1.1.2.
> + *
> + * \deprecated Since 1.1.5
> + * #snd_ctl_elem_info_set_dimension is deprecated without any replacement,
> + * under a decision to drop corresponding kernel ABI at Linux v4.21.
>   */
>  int snd_ctl_elem_info_set_dimension(snd_ctl_elem_info_t *info,
>  				    const int dimension[4])
> -- 
> 2.11.0
>