include/use-case.h

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