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 */ 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 */ 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