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