diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/tinyalsa/pcm.h | 182 |
1 files changed, 120 insertions, 62 deletions
diff --git a/include/tinyalsa/pcm.h b/include/tinyalsa/pcm.h index cfc2f1d..0b02e9d 100644 --- a/include/tinyalsa/pcm.h +++ b/include/tinyalsa/pcm.h @@ -26,6 +26,12 @@ ** DAMAGE. */ +/** @file */ + +/** @defgroup tinyalsa-pcm PCM Interface + * @brief All macros, structures and functions that make up the PCM interface. + */ + #ifndef TINYALSA_PCM_H #define TINYALSA_PCM_H @@ -36,61 +42,133 @@ extern "C" { #endif -/* - * PCM API +struct pcm; + +/** A flag that specifies that the PCM is an output. + * May not be bitwise AND'd with @ref PCM_IN. + * Used in @ref pcm_open. + * @ingroup tinyalsa-pcm */ +#define PCM_OUT 0x00000000 -struct pcm; +/** Specifies that the PCM is an input. + * May not be bitwise AND'd with @ref PCM_OUT. + * Used in @ref pcm_open. + * @ingroup tinyalsa-pcm + */ +#define PCM_IN 0x10000000 + +/** Specifies that the PCM will use mmap read and write methods. + * Used in @ref pcm_open. + * @ingroup tinyalsa-pcm + */ +#define PCM_MMAP 0x00000001 + +/** Specifies no interrupt requests. + * May only be bitwise AND'd with @ref PCM_MMAP. + * Used in @ref pcm_open. + * @ingroup tinyalsa-pcm + */ +#define PCM_NOIRQ 0x00000002 + +/* When set, calls to @ref pcm_write + * for a playback stream will not attempt + * to restart the stream in the case of an + * underflow, but will return -EPIPE instead. + * After the first -EPIPE error, the stream + * is considered to be stopped, and a second + * call to pcm_write will attempt to restart + * the stream. + * Used in @ref pcm_open. + * @ingroup tinyalsa-pcm + */ +#define PCM_NORESTART 0x00000004 + +/** Specifies monotonic timestamps. + * Used in @ref pcm_open. + * @ingroup tinyalsa-pcm + */ +#define PCM_MONOTONIC 0x00000008 + +/** For inputs, this means the PCM is recording audio samples. + * For outputs, this means the PCM is playing audio samples. + * @ingroup tinyalsa-pcm + */ +#define PCM_STATE_RUNNING 0x03 -#define PCM_OUT 0x00000000 -#define PCM_IN 0x10000000 -#define PCM_MMAP 0x00000001 -#define PCM_NOIRQ 0x00000002 -#define PCM_NORESTART 0x00000004 /* PCM_NORESTART - when set, calls to - * pcm_write for a playback stream will not - * attempt to restart the stream in the case - * of an underflow, but will return -EPIPE - * instead. After the first -EPIPE error, the - * stream is considered to be stopped, and a - * second call to pcm_write will attempt to - * restart the stream. - */ -#define PCM_MONOTONIC 0x00000008 /* see pcm_get_htimestamp */ - -/* PCM runtime states */ -#define PCM_STATE_RUNNING 3 -#define PCM_STATE_XRUN 4 -#define PCM_STATE_DRAINING 5 -#define PCM_STATE_SUSPENDED 7 -#define PCM_STATE_DISCONNECTED 8 - -/* Bit formats */ +/** For inputs, this means an underrun occured. + * For outputs, this means an overrun occured. + */ +#define PCM_STATE_XRUN 0x04 + +/** For outputs, this means audio samples are played. + * A PCM is in a draining state when it is coming to a stop. + */ +#define PCM_STATE_DRAINING 0x05 + +/** Means a PCM is suspended. + * @ingroup tinyalsa-pcm + */ +#define PCM_STATE_SUSPENDED 0x07 + +/** Means a PCM has been disconnected. + * @ingroup tinyalsa-pcm + */ +#define PCM_STATE_DISCONNECTED 0x08 + +/** Audio sample format of a PCM. + * The first letter specifiers whether the sample is signed or unsigned. + * The letter 'S' means signed. The letter 'U' means unsigned. + * The following number is the amount of bits that the sample occupies in memory. + * Following the underscore, specifiers whether the sample is big endian or little endian. + * The letters 'LE' mean little endian. + * The letters 'BE' mean big endian. + * This enumeration is used in the @ref config structure. + * @ingroup tinyalsa-pcm + */ enum pcm_format { + /** Signed, 8-bit */ PCM_FORMAT_S8 = 1, + /** Signed 16-bit, little endian */ PCM_FORMAT_S16_LE = 0, + /** Signed, 16-bit, big endian */ PCM_FORMAT_S16_BE = 2, + /** Signed, 24-bit (32-bit in memory), little endian */ PCM_FORMAT_S24_LE, + /** Signed, 24-bit (32-bit in memory), big endian */ PCM_FORMAT_S24_BE, + /** Signed, 24-bit, little endian */ PCM_FORMAT_S24_3LE, + /** Signed, 24-bit, big endian */ PCM_FORMAT_S24_3BE, + /** Signed, 32-bit, little endian */ PCM_FORMAT_S32_LE, + /** Signed, 32-bit, big endian */ PCM_FORMAT_S32_BE, + /** Max of the enumeration list, not an actual format. */ PCM_FORMAT_MAX }; -/* Bitmask has 256 bits (32 bytes) in asound.h */ +/** A bit mask of 256 bits (32 bytes) that describes some hardware parameters of a PCM */ struct pcm_mask { + /** bits of the bit mask */ unsigned int bits[32 / sizeof(unsigned int)]; }; -/* Configuration for a stream */ +/** Encapsulates the hardware and software parameters of a PCM. + * @ingroup tinyalsa-pcm + */ struct pcm_config { + /** The number of channels in a frame */ unsigned int channels; + /** The number of frames per second */ unsigned int rate; + /** The number of frames in a period */ unsigned int period_size; + /** The number of periods in a PCM */ unsigned int period_count; + /** The sample format of a PCM */ enum pcm_format format; - /* Values to use for the ALSA start, stop and silence thresholds. Setting * any one of these values to 0 will cause the default tinyalsa values to be * used instead. Tinyalsa defaults are as follows. @@ -104,21 +182,31 @@ struct pcm_config { unsigned int silence_threshold; }; -/* PCM parameters */ +/** Enumeration of a PCM's hardware parameters. + * Each of these parameters is either a mask or an interval. + * @ingroup tinyalsa-pcm + */ enum pcm_param { - /* mask parameters */ + /** A mask that represents the type of read or write method available (e.g. interleaved, mmap). */ PCM_PARAM_ACCESS, + /** A mask that represents the @ref pcm_format available (e.g. @ref PCM_FORMAT_S32_LE) */ PCM_PARAM_FORMAT, + /** A mask that represents the subformat available */ PCM_PARAM_SUBFORMAT, - /* interval parameters */ + /** An interval representing the range of sample bits available (e.g. 8 to 32) */ PCM_PARAM_SAMPLE_BITS, + /** An interval representing the range of frame bits available (e.g. 8 to 64) */ PCM_PARAM_FRAME_BITS, + /** An interval representing the range of channels available (e.g. 1 to 2) */ PCM_PARAM_CHANNELS, + /** An interval representing the range of rates available (e.g. 44100 to 192000) */ PCM_PARAM_RATE, PCM_PARAM_PERIOD_TIME, + /** The number of frames in a period */ PCM_PARAM_PERIOD_SIZE, PCM_PARAM_PERIOD_BYTES, + /** The number of periods for a PCM */ PCM_PARAM_PERIODS, PCM_PARAM_BUFFER_TIME, PCM_PARAM_BUFFER_SIZE, @@ -126,13 +214,11 @@ enum pcm_param PCM_PARAM_TICK_TIME, }; -/* Open and close a stream */ struct pcm *pcm_open(unsigned int card, unsigned int device, unsigned int flags, struct pcm_config *config); int pcm_close(struct pcm *pcm); int pcm_is_ready(struct pcm *pcm); -/* Obtain the parameters for a PCM */ struct pcm_params *pcm_params_get(unsigned int card, unsigned int device, unsigned int flags); void pcm_params_free(struct pcm_params *pcm_params); @@ -144,64 +230,36 @@ unsigned int pcm_params_get_min(struct pcm_params *pcm_params, unsigned int pcm_params_get_max(struct pcm_params *pcm_params, enum pcm_param param); -/* Returns the file descriptor associated with the pcm */ int pcm_get_file_descriptor(struct pcm *pcm); -/* Returns a human readable reason for the last error */ const char *pcm_get_error(struct pcm *pcm); -/* Returns the sample size in bits for a PCM format. - * As with ALSA formats, this is the storage size for the format, whereas the - * format represents the number of significant bits. For example, - * PCM_FORMAT_S24_LE uses 32 bits of storage. - */ unsigned int pcm_format_to_bits(enum pcm_format format); -/* Returns the buffer size (int frames) that should be used for pcm_write. */ unsigned int pcm_get_buffer_size(struct pcm *pcm); unsigned int pcm_frames_to_bytes(struct pcm *pcm, unsigned int frames); unsigned int pcm_bytes_to_frames(struct pcm *pcm, unsigned int bytes); -/* Returns available frames in pcm buffer and corresponding time stamp. - * The clock is CLOCK_MONOTONIC if flag PCM_MONOTONIC was specified in pcm_open, - * otherwise the clock is CLOCK_REALTIME. - * For an input stream, frames available are frames ready for the - * application to read. - * For an output stream, frames available are the number of empty frames available - * for the application to write. - */ int pcm_get_htimestamp(struct pcm *pcm, unsigned int *avail, struct timespec *tstamp); -/* Returns the subdevice on which the pcm has been opened */ unsigned int pcm_get_subdevice(struct pcm *pcm); -/* Write data to the fifo. - * Will start playback on the first write or on a write that - * occurs after a fifo underrun. - */ int pcm_write(struct pcm *pcm, const void *data, unsigned int count); int pcm_read(struct pcm *pcm, void *data, unsigned int count); -/* - * mmap() support. - */ int pcm_mmap_write(struct pcm *pcm, const void *data, unsigned int count); int pcm_mmap_read(struct pcm *pcm, void *data, unsigned int count); int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset, unsigned int *frames); int pcm_mmap_commit(struct pcm *pcm, unsigned int offset, unsigned int frames); -/* Prepare the PCM substream to be triggerable */ int pcm_prepare(struct pcm *pcm); -/* Start and stop a PCM channel that doesn't transfer data */ int pcm_start(struct pcm *pcm); int pcm_stop(struct pcm *pcm); -/* Interrupt driven API */ int pcm_wait(struct pcm *pcm, int timeout); -/* Get the pcm delay */ long pcm_get_delay(struct pcm *pcm); #if defined(__cplusplus) |