From: Abramo Bagnara Date: Fri, 23 Mar 2001 11:05:41 +0000 (+0000) Subject: First part of PCM documentation X-Git-Tag: v1.0.3~914 X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=445e2b0c0799f889caa2a314ec928fa2b273f989;p=alsa-lib.git First part of PCM documentation --- diff --git a/include/pcm.h b/include/pcm.h index 8ae73336..7d7422e6 100644 --- a/include/pcm.h +++ b/include/pcm.h @@ -5,132 +5,202 @@ * * ****************************************************************************/ +/** PCM generic info container */ typedef struct _snd_pcm_info snd_pcm_info_t; +/** PCM hardware configuration space container */ typedef struct _snd_pcm_hw_params snd_pcm_hw_params_t; +/** PCM software configuration container */ typedef struct _snd_pcm_sw_params snd_pcm_sw_params_t; +/** PCM status container */ typedef struct _snd_pcm_status snd_pcm_status_t; +/** PCM access types mask */ typedef struct _snd_pcm_access_mask snd_pcm_access_mask_t; +/** PCM formats mask */ typedef struct _snd_pcm_format_mask snd_pcm_format_mask_t; +/** PCM subformats mask */ typedef struct _snd_pcm_subformat_mask snd_pcm_subformat_mask_t; -#ifdef SND_ENUM_TYPECHECK -typedef struct __snd_pcm_class *snd_pcm_class_t; -typedef struct __snd_pcm_subclass *snd_pcm_subclass_t; -typedef struct __snd_pcm_stream *snd_pcm_stream_t; -typedef struct __snd_pcm_access *snd_pcm_access_t; -typedef struct __snd_pcm_format *snd_pcm_format_t; -typedef struct __snd_pcm_subformat *snd_pcm_subformat_t; -typedef struct __snd_pcm_state *snd_pcm_state_t; -typedef struct __snd_pcm_start *snd_pcm_start_t; -typedef struct __snd_pcm_xrun *snd_pcm_xrun_t; -typedef struct __snd_pcm_tstamp *snd_pcm_tstamp_t; -#else -typedef enum sndrv_pcm_class snd_pcm_class_t; -typedef enum sndrv_pcm_subclass snd_pcm_subclass_t; -typedef enum sndrv_pcm_stream snd_pcm_stream_t; -typedef enum sndrv_pcm_access snd_pcm_access_t; -typedef enum sndrv_pcm_format snd_pcm_format_t; -typedef enum sndrv_pcm_subformat snd_pcm_subformat_t; -typedef enum sndrv_pcm_state snd_pcm_state_t; -typedef enum sndrv_pcm_start snd_pcm_start_t; -typedef enum sndrv_pcm_xrun snd_pcm_xrun_t; -typedef enum sndrv_pcm_tstamp snd_pcm_tstamp_t; -#endif - -#define SND_PCM_CLASS_GENERIC ((snd_pcm_class_t) SNDRV_PCM_CLASS_GENERIC) -#define SND_PCM_CLASS_MULTI ((snd_pcm_class_t) SNDRV_PCM_CLASS_MULTI) -#define SND_PCM_CLASS_MODEM ((snd_pcm_class_t) SNDRV_PCM_CLASS_MODEM) -#define SND_PCM_CLASS_DIGITIZER ((snd_pcm_class_t) SNDRV_PCM_CLASS_DIGITIZER) -#define SND_PCM_CLASS_LAST ((snd_pcm_class_t) SNDRV_PCM_CLASS_LAST) - -#define SND_PCM_SUBCLASS_GENERIC_MIX ((snd_pcm_subclass_t) SNDRV_PCM_SUBCLASS_GENERIC_MIX) -#define SND_PCM_SUBCLASS_MULTI_MIX ((snd_pcm_subclass_t) SNDRV_PCM_SUBCLASS_MULTI_MIX) -#define SND_PCM_SUBCLASS_LAST ((snd_pcm_subclass_t) SNDRV_PCM_SUBCLASS_LAST) - -#define SND_PCM_STREAM_PLAYBACK ((snd_pcm_stream_t) SNDRV_PCM_STREAM_PLAYBACK) -#define SND_PCM_STREAM_CAPTURE ((snd_pcm_stream_t) SNDRV_PCM_STREAM_CAPTURE) -#define SND_PCM_STREAM_LAST ((snd_pcm_stream_t) SNDRV_PCM_STREAM_LAST) - -#define SND_PCM_ACCESS_MMAP_INTERLEAVED ((snd_pcm_access_t) SNDRV_PCM_ACCESS_MMAP_INTERLEAVED) -#define SND_PCM_ACCESS_MMAP_NONINTERLEAVED ((snd_pcm_access_t) SNDRV_PCM_ACCESS_MMAP_NONINTERLEAVED) -#define SND_PCM_ACCESS_MMAP_COMPLEX ((snd_pcm_access_t) SNDRV_PCM_ACCESS_MMAP_COMPLEX) -#define SND_PCM_ACCESS_RW_INTERLEAVED ((snd_pcm_access_t) SNDRV_PCM_ACCESS_RW_INTERLEAVED) -#define SND_PCM_ACCESS_RW_NONINTERLEAVED ((snd_pcm_access_t) SNDRV_PCM_ACCESS_RW_NONINTERLEAVED) -#define SND_PCM_ACCESS_LAST ((snd_pcm_access_t) SNDRV_PCM_ACCESS_LAST) - -#define SND_PCM_FORMAT_UNKNOWN ((snd_pcm_format_t) -1) -#define SND_PCM_FORMAT_S8 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S8) -#define SND_PCM_FORMAT_U8 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U8) -#define SND_PCM_FORMAT_S16_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S16_LE) -#define SND_PCM_FORMAT_S16_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S16_BE) -#define SND_PCM_FORMAT_U16_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U16_LE) -#define SND_PCM_FORMAT_U16_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U16_BE) -#define SND_PCM_FORMAT_S24_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S24_LE) -#define SND_PCM_FORMAT_S24_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S24_BE) -#define SND_PCM_FORMAT_U24_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U24_LE) -#define SND_PCM_FORMAT_U24_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U24_BE) -#define SND_PCM_FORMAT_S32_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S32_LE) -#define SND_PCM_FORMAT_S32_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S32_BE) -#define SND_PCM_FORMAT_U32_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U32_LE) -#define SND_PCM_FORMAT_U32_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U32_BE) -#define SND_PCM_FORMAT_FLOAT_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_FLOAT_LE) -#define SND_PCM_FORMAT_FLOAT_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_FLOAT_BE) -#define SND_PCM_FORMAT_FLOAT64_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_FLOAT64_LE) -#define SND_PCM_FORMAT_FLOAT64_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_FLOAT64_BE) -#define SND_PCM_FORMAT_IEC958_SUBFRAME_LE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_IEC958_SUBFRAME_LE) -#define SND_PCM_FORMAT_IEC958_SUBFRAME_BE ((snd_pcm_format_t) SNDRV_PCM_FORMAT_IEC958_SUBFRAME_BE) -#define SND_PCM_FORMAT_MU_LAW ((snd_pcm_format_t) SNDRV_PCM_FORMAT_MU_LAW) -#define SND_PCM_FORMAT_A_LAW ((snd_pcm_format_t) SNDRV_PCM_FORMAT_A_LAW) -#define SND_PCM_FORMAT_IMA_ADPCM ((snd_pcm_format_t) SNDRV_PCM_FORMAT_IMA_ADPCM) -#define SND_PCM_FORMAT_MPEG ((snd_pcm_format_t) SNDRV_PCM_FORMAT_MPEG) -#define SND_PCM_FORMAT_GSM ((snd_pcm_format_t) SNDRV_PCM_FORMAT_GSM) -#define SND_PCM_FORMAT_SPECIAL ((snd_pcm_format_t) SNDRV_PCM_FORMAT_SPECIAL) -#define SND_PCM_FORMAT_LAST ((snd_pcm_format_t) SNDRV_PCM_FORMAT_LAST) -#define SND_PCM_FORMAT_S16 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S16) -#define SND_PCM_FORMAT_U16 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U16) -#define SND_PCM_FORMAT_S24 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S24) -#define SND_PCM_FORMAT_U24 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U24) -#define SND_PCM_FORMAT_S32 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S32) -#define SND_PCM_FORMAT_U32 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U32) -#define SND_PCM_FORMAT_FLOAT ((snd_pcm_format_t) SNDRV_PCM_FORMAT_FLOAT) -#define SND_PCM_FORMAT_FLOAT64 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_FLOAT64) -#define SND_PCM_FORMAT_IEC958_SUBFRAME ((snd_pcm_format_t) SNDRV_PCM_FORMAT_IEC958_SUBFRAME) -#define SND_PCM_FORMAT_S16 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S16) -#define SND_PCM_FORMAT_U16 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U16) -#define SND_PCM_FORMAT_S24 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S24) -#define SND_PCM_FORMAT_U24 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U24) -#define SND_PCM_FORMAT_S32 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_S32) -#define SND_PCM_FORMAT_U32 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_U32) -#define SND_PCM_FORMAT_FLOAT ((snd_pcm_format_t) SNDRV_PCM_FORMAT_FLOAT) -#define SND_PCM_FORMAT_FLOAT64 ((snd_pcm_format_t) SNDRV_PCM_FORMAT_FLOAT64) -#define SND_PCM_FORMAT_IEC958_SUBFRAME ((snd_pcm_format_t) SNDRV_PCM_FORMAT_IEC958_SUBFRAME) - -#define SND_PCM_SUBFORMAT_STD ((snd_pcm_subformat_t) SNDRV_PCM_SUBFORMAT_STD) -#define SND_PCM_SUBFORMAT_LAST ((snd_pcm_subformat_t) SNDRV_PCM_SUBFORMAT_LAST) - -#define SND_PCM_STATE_OPEN ((snd_pcm_state_t) SNDRV_PCM_STATE_OPEN) -#define SND_PCM_STATE_SETUP ((snd_pcm_state_t) SNDRV_PCM_STATE_SETUP) -#define SND_PCM_STATE_PREPARED ((snd_pcm_state_t) SNDRV_PCM_STATE_PREPARED) -#define SND_PCM_STATE_RUNNING ((snd_pcm_state_t) SNDRV_PCM_STATE_RUNNING) -#define SND_PCM_STATE_XRUN ((snd_pcm_state_t) SNDRV_PCM_STATE_XRUN) -#define SND_PCM_STATE_DRAINING ((snd_pcm_state_t) SNDRV_PCM_STATE_DRAINING) -#define SND_PCM_STATE_PAUSED ((snd_pcm_state_t) SNDRV_PCM_STATE_PAUSED) -#define SND_PCM_STATE_LAST ((snd_pcm_state_t) SNDRV_PCM_STATE_LAST) - -#define SND_PCM_START_DATA ((snd_pcm_start_t) SNDRV_PCM_START_DATA) -#define SND_PCM_START_EXPLICIT ((snd_pcm_start_t) SNDRV_PCM_START_EXPLICIT) -#define SND_PCM_START_LAST ((snd_pcm_start_t) SNDRV_PCM_START_LAST) - -#define SND_PCM_XRUN_NONE ((snd_pcm_xrun_t) SNDRV_PCM_XRUN_NONE) -#define SND_PCM_XRUN_STOP ((snd_pcm_xrun_t) SNDRV_PCM_XRUN_STOP) -#define SND_PCM_XRUN_LAST ((snd_pcm_xrun_t) SNDRV_PCM_XRUN_LAST) - -#define SND_PCM_TSTAMP_NONE ((snd_pcm_tstamp_t) SNDRV_PCM_TSTAMP_NONE) -#define SND_PCM_TSTAMP_MMAP ((snd_pcm_tstamp_t) SNDRV_PCM_TSTAMP_MMAP) -#define SND_PCM_TSTAMP_LAST ((snd_pcm_tstamp_t) SNDRV_PCM_TSTAMP_LAST) - +/** PCM class */ +typedef enum _snd_pcm_class { + /** standard device */ + SND_PCM_CLASS_GENERIC = SNDRV_PCM_CLASS_GENERIC, + /** multichannel device */ + SND_PCM_CLASS_MULTI = SNDRV_PCM_CLASS_MULTI, + /** software modem device */ + SND_PCM_CLASS_MODEM = SNDRV_PCM_CLASS_MODEM, + /** digitizer device */ + SND_PCM_CLASS_DIGITIZER = SNDRV_PCM_CLASS_DIGITIZER, + SND_PCM_CLASS_LAST = SNDRV_PCM_CLASS_LAST, +} snd_pcm_class_t; + +/** PCM subclass */ +typedef enum _snd_pcm_subclass { + /** subdevices are mixed together */ + SND_PCM_SUBCLASS_GENERIC_MIX = SNDRV_PCM_SUBCLASS_GENERIC_MIX, + /** multichannel subdevices are mixed together */ + SND_PCM_SUBCLASS_MULTI_MIX = SNDRV_PCM_SUBCLASS_MULTI_MIX, + SND_PCM_SUBCLASS_LAST = SNDRV_PCM_SUBCLASS_LAST, +} snd_pcm_subclass_t; + +/** PCM stream (direction) */ +typedef enum _snd_pcm_stream { + /** Playback stream */ + SND_PCM_STREAM_PLAYBACK = SNDRV_PCM_STREAM_PLAYBACK, + /** Capture stream */ + SND_PCM_STREAM_CAPTURE = SNDRV_PCM_STREAM_CAPTURE, + SND_PCM_STREAM_LAST = SNDRV_PCM_STREAM_LAST, +} snd_pcm_stream_t; + +/** PCM access type */ +typedef enum _snd_pcm_access { + /** mmap access with simple interleaved channels */ + SND_PCM_ACCESS_MMAP_INTERLEAVED = SNDRV_PCM_ACCESS_MMAP_INTERLEAVED, + /** mmap access with simple non interleaved channels */ + SND_PCM_ACCESS_MMAP_NONINTERLEAVED = SNDRV_PCM_ACCESS_MMAP_NONINTERLEAVED, + /** mmap access with complex placement */ + SND_PCM_ACCESS_MMAP_COMPLEX = SNDRV_PCM_ACCESS_MMAP_COMPLEX, + /** snd_pcm_readi/snd_pcm_writei access */ + SND_PCM_ACCESS_RW_INTERLEAVED = SNDRV_PCM_ACCESS_RW_INTERLEAVED, + /** snd_pcm_readn/snd_pcm_writen access */ + SND_PCM_ACCESS_RW_NONINTERLEAVED = SNDRV_PCM_ACCESS_RW_NONINTERLEAVED, + SND_PCM_ACCESS_LAST = SNDRV_PCM_ACCESS_LAST, +} snd_pcm_access_t; + +/** PCM sample format */ +typedef enum _snd_pcm_format { + /** Unknown */ + SND_PCM_FORMAT_UNKNOWN = -1, + /** Signed 8 bit */ + SND_PCM_FORMAT_S8 = SNDRV_PCM_FORMAT_S8, + /** Unsigned 8 bit */ + SND_PCM_FORMAT_U8 = SNDRV_PCM_FORMAT_U8, + /** Signed 16 bit Little Endian */ + SND_PCM_FORMAT_S16_LE = SNDRV_PCM_FORMAT_S16_LE, + /** Signed 16 bit Big Endian */ + SND_PCM_FORMAT_S16_BE = SNDRV_PCM_FORMAT_S16_BE, + /** Unsigned 16 bit Little Endian */ + SND_PCM_FORMAT_U16_LE = SNDRV_PCM_FORMAT_U16_LE, + /** Unsigned 16 bit Big Endian */ + SND_PCM_FORMAT_U16_BE = SNDRV_PCM_FORMAT_U16_BE, + /** Signed 24 bit Little Endian */ + SND_PCM_FORMAT_S24_LE = SNDRV_PCM_FORMAT_S24_LE, + /** Signed 24 bit Big Endian */ + SND_PCM_FORMAT_S24_BE = SNDRV_PCM_FORMAT_S24_BE, + /** Unsigned 24 bit Little Endian */ + SND_PCM_FORMAT_U24_LE = SNDRV_PCM_FORMAT_U24_LE, + /** Unsigned 24 bit Big Endian */ + SND_PCM_FORMAT_U24_BE = SNDRV_PCM_FORMAT_U24_BE, + /** Signed 32 bit Little Endian */ + SND_PCM_FORMAT_S32_LE = SNDRV_PCM_FORMAT_S32_LE, + /** Signed 32 bit Big Endian */ + SND_PCM_FORMAT_S32_BE = SNDRV_PCM_FORMAT_S32_BE, + /** Unsigned 32 bit Little Endian */ + SND_PCM_FORMAT_U32_LE = SNDRV_PCM_FORMAT_U32_LE, + /** Unsigned 32 bit Big Endian */ + SND_PCM_FORMAT_U32_BE = SNDRV_PCM_FORMAT_U32_BE, + /** Float 32 bit Little Endian */ + SND_PCM_FORMAT_FLOAT_LE = SNDRV_PCM_FORMAT_FLOAT_LE, + /** Float 32 bit Big Endian */ + SND_PCM_FORMAT_FLOAT_BE = SNDRV_PCM_FORMAT_FLOAT_BE, + /** Float 64 bit Little Endian */ + SND_PCM_FORMAT_FLOAT64_LE = SNDRV_PCM_FORMAT_FLOAT64_LE, + /** Float 64 bit Big Endian */ + SND_PCM_FORMAT_FLOAT64_BE = SNDRV_PCM_FORMAT_FLOAT64_BE, + /** IEC-958 Little Endian */ + SND_PCM_FORMAT_IEC958_SUBFRAME_LE = SNDRV_PCM_FORMAT_IEC958_SUBFRAME_LE, + /** IEC-958 Big Endian */ + SND_PCM_FORMAT_IEC958_SUBFRAME_BE = SNDRV_PCM_FORMAT_IEC958_SUBFRAME_BE, + /** Mu-Law */ + SND_PCM_FORMAT_MU_LAW = SNDRV_PCM_FORMAT_MU_LAW, + /** A-Law */ + SND_PCM_FORMAT_A_LAW = SNDRV_PCM_FORMAT_A_LAW, + /** Ima-ADPCM */ + SND_PCM_FORMAT_IMA_ADPCM = SNDRV_PCM_FORMAT_IMA_ADPCM, + /** MPEG */ + SND_PCM_FORMAT_MPEG = SNDRV_PCM_FORMAT_MPEG, + /** GSM */ + SND_PCM_FORMAT_GSM = SNDRV_PCM_FORMAT_GSM, + /** Special */ + SND_PCM_FORMAT_SPECIAL = SNDRV_PCM_FORMAT_SPECIAL, + SND_PCM_FORMAT_LAST = SNDRV_PCM_FORMAT_LAST, + /** Signed 16 bit CPU endian */ + SND_PCM_FORMAT_S16 = SNDRV_PCM_FORMAT_S16, + /** Unsigned 16 bit CPU endian */ + SND_PCM_FORMAT_U16 = SNDRV_PCM_FORMAT_U16, + /** Signed 24 bit CPU endian */ + SND_PCM_FORMAT_S24 = SNDRV_PCM_FORMAT_S24, + /** Unsigned 24 bit CPU endian */ + SND_PCM_FORMAT_U24 = SNDRV_PCM_FORMAT_U24, + /** Signed 32 bit CPU endian */ + SND_PCM_FORMAT_S32 = SNDRV_PCM_FORMAT_S32, + /** Unsigned 32 bit CPU endian */ + SND_PCM_FORMAT_U32 = SNDRV_PCM_FORMAT_U32, + /** Float 32 bit CPU endian */ + SND_PCM_FORMAT_FLOAT = SNDRV_PCM_FORMAT_FLOAT, + /** Float 64 bit CPU endian */ + SND_PCM_FORMAT_FLOAT64 = SNDRV_PCM_FORMAT_FLOAT64, + /** IEC-958 CPU Endian */ + SND_PCM_FORMAT_IEC958_SUBFRAME = SNDRV_PCM_FORMAT_IEC958_SUBFRAME, +} snd_pcm_format_t; + +/** PCM sample subformat */ +typedef enum _snd_pcm_subformat { + /** Standard */ + SND_PCM_SUBFORMAT_STD = SNDRV_PCM_SUBFORMAT_STD, + SND_PCM_SUBFORMAT_LAST = SNDRV_PCM_SUBFORMAT_LAST, +} snd_pcm_subformat_t; + +/** PCM state */ +typedef enum _snd_pcm_state { + /** Open */ + SND_PCM_STATE_OPEN = SNDRV_PCM_STATE_OPEN, + /** Setup installed */ + SND_PCM_STATE_SETUP = SNDRV_PCM_STATE_SETUP, + /** Ready to start */ + SND_PCM_STATE_PREPARED = SNDRV_PCM_STATE_PREPARED, + /** Running */ + SND_PCM_STATE_RUNNING = SNDRV_PCM_STATE_RUNNING, + /** Stopped: underrun (playback) or overrun (capture) detected */ + SND_PCM_STATE_XRUN = SNDRV_PCM_STATE_XRUN, + /** Draining: running (playback) or stopped (capture) */ + SND_PCM_STATE_DRAINING = SNDRV_PCM_STATE_DRAINING, + /** Paused */ + SND_PCM_STATE_PAUSED = SNDRV_PCM_STATE_PAUSED, + SND_PCM_STATE_LAST = SNDRV_PCM_STATE_LAST, +} snd_pcm_state_t; + +/** PCM start mode */ +typedef enum _snd_pcm_start { + /** Automatic start on data read/write */ + SND_PCM_START_DATA = SNDRV_PCM_START_DATA, + /** Explicit start */ + SND_PCM_START_EXPLICIT = SNDRV_PCM_START_EXPLICIT, + SND_PCM_START_LAST = SNDRV_PCM_START_LAST, +} snd_pcm_start_t; + +/** PCM xrun mode */ +typedef enum _snd_pcm_xrun { + /** Xrun detection disabled */ + SND_PCM_XRUN_NONE = SNDRV_PCM_XRUN_NONE, + /** Stop on xrun detection */ + SND_PCM_XRUN_STOP = SNDRV_PCM_XRUN_STOP, + SND_PCM_XRUN_LAST = SNDRV_PCM_XRUN_LAST, +} snd_pcm_xrun_t; + +/** PCM timestamp mode */ +typedef enum _snd_pcm_tstamp { + /** No timestamp */ + SND_PCM_TSTAMP_NONE = SNDRV_PCM_TSTAMP_NONE, + /** Update mmap'ed timestamp */ + SND_PCM_TSTAMP_MMAP = SNDRV_PCM_TSTAMP_MMAP, + SND_PCM_TSTAMP_LAST = SNDRV_PCM_TSTAMP_LAST, +} snd_pcm_tstamp_t; + +/** Unsigned frames quantity */ typedef sndrv_pcm_uframes_t snd_pcm_uframes_t; +/** Signed frames quantity */ typedef sndrv_pcm_sframes_t snd_pcm_sframes_t; +/** Timestamp */ typedef struct timeval snd_timestamp_t; #define SND_PCM_INFO_MMAP SNDRV_PCM_INFO_MMAP @@ -146,67 +216,69 @@ typedef struct timeval snd_timestamp_t; #define SND_PCM_INFO_HALF_DUPLEX SNDRV_PCM_INFO_HALF_DUPLEX #define SND_PCM_INFO_JOINT_DUPLEX SNDRV_PCM_INFO_JOINT_DUPLEX #define SND_PCM_INFO_SYNC_START SNDRV_PCM_INFO_SYNC_START -#define SND_PCM_MMAP_OFFSET_DATA SNDRV_PCM_MMAP_OFFSET_DATA -#define SND_PCM_MMAP_OFFSET_STATUS SNDRV_PCM_MMAP_OFFSET_STATUS -#define SND_PCM_MMAP_OFFSET_CONTROL SNDRV_PCM_MMAP_OFFSET_CONTROL +/** Non blocking mode \hideinitializer */ #define SND_PCM_NONBLOCK 0x0001 +/** Async notification \hideinitializer */ #define SND_PCM_ASYNC 0x0002 +/** PCM handle */ typedef struct _snd_pcm snd_pcm_t; +/** PCM type */ enum _snd_pcm_type { + /** Kernel level PCM */ SND_PCM_TYPE_HW, + /** One ore more linked PCM with exclusive access to selected + channels */ SND_PCM_TYPE_MULTI, + /** File writing plugin */ SND_PCM_TYPE_FILE, + /** Null endpoint PCM */ SND_PCM_TYPE_NULL, + /** Shared memory client PCM */ SND_PCM_TYPE_SHM, + /** INET client PCM (not yet implemented) */ SND_PCM_TYPE_INET, + /** Copying plugin */ SND_PCM_TYPE_COPY, + /** Linear format conversion PCM */ SND_PCM_TYPE_LINEAR, + /** A-Law format conversion PCM */ SND_PCM_TYPE_ALAW, + /** Mu-Law format conversion PCM */ SND_PCM_TYPE_MULAW, + /** IMA-ADPCM format conversion PCM */ SND_PCM_TYPE_ADPCM, + /** Rate conversion PCM */ SND_PCM_TYPE_RATE, + /** Attenuated static route PCM */ SND_PCM_TYPE_ROUTE, + /** Format adjusted PCM */ SND_PCM_TYPE_PLUG, + /** Sharing PCM */ SND_PCM_TYPE_SHARE, + /** Meter plugin */ SND_PCM_TYPE_METER, + /** Mixing PCM */ SND_PCM_TYPE_MIX, + /** Attenuated dynamic route PCM (not yet implemented) */ SND_PCM_TYPE_DROUTE, + /** Loopback server plugin (not yet implemented) */ SND_PCM_TYPE_LBSERVER, }; -#ifdef SND_ENUM_TYPECHECK -typedef struct __snd_pcm_type *snd_pcm_type_t; -#else +/** PCM type */ typedef enum _snd_pcm_type snd_pcm_type_t; -#endif - -#define SND_PCM_TYPE_HW ((snd_pcm_type_t) SND_PCM_TYPE_HW) -#define SND_PCM_TYPE_MULTI ((snd_pcm_type_t) SND_PCM_TYPE_MULTI) -#define SND_PCM_TYPE_FILE ((snd_pcm_type_t) SND_PCM_TYPE_FILE) -#define SND_PCM_TYPE_NULL ((snd_pcm_type_t) SND_PCM_TYPE_NULL) -#define SND_PCM_TYPE_SHM ((snd_pcm_type_t) SND_PCM_TYPE_SHM) -#define SND_PCM_TYPE_INET ((snd_pcm_type_t) SND_PCM_TYPE_INET) -#define SND_PCM_TYPE_COPY ((snd_pcm_type_t) SND_PCM_TYPE_COPY) -#define SND_PCM_TYPE_LINEAR ((snd_pcm_type_t) SND_PCM_TYPE_LINEAR) -#define SND_PCM_TYPE_ALAW ((snd_pcm_type_t) SND_PCM_TYPE_ALAW) -#define SND_PCM_TYPE_MULAW ((snd_pcm_type_t) SND_PCM_TYPE_MULAW) -#define SND_PCM_TYPE_ADPCM ((snd_pcm_type_t) SND_PCM_TYPE_ADPCM) -#define SND_PCM_TYPE_RATE ((snd_pcm_type_t) SND_PCM_TYPE_RATE) -#define SND_PCM_TYPE_ROUTE ((snd_pcm_type_t) SND_PCM_TYPE_ROUTE) -#define SND_PCM_TYPE_PLUG ((snd_pcm_type_t) SND_PCM_TYPE_PLUG) -#define SND_PCM_TYPE_SHARE ((snd_pcm_type_t) SND_PCM_TYPE_SHARE) -#define SND_PCM_TYPE_METER ((snd_pcm_type_t) SND_PCM_TYPE_METER) -#define SND_PCM_TYPE_MIX ((snd_pcm_type_t) SND_PCM_TYPE_MIX) -#define SND_PCM_TYPE_DROUTE ((snd_pcm_type_t) SND_PCM_TYPE_DROUTE) -#define SND_PCM_TYPE_LBSERVER ((snd_pcm_type_t) SND_PCM_TYPE_LBSERVER) +/** PCM area specification */ typedef struct _snd_pcm_channel_area { - void *addr; /* base address of channel samples */ - unsigned int first; /* offset to first sample in bits */ - unsigned int step; /* samples distance in bits */ + /** base address of channel samples */ + void *addr; + /** offset to first sample in bits */ + unsigned int first; + /** samples distance in bits */ + unsigned int step; } snd_pcm_channel_area_t; typedef struct _snd_pcm_scope snd_pcm_scope_t; diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c index fc7fa2d6..549d326b 100644 --- a/src/pcm/pcm.c +++ b/src/pcm/pcm.c @@ -1,3 +1,16 @@ +/** + * \file pcm.c + * \author Jaroslav Kysela + * \author Abramo Bagnara + * \date 2000-2001 + * + * PCM Interface is designed to write or read digital audio frames. A + * frame is the data unit converted into/from sound in one time unit + * (1/rate seconds), by example if you set your playback PCM rate to + * 44100 you'll hear 44100 frames per second. The size in bytes of a + * frame may be obtained from bits needed to store a sample and + * channels count. + */ /* * PCM Interface - main file * Copyright (c) 1998 by Jaroslav Kysela @@ -33,24 +46,54 @@ #include "pcm_local.h" #include "list.h" +/** + * \brief get identifier of PCM handle + * \param pcm a PCM handle + * \return ascii identifier of PCM handle + * + * Returns the ASCII identifier of given PCM handle. It's the same + * identifier as for snd_pcm_open(). + */ const char *snd_pcm_name(snd_pcm_t *pcm) { assert(pcm); return pcm->name; } +/** + * \brief get type of PCM handle + * \param pcm a PCM handle + * \return type of PCM handle + * + * Returns the type #snd_pcm_type_t of given PCM handle. + */ snd_pcm_type_t snd_pcm_type(snd_pcm_t *pcm) { assert(pcm); return pcm->type; } +/** + * \brief get stream for a PCM handle + * \param pcm a PCM handle + * \return stream of PCM handle + * + * Returns the type #snd_pcm_stream_t of given PCM handle. + */ snd_pcm_stream_t snd_pcm_stream(snd_pcm_t *pcm) { assert(pcm); return pcm->stream; } +/** + * \brief close PCM handle + * \param pcm PCM handle + * \return zero on success otherwise a negative error code + * + * Closes the specified PCM handle and frees all associated + * resources. + */ int snd_pcm_close(snd_pcm_t *pcm) { int ret = 0; @@ -75,6 +118,12 @@ int snd_pcm_close(snd_pcm_t *pcm) return 0; } +/** + * \brief set nonblock mode + * \param pcm PCM handle + * \param nonblock 0 = block, 1 = nonblock mode + * \return zero on success otherwise a negative error code + */ int snd_pcm_nonblock(snd_pcm_t *pcm, int nonblock) { int err; @@ -88,6 +137,15 @@ int snd_pcm_nonblock(snd_pcm_t *pcm, int nonblock) return 0; } +/** + * \brief set async mode + * \param pcm PCM handle + * \param sig Signal to raise: < 0 disable, 0 default (SIGIO) + * \param pid Process ID to signal: 0 current + * \return zero on success otherwise a negative error code + * + * A signal is raised every period. + */ int snd_pcm_async(snd_pcm_t *pcm, int sig, pid_t pid) { int err; @@ -106,24 +164,115 @@ int snd_pcm_async(snd_pcm_t *pcm, int sig, pid_t pid) return 0; } +/** + * \brief Obtain general (static) information for PCM handle + * \param pcm PCM handle + * \param info Information container + * \return zero on success otherwise a negative error code + */ int snd_pcm_info(snd_pcm_t *pcm, snd_pcm_info_t *info) { assert(pcm && info); return pcm->ops->info(pcm->op_arg, info); } +/** \brief Install one PCM hardware configuration choosen from a configuration space and #snd_pcm_prepare it + * \param pcm PCM handle + * \param params Configuration space definition container + * \return zero on success otherwise a negative error code + * + * The configuration is choosen fixing single parameters in this order: + * first access, first format, first subformat, min channels, min rate, + * min period time, max buffer size, min tick time + */ +int snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params) +{ + int err; + assert(pcm && params); + err = _snd_pcm_hw_params(pcm, params); + if (err >= 0) + err = snd_pcm_prepare(pcm); + return err; +} + +/** \brief Remove PCM hardware configuration and free associated resources + * \param pcm PCM handle + * \return zero on success otherwise a negative error code + */ +int snd_pcm_hw_free(snd_pcm_t *pcm) +{ + int err; + assert(pcm->setup); + assert(snd_pcm_state(pcm) <= SND_PCM_STATE_PREPARED); + if (pcm->mmap_channels) { + err = snd_pcm_munmap(pcm); + if (err < 0) + return err; + } + err = pcm->ops->hw_free(pcm->op_arg); + pcm->setup = 0; + return err; +} + +/** \brief Install PCM software configuration defined by params + * \param pcm PCM handle + * \param params Configuration container + * \return zero on success otherwise a negative error code + */ +int snd_pcm_sw_params(snd_pcm_t *pcm, snd_pcm_sw_params_t *params) +{ + int err; + err = pcm->ops->sw_params(pcm->op_arg, params); + if (err < 0) + return err; + pcm->start_mode = snd_pcm_sw_params_get_start_mode(params); + pcm->xrun_mode = snd_pcm_sw_params_get_xrun_mode(params); + pcm->tstamp_mode = snd_pcm_sw_params_get_tstamp_mode(params); + pcm->period_step = params->period_step; + pcm->sleep_min = params->sleep_min; + pcm->avail_min = params->avail_min; + pcm->xfer_align = params->xfer_align; + pcm->silence_threshold = params->silence_threshold; + pcm->silence_size = params->silence_size; + pcm->boundary = params->boundary; + return 0; +} + +/** + * \brief Obtain status (runtime) information for PCM handle + * \param pcm PCM handle + * \param status Status container + * \return zero on success otherwise a negative error code + */ int snd_pcm_status(snd_pcm_t *pcm, snd_pcm_status_t *status) { assert(pcm && status); return pcm->fast_ops->status(pcm->fast_op_arg, status); } +/** + * \brief Return PCM state + * \param pcm PCM handle + * \return PCM state #snd_pcm_state_t of given PCM handle + */ snd_pcm_state_t snd_pcm_state(snd_pcm_t *pcm) { assert(pcm); return pcm->fast_ops->state(pcm->fast_op_arg); } +/** + * \brief Obtain delay in frames for a running PCM handle + * \param pcm PCM handle + * \param delayp Returned delay + * \return zero on success otherwise a negative error code + * + * Delay is distance between current application frame position and + * sound frame position. + * It's positive and less than buffer size in normal situation, + * negative on playback underrun and greater than buffer size on + * capture overrun. + */ int snd_pcm_delay(snd_pcm_t *pcm, snd_pcm_sframes_t *delayp) { assert(pcm); @@ -131,6 +280,11 @@ int snd_pcm_delay(snd_pcm_t *pcm, snd_pcm_sframes_t *delayp) return pcm->fast_ops->delay(pcm->fast_op_arg, delayp); } +/** + * \brief Prepare PCM for use + * \param pcm PCM handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_prepare(snd_pcm_t *pcm) { assert(pcm); @@ -138,6 +292,13 @@ int snd_pcm_prepare(snd_pcm_t *pcm) return pcm->fast_ops->prepare(pcm->fast_op_arg); } +/** + * \brief Reset PCM position + * \param pcm PCM handle + * \return zero on success otherwise a negative error code + * + * Reduce PCM delay to 0. + */ int snd_pcm_reset(snd_pcm_t *pcm) { assert(pcm); @@ -145,6 +306,11 @@ int snd_pcm_reset(snd_pcm_t *pcm) return pcm->fast_ops->reset(pcm->fast_op_arg); } +/** + * \brief Start a PCM + * \param pcm PCM handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_start(snd_pcm_t *pcm) { assert(pcm); @@ -152,6 +318,11 @@ int snd_pcm_start(snd_pcm_t *pcm) return pcm->fast_ops->start(pcm->fast_op_arg); } +/** + * \brief Stop a PCM dropping pending frames + * \param pcm PCM handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_drop(snd_pcm_t *pcm) { assert(pcm); @@ -159,6 +330,15 @@ int snd_pcm_drop(snd_pcm_t *pcm) return pcm->fast_ops->drop(pcm->fast_op_arg); } +/** + * \brief Stop a PCM preserving pending frames + * \param pcm PCM handle + * \return zero on success otherwise a negative error code + * + * For playback wait for all pending frames to be played and then stop + * the PCM. + * For capture stop PCM permitting to retrieve residual frames. + */ int snd_pcm_drain(snd_pcm_t *pcm) { assert(pcm); @@ -166,6 +346,12 @@ int snd_pcm_drain(snd_pcm_t *pcm) return pcm->fast_ops->drain(pcm->fast_op_arg); } +/** + * \brief Pause/resume PCM + * \param pcm PCM handle + * \param pause 0 = resume, 1 = pause + * \return zero on success otherwise a negative error code + */ int snd_pcm_pause(snd_pcm_t *pcm, int enable) { assert(pcm); @@ -173,7 +359,13 @@ int snd_pcm_pause(snd_pcm_t *pcm, int enable) return pcm->fast_ops->pause(pcm->fast_op_arg, enable); } - +/** + * \brief Move application frame position backward + * \param pcm PCM handle + * \param frames wanted displacement in frames + * \return a positive number for actual displacement otherwise a + * negative error code + */ snd_pcm_sframes_t snd_pcm_rewind(snd_pcm_t *pcm, snd_pcm_uframes_t frames) { assert(pcm); @@ -182,6 +374,14 @@ snd_pcm_sframes_t snd_pcm_rewind(snd_pcm_t *pcm, snd_pcm_uframes_t frames) return pcm->fast_ops->rewind(pcm->fast_op_arg, frames); } +/** + * \brief Write interleaved frames to a PCM + * \param pcm PCM handle + * \param buffer frames containing buffer + * \param size frames to be written + * \return a positive number of frames actually written otherwise a + * negative error code + */ snd_pcm_sframes_t snd_pcm_writei(snd_pcm_t *pcm, const void *buffer, snd_pcm_uframes_t size) { assert(pcm); @@ -191,6 +391,14 @@ snd_pcm_sframes_t snd_pcm_writei(snd_pcm_t *pcm, const void *buffer, snd_pcm_ufr return _snd_pcm_writei(pcm, buffer, size); } +/** + * \brief Write non interleaved frames to a PCM + * \param pcm PCM handle + * \param bufs frames containing buffers (one for each channel) + * \param size frames to be written + * \return a positive number of frames actually written otherwise a + * negative error code + */ snd_pcm_sframes_t snd_pcm_writen(snd_pcm_t *pcm, void **bufs, snd_pcm_uframes_t size) { assert(pcm); @@ -200,6 +408,14 @@ snd_pcm_sframes_t snd_pcm_writen(snd_pcm_t *pcm, void **bufs, snd_pcm_uframes_t return _snd_pcm_writen(pcm, bufs, size); } +/** + * \brief Read interleaved frames from a PCM + * \param pcm PCM handle + * \param buffer frames containing buffer + * \param size frames to be written + * \return a positive number of frames actually read otherwise a + * negative error code + */ snd_pcm_sframes_t snd_pcm_readi(snd_pcm_t *pcm, void *buffer, snd_pcm_uframes_t size) { assert(pcm); @@ -209,6 +425,14 @@ snd_pcm_sframes_t snd_pcm_readi(snd_pcm_t *pcm, void *buffer, snd_pcm_uframes_t return _snd_pcm_readi(pcm, buffer, size); } +/** + * \brief Read non interleaved frames to a PCM + * \param pcm PCM handle + * \param bufs frames containing buffers (one for each channel) + * \param size frames to be written + * \return a positive number of frames actually read otherwise a + * negative error code + */ snd_pcm_sframes_t snd_pcm_readn(snd_pcm_t *pcm, void **bufs, snd_pcm_uframes_t size) { assert(pcm); @@ -218,9 +442,14 @@ snd_pcm_sframes_t snd_pcm_readn(snd_pcm_t *pcm, void **bufs, snd_pcm_uframes_t s return _snd_pcm_readn(pcm, bufs, size); } -/* FIXME */ -#define _snd_pcm_link_descriptor _snd_pcm_poll_descriptor - +/** + * \brief Link two PCMs + * \param pcm1 first PCM handle + * \param pcm2 first PCM handle + * \return zero on success otherwise a negative error code + * + * The two PCMs will start/stop/prepare in sync. + */ int snd_pcm_link(snd_pcm_t *pcm1, snd_pcm_t *pcm2) { int fd1 = _snd_pcm_link_descriptor(pcm1); @@ -234,6 +463,11 @@ int snd_pcm_link(snd_pcm_t *pcm1, snd_pcm_t *pcm2) return 0; } +/** + * \brief Remove a PCM from a linked group + * \param pcm PCM handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_unlink(snd_pcm_t *pcm) { int fd; @@ -245,12 +479,25 @@ int snd_pcm_unlink(snd_pcm_t *pcm) return 0; } -int _snd_pcm_poll_descriptor(snd_pcm_t *pcm) +/** + * \brief get count of poll descriptors for PCM handle + * \param pcm PCM handle + * \return count of poll descriptors + */ +int snd_pcm_poll_descriptors_count(snd_pcm_t *pcm) { assert(pcm); - return pcm->poll_fd; + return 1; } + +/** + * \brief get poll descriptors + * \param pcm PCM handle + * \param pfds array of poll descriptors + * \param space space in the poll descriptor array + * \return count of filled descriptors + */ int snd_pcm_poll_descriptors(snd_pcm_t *pcm, struct pollfd *pfds, unsigned int space) { assert(pcm); @@ -261,6 +508,7 @@ int snd_pcm_poll_descriptors(snd_pcm_t *pcm, struct pollfd *pfds, unsigned int s return 1; } +#ifndef DOC_HIDDEN #define STATE(v) [SND_PCM_STATE_##v] = #v #define STREAM(v) [SND_PCM_STREAM_##v] = #v #define READY(v) [SND_PCM_READY_##v] = #v @@ -277,12 +525,12 @@ int snd_pcm_poll_descriptors(snd_pcm_t *pcm, struct pollfd *pfds, unsigned int s #define FORMATD(v, d) [SND_PCM_FORMAT_##v] = d #define SUBFORMATD(v, d) [SND_PCM_SUBFORMAT_##v] = d -const char *snd_pcm_stream_names[] = { +static const char *snd_pcm_stream_names[] = { STREAM(PLAYBACK), STREAM(CAPTURE), }; -const char *snd_pcm_state_names[] = { +static const char *snd_pcm_state_names[] = { STATE(OPEN), STATE(SETUP), STATE(PREPARED), @@ -291,25 +539,7 @@ const char *snd_pcm_state_names[] = { STATE(PAUSED), }; -const char *snd_pcm_hw_param_names[] = { - HW_PARAM(ACCESS), - HW_PARAM(FORMAT), - HW_PARAM(SUBFORMAT), - HW_PARAM(SAMPLE_BITS), - HW_PARAM(FRAME_BITS), - HW_PARAM(CHANNELS), - HW_PARAM(RATE), - HW_PARAM(PERIOD_TIME), - HW_PARAM(PERIOD_SIZE), - HW_PARAM(PERIOD_BYTES), - HW_PARAM(PERIODS), - HW_PARAM(BUFFER_TIME), - HW_PARAM(BUFFER_SIZE), - HW_PARAM(BUFFER_BYTES), - HW_PARAM(TICK_TIME), -}; - -const char *snd_pcm_access_names[] = { +static const char *snd_pcm_access_names[] = { ACCESS(MMAP_INTERLEAVED), ACCESS(MMAP_NONINTERLEAVED), ACCESS(MMAP_COMPLEX), @@ -317,7 +547,7 @@ const char *snd_pcm_access_names[] = { ACCESS(RW_NONINTERLEAVED), }; -const char *snd_pcm_format_names[] = { +static const char *snd_pcm_format_names[] = { FORMAT(S8), FORMAT(U8), FORMAT(S16_LE), @@ -346,25 +576,25 @@ const char *snd_pcm_format_names[] = { FORMAT(SPECIAL), }; -const char *snd_pcm_format_descriptions[] = { - FORMATD(S8, "Signed 8-bit"), - FORMATD(U8, "Unsigned 8-bit"), - FORMATD(S16_LE, "Signed 16-bit Little Endian"), - FORMATD(S16_BE, "Signed 16-bit Big Endian"), - FORMATD(U16_LE, "Unsigned 16-bit Little Endian"), - FORMATD(U16_BE, "Unsigned 16-bit Big Endian"), - FORMATD(S24_LE, "Signed 24-bit Little Endian"), - FORMATD(S24_BE, "Signed 24-bit Big Endian"), - FORMATD(U24_LE, "Unsigned 24-bit Little Endian"), - FORMATD(U24_BE, "Unsigned 24-bit Big Endian"), - FORMATD(S32_LE, "Signed 32-bit Little Endian"), - FORMATD(S32_BE, "Signed 32-bit Big Endian"), - FORMATD(U32_LE, "Unsigned 32-bit Little Endian"), - FORMATD(U32_BE, "Unsigned 32-bit Big Endian"), - FORMATD(FLOAT_LE, "Float Little Endian"), - FORMATD(FLOAT_BE, "Float Big Endian"), - FORMATD(FLOAT64_LE, "Float64 Little Endian"), - FORMATD(FLOAT64_BE, "Float64 Big Endian"), +static const char *snd_pcm_format_descriptions[] = { + FORMATD(S8, "Signed 8 bit"), + FORMATD(U8, "Unsigned 8 bit"), + FORMATD(S16_LE, "Signed 16 bit Little Endian"), + FORMATD(S16_BE, "Signed 16 bit Big Endian"), + FORMATD(U16_LE, "Unsigned 16 bit Little Endian"), + FORMATD(U16_BE, "Unsigned 16 bit Big Endian"), + FORMATD(S24_LE, "Signed 24 bit Little Endian"), + FORMATD(S24_BE, "Signed 24 bit Big Endian"), + FORMATD(U24_LE, "Unsigned 24 bit Little Endian"), + FORMATD(U24_BE, "Unsigned 24 bit Big Endian"), + FORMATD(S32_LE, "Signed 32 bit Little Endian"), + FORMATD(S32_BE, "Signed 32 bit Big Endian"), + FORMATD(U32_LE, "Unsigned 32 bit Little Endian"), + FORMATD(U32_BE, "Unsigned 32 bit Big Endian"), + FORMATD(FLOAT_LE, "Float 32 bit Little Endian"), + FORMATD(FLOAT_BE, "Float 32 bit Big Endian"), + FORMATD(FLOAT64_LE, "Float 64 bit Little Endian"), + FORMATD(FLOAT64_BE, "Float 64 bit Big Endian"), FORMATD(IEC958_SUBFRAME_LE, "IEC-958 Little Endian"), FORMATD(IEC958_SUBFRAME_BE, "IEC-958 Big Endian"), FORMATD(MU_LAW, "Mu-Law"), @@ -375,53 +605,79 @@ const char *snd_pcm_format_descriptions[] = { FORMATD(SPECIAL, "Special"), }; -const char *snd_pcm_subformat_names[] = { +static const char *snd_pcm_subformat_names[] = { SUBFORMAT(STD), }; -const char *snd_pcm_subformat_descriptions[] = { +static const char *snd_pcm_subformat_descriptions[] = { SUBFORMATD(STD, "Standard"), }; -const char *snd_pcm_start_mode_names[] = { +static const char *snd_pcm_start_mode_names[] = { START(EXPLICIT), START(DATA), }; -const char *snd_pcm_xrun_mode_names[] = { +static const char *snd_pcm_xrun_mode_names[] = { XRUN(NONE), XRUN(STOP), }; -const char *snd_pcm_tstamp_mode_names[] = { +static const char *snd_pcm_tstamp_mode_names[] = { TSTAMP(NONE), TSTAMP(MMAP), }; +#endif +/** + * \brief get name of PCM stream + * \param stream PCM stream + * \return ascii name of PCM stream + */ const char *snd_pcm_stream_name(snd_pcm_stream_t stream) { assert(stream <= SND_PCM_STREAM_LAST); return snd_pcm_stream_names[snd_enum_to_int(stream)]; } +/** + * \brief get name of PCM access type + * \param access PCM access type + * \return ascii name of PCM access type + */ const char *snd_pcm_access_name(snd_pcm_access_t access) { assert(access <= SND_PCM_ACCESS_LAST); return snd_pcm_access_names[snd_enum_to_int(access)]; } +/** + * \brief get name of PCM sample format + * \param format PCM sample format + * \return ascii name of PCM sample format + */ const char *snd_pcm_format_name(snd_pcm_format_t format) { assert(format <= SND_PCM_FORMAT_LAST); return snd_pcm_format_names[snd_enum_to_int(format)]; } +/** + * \brief get description of PCM sample format + * \param format PCM sample format + * \return ascii description of PCM sample format + */ const char *snd_pcm_format_description(snd_pcm_format_t format) { assert(format <= SND_PCM_FORMAT_LAST); return snd_pcm_format_descriptions[snd_enum_to_int(format)]; } +/** + * \brief get PCM sample format from name + * \param name PCM sample format name (case insensitive) + * \return PCM sample format + */ snd_pcm_format_t snd_pcm_format_value(const char* name) { snd_pcm_format_t format; @@ -434,42 +690,78 @@ snd_pcm_format_t snd_pcm_format_value(const char* name) return SND_PCM_FORMAT_UNKNOWN; } +/** + * \brief get name of PCM sample subformat + * \param format PCM sample subformat + * \return ascii name of PCM sample subformat + */ const char *snd_pcm_subformat_name(snd_pcm_subformat_t subformat) { assert(subformat <= SND_PCM_SUBFORMAT_LAST); return snd_pcm_subformat_names[snd_enum_to_int(subformat)]; } -const char *snd_pcm_hw_param_name(snd_pcm_hw_param_t param) +/** + * \brief get description of PCM sample subformat + * \param subformat PCM sample subformat + * \return ascii description of PCM sample subformat + */ +const char *snd_pcm_subformat_description(snd_pcm_subformat_t subformat) { - assert(param <= SND_PCM_HW_PARAM_LAST); - return snd_pcm_hw_param_names[snd_enum_to_int(param)]; + assert(subformat <= SND_PCM_SUBFORMAT_LAST); + return snd_pcm_subformat_descriptions[snd_enum_to_int(subformat)]; } +/** + * \brief get name of PCM start mode setting + * \param mode PCM start mode + * \return ascii name of PCM start mode setting + */ const char *snd_pcm_start_mode_name(snd_pcm_start_t mode) { assert(mode <= SND_PCM_START_LAST); return snd_pcm_start_mode_names[snd_enum_to_int(mode)]; } +/** + * \brief get name of PCM xrun mode setting + * \param mode PCM xrun mode + * \return ascii name of PCM xrun mode setting + */ const char *snd_pcm_xrun_mode_name(snd_pcm_xrun_t mode) { assert(mode <= SND_PCM_XRUN_LAST); return snd_pcm_xrun_mode_names[snd_enum_to_int(mode)]; } +/** + * \brief get name of PCM tstamp mode setting + * \param mode PCM tstamp mode + * \return ascii name of PCM tstamp mode setting + */ const char *snd_pcm_tstamp_mode_name(snd_pcm_tstamp_t mode) { assert(mode <= SND_PCM_TSTAMP_LAST); return snd_pcm_tstamp_mode_names[snd_enum_to_int(mode)]; } +/** + * \brief get name of PCM state + * \param state PCM state + * \return ascii name of PCM state + */ const char *snd_pcm_state_name(snd_pcm_state_t state) { assert(state <= SND_PCM_STATE_LAST); return snd_pcm_state_names[snd_enum_to_int(state)]; } +/** + * \brief Dump current hardware setup for PCM + * \param pcm PCM handle + * \param out Output handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_dump_hw_setup(snd_pcm_t *pcm, snd_output_t *out) { assert(pcm); @@ -490,6 +782,12 @@ int snd_pcm_dump_hw_setup(snd_pcm_t *pcm, snd_output_t *out) return 0; } +/** + * \brief Dump current software setup for PCM + * \param pcm PCM handle + * \param out Output handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_dump_sw_setup(snd_pcm_t *pcm, snd_output_t *out) { assert(pcm); @@ -508,6 +806,12 @@ int snd_pcm_dump_sw_setup(snd_pcm_t *pcm, snd_output_t *out) return 0; } +/** + * \brief Dump current setup (hardware and software) for PCM + * \param pcm PCM handle + * \param out Output handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_dump_setup(snd_pcm_t *pcm, snd_output_t *out) { snd_pcm_dump_hw_setup(pcm, out); @@ -515,6 +819,12 @@ int snd_pcm_dump_setup(snd_pcm_t *pcm, snd_output_t *out) return 0; } +/** + * \brief Dump status + * \param status Status container + * \param out Output handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_status_dump(snd_pcm_status_t *status, snd_output_t *out) { assert(status); @@ -529,6 +839,12 @@ int snd_pcm_status_dump(snd_pcm_status_t *status, snd_output_t *out) return 0; } +/** + * \brief Dump PCM info + * \param pcm PCM handle + * \param out Output handle + * \return zero on success otherwise a negative error code + */ int snd_pcm_dump(snd_pcm_t *pcm, snd_output_t *out) { assert(pcm); @@ -537,6 +853,12 @@ int snd_pcm_dump(snd_pcm_t *pcm, snd_output_t *out) return 0; } +/** + * \brief Convert bytes in frames for a PCM + * \param pcm PCM handle + * \param bytes quantity in bytes + * \return quantity expressed in frames + */ snd_pcm_sframes_t snd_pcm_bytes_to_frames(snd_pcm_t *pcm, ssize_t bytes) { assert(pcm); @@ -544,6 +866,12 @@ snd_pcm_sframes_t snd_pcm_bytes_to_frames(snd_pcm_t *pcm, ssize_t bytes) return bytes * 8 / pcm->frame_bits; } +/** + * \brief Convert frames in bytes for a PCM + * \param pcm PCM handle + * \param frames quantity in frames + * \return quantity expressed in bytes + */ ssize_t snd_pcm_frames_to_bytes(snd_pcm_t *pcm, snd_pcm_sframes_t frames) { assert(pcm); @@ -551,6 +879,12 @@ ssize_t snd_pcm_frames_to_bytes(snd_pcm_t *pcm, snd_pcm_sframes_t frames) return frames * pcm->frame_bits / 8; } +/** + * \brief Convert bytes in samples for a PCM + * \param pcm PCM handle + * \param bytes quantity in bytes + * \return quantity expressed in samples + */ int snd_pcm_bytes_to_samples(snd_pcm_t *pcm, ssize_t bytes) { assert(pcm); @@ -558,6 +892,12 @@ int snd_pcm_bytes_to_samples(snd_pcm_t *pcm, ssize_t bytes) return bytes * 8 / pcm->sample_bits; } +/** + * \brief Convert samples in bytes for a PCM + * \param pcm PCM handle + * \param samples quantity in samples + * \return quantity expressed in bytes + */ ssize_t snd_pcm_samples_to_bytes(snd_pcm_t *pcm, int samples) { assert(pcm); @@ -565,6 +905,14 @@ ssize_t snd_pcm_samples_to_bytes(snd_pcm_t *pcm, int samples) return samples * pcm->sample_bits / 8; } +/** + * \brief Opens a PCM + * \param pcmp Returned PCM handle + * \param name ASCII identifier of the PCM handle + * \param stream Wanted stream + * \param mode Open mode (see #SND_PCM_NONBLOCK, #SND_PCM_ASYNC) + * \return a negative error code on failure or zero on success + */ int snd_pcm_open(snd_pcm_t **pcmp, const char *name, snd_pcm_stream_t stream, int mode) { @@ -706,30 +1054,12 @@ int snd_pcm_open(snd_pcm_t **pcmp, const char *name, return open_func(pcmp, name, pcm_conf, stream, mode); } -void snd_pcm_areas_from_buf(snd_pcm_t *pcm, snd_pcm_channel_area_t *areas, - void *buf) -{ - unsigned int channel; - unsigned int channels = pcm->channels; - for (channel = 0; channel < channels; ++channel, ++areas) { - areas->addr = buf; - areas->first = channel * pcm->sample_bits; - areas->step = pcm->frame_bits; - } -} - -void snd_pcm_areas_from_bufs(snd_pcm_t *pcm, snd_pcm_channel_area_t *areas, - void **bufs) -{ - unsigned int channel; - unsigned int channels = pcm->channels; - for (channel = 0; channel < channels; ++channel, ++areas, ++bufs) { - areas->addr = *bufs; - areas->first = 0; - areas->step = pcm->sample_bits; - } -} - +/** + * \brief Wait for a PCM to become ready + * \param pcm a PCM handle + * \param timeout maximum time in milliseconds to wait + * \return a negative error code on failure or zero on success + */ int snd_pcm_wait(snd_pcm_t *pcm, int timeout) { struct pollfd pfd; @@ -742,11 +1072,30 @@ int snd_pcm_wait(snd_pcm_t *pcm, int timeout) return 0; } +/** + * \brief Return number of frames ready to be read/written + * \param pcm a PCM handle + * \return a positive number of frames ready otherwise a negative + * error code + * + * On capture does all the actions needed to transport to application + * level all the ready frames across underlying layers. + */ snd_pcm_sframes_t snd_pcm_avail_update(snd_pcm_t *pcm) { return pcm->fast_ops->avail_update(pcm->fast_op_arg); } +/** + * \brief Advance PCM frame position in mmap buffer + * \param pcm a PCM handle + * \param size movement size + * \return a positive number of actual movement size otherwise a negative + * error code + * + * On playback does all the actions needed to transport the frames across + * underlying layers. + */ snd_pcm_sframes_t snd_pcm_mmap_forward(snd_pcm_t *pcm, snd_pcm_uframes_t size) { assert(size > 0); @@ -754,6 +1103,14 @@ snd_pcm_sframes_t snd_pcm_mmap_forward(snd_pcm_t *pcm, snd_pcm_uframes_t size) return pcm->fast_ops->mmap_forward(pcm->fast_op_arg, size); } +/** + * \brief Silence an area + * \param dst_area area specification + * \param dst_offset offset in frames inside area + * \param samples samples to silence + * \param format PCM sample format + * \return zero on success otherwise a negative error code + */ int snd_pcm_area_silence(const snd_pcm_channel_area_t *dst_area, snd_pcm_uframes_t dst_offset, unsigned int samples, snd_pcm_format_t format) { @@ -836,6 +1193,15 @@ int snd_pcm_area_silence(const snd_pcm_channel_area_t *dst_area, snd_pcm_uframes return 0; } +/** + * \brief Silence one or more areas + * \param dst_areas areas specification (one for each channel) + * \param dst_offset offset in frames inside area + * \param channels channels count + * \param frames frames to silence + * \param format PCM sample format + * \return zero on success otherwise a negative error code + */ int snd_pcm_areas_silence(const snd_pcm_channel_area_t *dst_areas, snd_pcm_uframes_t dst_offset, unsigned int channels, snd_pcm_uframes_t frames, snd_pcm_format_t format) { @@ -877,6 +1243,16 @@ int snd_pcm_areas_silence(const snd_pcm_channel_area_t *dst_areas, snd_pcm_ufram } +/** + * \brief Copy an area + * \param dst_area destination area specification + * \param dst_offset offset in frames inside destination area + * \param src_area source area specification + * \param src_offset offset in frames inside source area + * \param samples samples to copy + * \param format PCM sample format + * \return zero on success otherwise a negative error code + */ int snd_pcm_area_copy(const snd_pcm_channel_area_t *dst_area, snd_pcm_uframes_t dst_offset, const snd_pcm_channel_area_t *src_area, snd_pcm_uframes_t src_offset, unsigned int samples, snd_pcm_format_t format) @@ -973,6 +1349,17 @@ int snd_pcm_area_copy(const snd_pcm_channel_area_t *dst_area, snd_pcm_uframes_t return 0; } +/** + * \brief Copy one or more areas + * \param dst_areas destination areas specification (one for each channel) + * \param dst_offset offset in frames inside destination area + * \param src_areas source areas specification (one for each channel) + * \param src_offset offset in frames inside source area + * \param channels channels count + * \param frames frames to copy + * \param format PCM sample format + * \return zero on success otherwise a negative error code + */ int snd_pcm_areas_copy(const snd_pcm_channel_area_t *dst_areas, snd_pcm_uframes_t dst_offset, const snd_pcm_channel_area_t *src_areas, snd_pcm_uframes_t src_offset, unsigned int channels, snd_pcm_uframes_t frames, snd_pcm_format_t format) @@ -1024,6 +1411,38 @@ int snd_pcm_areas_copy(const snd_pcm_channel_area_t *dst_areas, snd_pcm_uframes_ return 0; } +#ifndef DOC_HIDDEN + +int _snd_pcm_poll_descriptor(snd_pcm_t *pcm) +{ + assert(pcm); + return pcm->poll_fd; +} + +void snd_pcm_areas_from_buf(snd_pcm_t *pcm, snd_pcm_channel_area_t *areas, + void *buf) +{ + unsigned int channel; + unsigned int channels = pcm->channels; + for (channel = 0; channel < channels; ++channel, ++areas) { + areas->addr = buf; + areas->first = channel * pcm->sample_bits; + areas->step = pcm->frame_bits; + } +} + +void snd_pcm_areas_from_bufs(snd_pcm_t *pcm, snd_pcm_channel_area_t *areas, + void **bufs) +{ + unsigned int channel; + unsigned int channels = pcm->channels; + for (channel = 0; channel < channels; ++channel, ++areas, ++bufs) { + areas->addr = *bufs; + areas->first = 0; + areas->step = pcm->sample_bits; + } +} + snd_pcm_sframes_t snd_pcm_read_areas(snd_pcm_t *pcm, const snd_pcm_channel_area_t *areas, snd_pcm_uframes_t offset, snd_pcm_uframes_t size, snd_pcm_xfer_areas_func_t func) @@ -1307,3 +1726,4 @@ int snd_pcm_slave_conf(snd_config_t *conf, const char **namep, return 0; } +#endif diff --git a/src/pcm/pcm_hw.c b/src/pcm/pcm_hw.c index d3dc3d3d..8858a15b 100644 --- a/src/pcm/pcm_hw.c +++ b/src/pcm/pcm_hw.c @@ -362,7 +362,7 @@ static int snd_pcm_hw_mmap_status(snd_pcm_t *pcm) snd_pcm_hw_t *hw = pcm->private_data; void *ptr; ptr = mmap(NULL, page_align(sizeof(struct sndrv_pcm_mmap_status)), PROT_READ, MAP_FILE|MAP_SHARED, - hw->fd, SND_PCM_MMAP_OFFSET_STATUS); + hw->fd, SNDRV_PCM_MMAP_OFFSET_STATUS); if (ptr == MAP_FAILED || ptr == NULL) { SYSERR("status mmap failed"); return -errno; @@ -377,7 +377,7 @@ static int snd_pcm_hw_mmap_control(snd_pcm_t *pcm) snd_pcm_hw_t *hw = pcm->private_data; void *ptr; ptr = mmap(NULL, page_align(sizeof(struct sndrv_pcm_mmap_control)), PROT_READ|PROT_WRITE, MAP_FILE|MAP_SHARED, - hw->fd, SND_PCM_MMAP_OFFSET_CONTROL); + hw->fd, SNDRV_PCM_MMAP_OFFSET_CONTROL); if (ptr == MAP_FAILED || ptr == NULL) { SYSERR("control mmap failed"); return -errno; diff --git a/src/pcm/pcm_local.h b/src/pcm/pcm_local.h index 83e31568..5c93e50a 100644 --- a/src/pcm/pcm_local.h +++ b/src/pcm/pcm_local.h @@ -181,6 +181,9 @@ typedef int snd_pcm_route_ttable_entry_t; #define FULL ROUTE_PLUGIN_RESOLUTION #endif +/* FIXME */ +#define _snd_pcm_link_descriptor _snd_pcm_poll_descriptor + int snd_pcm_hw_open(snd_pcm_t **pcm, const char *name, int card, int device, int subdevice, snd_pcm_stream_t stream, int mode); int snd_pcm_plug_open(snd_pcm_t **pcmp, const char *name, @@ -478,7 +481,6 @@ unsigned int snd_pcm_hw_param_get_min(const snd_pcm_hw_params_t *params, snd_pcm_hw_param_t var, int *dir); unsigned int snd_pcm_hw_param_get_max(const snd_pcm_hw_params_t *params, snd_pcm_hw_param_t var, int *dir); -const char *snd_pcm_hw_param_name(snd_pcm_hw_param_t var); int snd_pcm_hw_strategy_simple_near(snd_pcm_hw_strategy_t *strategy, int order, snd_pcm_hw_param_t var, unsigned int best, diff --git a/src/pcm/pcm_misc.c b/src/pcm/pcm_misc.c index e5bd581b..cd8e3782 100644 --- a/src/pcm/pcm_misc.c +++ b/src/pcm/pcm_misc.c @@ -236,6 +236,7 @@ ssize_t snd_pcm_format_size(snd_pcm_format_t format, size_t samples) return -EINVAL; return samples / 2; default: + assert(0); return -EINVAL; } } @@ -344,6 +345,9 @@ u_int64_t snd_pcm_format_silence_64(snd_pcm_format_t format) case SNDRV_PCM_FORMAT_GSM: case SNDRV_PCM_FORMAT_SPECIAL: return 0; + default: + assert(0); + return -EINVAL; } return 0; } diff --git a/src/pcm/pcm_params.c b/src/pcm/pcm_params.c index 0ca21bf3..1baaabd6 100644 --- a/src/pcm/pcm_params.c +++ b/src/pcm/pcm_params.c @@ -1151,6 +1151,32 @@ void snd_pcm_hw_param_dump(const snd_pcm_hw_params_t *params, assert(0); } +#define HW_PARAM(v) [SND_PCM_HW_PARAM_##v] = #v + +const char *snd_pcm_hw_param_names[] = { + HW_PARAM(ACCESS), + HW_PARAM(FORMAT), + HW_PARAM(SUBFORMAT), + HW_PARAM(SAMPLE_BITS), + HW_PARAM(FRAME_BITS), + HW_PARAM(CHANNELS), + HW_PARAM(RATE), + HW_PARAM(PERIOD_TIME), + HW_PARAM(PERIOD_SIZE), + HW_PARAM(PERIOD_BYTES), + HW_PARAM(PERIODS), + HW_PARAM(BUFFER_TIME), + HW_PARAM(BUFFER_SIZE), + HW_PARAM(BUFFER_BYTES), + HW_PARAM(TICK_TIME), +}; + +static const char *snd_pcm_hw_param_name(snd_pcm_hw_param_t param) +{ + assert(param <= SND_PCM_HW_PARAM_LAST); + return snd_pcm_hw_param_names[snd_enum_to_int(param)]; +} + int snd_pcm_hw_params_dump(snd_pcm_hw_params_t *params, snd_output_t *out) { unsigned int k; @@ -2152,47 +2178,3 @@ int _snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params) return err; } -int snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params) -{ - int err; - assert(pcm && params); - err = _snd_pcm_hw_params(pcm, params); - if (err >= 0) - err = snd_pcm_prepare(pcm); - return err; -} - -int snd_pcm_hw_free(snd_pcm_t *pcm) -{ - int err; - assert(pcm->setup); - assert(snd_pcm_state(pcm) <= SND_PCM_STATE_PREPARED); - if (pcm->mmap_channels) { - err = snd_pcm_munmap(pcm); - if (err < 0) - return err; - } - err = pcm->ops->hw_free(pcm->op_arg); - pcm->setup = 0; - return err; -} - -int snd_pcm_sw_params(snd_pcm_t *pcm, snd_pcm_sw_params_t *params) -{ - int err; - err = pcm->ops->sw_params(pcm->op_arg, params); - if (err < 0) - return err; - pcm->start_mode = snd_pcm_sw_params_get_start_mode(params); - pcm->xrun_mode = snd_pcm_sw_params_get_xrun_mode(params); - pcm->tstamp_mode = snd_pcm_sw_params_get_tstamp_mode(params); - pcm->period_step = params->period_step; - pcm->sleep_min = params->sleep_min; - pcm->avail_min = params->avail_min; - pcm->xfer_align = params->xfer_align; - pcm->silence_threshold = params->silence_threshold; - pcm->silence_size = params->silence_size; - pcm->boundary = params->boundary; - return 0; -} - diff --git a/src/rawmidi/rawmidi.c b/src/rawmidi/rawmidi.c index 02242c97..3f42f839 100644 --- a/src/rawmidi/rawmidi.c +++ b/src/rawmidi/rawmidi.c @@ -11,7 +11,7 @@ * * RawMidi devices are opened exclusively for a selected direction. * While more than one process may not open a given MIDI device in the same - * direction simultaneously, seperate processes may open a single MIDI device + * direction simultaneously, separate processes may open a single MIDI device * in different directions (i.e. process one opens a MIDI device in write * direction and process two opens the same device in read direction). MIDI * devices return EBUSY error to applications when other applications have @@ -44,11 +44,27 @@ #include #include "rawmidi_local.h" +/** + * \brief setup the default parameters + * \param rawmidi RawMidi handle + * \param params pointer to a snd_rawmidi_params_t structure + * \return zero on success otherwise a negative error code + */ +static int snd_rawmidi_params_default(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params) +{ + assert(rawmidi); + assert(params); + params->buffer_size = page_size(); + params->avail_min = 1; + params->no_active_sensing = 0; + return 0; +} + /** * \brief Opens a new connection to the RawMidi interface. - * \param inputp Returned input handle - * \param outputp Returned output handle - * \param name ASCII identifier of the RawMidi stream + * \param inputp Returned input handle (NULL if not wanted) + * \param outputp Returned output handle (NULL if not wanted) + * \param name ASCII identifier of the RawMidi handle * \param mode Open mode * \return a negative error code on failure or zero on success * @@ -161,31 +177,31 @@ int snd_rawmidi_open(snd_rawmidi_t **inputp, snd_rawmidi_t **outputp, } /** - * \brief close rawmidi handle - * \param rmidi rawmidi handle - * \return zero if success otherwise a negative error code + * \brief close RawMidi handle + * \param rawmidi RawMidi handle + * \return zero on success otherwise a negative error code * - * Closes the specified rawmidi handle and frees all associated + * Closes the specified RawMidi handle and frees all associated * resources. */ -int snd_rawmidi_close(snd_rawmidi_t *rmidi) +int snd_rawmidi_close(snd_rawmidi_t *rawmidi) { int err; - assert(rmidi); - if ((err = rmidi->ops->close(rmidi)) < 0) + assert(rawmidi); + if ((err = rawmidi->ops->close(rawmidi)) < 0) return err; - if (rmidi->name) - free(rmidi->name); - free(rmidi); + if (rawmidi->name) + free(rawmidi->name); + free(rawmidi); return 0; } /** - * \brief get identifier of rawmidi handle - * \param rawmidi a rawmidi handle - * \return ascii identifier of rawmidi handle + * \brief get identifier of RawMidi handle + * \param rawmidi a RawMidi handle + * \return ascii identifier of RawMidi handle * - * Returns the ASCII identifier of given rawmidi handle. It's the same + * Returns the ASCII identifier of given RawMidi handle. It's the same * identifier as for snd_rawmidi_open(). */ const char *snd_rawmidi_name(snd_rawmidi_t *rawmidi) @@ -195,11 +211,11 @@ const char *snd_rawmidi_name(snd_rawmidi_t *rawmidi) } /** - * \brief get type of rawmidi handle - * \param rawmidi a rawmidi handle - * \return type of rawmidi handle + * \brief get type of RawMidi handle + * \param rawmidi a RawMidi handle + * \return type of RawMidi handle * - * Returns the type #snd_rawmidi_type_t of given rawmidi handle. + * Returns the type #snd_rawmidi_type_t of given RawMidi handle. */ snd_rawmidi_type_t snd_rawmidi_type(snd_rawmidi_t *rawmidi) { @@ -208,29 +224,42 @@ snd_rawmidi_type_t snd_rawmidi_type(snd_rawmidi_t *rawmidi) } /** - * \brief get count of poll descriptors for rawmidi handle - * \param rmidi rawmidi handle + * \brief get stream (direction) of RawMidi handle + * \param rawmidi a RawMidi handle + * \return stream of RawMidi handle + * + * Returns the stream #snd_rawmidi_stream_t of given RawMidi handle. + */ +snd_rawmidi_stream_t snd_rawmidi_stream(snd_rawmidi_t *rawmidi) +{ + assert(rawmidi); + return rawmidi->stream; +} + +/** + * \brief get count of poll descriptors for RawMidi handle + * \param rawmidi RawMidi handle * \return count of poll descriptors */ -int snd_rawmidi_poll_descriptors_count(snd_rawmidi_t *rmidi) +int snd_rawmidi_poll_descriptors_count(snd_rawmidi_t *rawmidi) { - assert(rmidi); + assert(rawmidi); return 1; } /** * \brief get poll descriptors - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param pfds array of poll descriptors * \param space space in the poll descriptor array * \return count of filled descriptors */ -int snd_rawmidi_poll_descriptors(snd_rawmidi_t *rmidi, struct pollfd *pfds, unsigned int space) +int snd_rawmidi_poll_descriptors(snd_rawmidi_t *rawmidi, struct pollfd *pfds, unsigned int space) { - assert(rmidi); + assert(rawmidi); if (space >= 1) { - pfds->fd = rmidi->poll_fd; - pfds->events = rmidi->stream == SND_RAWMIDI_STREAM_OUTPUT ? POLLOUT : POLLIN; + pfds->fd = rawmidi->poll_fd; + pfds->events = rawmidi->stream == SND_RAWMIDI_STREAM_OUTPUT ? POLLOUT : POLLIN; return 1; } return 0; @@ -238,21 +267,21 @@ int snd_rawmidi_poll_descriptors(snd_rawmidi_t *rmidi, struct pollfd *pfds, unsi /** * \brief set nonblock mode - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param nonblock 0 = block, 1 = nonblock mode - * \return zero if success otherwise a negative error code + * \return zero on success otherwise a negative error code */ -int snd_rawmidi_nonblock(snd_rawmidi_t *rmidi, int nonblock) +int snd_rawmidi_nonblock(snd_rawmidi_t *rawmidi, int nonblock) { int err; - assert(rmidi); - assert(!(rmidi->mode & SND_RAWMIDI_APPEND)); - if ((err = rmidi->ops->nonblock(rmidi, nonblock)) < 0) + assert(rawmidi); + assert(!(rawmidi->mode & SND_RAWMIDI_APPEND)); + if ((err = rawmidi->ops->nonblock(rawmidi, nonblock)) < 0) return err; if (nonblock) - rmidi->mode |= SND_RAWMIDI_NONBLOCK; + rawmidi->mode |= SND_RAWMIDI_NONBLOCK; else - rmidi->mode &= ~SND_RAWMIDI_NONBLOCK; + rawmidi->mode &= ~SND_RAWMIDI_NONBLOCK; return 0; } @@ -268,7 +297,7 @@ size_t snd_rawmidi_info_sizeof() /** * \brief allocate a new snd_rawmidi_info_t structure * \param ptr returned pointer - * \return zero if success or a negative error code if fails + * \return zero on success or a negative error code if fails * * Allocates a new snd_rawmidi_params_t structure using the standard * malloc C library function. @@ -450,16 +479,16 @@ void snd_rawmidi_info_set_stream(snd_rawmidi_info_t *info, snd_rawmidi_stream_t } /** - * \brief get information about rawmidi handle - * \param rmidi rawmidi handle + * \brief get information about RawMidi handle + * \param rawmidi RawMidi handle * \param info pointer to a snd_rawmidi_info_t structure to be filled - * \return zero if success otherwise a negative error code + * \return zero on success otherwise a negative error code */ -int snd_rawmidi_info(snd_rawmidi_t *rmidi, snd_rawmidi_info_t * info) +int snd_rawmidi_info(snd_rawmidi_t *rawmidi, snd_rawmidi_info_t * info) { - assert(rmidi); + assert(rawmidi); assert(info); - return rmidi->ops->info(rmidi, info); + return rawmidi->ops->info(rawmidi, info); } /** @@ -474,7 +503,7 @@ size_t snd_rawmidi_params_sizeof() /** * \brief allocate the snd_rawmidi_params_t structure * \param ptr returned pointer - * \return zero if success or a negative error code if fails + * \return zero on success or a negative error code if fails * * Allocates a new snd_rawmidi_params_t structure using the standard * malloc C library function. @@ -512,32 +541,16 @@ void snd_rawmidi_params_copy(snd_rawmidi_params_t *dst, const snd_rawmidi_params *dst = *src; } -/** - * \brief setup the default parameters - * \param rmidi rawmidi handle - * \param params pointer to a snd_rawmidi_params_t structure - * \return zero if success otherwise a negative error code - */ -int snd_rawmidi_params_default(snd_rawmidi_t *rmidi, snd_rawmidi_params_t *params) -{ - assert(rmidi); - assert(params); - params->buffer_size = page_size(); - params->avail_min = 1; - params->no_active_sensing = 0; - return 0; -} - /** * \brief set rawmidi I/O ring buffer size - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param params pointer to a snd_rawmidi_params_t structure * \param val size in bytes - * \return zero if success otherwise a negative error code + * \return zero on success otherwise a negative error code */ -int snd_rawmidi_params_set_buffer_size(snd_rawmidi_t *rmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, size_t val) +int snd_rawmidi_params_set_buffer_size(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, size_t val) { - assert(rmidi && params); + assert(rawmidi && params); assert(val > params->avail_min); params->buffer_size = val; return 0; @@ -556,13 +569,13 @@ size_t snd_rawmidi_params_get_buffer_size(const snd_rawmidi_params_t *params) /** * \brief set minimum available bytes in rawmidi I/O ring buffer for wakeup - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param params pointer to a snd_rawmidi_params_t structure * \param val desired value */ -int snd_rawmidi_params_set_avail_min(snd_rawmidi_t *rmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, size_t val) +int snd_rawmidi_params_set_avail_min(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, size_t val) { - assert(rmidi && params); + assert(rawmidi && params); assert(val < params->buffer_size); params->avail_min = val; return 0; @@ -581,14 +594,14 @@ size_t snd_rawmidi_params_get_avail_min(const snd_rawmidi_params_t *params) /** * \brief set no-active-sensing action on snd_rawmidi_close() - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param params pointer to snd_rawmidi_params_t structure * \param val value: 0 = enable to send the active sensing message, 1 = disable - * \return zero if success otherwise a negative error code + * \return zero on success otherwise a negative error code */ -int snd_rawmidi_params_set_no_active_sensing(snd_rawmidi_t *rmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, int val) +int snd_rawmidi_params_set_no_active_sensing(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, int val) { - assert(rmidi && params); + assert(rawmidi && params); params->no_active_sensing = val; return 0; } @@ -606,37 +619,37 @@ int snd_rawmidi_params_get_no_active_sensing(const snd_rawmidi_params_t *params) /** * \brief get parameters about rawmidi stream - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param params pointer to a snd_rawmidi_params_t structure to be filled - * \return zero if success otherwise a negative error code + * \return zero on success otherwise a negative error code */ -int snd_rawmidi_params(snd_rawmidi_t *rmidi, snd_rawmidi_params_t * params) +int snd_rawmidi_params(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t * params) { int err; - assert(rmidi); + assert(rawmidi); assert(params); - err = rmidi->ops->params(rmidi, params); + err = rawmidi->ops->params(rawmidi, params); if (err < 0) return err; - rmidi->buffer_size = params->buffer_size; - rmidi->avail_min = params->avail_min; - rmidi->no_active_sensing = params->no_active_sensing; + rawmidi->buffer_size = params->buffer_size; + rawmidi->avail_min = params->avail_min; + rawmidi->no_active_sensing = params->no_active_sensing; return 0; } /** * \brief get current parameters about rawmidi stream - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param params pointer to a snd_rawmidi_params_t structure to be filled - * \return zero if success otherwise a negative error code + * \return zero on success otherwise a negative error code */ -int snd_rawmidi_params_current(snd_rawmidi_t *rmidi, snd_rawmidi_params_t *params) +int snd_rawmidi_params_current(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params) { - assert(rmidi); + assert(rawmidi); assert(params); - params->buffer_size = rmidi->buffer_size; - params->avail_min = rmidi->avail_min; - params->no_active_sensing = rmidi->no_active_sensing; + params->buffer_size = rawmidi->buffer_size; + params->avail_min = rawmidi->avail_min; + params->no_active_sensing = rawmidi->no_active_sensing; return 0; } @@ -652,7 +665,7 @@ size_t snd_rawmidi_status_sizeof() /** * \brief allocate the snd_rawmidi_status_t structure * \param ptr returned pointer - * \return zero if success or a negative error code if fails + * \return zero on success or a negative error code if fails * * Allocates a new snd_rawmidi_status_t structure using the standard * malloc C library function. @@ -725,66 +738,66 @@ size_t snd_rawmidi_status_get_xruns(const snd_rawmidi_status_t *status) /** * \brief get status of rawmidi stream - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param status pointer to a snd_rawmidi_status_t structure to be filled - * \return zero if success otherwise a negative error code + * \return zero on success otherwise a negative error code */ -int snd_rawmidi_status(snd_rawmidi_t *rmidi, snd_rawmidi_status_t * status) +int snd_rawmidi_status(snd_rawmidi_t *rawmidi, snd_rawmidi_status_t * status) { - assert(rmidi); + assert(rawmidi); assert(status); - return rmidi->ops->status(rmidi, status); + return rawmidi->ops->status(rawmidi, status); } /** * \brief drop all bytes in the rawmidi I/O ring buffer immediately - * \param rmidi rawmidi handle - * \return zero if success otherwise a negative error code + * \param rawmidi RawMidi handle + * \return zero on success otherwise a negative error code */ -int snd_rawmidi_drop(snd_rawmidi_t *rmidi) +int snd_rawmidi_drop(snd_rawmidi_t *rawmidi) { - assert(rmidi); - return rmidi->ops->drop(rmidi); + assert(rawmidi); + return rawmidi->ops->drop(rawmidi); } /** * \brief drain all bytes in the rawmidi I/O ring buffer - * \param rmidi rawmidi handle - * \return zero if success otherwise a negative error code + * \param rawmidi RawMidi handle + * \return zero on success otherwise a negative error code * * Waits until all MIDI bytes are not drained (sent) to the * hardware device. */ -int snd_rawmidi_drain(snd_rawmidi_t *rmidi) +int snd_rawmidi_drain(snd_rawmidi_t *rawmidi) { - assert(rmidi); - return rmidi->ops->drain(rmidi); + assert(rawmidi); + return rawmidi->ops->drain(rawmidi); } /** * \brief write MIDI bytes to MIDI stream - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param buffer buffer containing MIDI bytes * \param size output buffer size in bytes */ -ssize_t snd_rawmidi_write(snd_rawmidi_t *rmidi, const void *buffer, size_t size) +ssize_t snd_rawmidi_write(snd_rawmidi_t *rawmidi, const void *buffer, size_t size) { - assert(rmidi); - assert(rmidi->stream == SND_RAWMIDI_STREAM_OUTPUT); + assert(rawmidi); + assert(rawmidi->stream == SND_RAWMIDI_STREAM_OUTPUT); assert(buffer || size == 0); - return rmidi->ops->write(rmidi, buffer, size); + return rawmidi->ops->write(rawmidi, buffer, size); } /** * \brief read MIDI bytes from MIDI stream - * \param rmidi rawmidi handle + * \param rawmidi RawMidi handle * \param buffer buffer to store the input MIDI bytes * \param size input buffer size in bytes */ -ssize_t snd_rawmidi_read(snd_rawmidi_t *rmidi, void *buffer, size_t size) +ssize_t snd_rawmidi_read(snd_rawmidi_t *rawmidi, void *buffer, size_t size) { - assert(rmidi); - assert(rmidi->stream == SND_RAWMIDI_STREAM_INPUT); + assert(rawmidi); + assert(rawmidi->stream == SND_RAWMIDI_STREAM_INPUT); assert(buffer || size == 0); - return rmidi->ops->read(rmidi, buffer, size); + return rawmidi->ops->read(rawmidi, buffer, size); }