Home | History | Annotate | Download | only in libalsa-intf
      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