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) 36 extern "C" { 37 #endif 38 39 /* 40 * PCM API 41 */ 42 43 struct 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 /* TLV header size*/ 72 #define TLV_HEADER_SIZE (2 * sizeof(unsigned int)) 73 74 /* Bit formats */ 75 enum pcm_format { 76 PCM_FORMAT_INVALID = -1, 77 PCM_FORMAT_S16_LE = 0, /* 16-bit signed */ 78 PCM_FORMAT_S32_LE, /* 32-bit signed */ 79 PCM_FORMAT_S8, /* 8-bit signed */ 80 PCM_FORMAT_S24_LE, /* 24-bits in 4-bytes */ 81 PCM_FORMAT_S24_3LE, /* 24-bits in 3-bytes */ 82 83 PCM_FORMAT_MAX, 84 }; 85 86 /* Bitmask has 256 bits (32 bytes) in asound.h */ 87 struct pcm_mask { 88 unsigned int bits[32 / sizeof(unsigned int)]; 89 }; 90 91 /* Configuration for a stream */ 92 struct pcm_config { 93 unsigned int channels; 94 unsigned int rate; 95 unsigned int period_size; 96 unsigned int period_count; 97 enum pcm_format format; 98 99 /* Values to use for the ALSA start, stop and silence thresholds, and 100 * silence size. Setting any one of these values to 0 will cause the 101 * default tinyalsa values to be used instead. 102 * Tinyalsa defaults are as follows. 103 * 104 * start_threshold : period_count * period_size 105 * stop_threshold : period_count * period_size 106 * silence_threshold : 0 107 * silence_size : 0 108 */ 109 unsigned int start_threshold; 110 unsigned int stop_threshold; 111 unsigned int silence_threshold; 112 unsigned int silence_size; 113 114 /* Minimum number of frames available before pcm_mmap_write() will actually 115 * write into the kernel buffer. Only used if the stream is opened in mmap mode 116 * (pcm_open() called with PCM_MMAP flag set). Use 0 for default. 117 */ 118 int avail_min; 119 }; 120 121 /* PCM parameters */ 122 enum pcm_param 123 { 124 /* mask parameters */ 125 PCM_PARAM_ACCESS, 126 PCM_PARAM_FORMAT, 127 PCM_PARAM_SUBFORMAT, 128 /* interval parameters */ 129 PCM_PARAM_SAMPLE_BITS, 130 PCM_PARAM_FRAME_BITS, 131 PCM_PARAM_CHANNELS, 132 PCM_PARAM_RATE, 133 PCM_PARAM_PERIOD_TIME, 134 PCM_PARAM_PERIOD_SIZE, 135 PCM_PARAM_PERIOD_BYTES, 136 PCM_PARAM_PERIODS, 137 PCM_PARAM_BUFFER_TIME, 138 PCM_PARAM_BUFFER_SIZE, 139 PCM_PARAM_BUFFER_BYTES, 140 PCM_PARAM_TICK_TIME, 141 }; 142 143 /* Mixer control types */ 144 enum mixer_ctl_type { 145 MIXER_CTL_TYPE_BOOL, 146 MIXER_CTL_TYPE_INT, 147 MIXER_CTL_TYPE_ENUM, 148 MIXER_CTL_TYPE_BYTE, 149 MIXER_CTL_TYPE_IEC958, 150 MIXER_CTL_TYPE_INT64, 151 MIXER_CTL_TYPE_UNKNOWN, 152 153 MIXER_CTL_TYPE_MAX, 154 }; 155 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); 161 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); 166 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); 177 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); 187 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); 192 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); 196 197 /* Returns a human readable reason for the last error */ 198 const char *pcm_get_error(struct pcm *pcm); 199 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); 206 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); 211 212 /* Returns the pcm latency in ms */ 213 unsigned int pcm_get_latency(struct pcm *pcm); 214 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); 225 226 /* Returns the subdevice on which the pcm has been opened */ 227 unsigned int pcm_get_subdevice(struct pcm *pcm); 228 229 /* Write data to the fifo. 230 * Will start playback on the first write or on a write that 231 * occurs after a fifo underrun. 232 */ 233 int pcm_write(struct pcm *pcm, const void *data, unsigned int count); 234 int pcm_read(struct pcm *pcm, void *data, unsigned int count); 235 236 /* 237 * mmap() support. 238 */ 239 int pcm_mmap_write(struct pcm *pcm, const void *data, unsigned int count); 240 int pcm_mmap_read(struct pcm *pcm, void *data, unsigned int count); 241 int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset, 242 unsigned int *frames); 243 int pcm_mmap_commit(struct pcm *pcm, unsigned int offset, unsigned int frames); 244 int pcm_mmap_avail(struct pcm *pcm); 245 246 /* Returns current read/write position in the mmap buffer with associated time stamp. 247 */ 248 int pcm_mmap_get_hw_ptr(struct pcm* pcm, unsigned int *hw_ptr, struct timespec *tstamp); 249 250 /* Prepare the PCM substream to be triggerable */ 251 int pcm_prepare(struct pcm *pcm); 252 /* Start and stop a PCM channel that doesn't transfer data */ 253 int pcm_start(struct pcm *pcm); 254 int pcm_stop(struct pcm *pcm); 255 256 /* ioctl function for PCM driver */ 257 int pcm_ioctl(struct pcm *pcm, int request, ...); 258 259 /* Interrupt driven API */ 260 int pcm_wait(struct pcm *pcm, int timeout); 261 int pcm_get_poll_fd(struct pcm *pcm); 262 263 /* Change avail_min after the stream has been opened with no need to stop the stream. 264 * Only accepted if opened with PCM_MMAP and PCM_NOIRQ flags 265 */ 266 int pcm_set_avail_min(struct pcm *pcm, int avail_min); 267 268 /* 269 * MIXER API 270 */ 271 272 struct mixer; 273 struct mixer_ctl; 274 275 /* Open and close a mixer */ 276 struct mixer *mixer_open(unsigned int card); 277 void mixer_close(struct mixer *mixer); 278 279 /* Get info about a mixer */ 280 const char *mixer_get_name(struct mixer *mixer); 281 282 /* Obtain mixer controls */ 283 unsigned int mixer_get_num_ctls(struct mixer *mixer); 284 struct mixer_ctl *mixer_get_ctl(struct mixer *mixer, unsigned int id); 285 struct mixer_ctl *mixer_get_ctl_by_name(struct mixer *mixer, const char *name); 286 287 /* Get info about mixer controls */ 288 const char *mixer_ctl_get_name(struct mixer_ctl *ctl); 289 enum mixer_ctl_type mixer_ctl_get_type(struct mixer_ctl *ctl); 290 const char *mixer_ctl_get_type_string(struct mixer_ctl *ctl); 291 unsigned int mixer_ctl_get_num_values(struct mixer_ctl *ctl); 292 unsigned int mixer_ctl_get_num_enums(struct mixer_ctl *ctl); 293 const char *mixer_ctl_get_enum_string(struct mixer_ctl *ctl, 294 unsigned int enum_id); 295 296 /* Some sound cards update their controls due to external events, 297 * such as HDMI EDID byte data changing when an HDMI cable is 298 * connected. This API allows the count of elements to be updated. 299 */ 300 void mixer_ctl_update(struct mixer_ctl *ctl); 301 302 /* Set and get mixer controls */ 303 int mixer_ctl_get_percent(struct mixer_ctl *ctl, unsigned int id); 304 int mixer_ctl_set_percent(struct mixer_ctl *ctl, unsigned int id, int percent); 305 306 int mixer_ctl_get_value(struct mixer_ctl *ctl, unsigned int id); 307 int mixer_ctl_is_access_tlv_rw(struct mixer_ctl *ctl); 308 int mixer_ctl_get_array(struct mixer_ctl *ctl, void *array, size_t count); 309 int mixer_ctl_set_value(struct mixer_ctl *ctl, unsigned int id, int value); 310 int mixer_ctl_set_array(struct mixer_ctl *ctl, const void *array, size_t count); 311 int mixer_ctl_set_enum_by_string(struct mixer_ctl *ctl, const char *string); 312 313 /* Determine range of integer mixer controls */ 314 int mixer_ctl_get_range_min(struct mixer_ctl *ctl); 315 int mixer_ctl_get_range_max(struct mixer_ctl *ctl); 316 317 int mixer_subscribe_events(struct mixer *mixer, int subscribe); 318 int mixer_wait_event(struct mixer *mixer, int timeout); 319 320 #if defined(__cplusplus) 321 } /* extern "C" */ 322 #endif 323 324 #endif 325