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

[Takashi Sakamoto]

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.

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.

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