asoundlib.h revision 7e8a656722b3b19d499ad89c9c1e46b8be3da896 
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*/
28
29#ifndef ASOUNDLIB_H
30#define ASOUNDLIB_H
31
32#include <sys/time.h>
33#include <stddef.h>
34
35#if defined(__cplusplus)
36extern "C" {
37#endif
38
39/*
40 * PCM API
41 */
42
43struct pcm;
44
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
59/* PCM runtime states */
60#define	PCM_STATE_OPEN		0
61#define	PCM_STATE_SETUP		1
62#define	PCM_STATE_PREPARED	2
63#define	PCM_STATE_RUNNING		3
64#define	PCM_STATE_XRUN		4
65#define	PCM_STATE_DRAINING	5
66#define	PCM_STATE_PAUSED		6
67#define	PCM_STATE_SUSPENDED	7
68#define	PCM_STATE_DISCONNECTED	8
69
70/* Bit formats */
71enum pcm_format {
72    PCM_FORMAT_S16_LE = 0,
73    PCM_FORMAT_S32_LE,
74    PCM_FORMAT_S8,
75    PCM_FORMAT_S24_LE,
76
77    PCM_FORMAT_MAX,
78};
79
80/* Configuration for a stream */
81struct pcm_config {
82    unsigned int channels;
83    unsigned int rate;
84    unsigned int period_size;
85    unsigned int period_count;
86    enum pcm_format format;
87
88    /* Values to use for the ALSA start, stop and silence thresholds.  Setting
89     * any one of these values to 0 will cause the default tinyalsa values to be
90     * used instead.  Tinyalsa defaults are as follows.
91     *
92     * start_threshold   : period_count * period_size
93     * stop_threshold    : period_count * period_size
94     * silence_threshold : 0
95     */
96    unsigned int start_threshold;
97    unsigned int stop_threshold;
98    unsigned int silence_threshold;
99
100    /* Minimum number of frames available before pcm_mmap_write() will actually
101     * write into the kernel buffer. Only used if the stream is opened in mmap mode
102     * (pcm_open() called with PCM_MMAP flag set).   Use 0 for default.
103     */
104    int avail_min;
105};
106
107/* PCM parameters */
108enum pcm_param
109{
110    PCM_PARAM_SAMPLE_BITS,
111    PCM_PARAM_FRAME_BITS,
112    PCM_PARAM_CHANNELS,
113    PCM_PARAM_RATE,
114    PCM_PARAM_PERIOD_TIME,
115    PCM_PARAM_PERIOD_SIZE,
116    PCM_PARAM_PERIOD_BYTES,
117    PCM_PARAM_PERIODS,
118    PCM_PARAM_BUFFER_TIME,
119    PCM_PARAM_BUFFER_SIZE,
120    PCM_PARAM_BUFFER_BYTES,
121    PCM_PARAM_TICK_TIME,
122};
123
124/* Mixer control types */
125enum mixer_ctl_type {
126    MIXER_CTL_TYPE_BOOL,
127    MIXER_CTL_TYPE_INT,
128    MIXER_CTL_TYPE_ENUM,
129    MIXER_CTL_TYPE_BYTE,
130    MIXER_CTL_TYPE_IEC958,
131    MIXER_CTL_TYPE_INT64,
132    MIXER_CTL_TYPE_UNKNOWN,
133
134    MIXER_CTL_TYPE_MAX,
135};
136
137/* Open and close a stream */
138struct pcm *pcm_open(unsigned int card, unsigned int device,
139                     unsigned int flags, struct pcm_config *config);
140int pcm_close(struct pcm *pcm);
141int pcm_is_ready(struct pcm *pcm);
142
143/* Obtain the parameters for a PCM */
144struct pcm_params *pcm_params_get(unsigned int card, unsigned int device,
145                                  unsigned int flags);
146void pcm_params_free(struct pcm_params *pcm_params);
147unsigned int pcm_params_get_min(struct pcm_params *pcm_params,
148                                enum pcm_param param);
149unsigned int pcm_params_get_max(struct pcm_params *pcm_params,
150                                enum pcm_param param);
151
152/* Set and get config */
153int pcm_get_config(struct pcm *pcm, struct pcm_config *config);
154int pcm_set_config(struct pcm *pcm, struct pcm_config *config);
155
156/* Returns a human readable reason for the last error */
157const char *pcm_get_error(struct pcm *pcm);
158
159/* Returns the buffer size (int frames) that should be used for pcm_write. */
160unsigned int pcm_get_buffer_size(struct pcm *pcm);
161unsigned int pcm_frames_to_bytes(struct pcm *pcm, unsigned int frames);
162unsigned int pcm_bytes_to_frames(struct pcm *pcm, unsigned int bytes);
163
164/* Returns the pcm latency in ms */
165unsigned int pcm_get_latency(struct pcm *pcm);
166
167/* Returns available frames in pcm buffer and corresponding time stamp.
168 * For an input stream, frames available are frames ready for the
169 * application to read.
170 * For an output stream, frames available are the number of empty frames available
171 * for the application to write.
172 */
173int pcm_get_htimestamp(struct pcm *pcm, unsigned int *avail,
174                       struct timespec *tstamp);
175
176/* Write data to the fifo.
177 * Will start playback on the first write or on a write that
178 * occurs after a fifo underrun.
179 */
180int pcm_write(struct pcm *pcm, const void *data, unsigned int count);
181int pcm_read(struct pcm *pcm, void *data, unsigned int count);
182
183/*
184 * mmap() support.
185 */
186int pcm_mmap_write(struct pcm *pcm, const void *data, unsigned int count);
187int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset,
188                   unsigned int *frames);
189int pcm_mmap_commit(struct pcm *pcm, unsigned int offset, unsigned int frames);
190
191/* Start and stop a PCM channel that doesn't transfer data */
192int pcm_start(struct pcm *pcm);
193int pcm_stop(struct pcm *pcm);
194
195/* Interrupt driven API */
196int pcm_wait(struct pcm *pcm, int timeout);
197
198/* Change avail_min after the stream has been opened with no need to stop the stream.
199 * Only accepted if opened with PCM_MMAP and PCM_NOIRQ flags
200 */
201int pcm_set_avail_min(struct pcm *pcm, int avail_min);
202
203/*
204 * MIXER API
205 */
206
207struct mixer;
208struct mixer_ctl;
209
210/* Open and close a mixer */
211struct mixer *mixer_open(unsigned int card);
212void mixer_close(struct mixer *mixer);
213
214/* Get info about a mixer */
215const char *mixer_get_name(struct mixer *mixer);
216
217/* Obtain mixer controls */
218unsigned int mixer_get_num_ctls(struct mixer *mixer);
219struct mixer_ctl *mixer_get_ctl(struct mixer *mixer, unsigned int id);
220struct mixer_ctl *mixer_get_ctl_by_name(struct mixer *mixer, const char *name);
221
222/* Get info about mixer controls */
223const char *mixer_ctl_get_name(struct mixer_ctl *ctl);
224enum mixer_ctl_type mixer_ctl_get_type(struct mixer_ctl *ctl);
225const char *mixer_ctl_get_type_string(struct mixer_ctl *ctl);
226unsigned int mixer_ctl_get_num_values(struct mixer_ctl *ctl);
227unsigned int mixer_ctl_get_num_enums(struct mixer_ctl *ctl);
228const char *mixer_ctl_get_enum_string(struct mixer_ctl *ctl,
229                                      unsigned int enum_id);
230
231/* Some sound cards update their controls due to external events,
232 * such as HDMI EDID byte data changing when an HDMI cable is
233 * connected. This API allows the count of elements to be updated.
234 */
235void mixer_ctl_update(struct mixer_ctl *ctl);
236
237/* Set and get mixer controls */
238int mixer_ctl_get_percent(struct mixer_ctl *ctl, unsigned int id);
239int mixer_ctl_set_percent(struct mixer_ctl *ctl, unsigned int id, int percent);
240
241int mixer_ctl_get_value(struct mixer_ctl *ctl, unsigned int id);
242int mixer_ctl_get_array(struct mixer_ctl *ctl, void *array, size_t count);
243int mixer_ctl_set_value(struct mixer_ctl *ctl, unsigned int id, int value);
244int mixer_ctl_set_array(struct mixer_ctl *ctl, const void *array, size_t count);
245int mixer_ctl_set_enum_by_string(struct mixer_ctl *ctl, const char *string);
246
247/* Determe range of integer mixer controls */
248int mixer_ctl_get_range_min(struct mixer_ctl *ctl);
249int mixer_ctl_get_range_max(struct mixer_ctl *ctl);
250
251#if defined(__cplusplus)
252}  /* extern "C" */
253#endif
254
255#endif
256