[PATCH 0/3] alsa-lib: UCM - Use Case Manager

[PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Liam Girdwood]

This patch series follows on from the RFC and adds sound card hardware Use Case
Management support to alsa-lib. 
 
The main features of UCM are :-

 o Abstraction of sound card hardware routing and controls into high level
   use case verbs, devices and modifiers.
 o Discovery of source/sink PCMs for each use case.
 o Discovery of hardware master volume controls for each use case.

It's intended UCM will provide clients (like pulseaudio) complete control over
hardware signal routing within a sound card without any knowledge of the
sound card hardware.

Use case definintions are stored in text files (per sound card) and are now
divided into three components as descibed in the RFC. 

A working use case definition file can be found here :-

http://git.slimlogic.co.uk/cgi-bin/cgit.cgi/alsa-ucm-conf.git/tree/cards/SDP4430/hifi

The three components of a use case are now :-

1) Verb (or action). This is mandatory and describes (in terms of ALSA
control settings) the system use case action. e.g "Phone Call", "Music
Playback".

2) Device. This is also mandatory and describes the audio playback or
capture device. e.g. "Handset", "Bluetooth", "Headset".

3) Modifier. This is optional and is used to modify the current use case
verb. i.e. The user could be listening to music when an incoming phone
call requires that a ring tone is played. In this case the use case verb
would be set to "Music Playback" when the music playback started and
then the "Tone Playback" modifier could be enabled to play the ring
tone. The use case verb would then be changed to "Voice Call" if the
call was accepted. 

Patch 2/3 is a little on the large side so, I've included a link if it gets
bounced by the list.

http://git.slimlogic.co.uk/cgi-bin/cgit.cgi/alsa-lib.git/commit/?h=ucm-upstream&id=15d5f619deba20f87075e7c711e6331115fd836d

Liam Girdwood (3):
  ucm: header - ALSA Use Case Manager
  ucm: core - Add initial Use Case Manager support.
  ucm: build - add build support for Use Case Manager

 doc/doxygen.cfg.in  |    1 +
 include/Makefile.am |    2 +-
 include/use-case.h  |  427 +++++++
 src/Makefile.am     |    2 +-
 src/use-case.c      | 3515 +++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 3945 insertions(+), 2 deletions(-)
 create mode 100644 include/use-case.h
 create mode 100644 src/use-case.c

[PATCH 1/3] ucm: header - ALSA Use Case Manager

[Liam Girdwood]

This patch adds the API header for alsa-lib Use Case Management support.

This file defines the public interface exported by UCM to client
applications.

UCM development has been kindly sponsored by Texas Instruments Inc,
Wolfson Microelectronics PLC and Slimlogic Ltd.

CC: Mark Brown <broonie@opensource.wolfsonmicro.com>
Signed-off-by: Stefan Schmidt <stefan@slimlogic.co.uk>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>
Signed-off-by: Justin Xu <justinx@slimlogic.co.uk>
Signed-off-by: Liam Girdwood <lrg@slimlogic.co.uk>
---
 include/use-case.h |  427 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 427 insertions(+), 0 deletions(-)
 create mode 100644 include/use-case.h

diff --git a/include/use-case.h b/include/use-case.h
new file mode 100644
index 0000000..18fe4d6
--- /dev/null
+++ b/include/use-case.h
@@ -0,0 +1,427 @@
+/**
+ * \file include/use-case.h
+ * \brief use case interface for the ALSA driver
+ * \author Liam Girdwood <lrg@slimlogic.co.uk>
+ * \author Stefan Schmidt <stefan@slimlogic.co.uk>
+ * \author Jaroslav Kysela <perex@perex.cz>
+ * \author Justin Xu <justinx@slimlogic.co.uk>
+ * \date 2008-2010
+ */
+/*
+ *
+ *  This library is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License as
+ *  published by the Free Software Foundation; either version 2.1 of
+ *  the License, or (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
+ *
+ *  Copyright (C) 2008-2010 SlimLogic Ltd
+ *  Copyright (C) 2010 Wolfson Microelectronics PLC
+ *  Copyright (C) 2010 Texas Instruments Inc.
+ *
+ *  Support for the verb/device/modifier core logic and API,
+ *  command line tool and file parser was kindly sponsored by
+ *  Texas Instruments Inc.
+ *  Support for multiple active modifiers and devices,
+ *  transition sequences, multiple client access and user defined use
+ *  cases was kindly sponsored by Wolfson Microelectronics PLC.
+ */
+
+#ifndef __ALSA_USE_CASE_H
+#define __ALSA_USE_CASE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ *  \defgroup Use Case Interface
+ *  The ALSA Use Case manager interface.
+ *  See \ref Usecase page for more details.
+ *  \{
+ */
+
+/**
+ * ALSA Use Case Interface
+ *
+ * The use case manager works by configuring the sound card ALSA kcontrols to
+ * change the hardware digital and analog audio routing to match the requested
+ * device use case. The use case manager kcontrol configurations are stored in
+ * easy to modify text files.
+ *
+ * An audio use case can be defined by a verb and device parameter. The verb
+ * describes the use case action i.e. a phone call, listening to music, recording
+ * a conversation etc. The device describes the physical audio capture and playback
+ * hardware i.e. headphones, phone handset, bluetooth headset, etc.
+ *
+ * It's intended clients will mostly only need to set the use case verb and
+ * device for each system use case change (as the verb and device parameters
+ * cover most audio use cases).
+ *
+ * However there are times when a use case has to be modified at runtime. e.g.
+ *
+ *  o Incoming phone call when the device is playing music
+ *  o Recording sections of a phone call
+ *  o Playing tones during a call.
+ *
+ * In order to allow asynchronous runtime use case adaptations, we have a third
+ * optional modifier parameter that can be used to further configure
+ * the use case during live audio runtime.
+ *
+ * This interface allows clients to :-
+ *
+ *  o Query the supported use case verbs, devices and modifiers for the machine.
+ *  o Set and Get use case verbs, devices and modifiers for the machine.
+ *  o Get the ALSA PCM playback and capture device PCMs for use case verb and
+ *     modifier.
+ *  o Get the QoS parameter for each use case verb and modifier.
+ *  o Get the ALSA master playback and capture volume/switch kcontrols
+ *     for each use case.
+ */
+
+
+/*
+ * Use Case Verb.
+ *
+ * The use case verb is the main device audio action. e.g. the "HiFi" use
+ * case verb will configure the audio hardware for HiFi Music playback
+ * and capture.
+ */
+#define SND_USE_CASE_VERB_INACTIVE		"Inactive"
+#define SND_USE_CASE_VERB_HIFI			"HiFi"
+#define SND_USE_CASE_VERB_HIFI_LOW_POWER	"HiFi Low Power"
+#define SND_USE_CASE_VERB_VOICE		"Voice"
+#define SND_USE_CASE_VERB_VOICE_LOW_POWER	"Voice Low Power"
+#define SND_USE_CASE_VERB_VOICECALL		"Voice Call"
+#define SND_USE_CASE_VERB_IP_VOICECALL		"Voice Call IP"
+#define SND_USE_CASE_VERB_ANALOG_RADIO		"FM Analog Radio"
+#define SND_USE_CASE_VERB_DIGITAL_RADIO	"FM Digital Radio"
+/* add new verbs to end of list */
+
+
+/*
+ * Use Case Device.
+ *
+ * Physical system devices the render and capture audio. Devices can be OR'ed
+ * together to support audio on similtanious devices.
+ */
+#define SND_USE_CASE_DEV_NONE		"None"
+#define SND_USE_CASE_DEV_SPEAKER	"Speaker"
+#define SND_USE_CASE_DEV_LINE		"Line"
+#define SND_USE_CASE_DEV_HEADPHONES	"Headphones"
+#define SND_USE_CASE_DEV_HEADSET	"Headset"
+#define SND_USE_CASE_DEV_HANDSET	"Handset"
+#define SND_USE_CASE_DEV_BLUETOOTH	"Bluetooth"
+#define SND_USE_CASE_DEV_EARPIECE	"Earpiece"
+#define SND_USE_CASE_DEV_SPDIF		"SPDIF"
+#define SND_USE_CASE_DEV_HDMI		"HDMI"
+/* add new devices to end of list */
+
+
+/*
+ * Use Case Modifiers.
+ *
+ * The use case modifier allows runtime configuration changes to deal with
+ * asynchronous events.
+ *
+ * e.g. to record a voice call :-
+ *  1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
+ *  2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
+ *  3. Call snd_use_case_get_verb_capture_pcm() to get ALSA source PCM
+ *     with captured voice pcm data.
+ *
+ * e.g. to play a ring tone when listenin to MP3 Music :-
+ *  1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
+ *  2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
+ *  3. Call snd_use_case_get_verb_playback_pcm() to get ALSA PCM sink for
+ *     ringtone pcm data.
+ */
+#define SND_USE_CASE_MOD_CAPTURE_VOICE		"Capture Voice"
+#define SND_USE_CASE_MOD_CAPTURE_MUSIC		"Capture Music"
+#define SND_USE_CASE_MOD_PLAY_MUSIC		"Play Music"
+#define SND_USE_CASE_MOD_PLAY_VOICE		"Play Voice"
+#define SND_USE_CASE_MOD_PLAY_TONE		"Play Tone"
+#define SND_USE_CASE_MOD_ECHO_REF		"Echo Reference"
+/* add new modifiers to end of list */
+
+
+/**
+ * QoS - Quality of Service
+ *
+ * The interface allows clients to determine the audio QoS required for each
+ * use case verb and modifier. It's intended as an optional hint to the
+ * audio driver in order to lower power consumption.
+ *
+ */
+enum snd_use_case_qos {
+	SND_USE_CASE_QOS_UNKNOWN,
+	SND_USE_CASE_QOS_MUSIC,
+	SND_USE_CASE_QOS_VOICE,
+	SND_USE_CASE_QOS_TONES,
+};
+
+/*
+ * Use Case Control Aliases.
+ *
+ * Use cases often use different internal hardware paths to route digital and
+ * analog audio. This can mean different controls are used to change volumes
+ * depending on the particular use case. This interface allows clients to
+ * find out the hardware controls associated with each use case.
+ */
+enum snd_use_case_control_alias {
+	SND_USE_CASE_ALIAS_PLAYBACK_VOLUME = 0,
+	SND_USE_CASE_ALIAS_PLAYBACK_SWITCH,
+	SND_USE_CASE_ALIAS_CAPTURE_VOLUME,
+	SND_USE_CASE_ALIAS_CAPTURE_SWITCH,
+};
+
+/** use case container */
+typedef struct snd_use_case_mgr snd_use_case_mgr_t;
+
+/**
+ * \brief List supported use case verbs for given soundcard
+ * \param uc_mgr Use case manager
+ * \param verb Returned list of supported use case verbs
+ * \return Number of use case verbs if success, otherwise a negative error code
+ */
+int snd_use_case_get_verb_list(snd_use_case_mgr_t *uc_mgr, const char **verb[]);
+
+/**
+ * \brief List supported use case devices for given use case verb
+ * \param uc_mgr Use case manager
+ * \param verb Verb name.
+ * \param device Returned list of supported use case devices
+ * \return Number of use case devices if success, otherwise a negative error code
+ */
+int snd_use_case_get_device_list(snd_use_case_mgr_t *uc_mgr,
+		const char *verb, const char **device[]);
+
+/**
+ * \brief List supported use case verb modifiers for given verb
+ * \param uc_mgr use case manager
+ * \param verb verb id.
+ * \param mod returned list of supported use case modifier id and names
+ * \return number of use case modifiers if success, otherwise a negative error code
+ */
+int snd_use_case_get_mod_list(snd_use_case_mgr_t *uc_mgr,
+		const char *verb, const char **mod[]);
+
+/**
+ * \brief Get current use case verb for sound card
+ * \param uc_mgr Use case manager
+ * \return Verb if success, otherwise NULL
+ */
+const char *snd_use_case_get_verb(snd_use_case_mgr_t *uc_mgr);
+
+/**
+ * \brief Set new use case verb for sound card
+ * \param uc_mgr Use case manager
+ * \param verb Verb
+ * \return Zero if success, otherwise a negative error code
+ */
+int snd_use_case_set_verb(snd_use_case_mgr_t *uc_mgr, const char *verb);
+
+/**
+ * \brief Enable use case device for current use case verb
+ * \param uc_mgr Use case manager
+ * \param device Device
+ * \return Zero if success, otherwise a negative error code
+ */
+int snd_use_case_enable_device(snd_use_case_mgr_t *uc_mgr, const char *device);
+
+/**
+ * \brief Disable use case device for current use case verb
+ * \param uc_mgr Use case manager
+ * \param device Device
+ * \return Zero if success, otherwise a negative error code
+ */
+int snd_use_case_disable_device(snd_use_case_mgr_t *uc_mgr, const char *device);
+
+/**
+ * \brief Disable old_device and then enable new_device.
+ *        If from_device is not enabled just return.
+ *        Check transmit sequence firstly.
+ * \param uc_mgr Use case manager
+ * \param old the device to be closed
+ * \param new the device to be opened
+ * \return 0 = successful negative = error
+ */
+int snd_use_case_switch_device(snd_use_case_mgr_t *uc_mgr,
+			const char *old, const char *new);
+
+
+/**
+ * \brief Enable use case modifier for current use case verb
+ * \param uc_mgr Use case manager
+ * \param modifier Modifier
+ * \return Zero if success, otherwise a negative error code
+ */
+int snd_use_case_enable_modifier(snd_use_case_mgr_t *uc_mgr,
+		const char *modifier);
+
+/**
+ * \brief Disable use case modifier for curent use case verb
+ * \param uc_mgr Use case manager
+ * \param modifier Modifier
+ * \return Zero if success, otherwise a negative error code
+ */
+int snd_use_case_disable_modifier(snd_use_case_mgr_t *uc_mgr,
+		const char *modifier);
+
+/**
+ * \brief Disable old_modifier and then enable new_modifier.
+ *        If old_modifier is not enabled just return.
+ *        Check transmit sequence firstly.
+ * \param uc_mgr Use case manager
+ * \param old the modifier to be closed
+ * \param new the modifier to be opened
+ * \return 0 = successful negative = error
+ */
+int snd_use_case_switch_modifier(snd_use_case_mgr_t *uc_mgr,
+			const char *old, const char *new);
+
+/**
+ * \brief Get device status for current use case verb
+ * \param uc_mgr Use case manager
+ * \param device_name The device we are interested in.
+ * \return - 1 = enabled, 0 = disabled, negative = error
+ */
+int snd_use_case_get_device_status(snd_use_case_mgr_t *uc_mgr,
+		const char *device_name);
+
+/**
+ * \brief Get modifier status for current use case verb
+ * \param uc_mgr Use case manager
+ * \param device_name The device we are interested in.
+ * \return - 1 = enabled, 0 = disabled, negative = error
+ */
+int snd_use_case_get_modifier_status(snd_use_case_mgr_t *uc_mgr,
+		const char *modifier_name);
+
+/**
+ * \brief Get the current use case verb QoS
+ * \param uc_mgr Use case manager
+ * \return QoS level
+ */
+enum snd_use_case_qos snd_use_case_get_verb_qos(snd_use_case_mgr_t *uc_mgr);
+
+/**
+ * \brief Get use case modifier QoS
+ * \param uc_mgr use case manager
+ * \param modifier Modifier
+ * \return QoS level
+ */
+enum snd_use_case_qos snd_use_case_get_mod_qos(snd_use_case_mgr_t *uc_mgr,
+	const char *modifier);
+
+/**
+ * \brief Get the current use case verb playback PCM sink ID.
+ * \param uc_mgr use case manager
+ * \return PCM number if success, otherwise negative
+ */
+int snd_use_case_get_verb_playback_pcm(snd_use_case_mgr_t *uc_mgr);
+
+/**
+ * \brief Get the current use case verb capture PCM source ID
+ * \param uc_mgr Use case manager
+ * \return PCM number if success, otherwise negative
+ */
+int snd_use_case_get_verb_capture_pcm(snd_use_case_mgr_t *uc_mgr);
+
+/**
+ * \brief Get use case modifier playback PCM sink ID
+ * \param uc_mgr Use case manager
+ * \param modifier Modifier
+ * \return PCM number if success, otherwise negative
+ */
+int snd_use_case_get_mod_playback_pcm(snd_use_case_mgr_t *uc_mgr,
+	const char *modifier);
+
+/**
+ * \brief Get use case modifier capture PCM source ID
+ * \param uc_mgr Use case manager
+ * \param modifier Modifier
+ * \return PCM number if success, otherwise negative
+ */
+int snd_use_case_get_mod_capture_pcm(snd_use_case_mgr_t *uc_mgr,
+	const char *modifier);
+
+/**
+ * \brief Get ALSA volume/mute control names depending on use case device.
+ * \param uc_mgr Use case manager
+ * \param type The control type we are looking for
+ * \param device The device we are interested in.
+ * \return name if success, otherwise NULL
+ *
+ * Get the control name for common volume and mute controls that are aliased
+ * in the current use case verb.
+ */
+const char *snd_use_case_get_device_ctl_elem_id(snd_use_case_mgr_t *uc_mgr,
+		enum snd_use_case_control_alias type, const char *device);
+
+/**
+ * \brief Get ALSA volume/mute control names depending on use case modifier.
+ * \param uc_mgr Use case manager
+ * \param type The control type we are looking for
+ * \param modifier The modifier we are interested in.
+ * \return name if success, otherwise NULL
+ *
+ * Get the control name for common volume and mute controls that are aliased
+ * in the current use case modifier.
+ */
+const char *snd_use_case_get_modifier_ctl_elem_id(snd_use_case_mgr_t *uc_mgr,
+		enum snd_use_case_control_alias type, const char *modifier);
+
+/**
+ * \brief Open and initialise use case core for sound card
+ * \param card_name Sound card name.
+ * \return Use case handle if success, otherwise NULL
+ */
+snd_use_case_mgr_t *snd_use_case_mgr_open(const char *card_name);
+
+
+/**
+ * \brief Reload and re-parse use case configuration files for sound card.
+ * \param uc_mgr Use case manager
+ * \return zero if success, otherwise a negative error code
+ */
+int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
+
+/**
+ * \brief Close use case manager
+ * \param uc_mgr Use case manager
+ * \return zero if success, otherwise a negative error code
+ */
+int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
+
+/**
+ * \brief Reset use case manager verb, device, modifier to deafult settings.
+ * \param uc_mgr Use case manager
+ * \return zero if success, otherwise a negative error code
+ */
+int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
+
+/**
+ * \brief Dump current sound card use case control settings
+ * \param card_name Sound card name
+ * \return zero if success, otherwise a negative error code
+ */
+int snd_use_case_dump(const char *card_name);
+
+/**
+ *  \}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __ALSA_USE_CASE_H */
-- 
1.7.0.4

[PATCH 3/3] ucm: build - add build support for Use Case Manager

[Liam Girdwood]

Add doxygen and make support for UCM.

CC: Mark Brown <broonie@opensource.wolfsonmicro.com>
Signed-off-by: Justin Xu <justinx@slimlogic.co.uk>
Signed-off-by: Stefan Schmidt <stefan@slimlogic.co.uk>
Signed-off-by: Liam Girdwood <lrg@slimlogic.co.uk>
---
 doc/doxygen.cfg.in  |    1 +
 include/Makefile.am |    2 +-
 src/Makefile.am     |    2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/doxygen.cfg.in b/doc/doxygen.cfg.in
index 8606c48..3929772 100644
--- a/doc/doxygen.cfg.in
+++ b/doc/doxygen.cfg.in
@@ -28,6 +28,7 @@ INPUT            = @top_srcdir@/doc/index.doxygen \
 		   @top_srcdir@/include/pcm_ioplug.h \
 		   @top_srcdir@/include/control_external.h \
 		   @top_srcdir@/include/mixer.h \
+		   @top_srcdir@/include/use-case.h \
 		   @top_srcdir@/src/error.c \
 		   @top_srcdir@/src/dlmisc.c \
 		   @top_srcdir@/src/async.c \
diff --git a/include/Makefile.am b/include/Makefile.am
index a291503..de37f2c 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -5,7 +5,7 @@ alsaincludedir = ${includedir}/alsa
 
 alsainclude_HEADERS = asoundlib.h asoundef.h \
 		      version.h global.h input.h output.h error.h \
-		      conf.h control.h iatomic.h
+		      conf.h control.h iatomic.h use-case.h
 
 if BUILD_CTL_PLUGIN_EXT
 alsainclude_HEADERS += control_external.h
diff --git a/src/Makefile.am b/src/Makefile.am
index 3204fe4..7206dbd 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -14,7 +14,7 @@ SYMFUNCS =
 endif
 
 lib_LTLIBRARIES = libasound.la
-libasound_la_SOURCES = conf.c confmisc.c input.c output.c async.c error.c dlmisc.c socket.c shmarea.c userfile.c names.c
+libasound_la_SOURCES = conf.c confmisc.c input.c output.c async.c error.c dlmisc.c socket.c shmarea.c userfile.c names.c use-case.c
 
 SUBDIRS=control
 libasound_la_LIBADD = control/libcontrol.la
-- 
1.7.0.4

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Mon, 23 Aug 2010, Liam Girdwood wrote:

> This patch series follows on from the RFC and adds sound card hardware Use Case
> Management support to alsa-lib.

Liam, can you give a URL for anonymous GIT repository with these patches?

Unfortunately, I have many ideas to improve the API before I can approve 
or recommend the inclusion to the alsa-lib's tree.

 					Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Mon, Aug 23, 2010 at 07:47:37PM +0200, Jaroslav Kysela wrote:

> Liam, can you give a URL for anonymous GIT repository with these patches?

git://git.slimlogic.co.uk/alsa-ucm-conf.git

is in the root of the cgit repo (this is standard for both cgit and gitweb).

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Mon, Aug 23, 2010 at 06:50:07PM +0100, Mark Brown wrote:
> On Mon, Aug 23, 2010 at 07:47:37PM +0200, Jaroslav Kysela wrote:

> > Liam, can you give a URL for anonymous GIT repository with these patches?

> git://git.slimlogic.co.uk/alsa-ucm-conf.git

> is in the root of the cgit repo (this is standard for both cgit and gitweb).

Sorry, wrong repo.  You want git://git.slimlogic.co.uk/alsa-lib.git
instead.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Raymond Yau]

2010/8/24 Liam Girdwood <lrg@slimlogic.co.uk>

> This patch series follows on from the RFC and adds sound card hardware Use
> Case
> Management support to alsa-lib.
>
> The main features of UCM are :-
>
>  o Abstraction of sound card hardware routing and controls into high level
>   use case verbs, devices and modifiers.
>  o Discovery of source/sink PCMs for each use case.
>  o Discovery of hardware master volume controls for each use case.
>
> It's intended UCM will provide clients (like pulseaudio) complete control
> over
> hardware signal routing within a sound card without any knowledge of the
> sound card hardware.
>
> Use case definintions are stored in text files (per sound card) and are now
> divided into three components as descibed in the RFC.
>
> A working use case definition file can be found here :-
>
>
> http://git.slimlogic.co.uk/cgi-bin/cgit.cgi/alsa-ucm-conf.git/tree/cards/SDP4430/hifi
>
> The three components of a use case are now :-
>
> 1) Verb (or action). This is mandatory and describes (in terms of ALSA
> control settings) the system use case action. e.g "Phone Call", "Music
> Playback".
>
> 2) Device. This is also mandatory and describes the audio playback or
> capture device. e.g. "Handset", "Bluetooth", "Headset".
>
> 3) Modifier. This is optional and is used to modify the current use case
> verb. i.e. The user could be listening to music when an incoming phone
> call requires that a ring tone is played. In this case the use case verb
> would be set to "Music Playback" when the music playback started and
> then the "Tone Playback" modifier could be enabled to play the ring
> tone. The use case verb would then be changed to "Voice Call" if the
> call was accepted.
>
> Patch 2/3 is a little on the large side so, I've included a link if it gets
> bounced by the list.
>
>
> http://git.slimlogic.co.uk/cgi-bin/cgit.cgi/alsa-lib.git/commit/?h=ucm-upstream&id=15d5f619deba20f87075e7c711e6331115fd836d
>
> Liam Girdwood (3):
>  ucm: header - ALSA Use Case Manager
>  ucm: core - Add initial Use Case Manager support.
>  ucm: build - add build support for Use Case Manager
>
>  doc/doxygen.cfg.in  |    1 +
>  include/Makefile.am |    2 +-
>  include/use-case.h  |  427 +++++++
>  src/Makefile.am     |    2 +-
>  src/use-case.c      | 3515
> +++++++++++++++++++++++++++++++++++++++++++++++++++
>  5 files changed, 3945 insertions(+), 2 deletions(-)
>  create mode 100644 include/use-case.h
>  create mode 100644 src/use-case.c
>

Can the use case manager discover whether the green/pink jack in front panel
can be used independent of  those audio jacks in rear panel for HDA-Intel in
desktop pc ?

How about those hardware mixing sound card ?
e.g. emu10k1 allow the user to output stereo to the selected  jacks (front ,
rear, .... )

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Liam Girdwood]

On Mon, 2010-08-23 at 19:47 +0200, Jaroslav Kysela wrote:
> On Mon, 23 Aug 2010, Liam Girdwood wrote:
> 
> > This patch series follows on from the RFC and adds sound card hardware Use Case
> > Management support to alsa-lib.
> 
> Liam, can you give a URL for anonymous GIT repository with these patches?
> 

There is also a testing tool called alsaucm in the ucm-upstream branch
of the alsa-utils git repo here :-

git://git.slimlogic.co.uk/alsa-utils.git

This will probably be useful if you are testing your ideas.

There are also some initial configuration files here :-

git://git.slimlogic.co.uk/alsa-ucm-conf.git

> Unfortunately, I have many ideas to improve the API before I can approve 
> or recommend the inclusion to the alsa-lib's tree.
> 

I wish you had shared your API ideas with us at the time of the RFC. A
lot of time and effort has since went into UCM development :-/

Can you share your ideas atm, or do you have some patches planned ?

Thanks

Liam
-- 
Freelance Developer, SlimLogic Ltd
ASoC and Voltage Regulator Maintainer.
http://www.slimlogic.co.uk

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Tue, Aug 24, 2010 at 09:23:14AM +0800, Raymond Yau wrote:

> Can the use case manager discover whether the green/pink jack in front panel
> can be used independent of  those audio jacks in rear panel for HDA-Intel in
> desktop pc ?

> How about those hardware mixing sound card ?
> e.g. emu10k1 allow the user to output stereo to the selected  jacks (front ,
> rear, .... )

These are all orthogonal problems.  UCM just provides a way of managing
configurations exposed by the drivers, it doesn't add any new features
for the drivers.

Re: [PATCH 1/3] ucm: header - ALSA Use Case Manager

[Chris Winter]

Hi Liam,

On Mon, Aug 23, 2010 at 11:17 AM, Liam Girdwood <lrg@slimlogic.co.uk> wrote:
> This patch adds the API header for alsa-lib Use Case Management support.
>
> This file defines the public interface exported by UCM to client
> applications.
>
> UCM development has been kindly sponsored by Texas Instruments Inc,
> Wolfson Microelectronics PLC and Slimlogic Ltd.
>
> CC: Mark Brown <broonie@opensource.wolfsonmicro.com>
> Signed-off-by: Stefan Schmidt <stefan@slimlogic.co.uk>
> Signed-off-by: Jaroslav Kysela <perex@perex.cz>
> Signed-off-by: Justin Xu <justinx@slimlogic.co.uk>
> Signed-off-by: Liam Girdwood <lrg@slimlogic.co.uk>
> ---
>  include/use-case.h |  427 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 427 insertions(+), 0 deletions(-)
>  create mode 100644 include/use-case.h

[...]

> +/**
> + * \brief Get ALSA volume/mute control names depending on use case device.
> + * \param uc_mgr Use case manager
> + * \param type The control type we are looking for
> + * \param device The device we are interested in.
> + * \return name if success, otherwise NULL
> + *
> + * Get the control name for common volume and mute controls that are aliased
> + * in the current use case verb.
> + */
> +const char *snd_use_case_get_device_ctl_elem_id(snd_use_case_mgr_t *uc_mgr,
> +               enum snd_use_case_control_alias type, const char *device);
> +
> +/**
> + * \brief Get ALSA volume/mute control names depending on use case modifier.
> + * \param uc_mgr Use case manager
> + * \param type The control type we are looking for
> + * \param modifier The modifier we are interested in.
> + * \return name if success, otherwise NULL
> + *
> + * Get the control name for common volume and mute controls that are aliased
> + * in the current use case modifier.
> + */
> +const char *snd_use_case_get_modifier_ctl_elem_id(snd_use_case_mgr_t *uc_mgr,
> +               enum snd_use_case_control_alias type, const char *modifier);


It would appear that the implementations of the above two functions
are named differently in src/use-case.c:

const char *snd_use_case_get_device_ctl_elem_name(...)
const char *snd_use_case_get_modifier_ctl_elem_name(...)

Regards,

Chris

Re: [PATCH 1/3] ucm: header - ALSA Use Case Manager

[Liam Girdwood]

On Tue, 2010-08-24 at 14:09 -0500, Chris Winter wrote:
> Hi Liam,
> 
> On Mon, Aug 23, 2010 at 11:17 AM, Liam Girdwood <lrg@slimlogic.co.uk> wrote:
> > This patch adds the API header for alsa-lib Use Case Management support.
> >
> > This file defines the public interface exported by UCM to client
> > applications.
> >
> > UCM development has been kindly sponsored by Texas Instruments Inc,
> > Wolfson Microelectronics PLC and Slimlogic Ltd.
> >
> > CC: Mark Brown <broonie@opensource.wolfsonmicro.com>
> > Signed-off-by: Stefan Schmidt <stefan@slimlogic.co.uk>
> > Signed-off-by: Jaroslav Kysela <perex@perex.cz>
> > Signed-off-by: Justin Xu <justinx@slimlogic.co.uk>
> > Signed-off-by: Liam Girdwood <lrg@slimlogic.co.uk>
> > ---
> >  include/use-case.h |  427 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 files changed, 427 insertions(+), 0 deletions(-)
> >  create mode 100644 include/use-case.h
> 
> [...]
> 
> > +/**
> > + * \brief Get ALSA volume/mute control names depending on use case device.
> > + * \param uc_mgr Use case manager
> > + * \param type The control type we are looking for
> > + * \param device The device we are interested in.
> > + * \return name if success, otherwise NULL
> > + *
> > + * Get the control name for common volume and mute controls that are aliased
> > + * in the current use case verb.
> > + */
> > +const char *snd_use_case_get_device_ctl_elem_id(snd_use_case_mgr_t *uc_mgr,
> > +               enum snd_use_case_control_alias type, const char *device);
> > +
> > +/**
> > + * \brief Get ALSA volume/mute control names depending on use case modifier.
> > + * \param uc_mgr Use case manager
> > + * \param type The control type we are looking for
> > + * \param modifier The modifier we are interested in.
> > + * \return name if success, otherwise NULL
> > + *
> > + * Get the control name for common volume and mute controls that are aliased
> > + * in the current use case modifier.
> > + */
> > +const char *snd_use_case_get_modifier_ctl_elem_id(snd_use_case_mgr_t *uc_mgr,
> > +               enum snd_use_case_control_alias type, const char *modifier);
> 
> 
> It would appear that the implementations of the above two functions
> are named differently in src/use-case.c:
> 
> const char *snd_use_case_get_device_ctl_elem_name(...)
> const char *snd_use_case_get_modifier_ctl_elem_name(...)
> 

Ah, they are indeed. I'll fix up. 

Thanks !

Liam
-- 
Freelance Developer, SlimLogic Ltd
ASoC and Voltage Regulator Maintainer.
http://www.slimlogic.co.uk

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Tue, 24 Aug 2010, Liam Girdwood wrote:

> On Mon, 2010-08-23 at 19:47 +0200, Jaroslav Kysela wrote:
>
>> Unfortunately, I have many ideas to improve the API before I can approve
>> or recommend the inclusion to the alsa-lib's tree.
>>
>
> I wish you had shared your API ideas with us at the time of the RFC. A
> lot of time and effort has since went into UCM development :-/

I too. My big problem is the lack of time.

I tried to rethink the API to be more universal for future extensions (but 
the implementation will not dramatically change and the mechanisms you 
want to expose are not touched at all). I just wanted to add the 
possibility to create the virtual cards combining resources from any 
PCM/control/mixer device available in system. The proper device evaluation 
and mixer control assignments is something which is wanted by PulseAudio 
developers.

My proposed header file with reduced function set but not reduced 
functionality is available at:

http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=include/use-case.h;h=33d480f66d000fa7c86367c68b98bdaad9217a74;hb=fcc9adb26058667656277ba92032ba7e0b00261c

The syntax of your proposed files is very close to the other alsa-lib's 
syntax. For example:

SectionModifier
 	Name "Capture Voice"
 	EnableSequence
 		seq1 1
 	EndSequence
 	QoS Voice
EndSection

Can be written in alsa-lib's syntax:

SectionModifier."Capture Voice" [
 	EnableSequence [
 		seq1 1
 	]
 	QoS Voice
]

So I'm thinking to recode all parsers to use the alsa-lib configuration 
parsers. As bonus, the alsa-lib configuration routines give us some 
runtime evaluation and possibility to reference (include) other files.

Next step may be to support the 'amixer' like syntax for the control and 
mixer element handling.

 						Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Liam Girdwood]

On Wed, 2010-08-25 at 10:28 +0200, Jaroslav Kysela wrote:
> On Tue, 24 Aug 2010, Liam Girdwood wrote:
> 
> > On Mon, 2010-08-23 at 19:47 +0200, Jaroslav Kysela wrote:
> >
> >> Unfortunately, I have many ideas to improve the API before I can approve
> >> or recommend the inclusion to the alsa-lib's tree.
> >>
> >
> > I wish you had shared your API ideas with us at the time of the RFC. A
> > lot of time and effort has since went into UCM development :-/
> 
> I too. My big problem is the lack of time.

Same here, not enough hours in the day.

> 
> I tried to rethink the API to be more universal for future extensions (but 
> the implementation will not dramatically change and the mechanisms you 
> want to expose are not touched at all). I just wanted to add the 
> possibility to create the virtual cards combining resources from any 
> PCM/control/mixer device available in system. The proper device evaluation 
> and mixer control assignments is something which is wanted by PulseAudio 
> developers.
> 
> My proposed header file with reduced function set but not reduced 
> functionality is available at:
> 
> http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=include/use-case.h;h=33d480f66d000fa7c86367c68b98bdaad9217a74;hb=fcc9adb26058667656277ba92032ba7e0b00261c
> 

ok, that looks good.

> The syntax of your proposed files is very close to the other alsa-lib's 
> syntax. For example:
> 
> SectionModifier
>  	Name "Capture Voice"
>  	EnableSequence
>  		seq1 1
>  	EndSequence
>  	QoS Voice
> EndSection
> 
> Can be written in alsa-lib's syntax:
> 
> SectionModifier."Capture Voice" [
>  	EnableSequence [
>  		seq1 1
>  	]
>  	QoS Voice
> ]
> 
> So I'm thinking to recode all parsers to use the alsa-lib configuration 
> parsers. As bonus, the alsa-lib configuration routines give us some 
> runtime evaluation and possibility to reference (include) other files.
> 

ok, I agree here too.

> Next step may be to support the 'amixer' like syntax for the control and 
> mixer element handling.

Btw, we need to try and avoid using the control ID in any mixer syntax.
I found that minor driver changes could change ID numbering meaning
major updates to config files. The mixer names are pretty constant and
using them has been quite painless.

Thanks

Liam


-- 
Freelance Developer, SlimLogic Ltd
ASoC and Voltage Regulator Maintainer.
http://www.slimlogic.co.uk

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Wed, 25 Aug 2010, Liam Girdwood wrote:

>> Next step may be to support the 'amixer' like syntax for the control and
>> mixer element handling.
>
> Btw, we need to try and avoid using the control ID in any mixer syntax.
> I found that minor driver changes could change ID numbering meaning
> major updates to config files. The mixer names are pretty constant and
> using them has been quite painless.

Definitely. I meant the full control identifier (not just numid).

 					Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Liam Girdwood]

On Wed, 2010-08-25 at 11:35 +0200, Jaroslav Kysela wrote:
> On Wed, 25 Aug 2010, Liam Girdwood wrote:
> 
> >> Next step may be to support the 'amixer' like syntax for the control and
> >> mixer element handling.
> >
> > Btw, we need to try and avoid using the control ID in any mixer syntax.
> > I found that minor driver changes could change ID numbering meaning
> > major updates to config files. The mixer names are pretty constant and
> > using them has been quite painless.
> 
> Definitely. I meant the full control identifier (not just numid).
> 

btw, have started any of the other API changes in use-case.c yet ?

I could make changes to the parser .....

Thanks

Liam
-- 
Freelance Developer, SlimLogic Ltd
ASoC and Voltage Regulator Maintainer.
http://www.slimlogic.co.uk

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Wed, 25 Aug 2010, Liam Girdwood wrote:

> On Wed, 2010-08-25 at 11:35 +0200, Jaroslav Kysela wrote:
>> On Wed, 25 Aug 2010, Liam Girdwood wrote:
>>
>>>> Next step may be to support the 'amixer' like syntax for the control and
>>>> mixer element handling.
>>>
>>> Btw, we need to try and avoid using the control ID in any mixer syntax.
>>> I found that minor driver changes could change ID numbering meaning
>>> major updates to config files. The mixer names are pretty constant and
>>> using them has been quite painless.
>>
>> Definitely. I meant the full control identifier (not just numid).
>>
>
> btw, have started any of the other API changes in use-case.c yet ?
>
> I could make changes to the parser .....

I am working on it slowly. I think that it would be fair to come with
a functional code from my side. I will appreciate review and testing, of 
course. Please, give me few days.

 					Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Tue, 7 Sep 2010, Liam Girdwood wrote:

> Hi Jaroslav,
>
> Any update on this ? I have someone scheduled to write new use case
> files and someone else ready to add PA support.

Hi,

I'm working on this. Unfortunately, I have other things which interrupts 
this work. The actual code is at:

http://git.alsa-project.org/?p=alsa-lib.git;a=shortlog;h=ucm

During coding, it appears that even the handling of controls might be 
changed. Your code has everything build-in. I'm not sure why to restrict 
the card/verb/modifier/transition definitions only for the universal 
control API. I think that it might be more "easy to understand" and 
universal to define just sequence of commands like:

SectionDefaults [
         exec "amixer cset name='Master Playback Switch',index=2 1,1"
         exec "amixer cset name='Master Playback Volume',index=2 25,25"
         exec "amixer cset name='Master Mono Playback',index=1 0"
         exec "amixer cset name='Master Mono Playback Volume',index=1 0"
         msleep 50 # or: exec "usleep 50000"
         exec "amixer cset name='PCM Switch',index=2 1,1"
         ........
]

Because "amixer cset" command will be probably most used command, we can 
eventually move the amixer code to alsa-lib to not create so much 
processes and speed-up things.

It means that the ucm should not track card controls, but commands for 
transitions.

The only thing which might "broke" things is calling fork from a pthread:

http://unix.derkeiler.com/Newsgroups/comp.unix.programmer/2003-09/0672.html

But it seems that fork/immediate-exec is an acceptable way.

Comments?

 						Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Tue, Sep 07, 2010 at 04:42:57PM +0200, Jaroslav Kysela wrote:

> control API. I think that it might be more "easy to understand" and 
> universal to define just sequence of commands like:

> SectionDefaults [
>          exec "amixer cset name='Master Playback Switch',index=2 1,1"

...

> Because "amixer cset" command will be probably most used command, we can 
> eventually move the amixer code to alsa-lib to not create so much 
> processes and speed-up things.

> It means that the ucm should not track card controls, but commands for 
> transitions.

I don't understand the motivation here - what does this buy us?

Looking at this from the embedded perspective I really would much rather
see a use case manager that understands what it's doing (rather than
essentially just running shell script).  This allows us to do things
like specify target states (rather than having to have full sequences
for all transitions, which is one of the things it'd be good to avoid)
and will allow us to take advantage of any additions to the ALSA APIs
for things like batching operations without changes to the per machine
configurations.

Having the facility to shell out in case some non-ALSA stuff needs to be
done might be handy but I'd expect that for things within ALSA a tool
like the use case manager would understand ALSA natively.

For embedded systems, especially those like mobile phones with extensive
use case requirements, the usability issues mostly come from the very
large numbers of controls which is at best orthogonal to shelling out to
amixer (or whatever) commands.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Tue, 7 Sep 2010, Mark Brown wrote:

> On Tue, Sep 07, 2010 at 04:42:57PM +0200, Jaroslav Kysela wrote:
>
>> control API. I think that it might be more "easy to understand" and
>> universal to define just sequence of commands like:
>
>> SectionDefaults [
>>          exec "amixer cset name='Master Playback Switch',index=2 1,1"
>
> ...
>
>> Because "amixer cset" command will be probably most used command, we can
>> eventually move the amixer code to alsa-lib to not create so much
>> processes and speed-up things.
>
>> It means that the ucm should not track card controls, but commands for
>> transitions.
>
> I don't understand the motivation here - what does this buy us?
>
> Looking at this from the embedded perspective I really would much rather
> see a use case manager that understands what it's doing (rather than
> essentially just running shell script).  This allows us to do things
> like specify target states (rather than having to have full sequences
> for all transitions, which is one of the things it'd be good to avoid)
> and will allow us to take advantage of any additions to the ALSA APIs
> for things like batching operations without changes to the per machine
> configurations.
>
> Having the facility to shell out in case some non-ALSA stuff needs to be
> done might be handy but I'd expect that for things within ALSA a tool
> like the use case manager would understand ALSA natively.
>
> For embedded systems, especially those like mobile phones with extensive
> use case requirements, the usability issues mostly come from the very
> large numbers of controls which is at best orthogonal to shelling out to
> amixer (or whatever) commands.

My idea is to have the most used commands working with the ALSA API 
built directly into the ucm code to not use fork/exec so much in embedded 
environments. But I can imagine that some system configurations can use 
this API to send events to another manager which can control another 
parts of the system like video, input devices, network devices and so on 
according the sound setup.

Also, the possibility to generate the alsa-lib's configuration files at 
run-time might be a nice feature for future. I take UCM like a way to 
integrate all things regarding PCM streams and mixer controls together and 
let users / system administrators / distribution makers create the 
abstract layers depending their requirements.

It's about flexibility.

 					Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Tue, Sep 07, 2010 at 08:17:19PM +0200, Jaroslav Kysela wrote:
> On Tue, 7 Sep 2010, Mark Brown wrote:

> >>SectionDefaults [
> >>         exec "amixer cset name='Master Playback Switch',index=2 1,1"
> >

> My idea is to have the most used commands working with the ALSA API
> built directly into the ucm code to not use fork/exec so much in
> embedded environments. But I can imagine that some system

I'm not sure how this follows on from what you're proposing above?  You
appear to be proposing the replacement of the lists of control settings
with shell commands, then later on optimising those forks busybox style
by building the relevant binaries into the library.

Currently outside of the explict sequences provided to override the
default transitions the use case manager configurations are declarative
rather than ordering based.  This lets the user specify end states and
lets the use case manager code work out the best way to accomplish those
configurations which seems like a valuable property.

> configurations can use this API to send events to another manager
> which can control another parts of the system like video, input
> devices, network devices and so on according the sound setup.

I do agree that this may be useful but I don't see that we need to
rewrite the ALSA control management bit of things for that, the
declarative style seems like a win there.  I also feel that it may make
more sense to do this externally to this library in a higher level tool
which controls both this and other things.

> Also, the possibility to generate the alsa-lib's configuration files
> at run-time might be a nice feature for future. I take UCM like a

This might be useful, though I'd expect that Pulse might be more useful
for a lot of systems.

> way to integrate all things regarding PCM streams and mixer controls
> together and let users / system administrators / distribution makers
> create the abstract layers depending their requirements.

That's my understanding of what the idea is.

> It's about flexibility.

As I said above I'm concerned that you're trying to move this into
something which is much more of a system level use case manager than an
audio specific one, and limiting the audio domain as part of that.  If
we're doing too much of that then we're into the domain of the system
level software that would be driving the UCM.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Liam Girdwood]

On Tue, 2010-09-07 at 20:17 +0200, Jaroslav Kysela wrote:
> On Tue, 7 Sep 2010, Mark Brown wrote:
> 
> > On Tue, Sep 07, 2010 at 04:42:57PM +0200, Jaroslav Kysela wrote:
> >
> >> control API. I think that it might be more "easy to understand" and
> >> universal to define just sequence of commands like:
> >
> >> SectionDefaults [
> >>          exec "amixer cset name='Master Playback Switch',index=2 1,1"
> >
> > ...
> >
> >> Because "amixer cset" command will be probably most used command, we can
> >> eventually move the amixer code to alsa-lib to not create so much
> >> processes and speed-up things.
> >
> >> It means that the ucm should not track card controls, but commands for
> >> transitions.
> >
> > I don't understand the motivation here - what does this buy us?
> >
> > Looking at this from the embedded perspective I really would much rather
> > see a use case manager that understands what it's doing (rather than
> > essentially just running shell script).  This allows us to do things
> > like specify target states (rather than having to have full sequences
> > for all transitions, which is one of the things it'd be good to avoid)
> > and will allow us to take advantage of any additions to the ALSA APIs
> > for things like batching operations without changes to the per machine
> > configurations.
> >
> > Having the facility to shell out in case some non-ALSA stuff needs to be
> > done might be handy but I'd expect that for things within ALSA a tool
> > like the use case manager would understand ALSA natively.
> >
> > For embedded systems, especially those like mobile phones with extensive
> > use case requirements, the usability issues mostly come from the very
> > large numbers of controls which is at best orthogonal to shelling out to
> > amixer (or whatever) commands.
> 
> My idea is to have the most used commands working with the ALSA API 
> built directly into the ucm code to not use fork/exec so much in embedded 
> environments. 

What does this really buy us over the current (direct alsa-lib API)
code ? 

Fwiw, UCM was never intended to replace any of the alsa-utils, but to
complement them in complex audio systems (like phones).

> But I can imagine that some system configurations can use 
> this API to send events to another manager which can control another 
> parts of the system like video, input devices, network devices and so on 
> according the sound setup.

UCM is purely to abstract the audio hardware for higher level
middle-ware and applications. It's really up to the system middle-ware
and daemons here to configure/control the other subsystems in line with
the system use case.

> 
> Also, the possibility to generate the alsa-lib's configuration files at 
> run-time might be a nice feature for future. 

Fwiw, UCM is _needed_ now and I really can't emphasise this strongly
enough atm. Some embedded ODMs are even now using and shipping closed
source proprietary software for audio hardware UCM.

The UCM configuration files for embedded system will likely be very
specific to the hardware and not really suited to run time generation.
However, there is nothing stopping runtime generation with the original
file format.   

> I take UCM like a way to 
> integrate all things regarding PCM streams and mixer controls together and 
> let users / system administrators / distribution makers create the 
> abstract layers depending their requirements.
> 
> It's about flexibility.

Exactly, but there is nothing stopping flexibility with the current code
base.

Liam 
-- 
Freelance Developer, SlimLogic Ltd
ASoC and Voltage Regulator Maintainer.
http://www.slimlogic.co.uk

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Tue, Sep 07, 2010 at 09:02:35PM +0100, Liam Girdwood wrote:
> On Tue, 2010-09-07 at 20:17 +0200, Jaroslav Kysela wrote:

> > Also, the possibility to generate the alsa-lib's configuration files at 
> > run-time might be a nice feature for future. 

> Fwiw, UCM is _needed_ now and I really can't emphasise this strongly
> enough atm. Some embedded ODMs are even now using and shipping closed
> source proprietary software for audio hardware UCM.

Now you mention this I feel remiss for not pointing it out before.  I'm
also working with many system manufacturers including smartphone vendors
(they're the people who are *really* suffering here) and a lot of them
have a use case problem to some degree.  There's two key issues I see
people having problems with:

 - Coming up with an abstraction for an audio use case which can be used
   to think about the possbilities for configuring ALSA and implementing
   the mechanics of it.  UCM pretty much deals with this.

 - Generating and maintaining use cases.  UCM provides a good start on
   this in itself - simply having the suggested way of thinking about
   things is a win, never mind the tools - and having the standard
   format is pretty much a requirement for doing any more tools work.

A procedural approach is a common solution but it makes both problems
harder, especially the second one since it means that every time you
think about a use case you must think about the mechanics of moving into
and out of it rather than just thinking about the configuration you want
to achieve.

> The UCM configuration files for embedded system will likely be very
> specific to the hardware and not really suited to run time generation.
> However, there is nothing stopping runtime generation with the original
> file format.   

For an example of the sort of system complexity one is dealing with in
the smartphone use case the WM8994 is an example of the sort of feature
set you can see in the audio CODEC alone:

   http://www.wolfsonmicro.com/products/WM8994

Trying to autogenerate the configuration for a system like this is
likely at best give a first pass result since the actual configurations
end up depending on not only your current use case but also the other
use cases you might want to use in the future.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Tue, 7 Sep 2010, Mark Brown wrote:

> Currently outside of the explict sequences provided to override the
> default transitions the use case manager configurations are declarative
> rather than ordering based.  This lets the user specify end states and
> lets the use case manager code work out the best way to accomplish those
> configurations which seems like a valuable property.

I don't see any difference here. I checked the Liam's code and there is 
no intelligence regarding the ALSA controls API. The sequences are just 
processed in the serialized way and they must be (for example to satisfy 
the time delay requirements between control writes).

>> configurations can use this API to send events to another manager
>> which can control another parts of the system like video, input
>> devices, network devices and so on according the sound setup.
>
> I do agree that this may be useful but I don't see that we need to
> rewrite the ALSA control management bit of things for that, the
> declarative style seems like a win there.  I also feel that it may make
> more sense to do this externally to this library in a higher level tool
> which controls both this and other things.

Note that my proposal is just extension. It's like difference between full 
desktop system and a small optimized system (for example for small 
wireless hardware platforms). There are many differences in the boot 
style and root system trees, because not all things are required for 
small systems. Nobody forces the user to use the exec command.

>> Also, the possibility to generate the alsa-lib's configuration files
>> at run-time might be a nice feature for future. I take UCM like a
>
> This might be useful, though I'd expect that Pulse might be more useful
> for a lot of systems.
>
>> way to integrate all things regarding PCM streams and mixer controls
>> together and let users / system administrators / distribution makers
>> create the abstract layers depending their requirements.
>
> That's my understanding of what the idea is.
>
>> It's about flexibility.
>
> As I said above I'm concerned that you're trying to move this into
> something which is much more of a system level use case manager than an
> audio specific one, and limiting the audio domain as part of that.  If
> we're doing too much of that then we're into the domain of the system
> level software that would be driving the UCM.

My motivation is to make UCM useable also for the desktop systems. In this 
environment might be useful to send external events to another layers when 
an app requests specific audio device. For example, HDMI is connected with 
the video link so the X11 server might be notified about this request.

 					Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

Creating another thread .... state locking ...

I understand the motivation to create a layer for phone or similar 
embedded devices which uses usually all streams from the one process.

But what about more concurrent processes? The state handling in the 
current implementation is per process, so another process just 
overwrite blindly the control values set by the first process.

I think that the layer should have some locking mechanism and state 
persistency (IPC semaphores / IPC shared memory) or a file and inotify?

Another question is how to handle collisions.

 						Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Wed, Sep 08, 2010 at 09:54:50AM +0200, Jaroslav Kysela wrote:
> On Tue, 7 Sep 2010, Mark Brown wrote:

> >Currently outside of the explict sequences provided to override the
> >default transitions the use case manager configurations are declarative
> >rather than ordering based.  This lets the user specify end states and
> >lets the use case manager code work out the best way to accomplish those
> >configurations which seems like a valuable property.

> I don't see any difference here. I checked the Liam's code and there
> is no intelligence regarding the ALSA controls API. The sequences

Right, just now it's not doing anything because at the minute we don't
have much option but it does mean that the control format doesn't lock
us into this and allows room for expansion.

> are just processed in the serialized way and they must be (for
> example to satisfy the time delay requirements between control
> writes).

I'd really expect the driver to be finiessing stuff.

> Note that my proposal is just extension. It's like difference
> between full desktop system and a small optimized system (for
> example for small wireless hardware platforms). There are many

See below.

> My motivation is to make UCM useable also for the desktop systems.
> In this environment might be useful to send external events to
> another layers when an app requests specific audio device. For
> example, HDMI is connected with the video link so the X11 server
> might be notified about this request.

Right, but the expectation is that the system management service which
is driving UCM will able to also drive other subsysems, and it's not
entirely obvious that the audio use case selection should drive too
much non-audio stuff directly.

This and some of your other comments make me concerned that you aren't
aware of the complexity of the audio subsystems on high end embedded
devices like smartphones.  Things like the video use case you describe
above are not at all unusual for smartphones - I actually currently have
a smartphone sitting plugged into my AV system at home and able to
deliver audio and video to it (though only with composite).

A modern smartphone can have multiple independant independantly
routeable audio streams between the CPU and primary audio CODEC, plus
separate digital audio streams between the CODEC and the cellular modem
and bluetooth.  There will be headphones, an earpiece speaker, possibly
one or more separate music/speakerphone speakers, at least one on-board
microphone and a headset microphone.  Add on to this a separate audio
CODEC for HDMI, A2DP, and accessory handling (including stuff like
muxing composite video out onto the same jack pins used for headset
microphone) and you've got a very flexible system.

When thinking about these issues it is generally safe to assume that
embedded systems can have software that's at least as complex as that on
PC class hardware.  I would be very surprised if a software model which
meets the needs of complex embedded systems is not also capable of doing
everything a desktop needs.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Wed, Sep 08, 2010 at 10:19:45AM +0200, Jaroslav Kysela wrote:

> I understand the motivation to create a layer for phone or similar
> embedded devices which uses usually all streams from the one
> process.

> But what about more concurrent processes? The state handling in the
> current implementation is per process, so another process just
> overwrite blindly the control values set by the first process.

You really need one single thing to own the physical audio device
configuration, even on a desktop.  On a desktop system that'd be
PulseAudio normally since applications end up talking to PulseAudio
rather than the hardware directly so only PulseAudio is actually
directly concerned with the hardware setup.  On an embedded system it'd
quite frequently be PulseAudio as well but obviously it will differ on
some systems.

> Another question is how to handle collisions.

This is the core issue which forces some central thing owning the policy
decisions on a system wide basis - something needs to take policy
decisions about what's happening.

The focus for UCM is providing a model for thinking about configurations
and the mechanics of applying them, which are the areas of the problem
which are well understood and shared by all implementations.  Mechanisms
for actually deciding on what the policy is and dealing with contention
for the hardware are very much open questions at the minute even on
desktops so keeping the solutions in that area separate to the bits that
are well understood allows flexibility in these more contentious areas.

Again, assuming that there's a substantial difference between embedded
and desktop systems isn't really reflecting the reality of actual
systems these days - they're all on a continuum and in many cases the
standardisation of hardware in desktop systems means they will be more
simple rather than less simple than embedded systems.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Colin Guthrie]

Hi Jaroslav,

'Twas brillig, and Jaroslav Kysela at 07/09/10 15:42 did gyre and gimble:
> On Tue, 7 Sep 2010, Liam Girdwood wrote:
> 
>> Hi Jaroslav,
>>
>> Any update on this ? I have someone scheduled to write new use case
>> files and someone else ready to add PA support.
> 
> Hi,
> 
> I'm working on this. Unfortunately, I have other things which interrupts 
> this work. The actual code is at:
> 
> http://git.alsa-project.org/?p=alsa-lib.git;a=shortlog;h=ucm

Has there been any progress on the UCM stuff? I'm quite interested to
see how this will develop from a PA perspective. It does have some
impact on work that I've been wanting to do for a while in PA so the
sooner this is available in ALSA the sooner I can start thinking about
some of the knock on effects. I know Liam is intending to do some work
on PA too to integrate UCM once the API has stabilised, so I'm obviously
keen to encourage that too :D

Cheers

Col



-- 

Colin Guthrie
gmane(at)colin.guthr.ie
http://colin.guthr.ie/

Day Job:
  Tribalogic Limited [http://www.tribalogic.net/]
Open Source:
  Mageia Contributor [http://www.mageia.org/]
  PulseAudio Hacker [http://www.pulseaudio.org/]
  Trac Hacker [http://trac.edgewall.org/]

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Chris Winter]

On Mon, Sep 20, 2010 at 11:26 AM, Colin Guthrie <gmane@colin.guthr.ie> wrote:
> Hi Jaroslav,
>
> 'Twas brillig, and Jaroslav Kysela at 07/09/10 15:42 did gyre and gimble:
>> On Tue, 7 Sep 2010, Liam Girdwood wrote:
>>
>>> Hi Jaroslav,
>>>
>>> Any update on this ? I have someone scheduled to write new use case
>>> files and someone else ready to add PA support.
>>
>> Hi,
>>
>> I'm working on this. Unfortunately, I have other things which interrupts
>> this work. The actual code is at:
>>
>> http://git.alsa-project.org/?p=alsa-lib.git;a=shortlog;h=ucm
>
> Has there been any progress on the UCM stuff? I'm quite interested to
> see how this will develop from a PA perspective. It does have some
> impact on work that I've been wanting to do for a while in PA so the
> sooner this is available in ALSA the sooner I can start thinking about
> some of the knock on effects. I know Liam is intending to do some work
> on PA too to integrate UCM once the API has stabilised, so I'm obviously
> keen to encourage that too :D

Since progress on UCM seems to have stalled, I'd also like to chip in
and say that it would be great to see UCM pushed to mainline as soon
as possible. I'm a software engineer at Garmin, responsible for
system-level audio support on Linux-based personal navigation devices,
and UCM would *really* help to simplify the management of audio state
on those devices. In fact, I've been hurting for something like UCM
for so long that I'm already developing against the version that Liam
has posted to the list.

I not entirely convinced that Jaroslav's proposed changes to UCM will
add much value to overall functionality. The reworked API seems more
clumsy and confusing to me, and I think it's a bad idea to make UCM
responsible for coordinating audio state management throughout
userspace -- as Mark B. said, that responsibility would seem to be
better left to some other entity who would be the sole consumer of UCM
API in the system (e.g., pulseaudio), which is really no different
from the current situation for basic playback or capture through Alsa,
i.e., if multiple processes want to playback/capture PCM data at the
same time, then some other entity must coordinate access (e.g., dmix,
pulseaudio).

>From the PND perspective, there is often a complex intermix of
business logic and asynchronous system events (from both hardware and
software) driving the audio hardware state changes. I can tell you
from experience that it is a nightmare to have to pass such arbitrary
information between processes for the purposes of making even the
simplest of policy decisions for system-wide audio state. If it is
truly desired to turn UCM into userspace's central manager and
coordinator for audio state, then it absolutely must provide a clear
and flexible way to pass arbitrary state variables through the system,
and also a generic mechanism for specifying how the audio policy must
change based on those state variables. A superb and worthy ideal,
perhaps, but it's a tall order, and I don't see it becoming a viable
reality any time soon.

I think the proposed switch to using alsa-lib's present conf file
parser code may be worth doing (even though I find the syntax to be
uglier). Otherwise, the only thing I would really like to see added to
UCM (after it gets mainlined!) is a more generic mechanism for
aliasing mixer control names, instead of how it is currently limited
to aliasing master playback/capture volumes and master
playback/capture switches. On PNDs at least, it is often necessary to
read/write some mixer controls directly, e.g., for mic gain, and so
it's a pain when mixer control names differ across codecs. It would be
great if Alsa provided for such aliasing, instead of leaving
developers to rely on custom solutions.

Regards,

Chris Winter

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Tue, Sep 21, 2010 at 12:13:33PM -0500, Chris Winter wrote:

> I think the proposed switch to using alsa-lib's present conf file
> parser code may be worth doing (even though I find the syntax to be
> uglier). Otherwise, the only thing I would really like to see added to
> UCM (after it gets mainlined!) is a more generic mechanism for
> aliasing mixer control names, instead of how it is currently limited
> to aliasing master playback/capture volumes and master

This was discussed when the original review round happened a while ago
and is the reason why the interfaces support other names even though the
implementation can't - it means someone can just substitute in different
library code without disrupting applications.  Definitely on the list to
do.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Tue, 21 Sep 2010, Chris Winter wrote:

> On Mon, Sep 20, 2010 at 11:26 AM, Colin Guthrie <gmane@colin.guthr.ie> wrote:
>> Hi Jaroslav,
>>
>> 'Twas brillig, and Jaroslav Kysela at 07/09/10 15:42 did gyre and gimble:
>>> On Tue, 7 Sep 2010, Liam Girdwood wrote:
>>>
>>>> Hi Jaroslav,
>>>>
>>>> Any update on this ? I have someone scheduled to write new use case
>>>> files and someone else ready to add PA support.
>>>
>>> Hi,
>>>
>>> I'm working on this. Unfortunately, I have other things which interrupts
>>> this work. The actual code is at:
>>>
>>> http://git.alsa-project.org/?p=alsa-lib.git;a=shortlog;h=ucm
>>
>> Has there been any progress on the UCM stuff? I'm quite interested to
>> see how this will develop from a PA perspective. It does have some
>> impact on work that I've been wanting to do for a while in PA so the
>> sooner this is available in ALSA the sooner I can start thinking about
>> some of the knock on effects. I know Liam is intending to do some work
>> on PA too to integrate UCM once the API has stabilised, so I'm obviously
>> keen to encourage that too :D
>
> Since progress on UCM seems to have stalled, I'd also like to chip in
> and say that it would be great to see UCM pushed to mainline as soon
> as possible. I'm a software engineer at Garmin, responsible for
> system-level audio support on Linux-based personal navigation devices,
> and UCM would *really* help to simplify the management of audio state
> on those devices. In fact, I've been hurting for something like UCM
> for so long that I'm already developing against the version that Liam
> has posted to the list.

Hi all,

 	I'm sorry to be silent in the last week, but the reason was quite 
simple - vacation. As my life goes, my second son was born and I decided 
to be with my family, so I was able to handle only really urgent things.

> I not entirely convinced that Jaroslav's proposed changes to UCM will
> add much value to overall functionality. The reworked API seems more
> clumsy and confusing to me, and I think it's a bad idea to make UCM
> responsible for coordinating audio state management throughout
> userspace -- as Mark B. said, that responsibility would seem to be
> better left to some other entity who would be the sole consumer of UCM
> API in the system (e.g., pulseaudio), which is really no different
> from the current situation for basic playback or capture through Alsa,
> i.e., if multiple processes want to playback/capture PCM data at the
> same time, then some other entity must coordinate access (e.g., dmix,
> pulseaudio).

There are two things and I think that we both talking about different 
ones.

1) Which devices can be used simultaneously in the system
    (basically determining the number of handled streams).
2) Physical output (or input) switching (I mean physical jacks etc.).

I don't want to add any complex manager. I just think that the UCM layer 
should give the information to the application which PCM streams can be 
used concurrently for a named card. Something like stream grouping.

The problem is that you think in the "ASoC" way to handle just one 
input and output stream for phones etc. and I think in "multiple 
independant streams" per card way.

>> From the PND perspective, there is often a complex intermix of
> business logic and asynchronous system events (from both hardware and
> software) driving the audio hardware state changes. I can tell you
> from experience that it is a nightmare to have to pass such arbitrary
> information between processes for the purposes of making even the
> simplest of policy decisions for system-wide audio state. If it is
> truly desired to turn UCM into userspace's central manager and
> coordinator for audio state, then it absolutely must provide a clear
> and flexible way to pass arbitrary state variables through the system,
> and also a generic mechanism for specifying how the audio policy must
> change based on those state variables. A superb and worthy ideal,
> perhaps, but it's a tall order, and I don't see it becoming a viable
> reality any time soon.

I agree.

> I think the proposed switch to using alsa-lib's present conf file
> parser code may be worth doing (even though I find the syntax to be
> uglier). Otherwise, the only thing I would really like to see added to
> UCM (after it gets mainlined!) is a more generic mechanism for
> aliasing mixer control names, instead of how it is currently limited
> to aliasing master playback/capture volumes and master
> playback/capture switches. On PNDs at least, it is often necessary to
> read/write some mixer controls directly, e.g., for mic gain, and so
> it's a pain when mixer control names differ across codecs. It would be
> great if Alsa provided for such aliasing, instead of leaving
> developers to rely on custom solutions.

This is really point why I switched from "many functions returning 
just values" to "one function with a universal string identifier 
returning requested value". It makes API much flexible for future 
extensions and the library will not export a next bunch of similar 
functions.

The question is how we can make much flexible the passing of these values 
from the configuration files. I think that we may use just a direct way 
between the "identifier" from the snd_use_case_get/set function and the 
configuration files, having syntax something like:

SectionDevice."Headphones".0 {
 	...
 	Value."_ctl_/_pctlsw" "name='Master Playback Switch'"
 	...
}

Note that we may talk about the API, identifier names etc.

 					Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Colin Guthrie]

'Twas brillig, and Jaroslav Kysela at 21/09/10 19:11 did gyre and gimble:
>  	I'm sorry to be silent in the last week, but the reason was quite 
> simple - vacation. As my life goes, my second son was born and I decided 
> to be with my family, so I was able to handle only really urgent things.

Call that an excuse??? Oh wait, it is actually a *very* good excuse :D

Congratulations to you and yours!

/me wonders if he was born with headphones already in his ears :p

Col

-- 

Colin Guthrie
gmane(at)colin.guthr.ie
http://colin.guthr.ie/

Day Job:
  Tribalogic Limited [http://www.tribalogic.net/]
Open Source:
  Mageia Contributor [http://www.mageia.org/]
  PulseAudio Hacker [http://www.pulseaudio.org/]
  Trac Hacker [http://trac.edgewall.org/]

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Tue, Sep 21, 2010 at 08:11:35PM +0200, Jaroslav Kysela wrote:

> There are two things and I think that we both talking about different 
> ones.

> 1) Which devices can be used simultaneously in the system
>     (basically determining the number of handled streams).
> 2) Physical output (or input) switching (I mean physical jacks etc.).

> I don't want to add any complex manager. I just think that the UCM layer 
> should give the information to the application which PCM streams can be 
> used concurrently for a named card. Something like stream grouping.

This is what the snd_use_case_*_pcm() functions are all about -
identifying which of the many available streams should be used for a
given output stream.  With modern mobile audio architectures the ability
to route different kind of audio to different PCM streams is essential.

Now, it's true that it doesn't explicitly support grouping multiple PCMs
together into a single use case which is probably a good extension to
think about - perhaps returning arrays would cover it, though to be
honest I'm not sure how often that'd get used (and I'd expect apps to
fail to cope).

> The problem is that you think in the "ASoC" way to handle just one 
> input and output stream for phones etc. and I think in "multiple 
> independant streams" per card way.

This is not the case at all.  As I said previously the sort of systems
that run ASoC already support pretty much all the use cases you have on
PCs and then some to the point where PC audio requirements are generally
noticably less complex than those for mobile platforms.  PCs have much
more regular hardware than the more complex embedded systems which helps
a lot with software complexity.

I previously pointed you at the WM8994 as an example of the sort of
device one sees in modern smartphones:

    http://www.wolfsonmicro.com/products/WM8994

This supports many bidirectional audio streams, with two being delivered
using TDM on one physical audio interface intended for connection to the
CPU and a more complex routing arragement available on the other two
physical audio interfaces for connection with the radios though it's
also possible to connect additional links to the CPU if the application
demands it.

These sorts of features aren't that new - even something several years
old like the Marvell Zylonite reference platform offers multiple streams
to the CPU.

> This is really point why I switched from "many functions returning 
> just values" to "one function with a universal string identifier 
> returning requested value". It makes API much flexible for future 
> extensions and the library will not export a next bunch of similar 
> functions.

I think there's a balance here in interface complexity terms - there's
value in having some structure provided by default with a more advanced
interface for more general use.  This provides some guidance and code
simplification for basic use while providing room for more complex use
cases.

> The question is how we can make much flexible the passing of these values 
> from the configuration files. I think that we may use just a direct way 
> between the "identifier" from the snd_use_case_get/set function and the 
> configuration files, having syntax something like:

There's some scaling issues that need to be dealt with - for example, if
you're asking for the controls for an EQ you likely want to be able to
get an array back with the per-band gains and possibly trimming options
for the bands since there's quite a bit of range in the control offered
by EQs.  This means we will need to be able to return a variably sized
set of controls.

> SectionDevice."Headphones".0 {
>  	...
>  	Value."_ctl_/_pctlsw" "name='Master Playback Switch'"
>  	...
> }

This sort of thing is quite different to what you were suggesting
previously and much less problematic.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Wed, 22 Sep 2010, Mark Brown wrote:

> On Tue, Sep 21, 2010 at 08:11:35PM +0200, Jaroslav Kysela wrote:
>
>> There are two things and I think that we both talking about different
>> ones.
>
>> 1) Which devices can be used simultaneously in the system
>>     (basically determining the number of handled streams).
>> 2) Physical output (or input) switching (I mean physical jacks etc.).
>
>> I don't want to add any complex manager. I just think that the UCM layer
>> should give the information to the application which PCM streams can be
>> used concurrently for a named card. Something like stream grouping.
>
> This is what the snd_use_case_*_pcm() functions are all about -
> identifying which of the many available streams should be used for a
> given output stream.  With modern mobile audio architectures the ability
> to route different kind of audio to different PCM streams is essential.

But it's not possible to guess if streams are independant from the PCM 
device name. Some hardware has restrictions or driver can offer more PCM 
devices for one hardware (for example stereo only devices and multichannel 
devices sharing same hardware portion).

> Now, it's true that it doesn't explicitly support grouping multiple PCMs
> together into a single use case which is probably a good extension to
> think about - perhaps returning arrays would cover it, though to be
> honest I'm not sure how often that'd get used (and I'd expect apps to
> fail to cope).

Maybe a simple extension to the current API might cover also this issue: 
Add a third state for devices and modifiers - "blocked". This state will 
be active when hardware has inter-device/modifier contraints or when 
another application uses hardware in the blocking way.

>> The question is how we can make much flexible the passing of these values
>> from the configuration files. I think that we may use just a direct way
>> between the "identifier" from the snd_use_case_get/set function and the
>> configuration files, having syntax something like:
>
> There's some scaling issues that need to be dealt with - for example, if
> you're asking for the controls for an EQ you likely want to be able to
> get an array back with the per-band gains and possibly trimming options
> for the bands since there's quite a bit of range in the control offered
> by EQs.  This means we will need to be able to return a variably sized
> set of controls.

Sure, but you can describe this array in a string with some delimiters.

>> SectionDevice."Headphones".0 {
>>  	...
>>  	Value."_ctl_/_pctlsw" "name='Master Playback Switch'"
>>  	...
>> }
>
> This sort of thing is quite different to what you were suggesting
> previously and much less problematic.

I just finished the implementation for all functions in my GIT tree 
(except card listing). Also, the "Value {}" section is implemented as I 
proposed - it means that users can pass any read-only values to the API 
user.

The code is not tested, I need to write a simple command line tool for 
testing the API and also move the control/mixer ID and value handling 
code from the alsa-utils/amixer utility to alsa-lib.

So, please, check the use-case.h again:

http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=include/use-case.h;h=fdbcaca04c032b22de41cce2d42ab5b84edd37f4;hb=404cd090b279b329c86514984dc74439dedf2e90

Note that this code is almost complete rewrite to use the kernel style 
lists (alsa-lib/include/list.h).

 					Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Wed, Sep 22, 2010 at 04:06:56PM +0200, Jaroslav Kysela wrote:
> On Wed, 22 Sep 2010, Mark Brown wrote:

> >This is what the snd_use_case_*_pcm() functions are all about -
> >identifying which of the many available streams should be used for a
> >given output stream.  With modern mobile audio architectures the ability
> >to route different kind of audio to different PCM streams is essential.

> But it's not possible to guess if streams are independant from the
> PCM device name. Some hardware has restrictions or driver can offer
> more PCM devices for one hardware (for example stereo only devices
> and multichannel devices sharing same hardware portion).

That sounds like an annotation for...

> >Now, it's true that it doesn't explicitly support grouping multiple PCMs
> >together into a single use case which is probably a good extension to
> >think about - perhaps returning arrays would cover it, though to be
> >honest I'm not sure how often that'd get used (and I'd expect apps to
> >fail to cope).

> Maybe a simple extension to the current API might cover also this
> issue: Add a third state for devices and modifiers - "blocked". This
> state will be active when hardware has inter-device/modifier
> contraints or when another application uses hardware in the blocking
> way.

...this, though I think the blocking concept is most likely a higher
level one than UCM since there's a lot of of overlap between this and
policy decisons about which outputs are active.  It might be easier to
implement blocking by setting up the use case with a /dev/null stream
instead of a real one so applications don't need to cope, though
obviously some things will want to know if their audio is being
blackholed.

> >>The question is how we can make much flexible the passing of these values
> >>from the configuration files. I think that we may use just a direct way
> >>between the "identifier" from the snd_use_case_get/set function and the
> >>configuration files, having syntax something like:

> >There's some scaling issues that need to be dealt with - for example, if
> >you're asking for the controls for an EQ you likely want to be able to
> >get an array back with the per-band gains and possibly trimming options
> >for the bands since there's quite a bit of range in the control offered
> >by EQs.  This means we will need to be able to return a variably sized
> >set of controls.
> 
> Sure, but you can describe this array in a string with some delimiters.

That's not going to be terribly pleasant as an API, though - I'd expect
the library to have demangled the data before applications are expected
to work with it.  Otherwise you end up with lots of people implementing
the same parsing code.

> I just finished the implementation for all functions in my GIT tree
> (except card listing). Also, the "Value {}" section is implemented
> as I proposed - it means that users can pass any read-only values to
> the API user.
> 
> The code is not tested, I need to write a simple command line tool
> for testing the API and also move the control/mixer ID and value
> handling code from the alsa-utils/amixer utility to alsa-lib.

> So, please, check the use-case.h again:

> http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=include/use-case.h;h=fdbcaca04c032b22de41cce2d42ab5b84edd37f4;hb=404cd090b279b329c86514984dc74439dedf2e90

Random points since there's no patch to quote:

 - For the list of known identifiers would it not make sense to just say
   that standard ALSA control names are used for things like Capture
   Volume?  Just say something like "Use standard ALSA control names or
   one of the following additional things with an optional /modifier"

 - For standard string identifiers it'd be nice to provide definitions
   to provide compile time checking for typos - if we just use strings
   then they'll only be noticed at runtime, if there's standard defines
   the build will fail if people use them with typos.

 - As I said above I don't like the idea of returning just a string for
   _get() - if the string needs any sort of parsing to be intelligable
   we shouldn't be forcing users to do all that.

In general I'm nervous about the usability and robustness here; there's
an awful lot of stuff getting passed around as strings which may or may
not need parsing.  This is much more of a concern for me on the output
side than on the input side since it pushes complexity onto client code
without any safety features at all and causes clients to have to
implement very similar code to understand the more complex strings.

What might work here would be to use this as a core API for advanced
users then layer on more specific APIs which make stronger guarantees
about what comes back (eg, guaranteeing to return only a single control
name).  We could perhaps merge something like what you've got here and
then add such features incrementally.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Liam Girdwood]

On Wed, 2010-09-22 at 16:06 +0200, Jaroslav Kysela wrote:

> 
> I just finished the implementation for all functions in my GIT tree 
> (except card listing). Also, the "Value {}" section is implemented as I 
> proposed - it means that users can pass any read-only values to the API 
> user.
> 

Not had a good look yet, I assume all the functionality from the old API
is preserved ? 


> The code is not tested, I need to write a simple command line tool for 
> testing the API and also move the control/mixer ID and value handling 
> code from the alsa-utils/amixer utility to alsa-lib.
> 

Fwiw, there is some command line code for the old API that may be useful
here :-

git://git.slimlogic.co.uk/alsa-utils.git ucm-upstream

Liam

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Jaroslav Kysela]

On Wed, 22 Sep 2010, Mark Brown wrote:

> On Wed, Sep 22, 2010 at 04:06:56PM +0200, Jaroslav Kysela wrote:
>> On Wed, 22 Sep 2010, Mark Brown wrote:
>
>>> This is what the snd_use_case_*_pcm() functions are all about -
>>> identifying which of the many available streams should be used for a
>>> given output stream.  With modern mobile audio architectures the ability
>>> to route different kind of audio to different PCM streams is essential.
>
>> But it's not possible to guess if streams are independant from the
>> PCM device name. Some hardware has restrictions or driver can offer
>> more PCM devices for one hardware (for example stereo only devices
>> and multichannel devices sharing same hardware portion).
>
> That sounds like an annotation for...
>
>>> Now, it's true that it doesn't explicitly support grouping multiple PCMs
>>> together into a single use case which is probably a good extension to
>>> think about - perhaps returning arrays would cover it, though to be
>>> honest I'm not sure how often that'd get used (and I'd expect apps to
>>> fail to cope).
>
>> Maybe a simple extension to the current API might cover also this
>> issue: Add a third state for devices and modifiers - "blocked". This
>> state will be active when hardware has inter-device/modifier
>> contraints or when another application uses hardware in the blocking
>> way.
>
> ...this, though I think the blocking concept is most likely a higher
> level one than UCM since there's a lot of of overlap between this and
> policy decisons about which outputs are active.  It might be easier to
> implement blocking by setting up the use case with a /dev/null stream
> instead of a real one so applications don't need to cope, though
> obviously some things will want to know if their audio is being
> blackholed.

If the blocking state can be set only from the ucm code (not from an 
application), there is no policy. It's just a reflection about 
actual hardware state. Yours and other comments persuaded me that we 
should not apply any policy in the ucm level.

>>>> The question is how we can make much flexible the passing of these values
>>>> from the configuration files. I think that we may use just a direct way
>>>> between the "identifier" from the snd_use_case_get/set function and the
>>>> configuration files, having syntax something like:
>
>>> There's some scaling issues that need to be dealt with - for example, if
>>> you're asking for the controls for an EQ you likely want to be able to
>>> get an array back with the per-band gains and possibly trimming options
>>> for the bands since there's quite a bit of range in the control offered
>>> by EQs.  This means we will need to be able to return a variably sized
>>> set of controls.
>>
>> Sure, but you can describe this array in a string with some delimiters.
>
> That's not going to be terribly pleasant as an API, though - I'd expect
> the library to have demangled the data before applications are expected
> to work with it.  Otherwise you end up with lots of people implementing
> the same parsing code.

See bellow.

>> I just finished the implementation for all functions in my GIT tree
>> (except card listing). Also, the "Value {}" section is implemented
>> as I proposed - it means that users can pass any read-only values to
>> the API user.
>>
>> The code is not tested, I need to write a simple command line tool
>> for testing the API and also move the control/mixer ID and value
>> handling code from the alsa-utils/amixer utility to alsa-lib.
>
>> So, please, check the use-case.h again:
>
>> http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=include/use-case.h;h=fdbcaca04c032b22de41cce2d42ab5b84edd37f4;hb=404cd090b279b329c86514984dc74439dedf2e90
>
> Random points since there's no patch to quote:
>
> - For the list of known identifiers would it not make sense to just say
>   that standard ALSA control names are used for things like Capture
>   Volume?  Just say something like "Use standard ALSA control names or
>   one of the following additional things with an optional /modifier"

I don't have any trouble to use the usuall control naming. These rules 
must be documented somewhere, otherwise they might be useless. I made this 
information completely optional and the names are not fixed (my code does 
not look to these values at all).

> - For standard string identifiers it'd be nice to provide definitions
>   to provide compile time checking for typos - if we just use strings
>   then they'll only be noticed at runtime, if there's standard defines
>   the build will fail if people use them with typos.

It's a cosmetic issue - I think that I leave this change to someone other.

> - As I said above I don't like the idea of returning just a string for
>   _get() - if the string needs any sort of parsing to be intelligable
>   we shouldn't be forcing users to do all that.
>
> In general I'm nervous about the usability and robustness here; there's
> an awful lot of stuff getting passed around as strings which may or may
> not need parsing.  This is much more of a concern for me on the output
> side than on the input side since it pushes complexity onto client code
> without any safety features at all and causes clients to have to
> implement very similar code to understand the more complex strings.
>
> What might work here would be to use this as a core API for advanced
> users then layer on more specific APIs which make stronger guarantees
> about what comes back (eg, guaranteeing to return only a single control
> name).  We could perhaps merge something like what you've got here and
> then add such features incrementally.

Basically, it's my idea. The major thing for ucm is the verb / device / 
modifier / transition handling and device listing. All other optional data 
might have many usages and it depends on the final purpose. So call
strings like data containers. We can even carry XML or so if necessary :-)

Also, I plan to add to alsa-lib all parsers for the control ID, control 
value stuff, but to the right API - the control API (snd_ctl_*). So there 
is no requirement to implement these parsers in applications. The parsers 
will return standard structures like 'snd_ctl_elem_id_t' or so.

 					Jaroslav

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

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Wed, Sep 22, 2010 at 08:05:12PM +0200, Jaroslav Kysela wrote:
> On Wed, 22 Sep 2010, Mark Brown wrote:

> >...this, though I think the blocking concept is most likely a higher
> >level one than UCM since there's a lot of of overlap between this and
> >policy decisons about which outputs are active.  It might be easier to
> >implement blocking by setting up the use case with a /dev/null stream
> >instead of a real one so applications don't need to cope, though
> >obviously some things will want to know if their audio is being
> >blackholed.

> If the blocking state can be set only from the ucm code (not from an
> application), there is no policy. It's just a reflection about
> actual hardware state. Yours and other comments persuaded me that we
> should not apply any policy in the ucm level.

OK, I think we agree here - my suggestion for using a /dev/null stream
is just an example of something the policy level could configure in the
UCM rather than UCM functionality.

> >Random points since there's no patch to quote:

> >- For the list of known identifiers would it not make sense to just say
> >  that standard ALSA control names are used for things like Capture
> >  Volume?  Just say something like "Use standard ALSA control names or
> >  one of the following additional things with an optional /modifier"

> I don't have any trouble to use the usuall control naming. These
> rules must be documented somewhere, otherwise they might be useless.
> I made this information completely optional and the names are not
> fixed (my code does not look to these values at all).

Right, broadly agree but think we should be providing guidance to users
otherwise the API might be overwhelming - look at the issues we have
with selecting appropriate control names with the current APIs.

> Basically, it's my idea. The major thing for ucm is the verb /
> device / modifier / transition handling and device listing. All
> other optional data might have many usages and it depends on the
> final purpose. So call
> strings like data containers. We can even carry XML or so if necessary :-)

I'm all for having the ability to annoate the use cases with other data
but I do feel that this should be within a much more structured framework
than is present here.  However...

> Also, I plan to add to alsa-lib all parsers for the control ID,
> control value stuff, but to the right API - the control API
> (snd_ctl_*). So there is no requirement to implement these parsers
> in applications. The parsers will return standard structures like
> 'snd_ctl_elem_id_t' or so.

...this is pretty much exactly what I was suggesting with layering on
higher level APIs which provide more useful formats to users.  I'm
therefore not sure if this would actually be resolved or not.  If we're
going to have these more packaged APIs then it would probably be good to
steer people away from the UCM API itself through a combination of
documentation and API naming - make it clear that this is for advanced
users and that for basic usage you're supposed to go via the simpler
APIs.  

Does that sound like a good plan to you?

Having looked at the implementation briefly I also note that you've
kept the procedural specification of the control settings in your
configuration file format.  As I outlined previously I do have serious
concerns about this as a model for users to work with (orthogonally to
the actual implementation which must come down to a procedure at present
due to the ALSA API, something I hope to provide features to avoid in
the future).

If we make everything procedural now it will become much harder to back
out of it later, and I would hope that one of the things that use case
management can do is ensure that users only need to specify their goal
states and don't need to deal with the mechanics of how to achieve them
except in exceptional circumstances.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Niels Mayer]

On Wed, Sep 22, 2010 at 11:48 AM, Mark Brown
<broonie@opensource.wolfsonmicro.com> wrote:
> Having looked at the implementation briefly I also note that you've
> kept the procedural specification of the control settings in your
> configuration file format.  As I outlined previously I do have serious
> concerns about this as a model for users to work with (orthogonally to
> the actual implementation which must come down to a procedure at present
> due to the ALSA API, something I hope to provide features to avoid in
> the future).
>
> If we make everything procedural now it will become much harder to back
> out of it later, and I would hope that one of the things that use case
> management can do is ensure that users only need to specify their goal
> states and don't need to deal with the mechanics of how to achieve them
> except in exceptional circumstances.

I completely agree. This problem seems best solved by "logic
programming" and ontologies describing both hardware capabilities,
constraints, as well as the applications needs and requirements. Such
problems tend to have multiple solutions and often require a way for
constraints to be loosely, or multiply satisfied -- including asking
the user after narrowing down the search space to just a few equally
weighted choices (e.g. do i match the channel count of the source to
the device by duplicating channels or sending blank channels?).

There is much literature and many industry solutions employing such
simple "AI" techniques, and there's no reason why declarative
programming capabilities couldn't be built into any C-based library --
e.g. http://clipsrules.sourceforge.net http://www.gprolog.org etc.
Certainly, there is no need to "reinvent the wheel" hacking language
constructs and concepts that already exist and have some formalisms
behind them.

Example literature from a slightly different domain that could be
applied here include:
http://ebiquity.umbc.edu/get/a/publication/466.pdf ("Towards a
Declarative Framework for Managing Application and Network
Adaptations")
..................
Abstract—Cross layer optimizations are increasingly being
used in a variety of applications to improve application perfor-
mance. However most of these implementations are ad hoc and
performed on a per application basis. In this paper we propose
a declarative framework for managing application and network
adaptations. The declarative paradigm provides a much needed
clean line of separation between the high level goals and the
low level implementations. Our framework exposes the tunable
features of both the application and the network across layers of
the network stack which can then be jointly optimized. We allow
operators to control the adaptation process through operator
specified policies. [...] To support evolution, we pursue
an ontological approach and use semantic web languages such as
OWL and RDF in our framework for the policy and declarative
specifications, thereby also leveraging the inherent reasoning and
conflict resolution features of these languages. ...
.....................

Nepomuk Desktop ontologies are relevant here as well:
http://library.gnome.org/devel/ontology/unstable/nmm-ontology.html
http://library.gnome.org/devel/ontology/unstable/nfo-ontology.html
... what's needed is similar ontologies abstractly describing hardware
and providing the semantics of constraints on using the hardware --
whether it be locking semantics for concurrent or multiple access, bit
depth or sample rate matching, etc. Thus the application constraints
would need to match up against constraints posed by a "media hardware
ontology." Solving the constraint problem between application and
hardware may thus dynamically invoke sample-rate conversion, bit-depth
conversion, channel duplication or reduction, stream mixing, etc.

IMHO, such a layer could obviate the need for pulseaudio and instead
dynamically  invoke the appropriate ALSA constructs (dmix, dsnoop,
plug, etc) needed to satisfy application constraints against hardware
limitations.

-- Niels
http://nielsmayer.com
_______________________________________________
Alsa-devel mailing list
Alsa-devel@alsa-project.org
http://mailman.alsa-project.org/mailman/listinfo/alsa-devel

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Mark Brown]

On Thu, Sep 23, 2010 at 12:18:33AM -0700, Niels Mayer wrote:
> On Wed, Sep 22, 2010 at 11:48 AM, Mark Brown

> > If we make everything procedural now it will become much harder to back
> > out of it later, and I would hope that one of the things that use case
> > management can do is ensure that users only need to specify their goal
> > states and don't need to deal with the mechanics of how to achieve them
> > except in exceptional circumstances.

> I completely agree. This problem seems best solved by "logic
> programming" and ontologies describing both hardware capabilities,
> constraints, as well as the applications needs and requirements. Such

A strong note of caution here: this is a very difficult task which
nobody is currently attempting to do except for very constrained sets of
systems such as standard PC hardware.  Nothing anyone is discussing here
involves the automatic generation of settings, it's all about how we
manage sets of explicitly defined settings.

Re: [PATCH 0/3] alsa-lib: UCM - Use Case Manager

[Colin Guthrie]

'Twas brillig, and Niels Mayer at 23/09/10 08:18 did gyre and gimble:
> IMHO, such a layer could obviate the need for pulseaudio and instead
> dynamically  invoke the appropriate ALSA constructs (dmix, dsnoop,
> plug, etc) needed to satisfy application constraints against hardware
> limitations.

I completely fail to see how this construct replaces PulseAudio.. The
UCM support is intended to be implemented in PA. We currently already
have a "poor man's UCM" in PA as we probe many popular configurations on
init to determine a list of "Profiles" the user can select. Once the UCM
stuff is available in ALSA, we (or rather Liam :p) can try and use UCM
instead of htis probing scheme. As not all h/w will instantly support
UCM metadata, the probing scheme will still be used as a fall back.

But obtaining these profiles is actually a very small part of PA. There
are many other things that PA does that is totally beyond this scope and
I see no way for ontologies or otherwise to implement those capabilities
and features.

Col

-- 

Colin Guthrie
gmane(at)colin.guthr.ie
http://colin.guthr.ie/

Day Job:
  Tribalogic Limited [http://www.tribalogic.net/]
Open Source:
  Mageia Contributor [http://www.mageia.org/]
  PulseAudio Hacker [http://www.pulseaudio.org/]
  Trac Hacker [http://trac.edgewall.org/]