Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/alsa/use-case.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
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 *
261 * - [=]{NAME}[/[{modifier}|{/device}][/{verb}]]
262 * - value identifier {NAME}
263 * - Search starts at given modifier or device if any,
264 * else at a verb
265 * - Search starts at given verb if any,
266 * else current verb
267 * - Searches modifier/device, then verb, then defaults
268 * - Specify a leading "=" to search only the exact
269 * device/modifier/verb specified, and not search
270 * through each object in turn.
271 * - Examples:
272 * - "PlaybackPCM/Play Music"
273 * - "CapturePCM/SPDIF"
274 * - From ValueDefaults only:
275 * "=Variable"
276 * - From current active verb:
277 * "=Variable//"
278 * - From verb "Verb":
279 * "=Variable//Verb"
280 * - From "Modifier" in current active verb:
281 * "=Variable/Modifier/"
282 * - From "Modifier" in "Verb":
283 * "=Variable/Modifier/Verb"
284 *
285 * Recommended names for values:
286 * - Linked
287 * - value "True" or "1" (case insensitive)
288 * - this is a linked UCM card
289 * - don't use this UCM card, because the other UCM card refers devices
290 * - valid only in the ValueDefaults section (query '=Linked')
291 * - TQ
292 * - Tone Quality
293 * - Priority
294 * - priority value (1-10000), higher value means higher priority
295 * - valid only for verbs
296 * - for devices - PlaybackPriority and CapturePriority
297 * - PlaybackPCM
298 * - full PCM playback device name
299 * - PlaybackPCMIsDummy
300 * - Valid values: "yes" and "no". If set to "yes", the PCM named by the
301 * PlaybackPCM value is a dummy device, meaning that opening it enables
302 * an audio path in the hardware, but writing to the PCM device has no
303 * effect.
304 * - CapturePCM
305 * - full PCM capture device name
306 * - CapturePCMIsDummy
307 * - Valid values: "yes" and "no". If set to "yes", the PCM named by the
308 * CapturePCM value is a dummy device, meaning that opening it enables
309 * an audio path in the hardware, but reading from the PCM device has no
310 * effect.
311 * - PlaybackRate
312 * - playback device sample rate
313 * - PlaybackChannels
314 * - playback device channel count
315 * - PlaybackCTL
316 * - playback control device name
317 * - PlaybackVolume
318 * - playback control volume identifier string
319 * - can be parsed using snd_use_case_parse_ctl_elem_id()
320 * - PlaybackSwitch
321 * - playback control switch identifier string
322 * - can be parsed using snd_use_case_parse_ctl_elem_id()
323 * - PlaybackPriority
324 * - priority value (1-10000), higher value means higher priority
325 * - CaptureRate
326 * - capture device sample rate
327 * - CaptureChannels
328 * - capture device channel count
329 * - CaptureCTL
330 * - capture control device name
331 * - CaptureVolume
332 * - capture control volume identifier string
333 * - can be parsed using snd_use_case_parse_ctl_elem_id()
334 * - CaptureSwitch
335 * - capture control switch identifier string
336 * - can be parsed using snd_use_case_parse_ctl_elem_id()
337 * - CapturePriority
338 * - priority value (1-10000), higher value means higher priority
339 * - PlaybackMixer
340 * - name of playback mixer
341 * - PlaybackMixerElem
342 * - mixer element playback identifier
343 * - can be parsed using snd_use_case_parse_selem_id()
344 * - PlaybackMasterElem
345 * - mixer element playback identifier for the master control
346 * - can be parsed using snd_use_case_parse_selem_id()
347 * - PlaybackMasterType
348 * - type of the master volume control
349 * - Valid values: "soft" (software attenuation)
350 * - CaptureMixer
351 * - name of capture mixer
352 * - CaptureMixerElem
353 * - mixer element capture identifier
354 * - can be parsed using snd_use_case_parse_selem_id()
355 * - CaptureMasterElem
356 * - mixer element playback identifier for the master control
357 * - can be parsed using snd_use_case_parse_selem_id()
358 * - CaptureMasterType
359 * - type of the master volume control
360 * - Valid values: "soft" (software attenuation)
361 * - EDIDFile
362 * - Path to EDID file for HDMI devices
363 * - JackCTL
364 * - jack control device name
365 * - JackControl
366 * - jack control identificator
367 * - can be parsed using snd_use_case_parse_ctl_elem_id()
368 * - UCM configuration files should contain both JackControl and JackDev
369 * when possible, because applications are likely to support only one
370 * or the other
371 * - JackDev
372 * - the input device id of the jack (if the full input device path is
373 * /dev/input/by-id/foo, the JackDev value should be "foo")
374 * - UCM configuration files should contain both JackControl and JackDev
375 * when possible, because applications are likely to support only one
376 * or the other
377 * - JackHWMute
378 * If this value is set, it indicates that when the jack is plugged
379 * in, the hardware automatically mutes some other device(s). The
380 * value is a space-separated list of device names. If the device
381 * name contains space, it must be enclosed to ' or ", e.g.:
382 * JackHWMute "'Dock Headphone' Headphone"
383 * Note that JackHWMute should be used only when the hardware enforces
384 * the automatic muting. If the hardware doesn't enforce any muting, it
385 * may still be tempting to set JackHWMute to trick upper software layers
386 * to e.g. automatically mute speakers when headphones are plugged in,
387 * but that's application policy configuration that doesn't belong
388 * to UCM configuration files.
389 * - MinBufferLevel
390 * - This is used on platform where reported buffer level is not accurate.
391 * E.g. "512", which holds 512 samples in device buffer. Note: this will
392 * increase latency.
393 */
394 int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
395 const char *identifier,
396 const char **value);
397
398 /**
399 * \brief Get current - integer
400 * \param uc_mgr Use case manager
401 * \param identifier
402 * \param value result
403 * \return Zero if success, otherwise a negative error code
404 *
405 * Known identifiers:
406 * - _devstatus/{device} - return status for given device
407 * - _modstatus/{modifier} - return status for given modifier
408 */
409 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
410 const char *identifier,
411 long *value);
412
413 /**
414 * \brief Set new
415 * \param uc_mgr Use case manager
416 * \param identifier
417 * \param value Value
418 * \return Zero if success, otherwise a negative error code
419 *
420 * Known identifiers:
421 * - _boot - execute the boot sequence (value = NULL)
422 * - _defaults - execute the 'defaults' sequence (value = NULL)
423 * - _verb - set current verb = value
424 * - _enadev - enable given device = value
425 * - _disdev - disable given device = value
426 * - _swdev/{old_device} - new_device = value
427 * - disable old_device and then enable new_device
428 * - if old_device is not enabled just return
429 * - check transmit sequence firstly
430 * - _enamod - enable given modifier = value
431 * - _dismod - disable given modifier = value
432 * - _swmod/{old_modifier} - new_modifier = value
433 * - disable old_modifier and then enable new_modifier
434 * - if old_modifier is not enabled just return
435 * - check transmit sequence firstly
436 */
437 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
438 const char *identifier,
439 const char *value);
440
441 /**
442 * \brief Open and initialise use case core for sound card
443 * \param uc_mgr Returned use case manager pointer
444 * \param card_name Sound card name.
445 * \return zero if success, otherwise a negative error code
446 *
447 * By default only first card is used when the driver card
448 * name or long name is passed in the card_name argument.
449 *
450 * The "strict:" prefix in the card_name defines that
451 * there is no driver name / long name matching. The straight
452 * configuration is used.
453 *
454 * The "hw:" prefix in the card_name will load the configuration
455 * for the ALSA card specified by the card index (value) or
456 * the card string identificator.
457 *
458 * The sound card might be also composed from several physical
459 * sound cards (for the default and strict card_name).
460 * The application cannot expect that the device names will refer
461 * only one ALSA sound card in this case.
462 */
463 int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr,
464 const char *card_name);
465
466
467 /**
468 * \brief Reload and re-parse use case configuration files for sound card.
469 * \param uc_mgr Use case manager
470 * \return zero if success, otherwise a negative error code
471 */
472 int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
473
474 /**
475 * \brief Close use case manager
476 * \param uc_mgr Use case manager
477 * \return zero if success, otherwise a negative error code
478 */
479 int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
480
481 /**
482 * \brief Reset use case manager verb, device, modifier to deafult settings.
483 * \param uc_mgr Use case manager
484 * \return zero if success, otherwise a negative error code
485 */
486 int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
487
488 /*
489 * helper functions
490 */
491
492 /**
493 * \brief Obtain a list of cards
494 * \param list Returned allocated list
495 * \return Number of list entries if success, otherwise a negative error code
496 */
497 static __inline__ int snd_use_case_card_list(const char **list[])
498 {
499 return snd_use_case_get_list(NULL, NULL, list);
500 }
501
502 /**
503 * \brief Obtain a list of verbs
504 * \param uc_mgr Use case manager
505 * \param list Returned list of verbs
506 * \return Number of list entries if success, otherwise a negative error code
507 */
508 static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
509 const char **list[])
510 {
511 return snd_use_case_get_list(uc_mgr, "_verbs", list);
512 }
513
514 /**
515 * \brief Parse control element identifier
516 * \param elem_id Element identifier
517 * \param ucm_id Use case identifier
518 * \param value String value to be parsed
519 * \return Zero if success, otherwise a negative error code
520 */
521 int snd_use_case_parse_ctl_elem_id(snd_ctl_elem_id_t *dst,
522 const char *ucm_id,
523 const char *value);
524
525 /**
526 * \brief Parse mixer element identifier
527 * \param dst Simple mixer element identifier
528 * \param ucm_id Use case identifier
529 * \param value String value to be parsed
530 * \return Zero if success, otherwise a negative error code
531 */
532 int snd_use_case_parse_selem_id(snd_mixer_selem_id_t *dst,
533 const char *ucm_id,
534 const char *value);
535
536 /**
537 * \}
538 */
539
540 #ifdef __cplusplus
541 }
542 #endif
543
544 #endif /* __ALSA_USE_CASE_H */