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 42extern "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#define SND_USE_CASE_DEV_DIRECT "Direct" /**< Direct Device (no channel remapping), (e.g. ProAudio usage) */ 145/* add new devices to end of list */ 146 147 148/* 149 * Use Case Modifiers. 150 * 151 * The use case modifier allows runtime configuration changes to deal with 152 * asynchronous events. 153 * 154 * If multiple modifiers with the same name exists, the number suffixes should 155 * be added to these names like 'Echo Reference 1','Echo Reference 2' etc. 156 * No number gaps are allowed. The names with numbers must be continuous. 157 * It is allowed to put a whitespace between name and index for the better 158 * readability. The modifier names 'Something 1' and 'Something1' are equal 159 * for this purpose. 160 * 161 * e.g. to record a voice call :- 162 * 1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call) 163 * 2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required. 164 * 3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name 165 * with captured voice pcm data. 166 * 167 * e.g. to play a ring tone when listenin to MP3 Music :- 168 * 1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback) 169 * 2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens. 170 * 3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for 171 * ringtone pcm data. 172 */ 173#define SND_USE_CASE_MOD_CAPTURE_VOICE "Capture Voice" /**< Capture Voice Modifier */ 174#define SND_USE_CASE_MOD_CAPTURE_MUSIC "Capture Music" /**< Capture Music Modifier */ 175#define SND_USE_CASE_MOD_PLAY_MUSIC "Play Music" /**< Play Music Modifier */ 176#define SND_USE_CASE_MOD_PLAY_VOICE "Play Voice" /**< Play Voice Modifier */ 177#define SND_USE_CASE_MOD_PLAY_TONE "Play Tone" /**< Play Tone Modifier */ 178#define SND_USE_CASE_MOD_ECHO_REF "Echo Reference" /**< Echo Reference Modifier */ 179/* add new modifiers to end of list */ 180 181 182/** 183 * TQ - Tone Quality 184 * 185 * The interface allows clients to determine the audio TQ required for each 186 * use case verb and modifier. It's intended as an optional hint to the 187 * audio driver in order to lower power consumption. 188 * 189 */ 190#define SND_USE_CASE_TQ_MUSIC "Music" /**< Music Tone Quality */ 191#define SND_USE_CASE_TQ_VOICE "Voice" /**< Voice Tone Quality */ 192#define SND_USE_CASE_TQ_TONES "Tones" /**< Tones Tone Quality */ 193 194/** use case container */ 195typedef struct snd_use_case_mgr snd_use_case_mgr_t; 196 197/** 198 * \brief Create an identifier 199 * \param fmt Format (sprintf like) 200 * \param ... Optional arguments for sprintf like format 201 * \return Allocated string identifier or NULL on error 202 */ 203char *snd_use_case_identifier(const char *fmt, ...); 204 205/** 206 * \brief Free a string list 207 * \param list The string list to free 208 * \param items Count of strings 209 * \return Zero if success, otherwise a negative error code 210 */ 211int snd_use_case_free_list(const char *list[], int items); 212 213/** 214 * \brief Obtain a list of entries 215 * \param uc_mgr Use case manager (may be NULL - card list) 216 * \param identifier (may be NULL - card list) 217 * \param list Returned allocated list 218 * \return Number of list entries if success, otherwise a negative error code 219 * 220 * Defined identifiers: 221 * - NULL - get card list 222 * (in pair cardname+comment) 223 * - _verbs - get verb list 224 * (in pair verb+comment) 225 * - _devices[/{verb}] - get list of supported devices 226 * (in pair device+comment) 227 * - _modifiers[/{verb}] - get list of supported modifiers 228 * (in pair modifier+comment) 229 * - TQ[/{verb}] - get list of TQ identifiers 230 * - _enadevs - get list of enabled devices 231 * - _enamods - get list of enabled modifiers 232 * 233 * - _identifiers/{modifier}|{device}[/{verb}] - list of value identifiers 234 * - _supporteddevs/{modifier}|{device}[/{verb}] - list of supported devices 235 * - _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices 236 * 237 * Note that at most one of the supported/conflicting devs lists has 238 * any entries, and when neither is present, all devices are supported. 239 * 240 */ 241int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr, 242 const char *identifier, 243 const char **list[]); 244 245 246/** 247 * \brief Get current - string 248 * \param uc_mgr Use case manager 249 * \param identifier 250 * \param value Value pointer 251 * \return Zero if success, otherwise a negative error code 252 * 253 * Note: The returned string is dynamically allocated, use free() to 254 * deallocate this string. (Yes, the value parameter shouldn't be marked as 255 * "const", but it's too late to fix it, sorry about that.) 256 * 257 * Known identifiers: 258 * - NULL - return current card 259 * - _verb - return current verb 260 * - _file - return configuration file loaded for current card 261 * - _alibcfg - return private alsa-lib's configuration for current card 262 * - _alibpref - return private alsa-lib's configuration device prefix for current card 263 * 264 * - [=]{NAME}[/[{modifier}|{/device}][/{verb}]] 265 * - value identifier {NAME} 266 * - Search starts at given modifier or device if any, 267 * else at a verb 268 * - Search starts at given verb if any, 269 * else current verb 270 * - Searches modifier/device, then verb, then defaults 271 * - Specify a leading "=" to search only the exact 272 * device/modifier/verb specified, and not search 273 * through each object in turn. 274 * - Examples: 275 * - "PlaybackPCM/Play Music" 276 * - "CapturePCM/SPDIF" 277 * - From ValueDefaults only: 278 * "=Variable" 279 * - From current active verb: 280 * "=Variable//" 281 * - From verb "Verb": 282 * "=Variable//Verb" 283 * - From "Modifier" in current active verb: 284 * "=Variable/Modifier/" 285 * - From "Modifier" in "Verb": 286 * "=Variable/Modifier/Verb" 287 * 288 * Recommended names for values: 289 * - Linked 290 * - value "True" or "1" (case insensitive) 291 * - this is a linked UCM card 292 * - don't use this UCM card, because the other UCM card refers devices 293 * - valid only in the ValueDefaults section (query '=Linked') 294 * - TQ 295 * - Tone Quality 296 * - Priority 297 * - priority value (1-10000), higher value means higher priority 298 * - valid only for verbs 299 * - for devices - PlaybackPriority and CapturePriority 300 * - PlaybackPCM 301 * - full PCM playback device name 302 * - PlaybackPCMIsDummy 303 * - Valid values: "yes" and "no". If set to "yes", the PCM named by the 304 * PlaybackPCM value is a dummy device, meaning that opening it enables 305 * an audio path in the hardware, but writing to the PCM device has no 306 * effect. 307 * - CapturePCM 308 * - full PCM capture device name 309 * - CapturePCMIsDummy 310 * - Valid values: "yes" and "no". If set to "yes", the PCM named by the 311 * CapturePCM value is a dummy device, meaning that opening it enables 312 * an audio path in the hardware, but reading from the PCM device has no 313 * effect. 314 * - PlaybackRate 315 * - playback device sample rate 316 * - PlaybackChannels 317 * - playback device channel count 318 * - PlaybackChannel# 319 * - describe index of the logical channel in the PCM stream 320 * - e.g. "PlaybackChannel0 2" - logical channel 0 is third channel in the PCM stream 321 * - PlaybackChannelPos# 322 * - describe sound position of the logical channel (ALSA chmap names) 323 * - e.g. "PlaybackChannel0 FR" - logical channel 0 is at front left 324 * - PlaybackCTL 325 * - playback control device name 326 * - PlaybackVolume 327 * - playback control volume identifier string 328 * - can be parsed using #snd_use_case_parse_ctl_elem_id() 329 * - PlaybackSwitch 330 * - playback control switch identifier string 331 * - can be parsed using #snd_use_case_parse_ctl_elem_id() 332 * - PlaybackPriority 333 * - priority value (1-10000), higher value means higher priority 334 * - CaptureRate 335 * - capture device sample rate 336 * - CaptureChannels 337 * - capture device channel count 338 * - CaptureChannel# 339 * - describe index of the logical channel in the PCM stream 340 * - e.g. "CaptureChannel0 2" - logical channel 0 is third channel in the PCM stream 341 * - CaptureChannelPos# 342 * - describe sound position of the logical channel (ALSA chmap names) 343 * - e.g. "CaptureChannel0 FR" - logical channel 0 is at front left 344 * - CaptureCTL 345 * - capture control device name 346 * - CaptureVolume 347 * - capture control volume identifier string 348 * - can be parsed using #snd_use_case_parse_ctl_elem_id() 349 * - CaptureSwitch 350 * - capture control switch identifier string 351 * - can be parsed using #snd_use_case_parse_ctl_elem_id() 352 * - CapturePriority 353 * - priority value (1-10000), higher value means higher priority 354 * - PlaybackMixer 355 * - name of playback mixer 356 * - PlaybackMixerElem 357 * - mixer element playback identifier 358 * - can be parsed using #snd_use_case_parse_selem_id() 359 * - PlaybackMasterElem 360 * - mixer element playback identifier for the master control 361 * - can be parsed using #snd_use_case_parse_selem_id() 362 * - PlaybackMasterType 363 * - type of the master volume control 364 * - Valid values: "soft" (software attenuation) 365 * - CaptureMixer 366 * - name of capture mixer 367 * - CaptureMixerElem 368 * - mixer element capture identifier 369 * - can be parsed using #snd_use_case_parse_selem_id() 370 * - CaptureMasterElem 371 * - mixer element playback identifier for the master control 372 * - can be parsed using #snd_use_case_parse_selem_id() 373 * - CaptureMasterType 374 * - type of the master volume control 375 * - Valid values: "soft" (software attenuation) 376 * - CaptureMicInfoFile 377 * - json file with the microphone array placement and type description 378 * (e.g. output from nhlt-dmic-info) 379 * - EDIDFile 380 * - Path to EDID file for HDMI devices 381 * - JackCTL 382 * - jack control device name 383 * - JackControl 384 * - jack control identificator 385 * - can be parsed using snd_use_case_parse_ctl_elem_id() 386 * - UCM configuration files should contain both JackControl and JackDev 387 * when possible, because applications are likely to support only one 388 * or the other 389 * - JackDev 390 * - the input device id of the jack (if the full input device path is 391 * /dev/input/by-id/foo, the JackDev value should be "foo") 392 * - UCM configuration files should contain both JackControl and JackDev 393 * when possible, because applications are likely to support only one 394 * or the other 395 * - JackHWMute 396 * If this value is set, it indicates that when the jack is plugged 397 * in, the hardware automatically mutes some other device(s). The 398 * value is a space-separated list of device names. If the device 399 * name contains space, it must be enclosed to ' or ", e.g.: 400 * JackHWMute "'Dock Headphone' Headphone" 401 * Note that JackHWMute should be used only when the hardware enforces 402 * the automatic muting. If the hardware doesn't enforce any muting, it 403 * may still be tempting to set JackHWMute to trick upper software layers 404 * to e.g. automatically mute speakers when headphones are plugged in, 405 * but that's application policy configuration that doesn't belong 406 * to UCM configuration files. 407 * - MinBufferLevel 408 * - This is used on platform where reported buffer level is not accurate. 409 * E.g. "512", which holds 512 samples in device buffer. Note: this will 410 * increase latency. 411 */ 412int snd_use_case_get(snd_use_case_mgr_t *uc_mgr, 413 const char *identifier, 414 const char **value); 415 416/** 417 * \brief Get current - integer 418 * \param uc_mgr Use case manager 419 * \param identifier 420 * \param value result 421 * \return Zero if success, otherwise a negative error code 422 * 423 * Known identifiers: 424 * - _devstatus/{device} - return status for given device 425 * - _modstatus/{modifier} - return status for given modifier 426 */ 427int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr, 428 const char *identifier, 429 long *value); 430 431/** 432 * \brief Set new 433 * \param uc_mgr Use case manager 434 * \param identifier 435 * \param value Value 436 * \return Zero if success, otherwise a negative error code 437 * 438 * Known identifiers: 439 * - _fboot - execute the fixed boot sequence (value = NULL) 440 * - _boot - execute the boot sequence (value = NULL) 441 * - only when driver controls identifiers are changed 442 * (otherwise the old control values are restored) 443 * - _defaults - execute the 'defaults' sequence (value = NULL) 444 * - _verb - set current verb = value 445 * - _enadev - enable given device = value 446 * - _disdev - disable given device = value 447 * - _swdev/{old_device} - new_device = value 448 * - disable old_device and then enable new_device 449 * - if old_device is not enabled just return 450 * - check transmit sequence firstly 451 * - _enamod - enable given modifier = value 452 * - _dismod - disable given modifier = value 453 * - _swmod/{old_modifier} - new_modifier = value 454 * - disable old_modifier and then enable new_modifier 455 * - if old_modifier is not enabled just return 456 * - check transmit sequence firstly 457 */ 458int snd_use_case_set(snd_use_case_mgr_t *uc_mgr, 459 const char *identifier, 460 const char *value); 461 462/** 463 * \brief Open and initialise use case core for sound card 464 * \param uc_mgr Returned use case manager pointer 465 * \param card_name Sound card name. 466 * \return zero if success, otherwise a negative error code 467 * 468 * By default only first card is used when the driver card 469 * name or long name is passed in the card_name argument. 470 * 471 * The "strict:" prefix in the card_name defines that 472 * there is no driver name / long name matching. The straight 473 * configuration is used. 474 * 475 * The "hw:" prefix in the card_name will load the configuration 476 * for the ALSA card specified by the card index (value) or 477 * the card string identificator. 478 * 479 * The sound card might be also composed from several physical 480 * sound cards (for the default and strict card_name). 481 * The application cannot expect that the device names will refer 482 * only one ALSA sound card in this case. 483 */ 484int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr, 485 const char *card_name); 486 487 488/** 489 * \brief Reload and re-parse use case configuration files for sound card. 490 * \param uc_mgr Use case manager 491 * \return zero if success, otherwise a negative error code 492 */ 493int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr); 494 495/** 496 * \brief Close use case manager 497 * \param uc_mgr Use case manager 498 * \return zero if success, otherwise a negative error code 499 */ 500int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr); 501 502/** 503 * \brief Reset use case manager verb, device, modifier to deafult settings. 504 * \param uc_mgr Use case manager 505 * \return zero if success, otherwise a negative error code 506 */ 507int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr); 508 509/* 510 * helper functions 511 */ 512 513/** 514 * \brief Obtain a list of cards 515 * \param list Returned allocated list 516 * \return Number of list entries if success, otherwise a negative error code 517 */ 518static __inline__ int snd_use_case_card_list(const char **list[]) 519{ 520 return snd_use_case_get_list(NULL, NULL, list); 521} 522 523/** 524 * \brief Obtain a list of verbs 525 * \param uc_mgr Use case manager 526 * \param list Returned list of verbs 527 * \return Number of list entries if success, otherwise a negative error code 528 */ 529static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr, 530 const char **list[]) 531{ 532 return snd_use_case_get_list(uc_mgr, "_verbs", list); 533} 534 535/** 536 * \brief Parse control element identifier 537 * \param dst Element identifier 538 * \param ucm_id Use case identifier 539 * \param value String value to be parsed 540 * \return Zero if success, otherwise a negative error code 541 */ 542int snd_use_case_parse_ctl_elem_id(snd_ctl_elem_id_t *dst, 543 const char *ucm_id, 544 const char *value); 545 546/** 547 * \brief Parse mixer element identifier 548 * \param dst Simple mixer element identifier 549 * \param ucm_id Use case identifier 550 * \param value String value to be parsed 551 * \return Zero if success, otherwise a negative error code 552 */ 553int snd_use_case_parse_selem_id(snd_mixer_selem_id_t *dst, 554 const char *ucm_id, 555 const char *value); 556 557/** 558 * \} 559 */ 560 561#ifdef __cplusplus 562} 563#endif 564 565#endif /* __ALSA_USE_CASE_H */ 566