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, 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
    311