You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
381 lines
13 KiB
381 lines
13 KiB
/** |
|
* \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, |
|
* use case device and modifier. |
|
* o Get the TQ parameter for each use case verb, use case device 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 simultaneous 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("CapturePCM") to get ALSA source PCM name |
|
* 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("PlaybackPCM") to get ALSA PCM sink name 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 */ |
|
|
|
|
|
/** |
|
* TQ - Tone Quality |
|
* |
|
* The interface allows clients to determine the audio TQ 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. |
|
* |
|
*/ |
|
#define SND_USE_CASE_TQ_MUSIC "Music" |
|
#define SND_USE_CASE_TQ_VOICE "Voice" |
|
#define SND_USE_CASE_TQ_TONES "Tones" |
|
|
|
/** use case container */ |
|
typedef struct snd_use_case_mgr snd_use_case_mgr_t; |
|
|
|
/** |
|
* \brief Create an identifier |
|
* \param fmt Format (sprintf like) |
|
* \param ... Optional arguments for sprintf like format |
|
* \return Allocated string identifier or NULL on error |
|
*/ |
|
char *snd_use_case_identifier(const char *fmt, ...); |
|
|
|
/** |
|
* \brief Free a string list |
|
* \param list The string list to free |
|
* \param items Count of strings |
|
* \return Zero if success, otherwise a negative error code |
|
*/ |
|
int snd_use_case_free_list(const char *list[], int items); |
|
|
|
/** |
|
* \brief Obtain a list of entries |
|
* \param uc_mgr Use case manager (may be NULL - card list) |
|
* \param identifier (may be NULL - card list) |
|
* \param list Returned allocated list |
|
* \return Number of list entries if success, otherwise a negative error code |
|
* |
|
* Defined identifiers: |
|
* NULL - get card list |
|
* (in pair cardname+comment) |
|
* _verbs - get verb list |
|
* (in pair verb+comment) |
|
* _devices[/<verb>] - get list of supported devices |
|
* (in pair device+comment) |
|
* _modifiers[/<verb>]- get list of supported modifiers |
|
* (in pair modifier+comment) |
|
* TQ[/<verb>] - get list of TQ identifiers |
|
* _enadevs - get list of enabled devices |
|
* _enamods - get list of enabled modifiers |
|
* |
|
* _supporteddevs/<modifier>|<device>[/<verb>] - list of supported devices |
|
* _conflictingdevs/<modifier>|<device>[/<verb>] - list of conflicting devices |
|
* Note that at most one of the supported/conflicting devs lists has |
|
* any entries, and when neither is present, all devices are supported. |
|
* |
|
*/ |
|
int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr, |
|
const char *identifier, |
|
const char **list[]); |
|
|
|
|
|
/** |
|
* \brief Get current - string |
|
* \param uc_mgr Use case manager |
|
* \param identifier |
|
* \param value Value pointer |
|
* \return Zero if success, otherwise a negative error code |
|
* |
|
* Note: String is dynamically allocated, use free() to |
|
* deallocate this string. |
|
* |
|
* Known identifiers: |
|
* NULL - return current card |
|
* _verb - return current verb |
|
* |
|
* [=]<NAME>[/[<modifier>|</device>][/<verb>]] |
|
* - value identifier <NAME> |
|
* - Search starts at given modifier or device if any, |
|
* else at a verb |
|
* - Search starts at given verb if any, |
|
* else current verb |
|
* - Searches modifier/device, then verb, then defaults |
|
* - Specify a leading "=" to search only the exact |
|
* device/modifier/verb specified, and not search |
|
* through each object in turn. |
|
* - Examples: |
|
* "PlaybackPCM/Play Music" |
|
* "CapturePCM/SPDIF" |
|
* From ValueDefaults only: |
|
* "=Variable" |
|
* From current active verb: |
|
* "=Variable//" |
|
* From verb "Verb": |
|
* "=Variable//Verb" |
|
* From "Modifier" in current active verb: |
|
* "=Variable/Modifier/" |
|
* From "Modifier" in "Verb": |
|
* "=Variable/Modifier/Verb" |
|
* |
|
* Recommended names for values: |
|
* TQ - Tone Quality |
|
* PlaybackPCM - full PCM playback device name |
|
* CapturePCM - full PCM capture device name |
|
* PlaybackCTL - playback control device name |
|
* PlaybackVolume - playback control volume ID string |
|
* PlaybackSwitch - playback control switch ID string |
|
* CaptureCTL - capture control device name |
|
* CaptureVolume - capture control volume ID string |
|
* CaptureSwitch - capture control switch ID string |
|
* PlaybackMixer - name of playback mixer |
|
* PlaybackMixerID - mixer playback ID |
|
* CaptureMixer - name of capture mixer |
|
* CaptureMixerID - mixer capture ID |
|
*/ |
|
int snd_use_case_get(snd_use_case_mgr_t *uc_mgr, |
|
const char *identifier, |
|
const char **value); |
|
|
|
/** |
|
* \brief Get current - integer |
|
* \param uc_mgr Use case manager |
|
* \param identifier |
|
* \param value result |
|
* \return Zero if success, otherwise a negative error code |
|
* |
|
* Known identifiers: |
|
* _devstatus/<device> - return status for given device |
|
* _modstatus/<modifier> - return status for given modifier |
|
*/ |
|
int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr, |
|
const char *identifier, |
|
long *value); |
|
|
|
/** |
|
* \brief Set new |
|
* \param uc_mgr Use case manager |
|
* \param identifier |
|
* \param value Value |
|
* \return Zero if success, otherwise a negative error code |
|
* |
|
* Known identifiers: |
|
* _verb - set current verb = value |
|
* _enadev - enable given device = value |
|
* _disdev - disable given device = value |
|
* _swdev/<old_device> - new_device = value |
|
* - disable old_device and then enable new_device |
|
* - if old_device is not enabled just return |
|
* - check transmit sequence firstly |
|
* _enamod - enable given modifier = value |
|
* _dismod - disable given modifier = value |
|
* _swmod/<old_modifier> - new_modifier = value |
|
* - disable old_modifier and then enable new_modifier |
|
* - if old_modifier is not enabled just return |
|
* - check transmit sequence firstly |
|
*/ |
|
int snd_use_case_set(snd_use_case_mgr_t *uc_mgr, |
|
const char *identifier, |
|
const char *value); |
|
|
|
/** |
|
* \brief Open and initialise use case core for sound card |
|
* \param uc_mgr Returned use case manager pointer |
|
* \param card_name Sound card name. |
|
* \return zero if success, otherwise a negative error code |
|
*/ |
|
int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr, 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); |
|
|
|
/* |
|
* helper functions |
|
*/ |
|
|
|
/** |
|
* \brief Obtain a list of cards |
|
* \param list Returned allocated list |
|
* \return Number of list entries if success, otherwise a negative error code |
|
*/ |
|
static inline int snd_use_case_card_list(const char **list[]) |
|
{ |
|
return snd_use_case_get_list(NULL, NULL, list); |
|
} |
|
|
|
/** |
|
* \brief Obtain a list of verbs |
|
* \param uc_mgr Use case manager |
|
* \param list Returned list of verbs |
|
* \return Number of list entries if success, otherwise a negative error code |
|
*/ |
|
static inline int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr, |
|
const char **list[]) |
|
{ |
|
return snd_use_case_get_list(uc_mgr, "_verbs", list); |
|
} |
|
|
|
/** |
|
* \} |
|
*/ |
|
|
|
#ifdef __cplusplus |
|
} |
|
#endif |
|
|
|
#endif /* __ALSA_USE_CASE_H */
|
|
|