1 /** 2 * \file include/use-case.h 3 * \brief use case interface for the ALSA driver 4 * \author Liam Girdwood <lrg (at) slimlogic.co.uk> 5 * \author Stefan Schmidt <stefan (at) slimlogic.co.uk> 6 * \author Jaroslav Kysela <perex (at) perex.cz> 7 * \author Justin Xu <justinx (at) 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 42 extern "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 */ 170 typedef 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 */ 178 char *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 */ 186 int 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 */ 214 int 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 */ 272 int 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 */ 287 int 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 */ 313 int 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 */ 323 int 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 */ 331 int 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 */ 338 int 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 */ 345 int 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 */ 356 static 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 */ 367 static 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
