Home | History | Annotate | Download | only in tinyalsa
      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.  Setting
     97      * any one of these values to 0 will cause the default tinyalsa values to be
     98      * used instead.  Tinyalsa defaults are as follows.
     99      *
    100      * start_threshold   : period_count * period_size
    101      * stop_threshold    : period_count * period_size
    102      * silence_threshold : 0
    103      */
    104     unsigned int start_threshold;
    105     unsigned int stop_threshold;
    106     unsigned int silence_threshold;
    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 /* Write data to the fifo.
    221  * Will start playback on the first write or on a write that
    222  * occurs after a fifo underrun.
    223  */
    224 int pcm_write(struct pcm *pcm, const void *data, unsigned int count);
    225 int pcm_read(struct pcm *pcm, void *data, unsigned int count);
    226 
    227 /*
    228  * mmap() support.
    229  */
    230 int pcm_mmap_write(struct pcm *pcm, const void *data, unsigned int count);
    231 int pcm_mmap_read(struct pcm *pcm, void *data, unsigned int count);
    232 int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset,
    233                    unsigned int *frames);
    234 int pcm_mmap_commit(struct pcm *pcm, unsigned int offset, unsigned int frames);
    235 
    236 /* Prepare the PCM substream to be triggerable */
    237 int pcm_prepare(struct pcm *pcm);
    238 /* Start and stop a PCM channel that doesn't transfer data */
    239 int pcm_start(struct pcm *pcm);
    240 int pcm_stop(struct pcm *pcm);
    241 
    242 /* Interrupt driven API */
    243 int pcm_wait(struct pcm *pcm, int timeout);
    244 
    245 /* Change avail_min after the stream has been opened with no need to stop the stream.
    246  * Only accepted if opened with PCM_MMAP and PCM_NOIRQ flags
    247  */
    248 int pcm_set_avail_min(struct pcm *pcm, int avail_min);
    249 
    250 /*
    251  * MIXER API
    252  */
    253 
    254 struct mixer;
    255 struct mixer_ctl;
    256 
    257 /* Open and close a mixer */
    258 struct mixer *mixer_open(unsigned int card);
    259 void mixer_close(struct mixer *mixer);
    260 
    261 /* Get info about a mixer */
    262 const char *mixer_get_name(struct mixer *mixer);
    263 
    264 /* Obtain mixer controls */
    265 unsigned int mixer_get_num_ctls(struct mixer *mixer);
    266 struct mixer_ctl *mixer_get_ctl(struct mixer *mixer, unsigned int id);
    267 struct mixer_ctl *mixer_get_ctl_by_name(struct mixer *mixer, const char *name);
    268 
    269 /* Get info about mixer controls */
    270 const char *mixer_ctl_get_name(struct mixer_ctl *ctl);
    271 enum mixer_ctl_type mixer_ctl_get_type(struct mixer_ctl *ctl);
    272 const char *mixer_ctl_get_type_string(struct mixer_ctl *ctl);
    273 unsigned int mixer_ctl_get_num_values(struct mixer_ctl *ctl);
    274 unsigned int mixer_ctl_get_num_enums(struct mixer_ctl *ctl);
    275 const char *mixer_ctl_get_enum_string(struct mixer_ctl *ctl,
    276                                       unsigned int enum_id);
    277 
    278 /* Some sound cards update their controls due to external events,
    279  * such as HDMI EDID byte data changing when an HDMI cable is
    280  * connected. This API allows the count of elements to be updated.
    281  */
    282 void mixer_ctl_update(struct mixer_ctl *ctl);
    283 
    284 /* Set and get mixer controls */
    285 int mixer_ctl_get_percent(struct mixer_ctl *ctl, unsigned int id);
    286 int mixer_ctl_set_percent(struct mixer_ctl *ctl, unsigned int id, int percent);
    287 
    288 int mixer_ctl_get_value(struct mixer_ctl *ctl, unsigned int id);
    289 int mixer_ctl_get_array(struct mixer_ctl *ctl, void *array, size_t count);
    290 int mixer_ctl_set_value(struct mixer_ctl *ctl, unsigned int id, int value);
    291 int mixer_ctl_set_array(struct mixer_ctl *ctl, const void *array, size_t count);
    292 int mixer_ctl_set_enum_by_string(struct mixer_ctl *ctl, const char *string);
    293 
    294 /* Determe range of integer mixer controls */
    295 int mixer_ctl_get_range_min(struct mixer_ctl *ctl);
    296 int mixer_ctl_get_range_max(struct mixer_ctl *ctl);
    297 
    298 #if defined(__cplusplus)
    299 }  /* extern "C" */
    300 #endif
    301 
    302 #endif
    303