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 ucm Use Case Interface
  47  *  The ALSA Use Case manager interface.
  48  *  See \ref Usecase page for more details.
  49  *  \{
  50  */
  51
  52 /*! \page Usecase ALSA Use Case Interface
  53  *
  54  * The use case manager works by configuring the sound card ALSA kcontrols to
  55  * change the hardware digital and analog audio routing to match the requested
  56  * device use case. The use case manager kcontrol configurations are stored in
  57  * easy to modify text files.
  58  *
  59  * An audio use case can be defined by a verb and device parameter. The verb
  60  * describes the use case action i.e. a phone call, listening to music, recording
  61  * a conversation etc. The device describes the physical audio capture and playback
  62  * hardware i.e. headphones, phone handset, bluetooth headset, etc.
  63  *
  64  * It's intended clients will mostly only need to set the use case verb and
  65  * device for each system use case change (as the verb and device parameters
  66  * cover most audio use cases).
  67  *
  68  * However there are times when a use case has to be modified at runtime. e.g.
  69  *
  70  *  + Incoming phone call when the device is playing music
  71  *  + Recording sections of a phone call
  72  *  + Playing tones during a call.
  73  *
  74  * In order to allow asynchronous runtime use case adaptations, we have a third
  75  * optional modifier parameter that can be used to further configure
  76  * the use case during live audio runtime.
  77  *
  78  * This interface allows clients to :-
  79  *
  80  *  + Query the supported use case verbs, devices and modifiers for the machine.
  81  *  + Set and Get use case verbs, devices and modifiers for the machine.
  82  *  + Get the ALSA PCM playback and capture device PCMs for use case verb,
  83  *     use case device and modifier.
  84  *  + Get the TQ parameter for each use case verb, use case device and
  85  *     modifier.
  86  *  + Get the ALSA master playback and capture volume/switch kcontrols
  87  *     for each use case.
  88  */
  89
  90
  91 /*
  92  * Use Case Verb.
  93  *
  94  * The use case verb is the main device audio action. e.g. the "HiFi" use
  95  * case verb will configure the audio hardware for HiFi Music playback
  96  * and capture.
  97  */
  98 #define SND_USE_CASE_VERB_INACTIVE              "Inactive"              /**< Inactive Verb */
  99 #define SND_USE_CASE_VERB_HIFI                  "HiFi"                  /**< HiFi Verb */
 100 #define SND_USE_CASE_VERB_HIFI_LOW_POWER        "HiFi Low Power"        /**< HiFi Low Power Verb */
 101 #define SND_USE_CASE_VERB_VOICE                 "Voice"                 /**< Voice Verb */
 102 #define SND_USE_CASE_VERB_VOICE_LOW_POWER       "Voice Low Power"       /**< Voice Low Power Verb */
 103 #define SND_USE_CASE_VERB_VOICECALL             "Voice Call"            /**< Voice Call Verb */
 104 #define SND_USE_CASE_VERB_IP_VOICECALL          "Voice Call IP"         /**< Voice Call IP Verb */
 105 #define SND_USE_CASE_VERB_ANALOG_RADIO          "FM Analog Radio"       /**< FM Analog Radio Verb */
 106 #define SND_USE_CASE_VERB_DIGITAL_RADIO         "FM Digital Radio"      /**< FM Digital Radio Verb */
 107 /* add new verbs to end of list */
 108
 109
 110 /*
 111  * Use Case Device.
 112  *
 113  * Physical system devices the render and capture audio. Devices can be OR'ed
 114  * together to support audio on simultaneous devices.
 115  */
 116 #define SND_USE_CASE_DEV_NONE           "None"          /**< None Device */
 117 #define SND_USE_CASE_DEV_SPEAKER        "Speaker"       /**< Speaker Device */
 118 #define SND_USE_CASE_DEV_LINE           "Line"          /**< Line Device */
 119 #define SND_USE_CASE_DEV_HEADPHONES     "Headphones"    /**< Headphones Device */
 120 #define SND_USE_CASE_DEV_HEADSET        "Headset"       /**< Headset Device */
 121 #define SND_USE_CASE_DEV_HANDSET        "Handset"       /**< Handset Device */
 122 #define SND_USE_CASE_DEV_BLUETOOTH      "Bluetooth"     /**< Bluetooth Device */
 123 #define SND_USE_CASE_DEV_EARPIECE       "Earpiece"      /**< Earpiece Device */
 124 #define SND_USE_CASE_DEV_SPDIF          "SPDIF"         /**< SPDIF Device */
 125 #define SND_USE_CASE_DEV_HDMI           "HDMI"          /**< HDMI Device */
 126 /* add new devices to end of list */
 127
 128
 129 /*
 130  * Use Case Modifiers.
 131  *
 132  * The use case modifier allows runtime configuration changes to deal with
 133  * asynchronous events.
 134  *
 135  * e.g. to record a voice call :-
 136  *  1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
 137  *  2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
 138  *  3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
 139  *     with captured voice pcm data.
 140  *
 141  * e.g. to play a ring tone when listenin to MP3 Music :-
 142  *  1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
 143  *  2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
 144  *  3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
 145  *     ringtone pcm data.
 146  */
 147 #define SND_USE_CASE_MOD_CAPTURE_VOICE          "Capture Voice"         /**< Capture Voice Modifier */
 148 #define SND_USE_CASE_MOD_CAPTURE_MUSIC          "Capture Music"         /**< Capture Music Modifier */
 149 #define SND_USE_CASE_MOD_PLAY_MUSIC             "Play Music"            /**< Play Music Modifier */
 150 #define SND_USE_CASE_MOD_PLAY_VOICE             "Play Voice"            /**< Play Voice Modifier */
 151 #define SND_USE_CASE_MOD_PLAY_TONE              "Play Tone"             /**< Play Tone Modifier */
 152 #define SND_USE_CASE_MOD_ECHO_REF               "Echo Reference"        /**< Echo Reference Modifier */
 153 /* add new modifiers to end of list */
 154
 155
 156 /**
 157  * TQ - Tone Quality
 158  *
 159  * The interface allows clients to determine the audio TQ required for each
 160  * use case verb and modifier. It's intended as an optional hint to the
 161  * audio driver in order to lower power consumption.
 162  *
 163  */
 164 #define SND_USE_CASE_TQ_MUSIC           "Music"         /**< Music Tone Quality */
 165 #define SND_USE_CASE_TQ_VOICE           "Voice"         /**< Voice Tone Quality */
 166 #define SND_USE_CASE_TQ_TONES           "Tones"         /**< Tones Tone Quality */
 167
 168 /** use case container */
 169 typedef struct snd_use_case_mgr snd_use_case_mgr_t;
 170
 171 /**
 172  * \brief Create an identifier
 173  * \param fmt Format (sprintf like)
 174  * \param ... Optional arguments for sprintf like format
 175  * \return Allocated string identifier or NULL on error
 176  */
 177 char *snd_use_case_identifier(const char *fmt, ...);
 178
 179 /**
 180  * \brief Free a string list
 181  * \param list The string list to free
 182  * \param items Count of strings
 183  * \return Zero if success, otherwise a negative error code
 184  */
 185 int snd_use_case_free_list(const char *list[], int items);
 186
 187 /**
 188  * \brief Obtain a list of entries
 189  * \param uc_mgr Use case manager (may be NULL - card list)
 190  * \param identifier (may be NULL - card list)
 191  * \param list Returned allocated list
 192  * \return Number of list entries if success, otherwise a negative error code
 193  *
 194  * Defined identifiers:
 195  *   - NULL                     - get card list
 196  *                               (in pair cardname+comment)
 197  *   - _verbs                   - get verb list
 198  *                                (in pair verb+comment)
 199  *   - _devices[/{verb}]        - get list of supported devices
 200  *                                (in pair device+comment)
 201  *   - _modifiers[/{verb}]      - get list of supported modifiers
 202  *                                (in pair modifier+comment)
 203  *   - TQ[/{verb}]              - get list of TQ identifiers
 204  *   - _enadevs                 - get list of enabled devices
 205  *   - _enamods                 - get list of enabled modifiers
 206  *
 207  *   - _supporteddevs/{modifier}|{device}[/{verb}]   - list of supported devices
 208  *   - _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices
 209  *
 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: The returned string is dynamically allocated, use free() to
 227  * deallocate this string. (Yes, the value parameter shouldn't be marked as
 228  * "const", but it's too late to fix it, sorry about that.)
 229  *
 230  * Known identifiers:
 231  *   - NULL             - return current card
 232  *   - _verb            - return current verb
 233  *
 234  *   - [=]{NAME}[/[{modifier}|{/device}][/{verb}]]
 235  *                      - value identifier {NAME}
 236  *                      - Search starts at given modifier or device if any,
 237  *                          else at a verb
 238  *                      - Search starts at given verb if any,
 239  *                          else current verb
 240  *                      - Searches modifier/device, then verb, then defaults
 241  *                      - Specify a leading "=" to search only the exact
 242  *                        device/modifier/verb specified, and not search
 243  *                        through each object in turn.
 244  *                      - Examples:
 245  *                          - "PlaybackPCM/Play Music"
 246  *                          - "CapturePCM/SPDIF"
 247  *                          - From ValueDefaults only:
 248  *                              "=Variable"
 249  *                          - From current active verb:
 250  *                              "=Variable//"
 251  *                          - From verb "Verb":
 252  *                              "=Variable//Verb"
 253  *                          - From "Modifier" in current active verb:
 254  *                              "=Variable/Modifier/"
 255  *                          - From "Modifier" in "Verb":
 256  *                              "=Variable/Modifier/Verb"
 257  *
 258  * Recommended names for values:
 259  *   - TQ
 260  *      - Tone Quality
 261  *   - PlaybackPCM
 262  *      - full PCM playback device name
 263  *   - PlaybackPCMIsDummy
 264  *      - Valid values: "yes" and "no". If set to "yes", the PCM named by the
 265  *        PlaybackPCM value is a dummy device, meaning that opening it enables
 266  *        an audio path in the hardware, but writing to the PCM device has no
 267  *        effect.
 268  *   - CapturePCM
 269  *      - full PCM capture device name
 270  *   - CapturePCMIsDummy
 271  *      - Valid values: "yes" and "no". If set to "yes", the PCM named by the
 272  *        CapturePCM value is a dummy device, meaning that opening it enables
 273  *        an audio path in the hardware, but reading from the PCM device has no
 274  *        effect.
 275  *   - PlaybackRate
 276  *      - playback device sample rate
 277  *   - PlaybackChannels
 278  *      - playback device channel count
 279  *   - PlaybackCTL
 280  *      - playback control device name
 281  *   - PlaybackVolume
 282  *      - playback control volume ID string
 283  *   - PlaybackSwitch
 284  *      - playback control switch ID string
 285  *   - CaptureRate
 286  *      - capture device sample rate
 287  *   - CaptureChannels
 288  *      - capture device channel count
 289  *   - CaptureCTL
 290  *      - capture control device name
 291  *   - CaptureVolume
 292  *      - capture control volume ID string
 293  *   - CaptureSwitch
 294  *      - capture control switch ID string
 295  *   - PlaybackMixer
 296  *      - name of playback mixer
 297  *   - PlaybackMixerID
 298  *      - mixer playback ID
 299  *   - CaptureMixer
 300  *      - name of capture mixer
 301  *   - CaptureMixerID
 302  *      - mixer capture ID
 303  *   - JackControl, JackDev, JackHWMute
 304  *      - Jack information for a device. The jack status can be reported via
 305  *        a kcontrol and/or via an input device. **JackControl** is the
 306  *        kcontrol name of the jack, and **JackDev** is the input device id of
 307  *        the jack (if the full input device path is /dev/input/by-id/foo, the
 308  *        JackDev value should be "foo"). UCM configuration files should
 309  *        contain both JackControl and JackDev when possible, because
 310  *        applications are likely to support only one or the other.
 311  *
 312  *        If **JackHWMute** is set, it indicates that when the jack is plugged
 313  *        in, the hardware automatically mutes some other device(s). The
 314  *        JackHWMute value is a space-separated list of device names (this
 315  *        isn't compatible with device names with spaces in them, so don't use
 316  *        such device names!). Note that JackHWMute should be used only when
 317  *        the hardware enforces the automatic muting. If the hardware doesn't
 318  *        enforce any muting, it may still be tempting to set JackHWMute to
 319  *        trick upper software layers to e.g. automatically mute speakers when
 320  *        headphones are plugged in, but that's application policy
 321  *        configuration that doesn't belong to UCM configuration files.
 322  */
 323 int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
 324                      const char *identifier,
 325                      const char **value);
 326
 327 /**
 328  * \brief Get current - integer
 329  * \param uc_mgr Use case manager
 330  * \param identifier
 331  * \param value result
 332  * \return Zero if success, otherwise a negative error code
 333  *
 334  * Known identifiers:
 335  *   - _devstatus/{device}      - return status for given device
 336  *   - _modstatus/{modifier}    - return status for given modifier
 337  */
 338 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
 339                       const char *identifier,
 340                       long *value);
 341
 342 /**
 343  * \brief Set new
 344  * \param uc_mgr Use case manager
 345  * \param identifier
 346  * \param value Value
 347  * \return Zero if success, otherwise a negative error code
 348  *
 349  * Known identifiers:
 350  *   - _verb                    - set current verb = value
 351  *   - _enadev                  - enable given device = value
 352  *   - _disdev                  - disable given device = value
 353  *   - _swdev/{old_device}      - new_device = value
 354  *                                - disable old_device and then enable new_device
 355  *                                - if old_device is not enabled just return
 356  *                                - check transmit sequence firstly
 357  *   - _enamod                  - enable given modifier = value
 358  *   - _dismod                  - disable given modifier = value
 359  *   - _swmod/{old_modifier}    - new_modifier = value
 360  *                                - disable old_modifier and then enable new_modifier
 361  *                                - if old_modifier is not enabled just return
 362  *                                - check transmit sequence firstly
 363  */
 364 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
 365                      const char *identifier,
 366                      const char *value);
 367
 368 /**
 369  * \brief Open and initialise use case core for sound card
 370  * \param uc_mgr Returned use case manager pointer
 371  * \param card_name Sound card name.
 372  * \return zero if success, otherwise a negative error code
 373  */
 374 int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr, const char *card_name);
 375
 376
 377 /**
 378  * \brief Reload and re-parse use case configuration files for sound card.
 379  * \param uc_mgr Use case manager
 380  * \return zero if success, otherwise a negative error code
 381  */
 382 int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
 383
 384 /**
 385  * \brief Close use case manager
 386  * \param uc_mgr Use case manager
 387  * \return zero if success, otherwise a negative error code
 388  */
 389 int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
 390
 391 /**
 392  * \brief Reset use case manager verb, device, modifier to deafult settings.
 393  * \param uc_mgr Use case manager
 394  * \return zero if success, otherwise a negative error code
 395  */
 396 int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
 397
 398 /*
 399  * helper functions
 400  */
 401
 402 /**
 403  * \brief Obtain a list of cards
 404  * \param list Returned allocated list
 405  * \return Number of list entries if success, otherwise a negative error code
 406  */
 407 static __inline__ int snd_use_case_card_list(const char **list[])
 408 {
 409         return snd_use_case_get_list(NULL, NULL, list);
 410 }
 411
 412 /**
 413  * \brief Obtain a list of verbs
 414  * \param uc_mgr Use case manager
 415  * \param list Returned list of verbs
 416  * \return Number of list entries if success, otherwise a negative error code
 417  */
 418 static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
 419                                          const char **list[])
 420 {
 421         return snd_use_case_get_list(uc_mgr, "_verbs", list);
 422 }
 423
 424 /**
 425  *  \}
 426  */
 427
 428 #ifdef __cplusplus
 429 }
 430 #endif
 431
 432 #endif /* __ALSA_USE_CASE_H */