mixer: Add get_card_name() API
[android-sdk/platform-external-tinyalsa.git] / include / tinyalsa / asoundlib.h
1 /* asoundlib.h
2 **
3 ** Copyright 2011, The Android Open Source Project
4 **
5 ** Redistribution and use in source and binary forms, with or without
6 ** modification, are permitted provided that the following conditions are met:
7 **     * Redistributions of source code must retain the above copyright
8 **       notice, this list of conditions and the following disclaimer.
9 **     * Redistributions in binary form must reproduce the above copyright
10 **       notice, this list of conditions and the following disclaimer in the
11 **       documentation and/or other materials provided with the distribution.
12 **     * Neither the name of The Android Open Source Project nor the names of
13 **       its contributors may be used to endorse or promote products derived
14 **       from this software without specific prior written permission.
15 **
16 ** THIS SOFTWARE IS PROVIDED BY The Android Open Source Project ``AS IS'' AND
17 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 ** ARE DISCLAIMED. IN NO EVENT SHALL The Android Open Source Project BE LIABLE
20 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22 ** SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23 ** CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
26 ** DAMAGE.
27 */
29 #ifndef ASOUNDLIB_H
30 #define ASOUNDLIB_H
32 #include <sys/time.h>
33 #include <stddef.h>
35 #if defined(__cplusplus)
36 extern "C" {
37 #endif
39 /*
40  * PCM API
41  */
43 struct pcm;
45 #define PCM_OUT        0x00000000
46 #define PCM_IN         0x10000000
47 #define PCM_MMAP       0x00000001
48 #define PCM_NOIRQ      0x00000002
49 #define PCM_NORESTART  0x00000004 /* PCM_NORESTART - when set, calls to
50                                    * pcm_write for a playback stream will not
51                                    * attempt to restart the stream in the case
52                                    * of an underflow, but will return -EPIPE
53                                    * instead.  After the first -EPIPE error, the
54                                    * stream is considered to be stopped, and a
55                                    * second call to pcm_write will attempt to
56                                    * restart the stream.
57                                    */
58 #define PCM_MONOTONIC  0x00000008 /* see pcm_get_htimestamp */
60 /* PCM runtime states */
61 #define PCM_STATE_OPEN          0
62 #define PCM_STATE_SETUP         1
63 #define PCM_STATE_PREPARED      2
64 #define PCM_STATE_RUNNING               3
65 #define PCM_STATE_XRUN          4
66 #define PCM_STATE_DRAINING      5
67 #define PCM_STATE_PAUSED                6
68 #define PCM_STATE_SUSPENDED     7
69 #define PCM_STATE_DISCONNECTED  8
71 /* Bit formats */
72 enum pcm_format {
73     PCM_FORMAT_INVALID = -1,
74     PCM_FORMAT_S16_LE = 0,  /* 16-bit signed */
75     PCM_FORMAT_S32_LE,      /* 32-bit signed */
76     PCM_FORMAT_S8,          /* 8-bit signed */
77     PCM_FORMAT_S24_LE,      /* 24-bits in 4-bytes */
78     PCM_FORMAT_S24_3LE,     /* 24-bits in 3-bytes */
80     PCM_FORMAT_MAX,
81 };
83 /* Bitmask has 256 bits (32 bytes) in asound.h */
84 struct pcm_mask {
85     unsigned int bits[32 / sizeof(unsigned int)];
86 };
88 /* Configuration for a stream */
89 struct pcm_config {
90     unsigned int channels;
91     unsigned int rate;
92     unsigned int period_size;
93     unsigned int period_count;
94     enum pcm_format format;
96     /* Values to use for the ALSA start, stop and silence thresholds.  Setting
97      * any one of these values to 0 will cause the default tinyalsa values to be
98      * used instead.  Tinyalsa defaults are as follows.
99      *
100      * start_threshold   : period_count * period_size
101      * stop_threshold    : period_count * period_size
102      * silence_threshold : 0
103      */
104     unsigned int start_threshold;
105     unsigned int stop_threshold;
106     unsigned int silence_threshold;
108     /* Minimum number of frames available before pcm_mmap_write() will actually
109      * write into the kernel buffer. Only used if the stream is opened in mmap mode
110      * (pcm_open() called with PCM_MMAP flag set).   Use 0 for default.
111      */
112     int avail_min;
113 };
115 /* PCM parameters */
116 enum pcm_param
118     /* mask parameters */
119     PCM_PARAM_ACCESS,
120     PCM_PARAM_FORMAT,
121     PCM_PARAM_SUBFORMAT,
122     /* interval parameters */
123     PCM_PARAM_SAMPLE_BITS,
124     PCM_PARAM_FRAME_BITS,
125     PCM_PARAM_CHANNELS,
126     PCM_PARAM_RATE,
127     PCM_PARAM_PERIOD_TIME,
128     PCM_PARAM_PERIOD_SIZE,
129     PCM_PARAM_PERIOD_BYTES,
130     PCM_PARAM_PERIODS,
131     PCM_PARAM_BUFFER_TIME,
132     PCM_PARAM_BUFFER_SIZE,
133     PCM_PARAM_BUFFER_BYTES,
134     PCM_PARAM_TICK_TIME,
135 };
137 /* Mixer control types */
138 enum mixer_ctl_type {
139     MIXER_CTL_TYPE_BOOL,
140     MIXER_CTL_TYPE_INT,
141     MIXER_CTL_TYPE_ENUM,
142     MIXER_CTL_TYPE_BYTE,
143     MIXER_CTL_TYPE_IEC958,
144     MIXER_CTL_TYPE_INT64,
145     MIXER_CTL_TYPE_UNKNOWN,
147     MIXER_CTL_TYPE_MAX,
148 };
150 #ifdef OMAP_ENHANCEMENT
151 #define MAX_CARD_COUNT 32
153 int mixer_get_card_name(int card, char *str, size_t strlen);
154 #endif
156 /* Open and close a stream */
157 struct pcm *pcm_open(unsigned int card, unsigned int device,
158                      unsigned int flags, struct pcm_config *config);
159 int pcm_close(struct pcm *pcm);
160 int pcm_is_ready(struct pcm *pcm);
162 /* Obtain the parameters for a PCM */
163 struct pcm_params *pcm_params_get(unsigned int card, unsigned int device,
164                                   unsigned int flags);
165 void pcm_params_free(struct pcm_params *pcm_params);
167 struct pcm_mask *pcm_params_get_mask(struct pcm_params *pcm_params,
168                                      enum pcm_param param);
169 unsigned int pcm_params_get_min(struct pcm_params *pcm_params,
170                                 enum pcm_param param);
171 void pcm_params_set_min(struct pcm_params *pcm_params,
172                                 enum pcm_param param, unsigned int val);
173 unsigned int pcm_params_get_max(struct pcm_params *pcm_params,
174                                 enum pcm_param param);
175 void pcm_params_set_max(struct pcm_params *pcm_params,
176                                 enum pcm_param param, unsigned int val);
178 /* Converts the pcm parameters to a human readable string.
179  * The string parameter is a caller allocated buffer of size bytes,
180  * which is then filled up to size - 1 and null terminated,
181  * if size is greater than zero.
182  * The return value is the number of bytes copied to string
183  * (not including null termination) if less than size; otherwise,
184  * the number of bytes required for the buffer.
185  */
186 int pcm_params_to_string(struct pcm_params *params, char *string, unsigned int size);
188 /* Returns 1 if the pcm_format is present (format bit set) in
189  * the pcm_params structure; 0 otherwise, or upon unrecognized format.
190  */
191 int pcm_params_format_test(struct pcm_params *params, enum pcm_format format);
193 /* Set and get config */
194 int pcm_get_config(struct pcm *pcm, struct pcm_config *config);
195 int pcm_set_config(struct pcm *pcm, struct pcm_config *config);
197 /* Returns a human readable reason for the last error */
198 const char *pcm_get_error(struct pcm *pcm);
200 /* Returns the sample size in bits for a PCM format.
201  * As with ALSA formats, this is the storage size for the format, whereas the
202  * format represents the number of significant bits. For example,
203  * PCM_FORMAT_S24_LE uses 32 bits of storage.
204  */
205 unsigned int pcm_format_to_bits(enum pcm_format format);
207 /* Returns the buffer size (int frames) that should be used for pcm_write. */
208 unsigned int pcm_get_buffer_size(struct pcm *pcm);
209 unsigned int pcm_frames_to_bytes(struct pcm *pcm, unsigned int frames);
210 unsigned int pcm_bytes_to_frames(struct pcm *pcm, unsigned int bytes);
212 /* Returns the pcm latency in ms */
213 unsigned int pcm_get_latency(struct pcm *pcm);
215 /* Returns available frames in pcm buffer and corresponding time stamp.
216  * The clock is CLOCK_MONOTONIC if flag PCM_MONOTONIC was specified in pcm_open,
217  * otherwise the clock is CLOCK_REALTIME.
218  * For an input stream, frames available are frames ready for the
219  * application to read.
220  * For an output stream, frames available are the number of empty frames available
221  * for the application to write.
222  */
223 int pcm_get_htimestamp(struct pcm *pcm, unsigned int *avail,
224                        struct timespec *tstamp);
226 /* Write data to the fifo.
227  * Will start playback on the first write or on a write that
228  * occurs after a fifo underrun.
229  */
230 int pcm_write(struct pcm *pcm, const void *data, unsigned int count);
231 int pcm_read(struct pcm *pcm, void *data, unsigned int count);
233 /*
234  * mmap() support.
235  */
236 int pcm_mmap_write(struct pcm *pcm, const void *data, unsigned int count);
237 int pcm_mmap_read(struct pcm *pcm, void *data, unsigned int count);
238 int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset,
239                    unsigned int *frames);
240 int pcm_mmap_commit(struct pcm *pcm, unsigned int offset, unsigned int frames);
242 /* Prepare the PCM substream to be triggerable */
243 int pcm_prepare(struct pcm *pcm);
244 /* Start and stop a PCM channel that doesn't transfer data */
245 int pcm_start(struct pcm *pcm);
246 int pcm_stop(struct pcm *pcm);
248 /* Interrupt driven API */
249 int pcm_wait(struct pcm *pcm, int timeout);
251 /* Change avail_min after the stream has been opened with no need to stop the stream.
252  * Only accepted if opened with PCM_MMAP and PCM_NOIRQ flags
253  */
254 int pcm_set_avail_min(struct pcm *pcm, int avail_min);
256 /*
257  * MIXER API
258  */
260 struct mixer;
261 struct mixer_ctl;
263 /* Open and close a mixer */
264 struct mixer *mixer_open(unsigned int card);
265 void mixer_close(struct mixer *mixer);
267 /* Get info about a mixer */
268 const char *mixer_get_name(struct mixer *mixer);
270 /* Obtain mixer controls */
271 unsigned int mixer_get_num_ctls(struct mixer *mixer);
272 struct mixer_ctl *mixer_get_ctl(struct mixer *mixer, unsigned int id);
273 struct mixer_ctl *mixer_get_ctl_by_name(struct mixer *mixer, const char *name);
275 /* Get info about mixer controls */
276 const char *mixer_ctl_get_name(struct mixer_ctl *ctl);
277 enum mixer_ctl_type mixer_ctl_get_type(struct mixer_ctl *ctl);
278 const char *mixer_ctl_get_type_string(struct mixer_ctl *ctl);
279 unsigned int mixer_ctl_get_num_values(struct mixer_ctl *ctl);
280 unsigned int mixer_ctl_get_num_enums(struct mixer_ctl *ctl);
281 const char *mixer_ctl_get_enum_string(struct mixer_ctl *ctl,
282                                       unsigned int enum_id);
284 /* Some sound cards update their controls due to external events,
285  * such as HDMI EDID byte data changing when an HDMI cable is
286  * connected. This API allows the count of elements to be updated.
287  */
288 void mixer_ctl_update(struct mixer_ctl *ctl);
290 /* Set and get mixer controls */
291 int mixer_ctl_get_percent(struct mixer_ctl *ctl, unsigned int id);
292 int mixer_ctl_set_percent(struct mixer_ctl *ctl, unsigned int id, int percent);
294 int mixer_ctl_get_value(struct mixer_ctl *ctl, unsigned int id);
295 int mixer_ctl_get_array(struct mixer_ctl *ctl, void *array, size_t count);
296 int mixer_ctl_set_value(struct mixer_ctl *ctl, unsigned int id, int value);
297 int mixer_ctl_set_array(struct mixer_ctl *ctl, const void *array, size_t count);
298 int mixer_ctl_set_enum_by_string(struct mixer_ctl *ctl, const char *string);
300 /* Determe range of integer mixer controls */
301 int mixer_ctl_get_range_min(struct mixer_ctl *ctl);
302 int mixer_ctl_get_range_max(struct mixer_ctl *ctl);
304 #if defined(__cplusplus)
305 }  /* extern "C" */
306 #endif
308 #endif