Iliyan Malchev | 4765c43 | 2012-06-11 14:36:16 -0700 | [diff] [blame] | 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., 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 */ |