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 42extern "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 */ 170typedef 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 */ 178char *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 */ 186int 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 */ 214int 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 */ 272int 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 */ 287int 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 */ 313int 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 */ 323int 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 */ 331int 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 */ 338int 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 */ 345int 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 */ 356static 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 */ 367static 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