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
42extern "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 */
170typedef 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 */
178char *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 */
186int 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 */
214int 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 */
272int 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 */
287int 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 */
313int 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 */
323int 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 */
331int 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 */
338int 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 */
345int 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 */
356static 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 */
367static 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