lh | 9ed821d | 2023-04-07 01:36:19 -0700 | [diff] [blame] | 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 | /* 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 */ |
| 79 | |
| 80 | PCM_FORMAT_MAX, |
| 81 | }; |
| 82 | |
| 83 | /* Bitmask has 256 bits (32 bytes) in asound.h */ |
| 84 | struct pcm_mask { |
| 85 | unsigned int bits[32 / sizeof(unsigned int)]; |
| 86 | }; |
| 87 | |
| 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; |
| 95 | |
| 96 | /* Values to use for the ALSA start, stop and silence thresholds, and |
| 97 | * silence size. Setting any one of these values to 0 will cause the |
| 98 | * default tinyalsa values to be used instead. |
| 99 | * Tinyalsa defaults are as follows. |
| 100 | * |
| 101 | * start_threshold : period_count * period_size |
| 102 | * stop_threshold : period_count * period_size |
| 103 | * silence_threshold : 0 |
| 104 | * silence_size : 0 |
| 105 | */ |
| 106 | unsigned int start_threshold; |
| 107 | unsigned int stop_threshold; |
| 108 | unsigned int silence_threshold; |
| 109 | unsigned int silence_size; |
| 110 | |
| 111 | /* Minimum number of frames available before pcm_mmap_write() will actually |
| 112 | * write into the kernel buffer. Only used if the stream is opened in mmap mode |
| 113 | * (pcm_open() called with PCM_MMAP flag set). Use 0 for default. |
| 114 | */ |
| 115 | int avail_min; |
| 116 | }; |
| 117 | |
| 118 | /* PCM parameters */ |
| 119 | enum pcm_param |
| 120 | { |
| 121 | /* mask parameters */ |
| 122 | PCM_PARAM_ACCESS, |
| 123 | PCM_PARAM_FORMAT, |
| 124 | PCM_PARAM_SUBFORMAT, |
| 125 | /* interval parameters */ |
| 126 | PCM_PARAM_SAMPLE_BITS, |
| 127 | PCM_PARAM_FRAME_BITS, |
| 128 | PCM_PARAM_CHANNELS, |
| 129 | PCM_PARAM_RATE, |
| 130 | PCM_PARAM_PERIOD_TIME, |
| 131 | PCM_PARAM_PERIOD_SIZE, |
| 132 | PCM_PARAM_PERIOD_BYTES, |
| 133 | PCM_PARAM_PERIODS, |
| 134 | PCM_PARAM_BUFFER_TIME, |
| 135 | PCM_PARAM_BUFFER_SIZE, |
| 136 | PCM_PARAM_BUFFER_BYTES, |
| 137 | PCM_PARAM_TICK_TIME, |
| 138 | }; |
| 139 | |
| 140 | /* Mixer control types */ |
| 141 | enum mixer_ctl_type { |
| 142 | MIXER_CTL_TYPE_BOOL, |
| 143 | MIXER_CTL_TYPE_INT, |
| 144 | MIXER_CTL_TYPE_ENUM, |
| 145 | MIXER_CTL_TYPE_BYTE, |
| 146 | MIXER_CTL_TYPE_IEC958, |
| 147 | MIXER_CTL_TYPE_INT64, |
| 148 | MIXER_CTL_TYPE_UNKNOWN, |
| 149 | |
| 150 | MIXER_CTL_TYPE_MAX, |
| 151 | }; |
| 152 | |
| 153 | /* Open and close a stream */ |
| 154 | struct pcm *pcm_open(unsigned int card, unsigned int device, |
| 155 | unsigned int flags, struct pcm_config *config); |
| 156 | int pcm_close(struct pcm *pcm); |
| 157 | int pcm_is_ready(struct pcm *pcm); |
| 158 | |
| 159 | /* Obtain the parameters for a PCM */ |
| 160 | struct pcm_params *pcm_params_get(unsigned int card, unsigned int device, |
| 161 | unsigned int flags); |
| 162 | void pcm_params_free(struct pcm_params *pcm_params); |
| 163 | |
| 164 | struct pcm_mask *pcm_params_get_mask(struct pcm_params *pcm_params, |
| 165 | enum pcm_param param); |
| 166 | unsigned int pcm_params_get_min(struct pcm_params *pcm_params, |
| 167 | enum pcm_param param); |
| 168 | void pcm_params_set_min(struct pcm_params *pcm_params, |
| 169 | enum pcm_param param, unsigned int val); |
| 170 | unsigned int pcm_params_get_max(struct pcm_params *pcm_params, |
| 171 | enum pcm_param param); |
| 172 | void pcm_params_set_max(struct pcm_params *pcm_params, |
| 173 | enum pcm_param param, unsigned int val); |
| 174 | |
| 175 | /* Converts the pcm parameters to a human readable string. |
| 176 | * The string parameter is a caller allocated buffer of size bytes, |
| 177 | * which is then filled up to size - 1 and null terminated, |
| 178 | * if size is greater than zero. |
| 179 | * The return value is the number of bytes copied to string |
| 180 | * (not including null termination) if less than size; otherwise, |
| 181 | * the number of bytes required for the buffer. |
| 182 | */ |
| 183 | int pcm_params_to_string(struct pcm_params *params, char *string, unsigned int size); |
| 184 | |
| 185 | /* Returns 1 if the pcm_format is present (format bit set) in |
| 186 | * the pcm_params structure; 0 otherwise, or upon unrecognized format. |
| 187 | */ |
| 188 | int pcm_params_format_test(struct pcm_params *params, enum pcm_format format); |
| 189 | |
| 190 | /* Set and get config */ |
| 191 | int pcm_get_config(struct pcm *pcm, struct pcm_config *config); |
| 192 | int pcm_set_config(struct pcm *pcm, struct pcm_config *config); |
| 193 | |
| 194 | /* Returns a human readable reason for the last error */ |
| 195 | const char *pcm_get_error(struct pcm *pcm); |
| 196 | |
| 197 | /* Returns the sample size in bits for a PCM format. |
| 198 | * As with ALSA formats, this is the storage size for the format, whereas the |
| 199 | * format represents the number of significant bits. For example, |
| 200 | * PCM_FORMAT_S24_LE uses 32 bits of storage. |
| 201 | */ |
| 202 | unsigned int pcm_format_to_bits(enum pcm_format format); |
| 203 | |
| 204 | /* Returns the buffer size (int frames) that should be used for pcm_write. */ |
| 205 | unsigned int pcm_get_buffer_size(struct pcm *pcm); |
| 206 | unsigned int pcm_frames_to_bytes(struct pcm *pcm, unsigned int frames); |
| 207 | unsigned int pcm_bytes_to_frames(struct pcm *pcm, unsigned int bytes); |
| 208 | |
| 209 | /* Returns the pcm latency in ms */ |
| 210 | unsigned int pcm_get_latency(struct pcm *pcm); |
| 211 | |
| 212 | /* Returns available frames in pcm buffer and corresponding time stamp. |
| 213 | * The clock is CLOCK_MONOTONIC if flag PCM_MONOTONIC was specified in pcm_open, |
| 214 | * otherwise the clock is CLOCK_REALTIME. |
| 215 | * For an input stream, frames available are frames ready for the |
| 216 | * application to read. |
| 217 | * For an output stream, frames available are the number of empty frames available |
| 218 | * for the application to write. |
| 219 | */ |
| 220 | int pcm_get_htimestamp(struct pcm *pcm, unsigned int *avail, |
| 221 | struct timespec *tstamp); |
| 222 | |
| 223 | /* Write data to the fifo. |
| 224 | * Will start playback on the first write or on a write that |
| 225 | * occurs after a fifo underrun. |
| 226 | */ |
| 227 | int pcm_write(struct pcm *pcm, const void *data, unsigned int count); |
| 228 | int pcm_read(struct pcm *pcm, void *data, unsigned int count); |
| 229 | |
| 230 | /* |
| 231 | * mmap() support. |
| 232 | */ |
| 233 | int pcm_mmap_write(struct pcm *pcm, const void *data, unsigned int count); |
| 234 | int pcm_mmap_read(struct pcm *pcm, void *data, unsigned int count); |
| 235 | int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset, |
| 236 | unsigned int *frames); |
| 237 | int pcm_mmap_commit(struct pcm *pcm, unsigned int offset, unsigned int frames); |
| 238 | int pcm_mmap_avail(struct pcm *pcm); |
| 239 | |
| 240 | /* Prepare the PCM substream to be triggerable */ |
| 241 | int pcm_prepare(struct pcm *pcm); |
| 242 | /* Start and stop a PCM channel that doesn't transfer data */ |
| 243 | int pcm_start(struct pcm *pcm); |
| 244 | int pcm_stop(struct pcm *pcm); |
| 245 | |
| 246 | /* ioctl function for PCM driver */ |
| 247 | int pcm_ioctl(struct pcm *pcm, int request, ...); |
| 248 | |
| 249 | /* Interrupt driven API */ |
| 250 | int pcm_wait(struct pcm *pcm, int timeout); |
| 251 | int pcm_get_poll_fd(struct pcm *pcm); |
| 252 | |
| 253 | /* Change avail_min after the stream has been opened with no need to stop the stream. |
| 254 | * Only accepted if opened with PCM_MMAP and PCM_NOIRQ flags |
| 255 | */ |
| 256 | int pcm_set_avail_min(struct pcm *pcm, int avail_min); |
| 257 | |
| 258 | /* |
| 259 | * MIXER API |
| 260 | */ |
| 261 | |
| 262 | struct mixer; |
| 263 | struct mixer_ctl; |
| 264 | |
| 265 | /* Open and close a mixer */ |
| 266 | struct mixer *mixer_open(unsigned int card); |
| 267 | void mixer_close(struct mixer *mixer); |
| 268 | |
| 269 | /* Get info about a mixer */ |
| 270 | const char *mixer_get_name(struct mixer *mixer); |
| 271 | |
| 272 | /* Obtain mixer controls */ |
| 273 | unsigned int mixer_get_num_ctls(struct mixer *mixer); |
| 274 | struct mixer_ctl *mixer_get_ctl(struct mixer *mixer, unsigned int id); |
| 275 | struct mixer_ctl *mixer_get_ctl_by_name(struct mixer *mixer, const char *name); |
| 276 | |
| 277 | /* Get info about mixer controls */ |
| 278 | const char *mixer_ctl_get_name(struct mixer_ctl *ctl); |
| 279 | enum mixer_ctl_type mixer_ctl_get_type(struct mixer_ctl *ctl); |
| 280 | const char *mixer_ctl_get_type_string(struct mixer_ctl *ctl); |
| 281 | unsigned int mixer_ctl_get_num_values(struct mixer_ctl *ctl); |
| 282 | unsigned int mixer_ctl_get_num_enums(struct mixer_ctl *ctl); |
| 283 | const char *mixer_ctl_get_enum_string(struct mixer_ctl *ctl, |
| 284 | unsigned int enum_id); |
| 285 | |
| 286 | /* Some sound cards update their controls due to external events, |
| 287 | * such as HDMI EDID byte data changing when an HDMI cable is |
| 288 | * connected. This API allows the count of elements to be updated. |
| 289 | */ |
| 290 | void mixer_ctl_update(struct mixer_ctl *ctl); |
| 291 | |
| 292 | /* Set and get mixer controls */ |
| 293 | int mixer_ctl_get_percent(struct mixer_ctl *ctl, unsigned int id); |
| 294 | int mixer_ctl_set_percent(struct mixer_ctl *ctl, unsigned int id, int percent); |
| 295 | |
| 296 | int mixer_ctl_get_value(struct mixer_ctl *ctl, unsigned int id); |
| 297 | int mixer_ctl_get_array(struct mixer_ctl *ctl, void *array, size_t count); |
| 298 | int mixer_ctl_set_value(struct mixer_ctl *ctl, unsigned int id, int value); |
| 299 | int mixer_ctl_set_array(struct mixer_ctl *ctl, const void *array, size_t count); |
| 300 | int mixer_ctl_set_enum_by_string(struct mixer_ctl *ctl, const char *string); |
| 301 | |
| 302 | /* Determe range of integer mixer controls */ |
| 303 | int mixer_ctl_get_range_min(struct mixer_ctl *ctl); |
| 304 | int mixer_ctl_get_range_max(struct mixer_ctl *ctl); |
| 305 | |
| 306 | #if defined(__cplusplus) |
| 307 | } /* extern "C" */ |
| 308 | #endif |
| 309 | |
| 310 | #endif |