1 /******************************************************************************* 2 * Copyright (C) 2018 Cadence Design Systems, Inc. 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining 5 * a copy of this software and associated documentation files (the 6 * "Software"), to use this Software with Cadence processor cores only and 7 * not with any other processors and platforms, subject to 8 * the following conditions: 9 * 10 * The above copyright notice and this permission notice shall be included 11 * in all copies or substantial portions of the Software. 12 * 13 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 14 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 15 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 16 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 17 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 18 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 19 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 20 21 ******************************************************************************/ 22 23 #ifndef ASOUNDLIB_H 24 #define ASOUNDLIB_H 25 26 #include <sys/time.h> 27 #include <stddef.h> 28 29 #if defined(__cplusplus) 30 extern "C" { 31 #endif 32 33 /* 34 * PCM API 35 */ 36 37 struct pcm; 38 39 #define PCM_OUT 0x00000000 40 #define PCM_IN 0x10000000 41 #define PCM_MMAP 0x00000001 42 #define PCM_NOIRQ 0x00000002 43 #define PCM_NORESTART 0x00000004 /* PCM_NORESTART - when set, calls to 44 * pcm_write for a playback stream will not 45 * attempt to restart the stream in the case 46 * of an underflow, but will return -EPIPE 47 * instead. After the first -EPIPE error, the 48 * stream is considered to be stopped, and a 49 * second call to pcm_write will attempt to 50 * restart the stream. 51 */ 52 #define PCM_MONOTONIC 0x00000008 /* see pcm_get_htimestamp */ 53 54 /* PCM runtime states */ 55 #define PCM_STATE_OPEN 0 56 #define PCM_STATE_SETUP 1 57 #define PCM_STATE_PREPARED 2 58 #define PCM_STATE_RUNNING 3 59 #define PCM_STATE_XRUN 4 60 #define PCM_STATE_DRAINING 5 61 #define PCM_STATE_PAUSED 6 62 #define PCM_STATE_SUSPENDED 7 63 #define PCM_STATE_DISCONNECTED 8 64 65 /* TLV header size*/ 66 #define TLV_HEADER_SIZE (2 * sizeof(unsigned int)) 67 68 /* Bit formats */ 69 enum pcm_format { 70 PCM_FORMAT_INVALID = -1, 71 PCM_FORMAT_S16_LE = 0, /* 16-bit signed */ 72 PCM_FORMAT_S32_LE, /* 32-bit signed */ 73 PCM_FORMAT_S8, /* 8-bit signed */ 74 PCM_FORMAT_S24_LE, /* 24-bits in 4-bytes */ 75 PCM_FORMAT_S24_3LE, /* 24-bits in 3-bytes */ 76 77 PCM_FORMAT_MAX, 78 }; 79 80 /* Bitmask has 256 bits (32 bytes) in asound.h */ 81 struct pcm_mask { 82 unsigned int bits[32 / sizeof(unsigned int)]; 83 }; 84 85 /* Configuration for a stream */ 86 struct pcm_config { 87 unsigned int channels; 88 unsigned int rate; 89 unsigned int period_size; 90 unsigned int period_count; 91 enum pcm_format format; 92 93 /* Values to use for the ALSA start, stop and silence thresholds, and 94 * silence size. Setting any one of these values to 0 will cause the 95 * default tinyalsa values to be used instead. 96 * Tinyalsa defaults are as follows. 97 * 98 * start_threshold : period_count * period_size 99 * stop_threshold : period_count * period_size 100 * silence_threshold : 0 101 * silence_size : 0 102 */ 103 unsigned int start_threshold; 104 unsigned int stop_threshold; 105 unsigned int silence_threshold; 106 unsigned int silence_size; 107 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 }; 114 115 /* PCM parameters */ 116 enum pcm_param 117 { 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 }; 136 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, 146 147 MIXER_CTL_TYPE_MAX, 148 }; 149 150 /* Open and close a stream */ 151 struct pcm *pcm_open(unsigned int card, unsigned int device, 152 unsigned int flags, struct pcm_config *config); 153 int pcm_close(struct pcm *pcm); 154 int pcm_is_ready(struct pcm *pcm); 155 156 /* Obtain the parameters for a PCM */ 157 struct pcm_params *pcm_params_get(unsigned int card, unsigned int device, 158 unsigned int flags); 159 void pcm_params_free(struct pcm_params *pcm_params); 160 161 struct pcm_mask *pcm_params_get_mask(struct pcm_params *pcm_params, 162 enum pcm_param param); 163 unsigned int pcm_params_get_min(struct pcm_params *pcm_params, 164 enum pcm_param param); 165 void pcm_params_set_min(struct pcm_params *pcm_params, 166 enum pcm_param param, unsigned int val); 167 unsigned int pcm_params_get_max(struct pcm_params *pcm_params, 168 enum pcm_param param); 169 void pcm_params_set_max(struct pcm_params *pcm_params, 170 enum pcm_param param, unsigned int val); 171 172 /* Converts the pcm parameters to a human readable string. 173 * The string parameter is a caller allocated buffer of size bytes, 174 * which is then filled up to size - 1 and null terminated, 175 * if size is greater than zero. 176 * The return value is the number of bytes copied to string 177 * (not including null termination) if less than size; otherwise, 178 * the number of bytes required for the buffer. 179 */ 180 int pcm_params_to_string(struct pcm_params *params, char *string, unsigned int size); 181 182 /* Returns 1 if the pcm_format is present (format bit set) in 183 * the pcm_params structure; 0 otherwise, or upon unrecognized format. 184 */ 185 int pcm_params_format_test(struct pcm_params *params, enum pcm_format format); 186 187 /* Set and get config */ 188 int pcm_get_config(struct pcm *pcm, struct pcm_config *config); 189 int pcm_set_config(struct pcm *pcm, struct pcm_config *config); 190 191 /* Returns a human readable reason for the last error */ 192 const char *pcm_get_error(struct pcm *pcm); 193 194 /* Returns the sample size in bits for a PCM format. 195 * As with ALSA formats, this is the storage size for the format, whereas the 196 * format represents the number of significant bits. For example, 197 * PCM_FORMAT_S24_LE uses 32 bits of storage. 198 */ 199 unsigned int pcm_format_to_bits(enum pcm_format format); 200 201 /* Returns the buffer size (int frames) that should be used for pcm_write. */ 202 unsigned int pcm_get_buffer_size(struct pcm *pcm); 203 unsigned int pcm_frames_to_bytes(struct pcm *pcm, unsigned int frames); 204 unsigned int pcm_bytes_to_frames(struct pcm *pcm, unsigned int bytes); 205 206 /* Returns the pcm latency in ms */ 207 unsigned int pcm_get_latency(struct pcm *pcm); 208 209 /* Returns available frames in pcm buffer and corresponding time stamp. 210 * The clock is CLOCK_MONOTONIC if flag PCM_MONOTONIC was specified in pcm_open, 211 * otherwise the clock is CLOCK_REALTIME. 212 * For an input stream, frames available are frames ready for the 213 * application to read. 214 * For an output stream, frames available are the number of empty frames available 215 * for the application to write. 216 */ 217 int pcm_get_htimestamp(struct pcm *pcm, unsigned int *avail, 218 struct timespec *tstamp); 219 220 /* Returns the subdevice on which the pcm has been opened */ 221 unsigned int pcm_get_subdevice(struct pcm *pcm); 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_is_access_tlv_rw(struct mixer_ctl *ctl); 298 int mixer_ctl_get_array(struct mixer_ctl *ctl, void *array, size_t count); 299 int mixer_ctl_set_value(struct mixer_ctl *ctl, unsigned int id, int value); 300 int mixer_ctl_set_array(struct mixer_ctl *ctl, const void *array, size_t count); 301 int mixer_ctl_set_enum_by_string(struct mixer_ctl *ctl, const char *string); 302 303 /* Determe range of integer mixer controls */ 304 int mixer_ctl_get_range_min(struct mixer_ctl *ctl); 305 int mixer_ctl_get_range_max(struct mixer_ctl *ctl); 306 307 int mixer_subscribe_events(struct mixer *mixer, int subscribe); 308 int mixer_wait_event(struct mixer *mixer, int timeout); 309 310 #if defined(__cplusplus) 311 } /* extern "C" */ 312 #endif 313 314 #endif 315