[alsa-lib][PATCH v2 0/2] ctl: deprecate APIs of dimension information

[alsa-lib][PATCH v2 0/2] ctl: deprecate APIs of dimension information

[Takashi Sakamoto]

Hi,

This patchset is to update my previous one:
[alsa-devel] [alsa-lib][PATCH 0/2] ctl: deprecate APIs of dimension information
http://mailman.alsa-project.org/pipermail/alsa-devel/2017-November/126972.html

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. A series of echoaudio drivers is an actual example of the
inconsistent usage.

This issue was addressed in a commit 51db452df07b ('Revert "ALSA: echoaudio:
purge contradictions between dimension matrix members and total number of
members"') to Linux kernel[1]. Fortunately, at present, this feature of
interface is just used by the drivers, and there's a way to obsolete usage
of the feature. We can obsolete it without large impacts to userland.

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 patchset is for proposed tasks at a development period of
Linux kernel v4.15[3]. Some APIs of dimension information are deprecated.

In a short discussion in my previous patchset, it's clear that actual
removal of kernel interface is uncertain depending on several conditions.
Thus the timing to remove the library APIs is not decided yet. This updated
version reflects the issue in API documentation (but simply removes
statement of the schedule...).

[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/sound/pci/echoaudio?id=51db452df07bb4c5754b73789253ba21681d9dc2

[2] [alsa-devel] [ANNOUNCE] Audio Mini Summit 2017 at Prague, Oct 27
http://mailman.alsa-project.org/pipermail/alsa-devel/2017-July/123110.html

[3] https://github.com/takaswie/presentations/blob/master/20171027/contents.md

Takashi Sakamoto (2):
  ctl: deprecate APIs of dimensional information
  test: obsolete usage of APIs of dimensional information

 src/control/control.c       |  9 +++++++++
 test/user-ctl-element-set.c | 31 -------------------------------
 2 files changed, 9 insertions(+), 31 deletions(-)

-- 
2.14.1

[alsa-lib][PATCH v2 1/2] ctl: deprecate APIs of dimensional information

[Takashi Sakamoto]

In ALSA control interface in 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.

A removal of kernel interface can cause regression issues. However no ALSA
driver in kernel land except for 'echoaudio' series utilizes this feature.
Actually it's reasonable to assume that 'echomixer' program is an unique
consumer of the interface in user land and the removal rarely brings any
impact to user land.

This commit deprecates some APIs corresponding to the kernel interface. The
kernel interface is kept till Linux kernel v4.20 at least, but actual
timing of removal is not fixed yet. After that, these APIs may also be
removed at a reasonable timing.
---
 src/control/control.c | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/control/control.c b/src/control/control.c
index 6439b294..268c5e9c 100644
--- a/src/control/control.c
+++ b/src/control/control.c
@@ -2503,6 +2503,9 @@ 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.
  */
 #ifndef DOXYGEN
 int INTERNAL(snd_ctl_elem_info_get_dimensions)(const snd_ctl_elem_info_t *obj)
@@ -2525,6 +2528,9 @@ 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.
  */
 #ifndef DOXYGEN
 int INTERNAL(snd_ctl_elem_info_get_dimension)(const snd_ctl_elem_info_t *obj, unsigned int idx)
@@ -2553,6 +2559,9 @@ 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.
  */
 int snd_ctl_elem_info_set_dimension(snd_ctl_elem_info_t *info,
 				    const int dimension[4])
-- 
2.14.1

[alsa-lib][PATCH v2 2/2] test: obsolete usage of APIs of dimensional information

[Takashi Sakamoto]

APIs of dimensional information are deprecated for future removal. This
commit removes test codes for user-defined element set in an aspect of
the feature.
---
 test/user-ctl-element-set.c | 31 -------------------------------
 1 file changed, 31 deletions(-)

diff --git a/test/user-ctl-element-set.c b/test/user-ctl-element-set.c
index f3710732..668831a8 100644
--- a/test/user-ctl-element-set.c
+++ b/test/user-ctl-element-set.c
@@ -19,7 +19,6 @@ struct elem_set_trial {
 	unsigned int element_count;
 
 	snd_ctl_elem_id_t *id;
-	int dimension[4];
 
 	int (*add_elem_set)(struct elem_set_trial *trial,
 			    snd_ctl_elem_info_t *info);
@@ -373,7 +372,6 @@ static int add_elem_set(struct elem_set_trial *trial)
 	snd_ctl_elem_info_alloca(&info);
 	snd_ctl_elem_info_set_interface(info, SND_CTL_ELEM_IFACE_MIXER);
 	snd_ctl_elem_info_set_name(info, name);
-	snd_ctl_elem_info_set_dimension(info, trial->dimension);
 
 	err = trial->add_elem_set(trial, info);
 	if (err >= 0)
@@ -544,11 +542,6 @@ static int check_elem_set_props(struct elem_set_trial *trial)
 			return -EIO;
 		if (snd_ctl_elem_info_get_count(info) != trial->member_count)
 			return -EIO;
-		for (j = 0; j < 4; ++j) {
-			if (snd_ctl_elem_info_get_dimension(info, j) !=
-							trial->dimension[j])
-				return -EIO;
-		}
 
 		/*
 		 * In a case of IPC, this is the others. But in this case,
@@ -745,10 +738,6 @@ int main(void)
 		case SND_CTL_ELEM_TYPE_BOOLEAN:
 			trial.element_count = 900;
 			trial.member_count = 128;
-			trial.dimension[0] = 4;
-			trial.dimension[1] = 4;
-			trial.dimension[2] = 8;
-			trial.dimension[3] = 0;
 			trial.add_elem_set = add_bool_elem_set;
 			trial.check_elem_props = NULL;
 			trial.change_elem_members = change_bool_elem_members;
@@ -759,10 +748,6 @@ int main(void)
 		case SND_CTL_ELEM_TYPE_INTEGER:
 			trial.element_count = 900;
 			trial.member_count = 128;
-			trial.dimension[0] = 128;
-			trial.dimension[1] = 0;
-			trial.dimension[2] = 0;
-			trial.dimension[3] = 0;
 			trial.add_elem_set = add_int_elem_set;
 			trial.check_elem_props = check_int_elem_props;
 			trial.change_elem_members = change_int_elem_members;
@@ -773,10 +758,6 @@ int main(void)
 		case SND_CTL_ELEM_TYPE_ENUMERATED:
 			trial.element_count = 900;
 			trial.member_count = 128;
-			trial.dimension[0] = 16;
-			trial.dimension[1] = 8;
-			trial.dimension[2] = 0;
-			trial.dimension[3] = 0;
 			trial.add_elem_set = add_enum_elem_set;
 			trial.check_elem_props = check_enum_elem_props;
 			trial.change_elem_members = change_enum_elem_members;
@@ -786,10 +767,6 @@ int main(void)
 		case SND_CTL_ELEM_TYPE_BYTES:
 			trial.element_count = 900;
 			trial.member_count = 512;
-			trial.dimension[0] = 8;
-			trial.dimension[1] = 4;
-			trial.dimension[2] = 8;
-			trial.dimension[3] = 2;
 			trial.add_elem_set = add_bytes_elem_set;
 			trial.check_elem_props = NULL;
 			trial.change_elem_members = change_bytes_elem_members;
@@ -800,10 +777,6 @@ int main(void)
 		case SND_CTL_ELEM_TYPE_IEC958:
 			trial.element_count = 1;
 			trial.member_count = 1;
-			trial.dimension[0] = 0;
-			trial.dimension[1] = 0;
-			trial.dimension[2] = 0;
-			trial.dimension[3] = 0;
 			trial.add_elem_set = add_iec958_elem_set;
 			trial.check_elem_props = NULL;
 			trial.change_elem_members = change_iec958_elem_members;
@@ -814,10 +787,6 @@ int main(void)
 		default:
 			trial.element_count = 900;
 			trial.member_count = 64;
-			trial.dimension[0] = 0;
-			trial.dimension[1] = 0;
-			trial.dimension[2] = 0;
-			trial.dimension[3] = 0;
 			trial.add_elem_set = add_int64_elem_set;
 			trial.check_elem_props = check_int64_elem_props;
 			trial.change_elem_members = change_int64_elem_members;
-- 
2.14.1

Re: [alsa-lib][PATCH v2 0/2] ctl: deprecate APIs of dimension information

[Takashi Sakamoto]

On Nov 13 2017 09:14, Takashi Sakamoto wrote:
> Hi,
> 
> This patchset is to update my previous one:
> [alsa-devel] [alsa-lib][PATCH 0/2] ctl: deprecate APIs of dimension information
> http://mailman.alsa-project.org/pipermail/alsa-devel/2017-November/126972.html
> 
> 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. A series of echoaudio drivers is an actual example of the
> inconsistent usage.
> 
> This issue was addressed in a commit 51db452df07b ('Revert "ALSA: echoaudio:
> purge contradictions between dimension matrix members and total number of
> members"') to Linux kernel[1]. Fortunately, at present, this feature of
> interface is just used by the drivers, and there's a way to obsolete usage
> of the feature. We can obsolete it without large impacts to userland.
> 
> 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 patchset is for proposed tasks at a development period of
> Linux kernel v4.15[3]. Some APIs of dimension information are deprecated.
> 
> In a short discussion in my previous patchset, it's clear that actual
> removal of kernel interface is uncertain depending on several conditions.
> Thus the timing to remove the library APIs is not decided yet. This updated
> version reflects the issue in API documentation (but simply removes
> statement of the schedule...).
> 
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/sound/pci/echoaudio?id=51db452df07bb4c5754b73789253ba21681d9dc2
> 
> [2] [alsa-devel] [ANNOUNCE] Audio Mini Summit 2017 at Prague, Oct 27
> http://mailman.alsa-project.org/pipermail/alsa-devel/2017-July/123110.html
> 
> [3] https://github.com/takaswie/presentations/blob/master/20171027/contents.md
> 
> Takashi Sakamoto (2):
>    ctl: deprecate APIs of dimensional information
>    test: obsolete usage of APIs of dimensional information
> 
>   src/control/control.c       |  9 +++++++++
>   test/user-ctl-element-set.c | 31 -------------------------------
>   2 files changed, 9 insertions(+), 31 deletions(-)

Oops. I forgot to add my signature... I'm sorry but would you please add 
below when applying these patches into your repository, maintainers?

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>


Thanks

Takashi Sakamoto

Re: [alsa-lib][PATCH v2 0/2] ctl: deprecate APIs of dimension information

[Takashi Iwai]

On Mon, 13 Nov 2017 01:14:09 +0100,
Takashi Sakamoto wrote:
> 
> Hi,
> 
> This patchset is to update my previous one:
> [alsa-devel] [alsa-lib][PATCH 0/2] ctl: deprecate APIs of dimension information
> http://mailman.alsa-project.org/pipermail/alsa-devel/2017-November/126972.html
> 
> 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. A series of echoaudio drivers is an actual example of the
> inconsistent usage.
> 
> This issue was addressed in a commit 51db452df07b ('Revert "ALSA: echoaudio:
> purge contradictions between dimension matrix members and total number of
> members"') to Linux kernel[1]. Fortunately, at present, this feature of
> interface is just used by the drivers, and there's a way to obsolete usage
> of the feature. We can obsolete it without large impacts to userland.
> 
> 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 patchset is for proposed tasks at a development period of
> Linux kernel v4.15[3]. Some APIs of dimension information are deprecated.
> 
> In a short discussion in my previous patchset, it's clear that actual
> removal of kernel interface is uncertain depending on several conditions.
> Thus the timing to remove the library APIs is not decided yet. This updated
> version reflects the issue in API documentation (but simply removes
> statement of the schedule...).
> 
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/sound/pci/echoaudio?id=51db452df07bb4c5754b73789253ba21681d9dc2
> 
> [2] [alsa-devel] [ANNOUNCE] Audio Mini Summit 2017 at Prague, Oct 27
> http://mailman.alsa-project.org/pipermail/alsa-devel/2017-July/123110.html
> 
> [3] https://github.com/takaswie/presentations/blob/master/20171027/contents.md
> 
> Takashi Sakamoto (2):
>   ctl: deprecate APIs of dimensional information
>   test: obsolete usage of APIs of dimensional information

Applied both patches now (with your sign-off).

Thanks!


Takashi