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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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 #include <alsa/asoundlib.h>
46
47 /**
48 * \defgroup ucm Use Case Interface
49 * The ALSA Use Case manager interface.
50 * See \ref Usecase page for more details.
51 * \{
52 */
53
54 /*! \page Usecase ALSA Use Case Interface
55 *
56 * The use case manager works by configuring the sound card ALSA kcontrols to
57 * change the hardware digital and analog audio routing to match the requested
58 * device use case. The use case manager kcontrol configurations are stored in
59 * easy to modify text files.
60 *
61 * An audio use case can be defined by a verb and device parameter. The verb
62 * describes the use case action i.e. a phone call, listening to music, recording
63 * a conversation etc. The device describes the physical audio capture and playback
64 * hardware i.e. headphones, phone handset, bluetooth headset, etc.
65 *
66 * It's intended clients will mostly only need to set the use case verb and
67 * device for each system use case change (as the verb and device parameters
68 * cover most audio use cases).
69 *
70 * However there are times when a use case has to be modified at runtime. e.g.
71 *
72 * + Incoming phone call when the device is playing music
73 * + Recording sections of a phone call
74 * + Playing tones during a call.
75 *
76 * In order to allow asynchronous runtime use case adaptations, we have a third
77 * optional modifier parameter that can be used to further configure
78 * the use case during live audio runtime.
79 *
80 * This interface allows clients to :-
81 *
82 * + Query the supported use case verbs, devices and modifiers for the machine.
83 * + Set and Get use case verbs, devices and modifiers for the machine.
84 * + Get the ALSA PCM playback and capture device PCMs for use case verb,
85 * use case device and modifier.
86 * + Get the TQ parameter for each use case verb, use case device and
87 * modifier.
88 * + Get the ALSA master playback and capture volume/switch kcontrols
89 * or mixer elements for each use case.
90 */
91
92
93 /*
94 * Use Case Verb.
95 *
96 * The use case verb is the main device audio action. e.g. the "HiFi" use
97 * case verb will configure the audio hardware for HiFi Music playback
98 * and capture.
99 */
100 #define SND_USE_CASE_VERB_INACTIVE "Inactive" /**< Inactive Verb */
101 #define SND_USE_CASE_VERB_HIFI "HiFi" /**< HiFi Verb */
102 #define SND_USE_CASE_VERB_HIFI_LOW_POWER "HiFi Low Power" /**< HiFi Low Power Verb */
103 #define SND_USE_CASE_VERB_VOICE "Voice" /**< Voice Verb */
104 #define SND_USE_CASE_VERB_VOICE_LOW_POWER "Voice Low Power" /**< Voice Low Power Verb */
105 #define SND_USE_CASE_VERB_VOICECALL "Voice Call" /**< Voice Call Verb */
106 #define SND_USE_CASE_VERB_IP_VOICECALL "Voice Call IP" /**< Voice Call IP Verb */
107 #define SND_USE_CASE_VERB_ANALOG_RADIO "FM Analog Radio" /**< FM Analog Radio Verb */
108 #define SND_USE_CASE_VERB_DIGITAL_RADIO "FM Digital Radio" /**< FM Digital Radio Verb */
109 /* add new verbs to end of list */
110
111
112 /*
113 * Use Case Device.
114 *
115 * Physical system devices the render and capture audio. Devices can be OR'ed
116 * together to support audio on simultaneous devices.
117 *
118 * If multiple devices with the same name exists, the number suffixes should
119 * be added to these names like HDMI1,HDMI2,HDMI3 etc. No number gaps are
120 * allowed. The names with numbers must be continuous. It is allowed to put
121 * a whitespace between name and index (like 'Line 1') for the better
122 * readability. The device names 'Line 1' and 'Line1' are equal for
123 * this purpose.
124 *
125 * If EnableSequence/DisableSequence controls independent paths in the hardware
126 * it is also recommended to split playback and capture UCM devices and use
127 * the number suffixes. Example use case: Use the integrated microphone
128 * in the laptop instead the microphone in headphones.
129 *
130 * The preference of the devices is determined by the priority value.
131 */
132 #define SND_USE_CASE_DEV_NONE "None" /**< None Device */
133 #define SND_USE_CASE_DEV_SPEAKER "Speaker" /**< Speaker Device */
134 #define SND_USE_CASE_DEV_LINE "Line" /**< Line Device */
135 #define SND_USE_CASE_DEV_MIC "Mic" /**< Microphone Device */
136 #define SND_USE_CASE_DEV_HEADPHONES "Headphones" /**< Headphones Device */
137 #define SND_USE_CASE_DEV_HEADSET "Headset" /**< Headset Device */
138 #define SND_USE_CASE_DEV_HANDSET "Handset" /**< Handset Device */
139 #define SND_USE_CASE_DEV_BLUETOOTH "Bluetooth" /**< Bluetooth Device */
140 #define SND_USE_CASE_DEV_EARPIECE "Earpiece" /**< Earpiece Device */
141 #define SND_USE_CASE_DEV_SPDIF "SPDIF" /**< SPDIF Device */
142 #define SND_USE_CASE_DEV_HDMI "HDMI" /**< HDMI Device */
143 #define SND_USE_CASE_DEV_USB "USB" /**< USB Device (multifunctional) */
144 /* add new devices to end of list */
145
146
147 /*
148 * Use Case Modifiers.
149 *
150 * The use case modifier allows runtime configuration changes to deal with
151 * asynchronous events.
152 *
153 * If multiple modifiers with the same name exists, the number suffixes should
154 * be added to these names like 'Echo Reference 1','Echo Reference 2' etc.
155 * No number gaps are allowed. The names with numbers must be continuous.
156 * It is allowed to put a whitespace between name and index for the better
157 * readability. The modifier names 'Something 1' and 'Something1' are equal
158 * for this purpose.
159 *
160 * e.g. to record a voice call :-
161 * 1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
162 * 2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
163 * 3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
164 * with captured voice pcm data.
165 *
166 * e.g. to play a ring tone when listenin to MP3 Music :-
167 * 1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
168 * 2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
169 * 3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
170 * ringtone pcm data.
171 */
172 #define SND_USE_CASE_MOD_CAPTURE_VOICE "Capture Voice" /**< Capture Voice Modifier */
173 #define SND_USE_CASE_MOD_CAPTURE_MUSIC "Capture Music" /**< Capture Music Modifier */
174 #define SND_USE_CASE_MOD_PLAY_MUSIC "Play Music" /**< Play Music Modifier */
175 #define SND_USE_CASE_MOD_PLAY_VOICE "Play Voice" /**< Play Voice Modifier */
176 #define SND_USE_CASE_MOD_PLAY_TONE "Play Tone" /**< Play Tone Modifier */
177 #define SND_USE_CASE_MOD_ECHO_REF "Echo Reference" /**< Echo Reference Modifier */
178 /* add new modifiers to end of list */
179
180
181 /**
182 * TQ - Tone Quality
183 *
184 * The interface allows clients to determine the audio TQ required for each
185 * use case verb and modifier. It's intended as an optional hint to the
186 * audio driver in order to lower power consumption.
187 *
188 */
189 #define SND_USE_CASE_TQ_MUSIC "Music" /**< Music Tone Quality */
190 #define SND_USE_CASE_TQ_VOICE "Voice" /**< Voice Tone Quality */
191 #define SND_USE_CASE_TQ_TONES "Tones" /**< Tones Tone Quality */
192
193 /** use case container */
194 typedef struct snd_use_case_mgr snd_use_case_mgr_t;
195
196 /**
197 * \brief Create an identifier
198 * \param fmt Format (sprintf like)
199 * \param ... Optional arguments for sprintf like format
200 * \return Allocated string identifier or NULL on error
201 */
202 char *snd_use_case_identifier(const char *fmt, ...);
203
204 /**
205 * \brief Free a string list
206 * \param list The string list to free
207 * \param items Count of strings
208 * \return Zero if success, otherwise a negative error code
209 */
210 int snd_use_case_free_list(const char *list[], int items);
211
212 /**
213 * \brief Obtain a list of entries
214 * \param uc_mgr Use case manager (may be NULL - card list)
215 * \param identifier (may be NULL - card list)
216 * \param list Returned allocated list
217 * \return Number of list entries if success, otherwise a negative error code
218 *
219 * Defined identifiers:
220 * - NULL - get card list
221 * (in pair cardname+comment)
222 * - _verbs - get verb list
223 * (in pair verb+comment)
224 * - _devices[/{verb}] - get list of supported devices
225 * (in pair device+comment)
226 * - _modifiers[/{verb}] - get list of supported modifiers
227 * (in pair modifier+comment)
228 * - TQ[/{verb}] - get list of TQ identifiers
229 * - _enadevs - get list of enabled devices
230 * - _enamods - get list of enabled modifiers
231 *
232 * - _identifiers/{modifier}|{device}[/{verb}] - list of value identifiers
233 * - _supporteddevs/{modifier}|{device}[/{verb}] - list of supported devices
234 * - _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices
235 *
236 * Note that at most one of the supported/conflicting devs lists has
237 * any entries, and when neither is present, all devices are supported.
238 *
239 */
240 int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
241 const char *identifier,
242 const char **list[]);
243
244
245 /**
246 * \brief Get current - string
247 * \param uc_mgr Use case manager
248 * \param identifier
249 * \param value Value pointer
250 * \return Zero if success, otherwise a negative error code
251 *
252 * Note: The returned string is dynamically allocated, use free() to
253 * deallocate this string. (Yes, the value parameter shouldn't be marked as
254 * "const", but it's too late to fix it, sorry about that.)
255 *
256 * Known identifiers:
257 * - NULL - return current card
258 * - _verb - return current verb
259 * - _file - return configuration file loaded for current card
260 * - _alibcfg - return private alsa-lib's configuration for current card
261 * - _alibpref - return private alsa-lib's configuration device prefix for current card
262 *
263 * - [=]{NAME}[/[{modifier}|{/device}][/{verb}]]
264 * - value identifier {NAME}
265 * - Search starts at given modifier or device if any,
266 * else at a verb
267 * - Search starts at given verb if any,
268 * else current verb
269 * - Searches modifier/device, then verb, then defaults
270 * - Specify a leading "=" to search only the exact
271 * device/modifier/verb specified, and not search
272 * through each object in turn.
273 * - Examples:
274 * - "PlaybackPCM/Play Music"
275 * - "CapturePCM/SPDIF"
276 * - From ValueDefaults only:
277 * "=Variable"
278 * - From current active verb:
279 * "=Variable//"
280 * - From verb "Verb":
281 * "=Variable//Verb"
282 * - From "Modifier" in current active verb:
283 * "=Variable/Modifier/"
284 * - From "Modifier" in "Verb":
285 * "=Variable/Modifier/Verb"
286 *
287 * Recommended names for values:
288 * - Linked
289 * - value "True" or "1" (case insensitive)
290 * - this is a linked UCM card
291 * - don't use this UCM card, because the other UCM card refers devices
292 * - valid only in the ValueDefaults section (query '=Linked')
293 * - TQ
294 * - Tone Quality
295 * - Priority
296 * - priority value (1-10000), higher value means higher priority
297 * - valid only for verbs
298 * - for devices - PlaybackPriority and CapturePriority
299 * - PlaybackPCM
300 * - full PCM playback device name
301 * - PlaybackPCMIsDummy
302 * - Valid values: "yes" and "no". If set to "yes", the PCM named by the
303 * PlaybackPCM value is a dummy device, meaning that opening it enables
304 * an audio path in the hardware, but writing to the PCM device has no
305 * effect.
306 * - CapturePCM
307 * - full PCM capture device name
308 * - CapturePCMIsDummy
309 * - Valid values: "yes" and "no". If set to "yes", the PCM named by the
310 * CapturePCM value is a dummy device, meaning that opening it enables
311 * an audio path in the hardware, but reading from the PCM device has no
312 * effect.
313 * - PlaybackRate
314 * - playback device sample rate
315 * - PlaybackChannels
316 * - playback device channel count
317 * - PlaybackCTL
318 * - playback control device name
319 * - PlaybackVolume
320 * - playback control volume identifier string
321 * - can be parsed using snd_use_case_parse_ctl_elem_id()
322 * - PlaybackSwitch
323 * - playback control switch identifier string
324 * - can be parsed using snd_use_case_parse_ctl_elem_id()
325 * - PlaybackPriority
326 * - priority value (1-10000), higher value means higher priority
327 * - CaptureRate
328 * - capture device sample rate
329 * - CaptureChannels
330 * - capture device channel count
331 * - CaptureCTL
332 * - capture control device name
333 * - CaptureVolume
334 * - capture control volume identifier string
335 * - can be parsed using snd_use_case_parse_ctl_elem_id()
336 * - CaptureSwitch
337 * - capture control switch identifier string
338 * - can be parsed using snd_use_case_parse_ctl_elem_id()
339 * - CapturePriority
340 * - priority value (1-10000), higher value means higher priority
341 * - PlaybackMixer
342 * - name of playback mixer
343 * - PlaybackMixerElem
344 * - mixer element playback identifier
345 * - can be parsed using snd_use_case_parse_selem_id()
346 * - PlaybackMasterElem
347 * - mixer element playback identifier for the master control
348 * - can be parsed using snd_use_case_parse_selem_id()
349 * - PlaybackMasterType
350 * - type of the master volume control
351 * - Valid values: "soft" (software attenuation)
352 * - CaptureMixer
353 * - name of capture mixer
354 * - CaptureMixerElem
355 * - mixer element capture identifier
356 * - can be parsed using snd_use_case_parse_selem_id()
357 * - CaptureMasterElem
358 * - mixer element playback identifier for the master control
359 * - can be parsed using snd_use_case_parse_selem_id()
360 * - CaptureMasterType
361 * - type of the master volume control
362 * - Valid values: "soft" (software attenuation)
363 * - EDIDFile
364 * - Path to EDID file for HDMI devices
365 * - JackCTL
366 * - jack control device name
367 * - JackControl
368 * - jack control identificator
369 * - can be parsed using snd_use_case_parse_ctl_elem_id()
370 * - UCM configuration files should contain both JackControl and JackDev
371 * when possible, because applications are likely to support only one
372 * or the other
373 * - JackDev
374 * - the input device id of the jack (if the full input device path is
375 * /dev/input/by-id/foo, the JackDev value should be "foo")
376 * - UCM configuration files should contain both JackControl and JackDev
377 * when possible, because applications are likely to support only one
378 * or the other
379 * - JackHWMute
380 * If this value is set, it indicates that when the jack is plugged
381 * in, the hardware automatically mutes some other device(s). The
382 * value is a space-separated list of device names. If the device
383 * name contains space, it must be enclosed to ' or ", e.g.:
384 * JackHWMute "'Dock Headphone' Headphone"
385 * Note that JackHWMute should be used only when the hardware enforces
386 * the automatic muting. If the hardware doesn't enforce any muting, it
387 * may still be tempting to set JackHWMute to trick upper software layers
388 * to e.g. automatically mute speakers when headphones are plugged in,
389 * but that's application policy configuration that doesn't belong
390 * to UCM configuration files.
391 * - MinBufferLevel
392 * - This is used on platform where reported buffer level is not accurate.
393 * E.g. "512", which holds 512 samples in device buffer. Note: this will
394 * increase latency.
395 */
396 int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
397 const char *identifier,
398 const char **value);
399
400 /**
401 * \brief Get current - integer
402 * \param uc_mgr Use case manager
403 * \param identifier
404 * \param value result
405 * \return Zero if success, otherwise a negative error code
406 *
407 * Known identifiers:
408 * - _devstatus/{device} - return status for given device
409 * - _modstatus/{modifier} - return status for given modifier
410 */
411 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
412 const char *identifier,
413 long *value);
414
415 /**
416 * \brief Set new
417 * \param uc_mgr Use case manager
418 * \param identifier
419 * \param value Value
420 * \return Zero if success, otherwise a negative error code
421 *
422 * Known identifiers:
423 * - _fboot - execute the fixed boot sequence (value = NULL)
424 * - _boot - execute the boot sequence (value = NULL)
425 * - only when driver controls identifiers are changed
426 * (otherwise the old control values are restored)
427 * - _defaults - execute the 'defaults' sequence (value = NULL)
428 * - _verb - set current verb = value
429 * - _enadev - enable given device = value
430 * - _disdev - disable given device = value
431 * - _swdev/{old_device} - new_device = value
432 * - disable old_device and then enable new_device
433 * - if old_device is not enabled just return
434 * - check transmit sequence firstly
435 * - _enamod - enable given modifier = value
436 * - _dismod - disable given modifier = value
437 * - _swmod/{old_modifier} - new_modifier = value
438 * - disable old_modifier and then enable new_modifier
439 * - if old_modifier is not enabled just return
440 * - check transmit sequence firstly
441 */
442 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
443 const char *identifier,
444 const char *value);
445
446 /**
447 * \brief Open and initialise use case core for sound card
448 * \param uc_mgr Returned use case manager pointer
449 * \param card_name Sound card name.
450 * \return zero if success, otherwise a negative error code
451 *
452 * By default only first card is used when the driver card
453 * name or long name is passed in the card_name argument.
454 *
455 * The "strict:" prefix in the card_name defines that
456 * there is no driver name / long name matching. The straight
457 * configuration is used.
458 *
459 * The "hw:" prefix in the card_name will load the configuration
460 * for the ALSA card specified by the card index (value) or
461 * the card string identificator.
462 *
463 * The sound card might be also composed from several physical
464 * sound cards (for the default and strict card_name).
465 * The application cannot expect that the device names will refer
466 * only one ALSA sound card in this case.
467 */
468 int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr,
469 const char *card_name);
470
471
472 /**
473 * \brief Reload and re-parse use case configuration files for sound card.
474 * \param uc_mgr Use case manager
475 * \return zero if success, otherwise a negative error code
476 */
477 int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
478
479 /**
480 * \brief Close use case manager
481 * \param uc_mgr Use case manager
482 * \return zero if success, otherwise a negative error code
483 */
484 int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
485
486 /**
487 * \brief Reset use case manager verb, device, modifier to deafult settings.
488 * \param uc_mgr Use case manager
489 * \return zero if success, otherwise a negative error code
490 */
491 int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
492
493 /*
494 * helper functions
495 */
496
497 /**
498 * \brief Obtain a list of cards
499 * \param list Returned allocated list
500 * \return Number of list entries if success, otherwise a negative error code
501 */
snd_use_case_card_list(const char ** list[])502 static __inline__ int snd_use_case_card_list(const char **list[])
503 {
504 return snd_use_case_get_list(NULL, NULL, list);
505 }
506
507 /**
508 * \brief Obtain a list of verbs
509 * \param uc_mgr Use case manager
510 * \param list Returned list of verbs
511 * \return Number of list entries if success, otherwise a negative error code
512 */
snd_use_case_verb_list(snd_use_case_mgr_t * uc_mgr,const char ** list[])513 static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
514 const char **list[])
515 {
516 return snd_use_case_get_list(uc_mgr, "_verbs", list);
517 }
518
519 /**
520 * \brief Parse control element identifier
521 * \param elem_id Element identifier
522 * \param ucm_id Use case identifier
523 * \param value String value to be parsed
524 * \return Zero if success, otherwise a negative error code
525 */
526 int snd_use_case_parse_ctl_elem_id(snd_ctl_elem_id_t *dst,
527 const char *ucm_id,
528 const char *value);
529
530 /**
531 * \brief Parse mixer element identifier
532 * \param dst Simple mixer element identifier
533 * \param ucm_id Use case identifier
534 * \param value String value to be parsed
535 * \return Zero if success, otherwise a negative error code
536 */
537 int snd_use_case_parse_selem_id(snd_mixer_selem_id_t *dst,
538 const char *ucm_id,
539 const char *value);
540
541 /**
542 * \}
543 */
544
545 #ifdef __cplusplus
546 }
547 #endif
548
549 #endif /* __ALSA_USE_CASE_H */
550