ucm: Introduce "Value {}" section, more implementation work
[alsa-lib.git] / 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 and
84  *     modifier.
85  *  o Get the QoS parameter for each use case verb and modifier.
86  *  o 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"
99 #define SND_USE_CASE_VERB_HIFI                  "HiFi"
100 #define SND_USE_CASE_VERB_HIFI_LOW_POWER        "HiFi Low Power"
101 #define SND_USE_CASE_VERB_VOICE                 "Voice"
102 #define SND_USE_CASE_VERB_VOICE_LOW_POWER       "Voice Low Power"
103 #define SND_USE_CASE_VERB_VOICECALL             "Voice Call"
104 #define SND_USE_CASE_VERB_IP_VOICECALL          "Voice Call IP"
105 #define SND_USE_CASE_VERB_ANALOG_RADIO          "FM Analog Radio"
106 #define SND_USE_CASE_VERB_DIGITAL_RADIO         "FM Digital Radio"
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 similtanious devices.
115  */
116 #define SND_USE_CASE_DEV_NONE           "None"
117 #define SND_USE_CASE_DEV_SPEAKER        "Speaker"
118 #define SND_USE_CASE_DEV_LINE           "Line"
119 #define SND_USE_CASE_DEV_HEADPHONES     "Headphones"
120 #define SND_USE_CASE_DEV_HEADSET        "Headset"
121 #define SND_USE_CASE_DEV_HANDSET        "Handset"
122 #define SND_USE_CASE_DEV_BLUETOOTH      "Bluetooth"
123 #define SND_USE_CASE_DEV_EARPIECE       "Earpiece"
124 #define SND_USE_CASE_DEV_SPDIF          "SPDIF"
125 #define SND_USE_CASE_DEV_HDMI           "HDMI"
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("_pcm_/_cdevice") 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("_pcm_/_pdevice") to get ALSA PCM sink name for
145  *     ringtone pcm data.
146  */
147 #define SND_USE_CASE_MOD_CAPTURE_VOICE          "Capture Voice"
148 #define SND_USE_CASE_MOD_CAPTURE_MUSIC          "Capture Music"
149 #define SND_USE_CASE_MOD_PLAY_MUSIC             "Play Music"
150 #define SND_USE_CASE_MOD_PLAY_VOICE             "Play Voice"
151 #define SND_USE_CASE_MOD_PLAY_TONE              "Play Tone"
152 #define SND_USE_CASE_MOD_ECHO_REF               "Echo Reference"
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"
165 #define SND_USE_CASE_TQ_VOICE           "Voice"
166 #define SND_USE_CASE_TQ_TONES           "Tones"
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  */
208 int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
209                           const char *identifier,
210                           const char **list[]);
211
212
213 /**
214  * \brief Get current - string
215  * \param uc_mgr Use case manager
216  * \param identifier 
217  * \param value Value pointer
218  * \return Zero if success, otherwise a negative error code
219  *
220  * Note: String is dynamically allocated, use free() to
221  * deallocate this string.
222  *
223  * Known identifiers:
224  *   NULL                               - return current card
225  *   _verb                              - return current verb
226  *   TQ[/<modifier>]                    - Tone Quality [for given modifier]
227  *   PlaybackPCM[/<modifier>]           - full PCM playback device name
228  *   CapturePCM[/<modifier>]            - full PCM capture device name
229  *   PlaybackCTL[/<modifier>]           - playback control device name
230  *   PlaybackVolume[/<modifier>]        - playback control volume ID string
231  *   PlaybackSwitch[/<modifier>]        - playback control switch ID string
232  *   CaptureCTL[/<modifier>]            - capture control device name
233  *   CaptureVolume[/<modifier>]         - capture control volume ID string
234  *   CaptureSwitch[/<modifier>]         - capture control switch ID string
235  *   PlaybackMixer[/<modifier>]         - name of playback mixer
236  *   PlaybackMixerID[/<modifier>]       - mixer playback ID
237  *   CaptureMixer[/<modifier>]          - name of capture mixer
238  *   CaptureMixerID[/<modifier>]        - mixer capture ID
239  */
240 int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
241                      const char *identifier,
242                      const char **value);
243
244 /**
245  * \brief Get current - integer
246  * \param uc_mgr Use case manager
247  * \param identifier 
248  * \return Value if success, otherwise a negative error code
249  *
250  * Known identifiers:
251  *   _devstatus/<device>        - return status for given device
252  *   _modstatus/<modifier>      - return status for given modifier
253  */
254 long snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
255                        const char *identifier);
256
257 /**
258  * \brief Set new
259  * \param uc_mgr Use case manager
260  * \param identifier
261  * \param value Value
262  * \return Zero if success, otherwise a negative error code
263  *
264  * Known identifiers:
265  *   _verb              - set current verb = value
266  *   _enadev            - enable given device = value
267  *   _disdev            - disable given device = value
268  *   _swdev/<old_device> - new_device = value
269  *                      - disable old_device and then enable new_device
270  *                      - if old_device is not enabled just return
271  *                      - check transmit sequence firstly
272  *   _enamod            - enable given modifier = value
273  *   _dismod            - disable given modifier = value
274  *   _swmod/<old_modifier> - new_modifier = value
275  *                      - disable old_modifier and then enable new_modifier
276  *                      - if old_modifier is not enabled just return
277  *                      - check transmit sequence firstly
278  */
279 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
280                      const char *identifier,
281                      const char *value);
282
283 /**
284  * \brief Open and initialise use case core for sound card
285  * \param uc_mgr Returned use case manager pointer
286  * \param card_name Sound card name.
287  * \return zero if success, otherwise a negative error code
288  */
289 int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr, const char *card_name);
290
291
292 /**
293  * \brief Reload and re-parse use case configuration files for sound card.
294  * \param uc_mgr Use case manager
295  * \return zero if success, otherwise a negative error code
296  */
297 int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
298
299 /**
300  * \brief Close use case manager
301  * \param uc_mgr Use case manager
302  * \return zero if success, otherwise a negative error code
303  */
304 int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
305
306 /**
307  * \brief Reset use case manager verb, device, modifier to deafult settings.
308  * \param uc_mgr Use case manager
309  * \return zero if success, otherwise a negative error code
310  */
311 int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
312
313 /**
314  *  \}
315  */
316
317 #ifdef __cplusplus
318 }
319 #endif
320
321 #endif /* __ALSA_USE_CASE_H */