1 /**
2  * \file include/use-case.h
3  * \brief use case interface for the ALSA driver
4  * \author Liam Girdwood <lrg@slimlogic.co.uk>
5  * \author Stefan Schmidt <stefan@slimlogic.co.uk>
6  * \author Jaroslav Kysela <perex@perex.cz>
7  * \author Justin Xu <justinx@slimlogic.co.uk>
8  * \date 2008-2010
9  */
10 /*
11  *
12  *  This library is free software; you can redistribute it and/or modify
13  *  it under the terms of the GNU Lesser General Public License as
14  *  published by the Free Software Foundation; either version 2.1 of
15  *  the License, or (at your option) any later version.
16  *
17  *  This program is distributed in the hope that it will be useful,
18  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
19  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20  *  GNU Lesser General Public License for more details.
21  *
22  *  You should have received a copy of the GNU Lesser General Public
23  *  License along with this library; if not, write to the Free Software
24  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
25  *
26  *  Copyright (C) 2008-2010 SlimLogic Ltd
27  *  Copyright (C) 2010 Wolfson Microelectronics PLC
28  *  Copyright (C) 2010 Texas Instruments Inc.
29  *
30  *  Support for the verb/device/modifier core logic and API,
31  *  command line tool and file parser was kindly sponsored by
32  *  Texas Instruments Inc.
33  *  Support for multiple active modifiers and devices,
34  *  transition sequences, multiple client access and user defined use
35  *  cases was kindly sponsored by Wolfson Microelectronics PLC.
36  */
37 
38 #ifndef __ALSA_USE_CASE_H
39 #define __ALSA_USE_CASE_H
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 /**
46  *  \defgroup Use Case Interface
47  *  The ALSA Use Case manager interface.
48  *  See \ref Usecase page for more details.
49  *  \{
50  */
51 
52 /**
53  * ALSA Use Case Interface
54  *
55  * The use case manager works by configuring the sound card ALSA kcontrols to
56  * change the hardware digital and analog audio routing to match the requested
57  * device use case. The use case manager kcontrol configurations are stored in
58  * easy to modify text files.
59  *
60  * An audio use case can be defined by a verb and device parameter. The verb
61  * describes the use case action i.e. a phone call, listening to music, recording
62  * a conversation etc. The device describes the physical audio capture and playback
63  * hardware i.e. headphones, phone handset, bluetooth headset, etc.
64  *
65  * It's intended clients will mostly only need to set the use case verb and
66  * device for each system use case change (as the verb and device parameters
67  * cover most audio use cases).
68  *
69  * However there are times when a use case has to be modified at runtime. e.g.
70  *
71  *  o Incoming phone call when the device is playing music
72  *  o Recording sections of a phone call
73  *  o Playing tones during a call.
74  *
75  * In order to allow asynchronous runtime use case adaptations, we have a third
76  * optional modifier parameter that can be used to further configure
77  * the use case during live audio runtime.
78  *
79  * This interface allows clients to :-
80  *
81  *  o Query the supported use case verbs, devices and modifiers for the machine.
82  *  o Set and Get use case verbs, devices and modifiers for the machine.
83  *  o Get the ALSA PCM playback and capture device PCMs for use case verb,
84  *     use case device and modifier.
85  *  o Get the TQ parameter for each use case verb, use case device and
86  *     modifier.
87  *  o Get the ALSA master playback and capture volume/switch kcontrols
88  *     for each use case.
89  */
90 
91 
92 /*
93  * Use Case Verb.
94  *
95  * The use case verb is the main device audio action. e.g. the "HiFi" use
96  * case verb will configure the audio hardware for HiFi Music playback
97  * and capture.
98  */
99 #define SND_USE_CASE_VERB_INACTIVE		"Inactive"
100 #define SND_USE_CASE_VERB_HIFI			"HiFi"
101 #define SND_USE_CASE_VERB_HIFI_LOW_POWER	"HiFi Low Power"
102 #define SND_USE_CASE_VERB_VOICE			"Voice"
103 #define SND_USE_CASE_VERB_VOICE_LOW_POWER	"Voice Low Power"
104 #define SND_USE_CASE_VERB_VOICECALL		"Voice Call"
105 #define SND_USE_CASE_VERB_IP_VOICECALL		"Voice Call IP"
106 #define SND_USE_CASE_VERB_ANALOG_RADIO		"FM Analog Radio"
107 #define SND_USE_CASE_VERB_DIGITAL_RADIO		"FM Digital Radio"
108 /* add new verbs to end of list */
109 
110 
111 /*
112  * Use Case Device.
113  *
114  * Physical system devices the render and capture audio. Devices can be OR'ed
115  * together to support audio on simultaneous devices.
116  */
117 #define SND_USE_CASE_DEV_NONE		"None"
118 #define SND_USE_CASE_DEV_SPEAKER	"Speaker"
119 #define SND_USE_CASE_DEV_LINE		"Line"
120 #define SND_USE_CASE_DEV_HEADPHONES	"Headphones"
121 #define SND_USE_CASE_DEV_HEADSET	"Headset"
122 #define SND_USE_CASE_DEV_HANDSET	"Handset"
123 #define SND_USE_CASE_DEV_BLUETOOTH	"Bluetooth"
124 #define SND_USE_CASE_DEV_EARPIECE	"Earpiece"
125 #define SND_USE_CASE_DEV_SPDIF		"SPDIF"
126 #define SND_USE_CASE_DEV_HDMI		"HDMI"
127 /* add new devices to end of list */
128 
129 
130 /*
131  * Use Case Modifiers.
132  *
133  * The use case modifier allows runtime configuration changes to deal with
134  * asynchronous events.
135  *
136  * e.g. to record a voice call :-
137  *  1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
138  *  2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
139  *  3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
140  *     with captured voice pcm data.
141  *
142  * e.g. to play a ring tone when listenin to MP3 Music :-
143  *  1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
144  *  2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
145  *  3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
146  *     ringtone pcm data.
147  */
148 #define SND_USE_CASE_MOD_CAPTURE_VOICE		"Capture Voice"
149 #define SND_USE_CASE_MOD_CAPTURE_MUSIC		"Capture Music"
150 #define SND_USE_CASE_MOD_PLAY_MUSIC		"Play Music"
151 #define SND_USE_CASE_MOD_PLAY_VOICE		"Play Voice"
152 #define SND_USE_CASE_MOD_PLAY_TONE		"Play Tone"
153 #define SND_USE_CASE_MOD_ECHO_REF		"Echo Reference"
154 /* add new modifiers to end of list */
155 
156 
157 /**
158  * TQ - Tone Quality
159  *
160  * The interface allows clients to determine the audio TQ required for each
161  * use case verb and modifier. It's intended as an optional hint to the
162  * audio driver in order to lower power consumption.
163  *
164  */
165 #define SND_USE_CASE_TQ_MUSIC		"Music"
166 #define SND_USE_CASE_TQ_VOICE		"Voice"
167 #define SND_USE_CASE_TQ_TONES		"Tones"
168 
169 /** use case container */
170 typedef struct snd_use_case_mgr snd_use_case_mgr_t;
171 
172 /**
173  * \brief Create an identifier
174  * \param fmt Format (sprintf like)
175  * \param ... Optional arguments for sprintf like format
176  * \return Allocated string identifier or NULL on error
177  */
178 char *snd_use_case_identifier(const char *fmt, ...);
179 
180 /**
181  * \brief Free a string list
182  * \param list The string list to free
183  * \param items Count of strings
184  * \return Zero if success, otherwise a negative error code
185  */
186 int snd_use_case_free_list(const char *list[], int items);
187 
188 /**
189  * \brief Obtain a list of entries
190  * \param uc_mgr Use case manager (may be NULL - card list)
191  * \param identifier (may be NULL - card list)
192  * \param list Returned allocated list
193  * \return Number of list entries if success, otherwise a negative error code
194  *
195  * Defined identifiers:
196  *   NULL 		- get card list
197  *			  (in pair cardname+comment)
198  *   _verbs		- get verb list
199  *			  (in pair verb+comment)
200  *   _devices[/<verb>]	- get list of supported devices
201  *			  (in pair device+comment)
202  *   _modifiers[/<verb>]- get list of supported modifiers
203  *			  (in pair modifier+comment)
204  *   TQ[/<verb>]	- get list of TQ identifiers
205  *   _enadevs		- get list of enabled devices
206  *   _enamods		- get list of enabled modifiers
207  *
208  *   _supporteddevs/<modifier>|<device>[/<verb>]   - list of supported devices
209  *   _conflictingdevs/<modifier>|<device>[/<verb>] - list of conflicting devices
210  *   Note that at most one of the supported/conflicting devs lists has
211  *   any entries, and when neither is present, all devices are supported.
212  *
213  */
214 int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
215                           const char *identifier,
216                           const char **list[]);
217 
218 
219 /**
220  * \brief Get current - string
221  * \param uc_mgr Use case manager
222  * \param identifier
223  * \param value Value pointer
224  * \return Zero if success, otherwise a negative error code
225  *
226  * Note: String is dynamically allocated, use free() to
227  * deallocate this string.
228  *
229  * Known identifiers:
230  *   NULL 		- return current card
231  *   _verb		- return current verb
232  *
233  *   [=]<NAME>[/[<modifier>|</device>][/<verb>]]
234  *                      - value identifier <NAME>
235  *                      - Search starts at given modifier or device if any,
236  *                          else at a verb
237  *                      - Search starts at given verb if any,
238  *                          else current verb
239  *                      - Searches modifier/device, then verb, then defaults
240  *                      - Specify a leading "=" to search only the exact
241  *                        device/modifier/verb specified, and not search
242  *                        through each object in turn.
243  *                      - Examples:
244  *                          "PlaybackPCM/Play Music"
245  *                          "CapturePCM/SPDIF"
246  *                        From ValueDefaults only:
247  *                          "=Variable"
248  *                        From current active verb:
249  *                          "=Variable//"
250  *                        From verb "Verb":
251  *                          "=Variable//Verb"
252  *                        From "Modifier" in current active verb:
253  *                          "=Variable/Modifier/"
254  *                        From "Modifier" in "Verb":
255  *                          "=Variable/Modifier/Verb"
256  *
257  * Recommended names for values:
258  *   TQ			- Tone Quality
259  *   PlaybackPCM	- full PCM playback device name
260  *   CapturePCM		- full PCM capture device name
261  *   PlaybackCTL	- playback control device name
262  *   PlaybackVolume	- playback control volume ID string
263  *   PlaybackSwitch	- playback control switch ID string
264  *   CaptureCTL		- capture control device name
265  *   CaptureVolume	- capture control volume ID string
266  *   CaptureSwitch	- capture control switch ID string
267  *   PlaybackMixer	- name of playback mixer
268  *   PlaybackMixerID	- mixer playback ID
269  *   CaptureMixer	- name of capture mixer
270  *   CaptureMixerID	- mixer capture ID
271  */
272 int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
273                      const char *identifier,
274                      const char **value);
275 
276 /**
277  * \brief Get current - integer
278  * \param uc_mgr Use case manager
279  * \param identifier
280  * \param value result
281  * \return Zero if success, otherwise a negative error code
282  *
283  * Known identifiers:
284  *   _devstatus/<device>	- return status for given device
285  *   _modstatus/<modifier>	- return status for given modifier
286  */
287 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
288 		      const char *identifier,
289 		      long *value);
290 
291 /**
292  * \brief Set new
293  * \param uc_mgr Use case manager
294  * \param identifier
295  * \param value Value
296  * \return Zero if success, otherwise a negative error code
297  *
298  * Known identifiers:
299  *   _verb 		- set current verb = value
300  *   _enadev		- enable given device = value
301  *   _disdev		- disable given device = value
302  *   _swdev/<old_device> - new_device = value
303  *			- disable old_device and then enable new_device
304  *			- if old_device is not enabled just return
305  *			- check transmit sequence firstly
306  *   _enamod		- enable given modifier = value
307  *   _dismod		- disable given modifier = value
308  *   _swmod/<old_modifier> - new_modifier = value
309  *			- disable old_modifier and then enable new_modifier
310  *			- if old_modifier is not enabled just return
311  *			- check transmit sequence firstly
312  */
313 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
314                      const char *identifier,
315                      const char *value);
316 
317 /**
318  * \brief Open and initialise use case core for sound card
319  * \param uc_mgr Returned use case manager pointer
320  * \param card_name Sound card name.
321  * \return zero if success, otherwise a negative error code
322  */
323 int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr, const char *card_name);
324 
325 
326 /**
327  * \brief Reload and re-parse use case configuration files for sound card.
328  * \param uc_mgr Use case manager
329  * \return zero if success, otherwise a negative error code
330  */
331 int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
332 
333 /**
334  * \brief Close use case manager
335  * \param uc_mgr Use case manager
336  * \return zero if success, otherwise a negative error code
337  */
338 int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
339 
340 /**
341  * \brief Reset use case manager verb, device, modifier to deafult settings.
342  * \param uc_mgr Use case manager
343  * \return zero if success, otherwise a negative error code
344  */
345 int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
346 
347 /*
348  * helper functions
349  */
350 
351 /**
352  * \brief Obtain a list of cards
353  * \param list Returned allocated list
354  * \return Number of list entries if success, otherwise a negative error code
355  */
snd_use_case_card_list(const char ** list[])356 static inline int snd_use_case_card_list(const char **list[])
357 {
358 	return snd_use_case_get_list(NULL, NULL, list);
359 }
360 
361 /**
362  * \brief Obtain a list of verbs
363  * \param uc_mgr Use case manager
364  * \param list Returned list of verbs
365  * \return Number of list entries if success, otherwise a negative error code
366  */
snd_use_case_verb_list(snd_use_case_mgr_t * uc_mgr,const char ** list[])367 static inline int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
368 					 const char **list[])
369 {
370 	return snd_use_case_get_list(uc_mgr, "_verbs", list);
371 }
372 
373 /**
374  *  \}
375  */
376 
377 #ifdef __cplusplus
378 }
379 #endif
380 
381 #endif /* __ALSA_USE_CASE_H */
382