include/tinyalsa/asoundlib.h

   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
  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 */
  71 enum 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 */
  81 struct 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 */
 108 enum 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 */
 125 enum 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 */
 138 struct pcm *pcm_open(unsigned int card, unsigned int device,
 139                      unsigned int flags, struct pcm_config *config);
 140 int pcm_close(struct pcm *pcm);
 141 int pcm_is_ready(struct pcm *pcm);
 142
 143 /* Obtain the parameters for a PCM */
 144 struct pcm_params *pcm_params_get(unsigned int card, unsigned int device,
 145                                   unsigned int flags);
 146 void pcm_params_free(struct pcm_params *pcm_params);
 147 unsigned int pcm_params_get_min(struct pcm_params *pcm_params,
 148                                 enum pcm_param param);
 149 unsigned int pcm_params_get_max(struct pcm_params *pcm_params,
 150                                 enum pcm_param param);
 151
 152 /* Set and get config */
 153 int pcm_get_config(struct pcm *pcm, struct pcm_config *config);
 154 int pcm_set_config(struct pcm *pcm, struct pcm_config *config);
 155
 156 /* Returns a human readable reason for the last error */
 157 const char *pcm_get_error(struct pcm *pcm);
 158
 159 /* Returns the buffer size (int frames) that should be used for pcm_write. */
 160 unsigned int pcm_get_buffer_size(struct pcm *pcm);
 161 unsigned int pcm_frames_to_bytes(struct pcm *pcm, unsigned int frames);
 162 unsigned int pcm_bytes_to_frames(struct pcm *pcm, unsigned int bytes);
 163
 164 /* Returns the pcm latency in ms */
 165 unsigned 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  */
 173 int 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  */
 180 int pcm_write(struct pcm *pcm, const void *data, unsigned int count);
 181 int pcm_read(struct pcm *pcm, void *data, unsigned int count);
 182
 183 /*
 184  * mmap() support.
 185  */
 186 int pcm_mmap_write(struct pcm *pcm, const void *data, unsigned int count);
 187 int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset,
 188                    unsigned int *frames);
 189 int 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 */
 192 int pcm_start(struct pcm *pcm);
 193 int pcm_stop(struct pcm *pcm);
 194
 195 /* Interrupt driven API */
 196 int 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  */
 201 int pcm_set_avail_min(struct pcm *pcm, int avail_min);
 202
 203 /*
 204  * MIXER API
 205  */
 206
 207 struct mixer;
 208 struct mixer_ctl;
 209
 210 /* Open and close a mixer */
 211 struct mixer *mixer_open(unsigned int card);
 212 void mixer_close(struct mixer *mixer);
 213
 214 /* Obtain mixer controls */
 215 unsigned int mixer_get_num_ctls(struct mixer *mixer);
 216 struct mixer_ctl *mixer_get_ctl(struct mixer *mixer, unsigned int id);
 217 struct mixer_ctl *mixer_get_ctl_by_name(struct mixer *mixer, const char *name);
 218
 219 /* Get info about mixer controls */
 220 const char *mixer_ctl_get_name(struct mixer_ctl *ctl);
 221 enum mixer_ctl_type mixer_ctl_get_type(struct mixer_ctl *ctl);
 222 const char *mixer_ctl_get_type_string(struct mixer_ctl *ctl);
 223 unsigned int mixer_ctl_get_num_values(struct mixer_ctl *ctl);
 224 unsigned int mixer_ctl_get_num_enums(struct mixer_ctl *ctl);
 225 const char *mixer_ctl_get_enum_string(struct mixer_ctl *ctl,
 226                                       unsigned int enum_id);
 227
 228 /* Set and get mixer controls */
 229 int mixer_ctl_get_percent(struct mixer_ctl *ctl, unsigned int id);
 230 int mixer_ctl_set_percent(struct mixer_ctl *ctl, unsigned int id, int percent);
 231
 232 int mixer_ctl_get_value(struct mixer_ctl *ctl, unsigned int id);
 233 int mixer_ctl_get_array(struct mixer_ctl *ctl, void *array, size_t count);
 234 int mixer_ctl_set_value(struct mixer_ctl *ctl, unsigned int id, int value);
 235 int mixer_ctl_set_array(struct mixer_ctl *ctl, const void *array, size_t count);
 236 int mixer_ctl_set_enum_by_string(struct mixer_ctl *ctl, const char *string);
 237
 238 /* Determe range of integer mixer controls */
 239 int mixer_ctl_get_range_min(struct mixer_ctl *ctl);
 240 int mixer_ctl_get_range_max(struct mixer_ctl *ctl);
 241
 242 #if defined(__cplusplus)
 243 }  /* extern "C" */
 244 #endif
 245
 246 #endif