ucm: Recode header to be more universal
[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 Obtain a list of entries
181  * \param uc_mgr Use case manager
182  * \param identifier (may be NULL)
183  * \param list Returned list
184  * \return Number of list entries if success, otherwise a negative error code
185  *
186  * Defined identifiers:
187  *   NULL               - get card list
188  *                        (in pair verb+comment)
189  *   _verbs             - get verb list
190  *                        (in pair verb+comment)
191  *   _devices[/<verb>]  - get list of supported devices
192  *                        (in pair device+comment)
193  *   _modifiers[/<verb>]- get list of supported modifiers
194  *                        (in pair modifier+comment)
195  *   _tqs[/<verb>]      - get list of QoS identifiers
196  *   _enadevs           - get list of enabled devices
197  *   _enamods           - get list of enabled modifiers
198  *
199  */
200 int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
201                           const char *identifier,
202                           const char **list[]);
203
204
205 /**
206  * \brief Get current - string
207  * \param uc_mgr Use case manager
208  * \param identifier 
209  * \param value Value pointer
210  * \return Zero if success, otherwise a negative error code
211  *
212  * Note: String is dynamically allocated, use free() to
213  * deallocate this string.
214  *
215  * Known identifiers:
216  *   NULL                               - return current card
217  *   _verb                              - return current verb
218  *   _pcm_/_pdevice[/<modifier>]        - full PCM playback device name
219  *   _pcm_/_cdevice[/<modifier>]        - full PCM capture device name
220  *   _ctl_/_pctl_[/<modifier>]          - playback control device name
221  *   _ctl_/_pctlvol[/<modifier>]        - playback control volume ID string
222  *   _ctl_/_pctlsw[/<modifier>]         - playback control switch ID string
223  *   _ctl_/_cctl[/<modifier>]           - capture control device name
224  *   _ctl_/_cctlvol[/<modifier>]        - capture control volume ID string
225  *   _ctl_/_cctlsw[/<modifier>]         - capture control switch ID string
226  *   _mixer_/_pname[/<modifier>]        - name of playback mixer
227  *   _mixer_/_pid[/<modifier>]          - mixer playback ID
228  *   _mixer_/_cname[/<modifier>]        - name of capture mixer
229  *   _mixer_/_cid[/<modifier>]          - mixer capture ID
230  */
231 int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
232                      const char *identifier,
233                      const char **value);
234
235 /**
236  * \brief Get current - integer
237  * \param uc_mgr Use case manager
238  * \param identifier 
239  * \return Value if success, otherwise a negative error code
240  *
241  * Known identifiers:
242  *   _devstatus/<device>        - return status for given device
243  *   _modstatus/<modifier>      - return status for given modifier
244  *   _tq                        - return current Tone Quality
245  *   _tq/<modifier>             - return Tone Quality for given modifier
246  */
247 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
248                       const char *identifier);
249
250 /**
251  * \brief Set new
252  * \param uc_mgr Use case manager
253  * \param identifier
254  * \param value Value
255  * \return Zero if success, otherwise a negative error code
256  *
257  * Known identifiers:
258  *   _verb              - set current verb = value
259  *   _enadev            - enable given device = value
260  *   _disdev            - disable given device = value
261  *   _swdev/<old_device> - new_device = value
262  *                      - disable old_device and then enable new_device
263  *                      - if old_device is not enabled just return
264  *                      - check transmit sequence firstly
265  *   _enamod            - enable given modifier = value
266  *   _dismod            - disable given modifier = value
267  *   _swmod/<old_modifier> - new_modifier = value
268  *                      - disable old_modifier and then enable new_modifier
269  *                      - if old_modifier is not enabled just return
270  *                      - check transmit sequence firstly
271  */
272 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
273                      const char *identifier,
274                      const char *value);
275
276 /**
277  * \brief Open and initialise use case core for sound card
278  * \param card_name Sound card name.
279  * \return Use case handle if success, otherwise NULL
280  */
281 snd_use_case_mgr_t *snd_use_case_mgr_open(const char *card_name);
282
283
284 /**
285  * \brief Reload and re-parse use case configuration files for sound card.
286  * \param uc_mgr Use case manager
287  * \return zero if success, otherwise a negative error code
288  */
289 int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
290
291 /**
292  * \brief Close use case manager
293  * \param uc_mgr Use case manager
294  * \return zero if success, otherwise a negative error code
295  */
296 int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
297
298 /**
299  * \brief Reset use case manager verb, device, modifier to deafult settings.
300  * \param uc_mgr Use case manager
301  * \return zero if success, otherwise a negative error code
302  */
303 int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
304
305 /**
306  * \brief Dump current sound card use case control settings
307  * \param card_name Sound card name
308  * \return zero if success, otherwise a negative error code
309  */
310 int snd_use_case_dump(const char *card_name);
311
312 /**
313  *  \}
314  */
315
316 #ifdef __cplusplus
317 }
318 #endif
319
320 #endif /* __ALSA_USE_CASE_H */