diff options
| -rw-r--r-- | include/use-case.h | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/include/use-case.h b/include/use-case.h new file mode 100644 index 00000000..18fe4d60 --- /dev/null +++ b/include/use-case.h @@ -0,0 +1,427 @@ +/** + * \file include/use-case.h + * \brief use case interface for the ALSA driver + * \author Liam Girdwood <lrg@slimlogic.co.uk> + * \author Stefan Schmidt <stefan@slimlogic.co.uk> + * \author Jaroslav Kysela <perex@perex.cz> + * \author Justin Xu <justinx@slimlogic.co.uk> + * \date 2008-2010 + */ +/* + * + * This library is free software; you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * + * Copyright (C) 2008-2010 SlimLogic Ltd + * Copyright (C) 2010 Wolfson Microelectronics PLC + * Copyright (C) 2010 Texas Instruments Inc. + * + * Support for the verb/device/modifier core logic and API, + * command line tool and file parser was kindly sponsored by + * Texas Instruments Inc. + * Support for multiple active modifiers and devices, + * transition sequences, multiple client access and user defined use + * cases was kindly sponsored by Wolfson Microelectronics PLC. + */ + +#ifndef __ALSA_USE_CASE_H +#define __ALSA_USE_CASE_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup Use Case Interface + * The ALSA Use Case manager interface. + * See \ref Usecase page for more details. + * \{ + */ + +/** + * ALSA Use Case Interface + * + * The use case manager works by configuring the sound card ALSA kcontrols to + * change the hardware digital and analog audio routing to match the requested + * device use case. The use case manager kcontrol configurations are stored in + * easy to modify text files. + * + * An audio use case can be defined by a verb and device parameter. The verb + * describes the use case action i.e. a phone call, listening to music, recording + * a conversation etc. The device describes the physical audio capture and playback + * hardware i.e. headphones, phone handset, bluetooth headset, etc. + * + * It's intended clients will mostly only need to set the use case verb and + * device for each system use case change (as the verb and device parameters + * cover most audio use cases). + * + * However there are times when a use case has to be modified at runtime. e.g. + * + * o Incoming phone call when the device is playing music + * o Recording sections of a phone call + * o Playing tones during a call. + * + * In order to allow asynchronous runtime use case adaptations, we have a third + * optional modifier parameter that can be used to further configure + * the use case during live audio runtime. + * + * This interface allows clients to :- + * + * o Query the supported use case verbs, devices and modifiers for the machine. + * o Set and Get use case verbs, devices and modifiers for the machine. + * o Get the ALSA PCM playback and capture device PCMs for use case verb and + * modifier. + * o Get the QoS parameter for each use case verb and modifier. + * o Get the ALSA master playback and capture volume/switch kcontrols + * for each use case. + */ + + +/* + * Use Case Verb. + * + * The use case verb is the main device audio action. e.g. the "HiFi" use + * case verb will configure the audio hardware for HiFi Music playback + * and capture. + */ +#define SND_USE_CASE_VERB_INACTIVE "Inactive" +#define SND_USE_CASE_VERB_HIFI "HiFi" +#define SND_USE_CASE_VERB_HIFI_LOW_POWER "HiFi Low Power" +#define SND_USE_CASE_VERB_VOICE "Voice" +#define SND_USE_CASE_VERB_VOICE_LOW_POWER "Voice Low Power" +#define SND_USE_CASE_VERB_VOICECALL "Voice Call" +#define SND_USE_CASE_VERB_IP_VOICECALL "Voice Call IP" +#define SND_USE_CASE_VERB_ANALOG_RADIO "FM Analog Radio" +#define SND_USE_CASE_VERB_DIGITAL_RADIO "FM Digital Radio" +/* add new verbs to end of list */ + + +/* + * Use Case Device. + * + * Physical system devices the render and capture audio. Devices can be OR'ed + * together to support audio on similtanious devices. + */ +#define SND_USE_CASE_DEV_NONE "None" +#define SND_USE_CASE_DEV_SPEAKER "Speaker" +#define SND_USE_CASE_DEV_LINE "Line" +#define SND_USE_CASE_DEV_HEADPHONES "Headphones" +#define SND_USE_CASE_DEV_HEADSET "Headset" +#define SND_USE_CASE_DEV_HANDSET "Handset" +#define SND_USE_CASE_DEV_BLUETOOTH "Bluetooth" +#define SND_USE_CASE_DEV_EARPIECE "Earpiece" +#define SND_USE_CASE_DEV_SPDIF "SPDIF" +#define SND_USE_CASE_DEV_HDMI "HDMI" +/* add new devices to end of list */ + + +/* + * Use Case Modifiers. + * + * The use case modifier allows runtime configuration changes to deal with + * asynchronous events. + * + * e.g. to record a voice call :- + * 1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call) + * 2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required. + * 3. Call snd_use_case_get_verb_capture_pcm() to get ALSA source PCM + * with captured voice pcm data. + * + * e.g. to play a ring tone when listenin to MP3 Music :- + * 1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback) + * 2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens. + * 3. Call snd_use_case_get_verb_playback_pcm() to get ALSA PCM sink for + * ringtone pcm data. + */ +#define SND_USE_CASE_MOD_CAPTURE_VOICE "Capture Voice" +#define SND_USE_CASE_MOD_CAPTURE_MUSIC "Capture Music" +#define SND_USE_CASE_MOD_PLAY_MUSIC "Play Music" +#define SND_USE_CASE_MOD_PLAY_VOICE "Play Voice" +#define SND_USE_CASE_MOD_PLAY_TONE "Play Tone" +#define SND_USE_CASE_MOD_ECHO_REF "Echo Reference" +/* add new modifiers to end of list */ + + +/** + * QoS - Quality of Service + * + * The interface allows clients to determine the audio QoS required for each + * use case verb and modifier. It's intended as an optional hint to the + * audio driver in order to lower power consumption. + * + */ +enum snd_use_case_qos { + SND_USE_CASE_QOS_UNKNOWN, + SND_USE_CASE_QOS_MUSIC, + SND_USE_CASE_QOS_VOICE, + SND_USE_CASE_QOS_TONES, +}; + +/* + * Use Case Control Aliases. + * + * Use cases often use different internal hardware paths to route digital and + * analog audio. This can mean different controls are used to change volumes + * depending on the particular use case. This interface allows clients to + * find out the hardware controls associated with each use case. + */ +enum snd_use_case_control_alias { + SND_USE_CASE_ALIAS_PLAYBACK_VOLUME = 0, + SND_USE_CASE_ALIAS_PLAYBACK_SWITCH, + SND_USE_CASE_ALIAS_CAPTURE_VOLUME, + SND_USE_CASE_ALIAS_CAPTURE_SWITCH, +}; + +/** use case container */ +typedef struct snd_use_case_mgr snd_use_case_mgr_t; + +/** + * \brief List supported use case verbs for given soundcard + * \param uc_mgr Use case manager + * \param verb Returned list of supported use case verbs + * \return Number of use case verbs if success, otherwise a negative error code + */ +int snd_use_case_get_verb_list(snd_use_case_mgr_t *uc_mgr, const char **verb[]); + +/** + * \brief List supported use case devices for given use case verb + * \param uc_mgr Use case manager + * \param verb Verb name. + * \param device Returned list of supported use case devices + * \return Number of use case devices if success, otherwise a negative error code + */ +int snd_use_case_get_device_list(snd_use_case_mgr_t *uc_mgr, + const char *verb, const char **device[]); + +/** + * \brief List supported use case verb modifiers for given verb + * \param uc_mgr use case manager + * \param verb verb id. + * \param mod returned list of supported use case modifier id and names + * \return number of use case modifiers if success, otherwise a negative error code + */ +int snd_use_case_get_mod_list(snd_use_case_mgr_t *uc_mgr, + const char *verb, const char **mod[]); + +/** + * \brief Get current use case verb for sound card + * \param uc_mgr Use case manager + * \return Verb if success, otherwise NULL + */ +const char *snd_use_case_get_verb(snd_use_case_mgr_t *uc_mgr); + +/** + * \brief Set new use case verb for sound card + * \param uc_mgr Use case manager + * \param verb Verb + * \return Zero if success, otherwise a negative error code + */ +int snd_use_case_set_verb(snd_use_case_mgr_t *uc_mgr, const char *verb); + +/** + * \brief Enable use case device for current use case verb + * \param uc_mgr Use case manager + * \param device Device + * \return Zero if success, otherwise a negative error code + */ +int snd_use_case_enable_device(snd_use_case_mgr_t *uc_mgr, const char *device); + +/** + * \brief Disable use case device for current use case verb + * \param uc_mgr Use case manager + * \param device Device + * \return Zero if success, otherwise a negative error code + */ +int snd_use_case_disable_device(snd_use_case_mgr_t *uc_mgr, const char *device); + +/** + * \brief Disable old_device and then enable new_device. + * If from_device is not enabled just return. + * Check transmit sequence firstly. + * \param uc_mgr Use case manager + * \param old the device to be closed + * \param new the device to be opened + * \return 0 = successful negative = error + */ +int snd_use_case_switch_device(snd_use_case_mgr_t *uc_mgr, + const char *old, const char *new); + + +/** + * \brief Enable use case modifier for current use case verb + * \param uc_mgr Use case manager + * \param modifier Modifier + * \return Zero if success, otherwise a negative error code + */ +int snd_use_case_enable_modifier(snd_use_case_mgr_t *uc_mgr, + const char *modifier); + +/** + * \brief Disable use case modifier for curent use case verb + * \param uc_mgr Use case manager + * \param modifier Modifier + * \return Zero if success, otherwise a negative error code + */ +int snd_use_case_disable_modifier(snd_use_case_mgr_t *uc_mgr, + const char *modifier); + +/** + * \brief Disable old_modifier and then enable new_modifier. + * If old_modifier is not enabled just return. + * Check transmit sequence firstly. + * \param uc_mgr Use case manager + * \param old the modifier to be closed + * \param new the modifier to be opened + * \return 0 = successful negative = error + */ +int snd_use_case_switch_modifier(snd_use_case_mgr_t *uc_mgr, + const char *old, const char *new); + +/** + * \brief Get device status for current use case verb + * \param uc_mgr Use case manager + * \param device_name The device we are interested in. + * \return - 1 = enabled, 0 = disabled, negative = error + */ +int snd_use_case_get_device_status(snd_use_case_mgr_t *uc_mgr, + const char *device_name); + +/** + * \brief Get modifier status for current use case verb + * \param uc_mgr Use case manager + * \param device_name The device we are interested in. + * \return - 1 = enabled, 0 = disabled, negative = error + */ +int snd_use_case_get_modifier_status(snd_use_case_mgr_t *uc_mgr, + const char *modifier_name); + +/** + * \brief Get the current use case verb QoS + * \param uc_mgr Use case manager + * \return QoS level + */ +enum snd_use_case_qos snd_use_case_get_verb_qos(snd_use_case_mgr_t *uc_mgr); + +/** + * \brief Get use case modifier QoS + * \param uc_mgr use case manager + * \param modifier Modifier + * \return QoS level + */ +enum snd_use_case_qos snd_use_case_get_mod_qos(snd_use_case_mgr_t *uc_mgr, + const char *modifier); + +/** + * \brief Get the current use case verb playback PCM sink ID. + * \param uc_mgr use case manager + * \return PCM number if success, otherwise negative + */ +int snd_use_case_get_verb_playback_pcm(snd_use_case_mgr_t *uc_mgr); + +/** + * \brief Get the current use case verb capture PCM source ID + * \param uc_mgr Use case manager + * \return PCM number if success, otherwise negative + */ +int snd_use_case_get_verb_capture_pcm(snd_use_case_mgr_t *uc_mgr); + +/** + * \brief Get use case modifier playback PCM sink ID + * \param uc_mgr Use case manager + * \param modifier Modifier + * \return PCM number if success, otherwise negative + */ +int snd_use_case_get_mod_playback_pcm(snd_use_case_mgr_t *uc_mgr, + const char *modifier); + +/** + * \brief Get use case modifier capture PCM source ID + * \param uc_mgr Use case manager + * \param modifier Modifier + * \return PCM number if success, otherwise negative + */ +int snd_use_case_get_mod_capture_pcm(snd_use_case_mgr_t *uc_mgr, + const char *modifier); + +/** + * \brief Get ALSA volume/mute control names depending on use case device. + * \param uc_mgr Use case manager + * \param type The control type we are looking for + * \param device The device we are interested in. + * \return name if success, otherwise NULL + * + * Get the control name for common volume and mute controls that are aliased + * in the current use case verb. + */ +const char *snd_use_case_get_device_ctl_elem_id(snd_use_case_mgr_t *uc_mgr, + enum snd_use_case_control_alias type, const char *device); + +/** + * \brief Get ALSA volume/mute control names depending on use case modifier. + * \param uc_mgr Use case manager + * \param type The control type we are looking for + * \param modifier The modifier we are interested in. + * \return name if success, otherwise NULL + * + * Get the control name for common volume and mute controls that are aliased + * in the current use case modifier. + */ +const char *snd_use_case_get_modifier_ctl_elem_id(snd_use_case_mgr_t *uc_mgr, + enum snd_use_case_control_alias type, const char *modifier); + +/** + * \brief Open and initialise use case core for sound card + * \param card_name Sound card name. + * \return Use case handle if success, otherwise NULL + */ +snd_use_case_mgr_t *snd_use_case_mgr_open(const char *card_name); + + +/** + * \brief Reload and re-parse use case configuration files for sound card. + * \param uc_mgr Use case manager + * \return zero if success, otherwise a negative error code + */ +int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr); + +/** + * \brief Close use case manager + * \param uc_mgr Use case manager + * \return zero if success, otherwise a negative error code + */ +int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr); + +/** + * \brief Reset use case manager verb, device, modifier to deafult settings. + * \param uc_mgr Use case manager + * \return zero if success, otherwise a negative error code + */ +int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr); + +/** + * \brief Dump current sound card use case control settings + * \param card_name Sound card name + * \return zero if success, otherwise a negative error code + */ +int snd_use_case_dump(const char *card_name); + +/** + * \} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* __ALSA_USE_CASE_H */ |