Added more doxygen comments in pcm_extplug and pcm_ioplug codes.
../src/pcm/pcm_asym.c \
../src/pcm/pcm_iec958.c \
../src/pcm/pcm_softvol.c \
+ ../src/pcm/pcm_extplug.c \
+ ../src/pcm/pcm_ioplug.c \
../src/pcm/pcm_misc.c \
../src/rawmidi \
../src/timer \
#ifndef __ALSA_PCM_EXTPLUG_H
#define __ALSA_PCM_EXTPLUG_H
-/* hw constraints */
+/** hw constraints for extplug */
enum {
- SND_PCM_EXTPLUG_HW_FORMAT,
- SND_PCM_EXTPLUG_HW_CHANNELS,
- SND_PCM_EXTPLUG_HW_PARAMS
+ SND_PCM_EXTPLUG_HW_FORMAT, /**< format */
+ SND_PCM_EXTPLUG_HW_CHANNELS, /**< channels */
+ SND_PCM_EXTPLUG_HW_PARAMS /**< max number of hw constraints */
};
typedef struct snd_pcm_extplug snd_pcm_extplug_t;
typedef struct snd_pcm_extplug_callback snd_pcm_extplug_callback_t;
-/* exported pcm data */
+/** handle of extplug */
struct snd_pcm_extplug {
- /* must be filled before calling snd_pcm_extplug_create() */
+ /**
+ * name of this plugin; must be filled before calling #snd_pcm_extplug_create()
+ */
const char *name;
+ /**
+ * callbacks of this plugin; must be filled before calling #snd_pcm_extplug_create()
+ */
const snd_pcm_extplug_callback_t *callback;
+ /**
+ * private data, which can be used freely in the driver callbacks
+ */
void *private_data;
- /* filled by snd_pcm_extplug_open() */
+ /**
+ * PCM handle filled by #snd_pcm_extplug_create()
+ */
snd_pcm_t *pcm;
- /* read-only status */
+ /**
+ * stream direction; read-only status
+ */
snd_pcm_stream_t stream;
- /* filled in hw_params */
+ /**
+ * format hw parameter; filled after hw_params is caled
+ */
snd_pcm_format_t format;
+ /**
+ * subformat hw parameter; filled after hw_params is caled
+ */
snd_pcm_subformat_t subformat;
+ /**
+ * channels hw parameter; filled after hw_params is caled
+ */
unsigned int channels;
+ /**
+ * rate hw parameter; filled after hw_params is caled
+ */
unsigned int rate;
+ /**
+ * slave_format hw parameter; filled after hw_params is caled
+ */
snd_pcm_format_t slave_format;
+ /**
+ * slave_subformat hw parameter; filled after hw_params is caled
+ */
snd_pcm_subformat_t slave_subformat;
+ /**
+ * slave_channels hw parameter; filled after hw_params is caled
+ */
unsigned int slave_channels;
};
-/* callback table */
+/** callback table of extplug */
struct snd_pcm_extplug_callback {
- /* required */
+ /**
+ * transfer between source and destination; this is a required callback
+ */
snd_pcm_sframes_t (*transfer)(snd_pcm_extplug_t *ext,
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,
snd_pcm_uframes_t size);
+ /**
+ * close the PCM; optional
+ */
int (*close)(snd_pcm_extplug_t *ext);
+ /**
+ * hw_params; optional
+ */
int (*hw_params)(snd_pcm_extplug_t *ext, snd_pcm_hw_params_t *params);
+ /**
+ * hw_free; optional
+ */
int (*hw_free)(snd_pcm_extplug_t *ext);
+ /**
+ * dump; optional
+ */
void (*dump)(snd_pcm_extplug_t *ext, snd_output_t *out);
};
#ifndef __ALSA_PCM_IOPLUG_H
#define __ALSA_PCM_IOPLUG_H
-/* hw constraints */
+/** hw constraints for ioplug */
enum {
- SND_PCM_IOPLUG_HW_ACCESS = 0,
- SND_PCM_IOPLUG_HW_FORMAT,
- SND_PCM_IOPLUG_HW_CHANNELS,
- SND_PCM_IOPLUG_HW_RATE,
- SND_PCM_IOPLUG_HW_PERIOD_BYTES,
- SND_PCM_IOPLUG_HW_BUFFER_BYTES,
- SND_PCM_IOPLUG_HW_PERIODS,
- SND_PCM_IOPLUG_HW_PARAMS
+ SND_PCM_IOPLUG_HW_ACCESS = 0, /**< access type */
+ SND_PCM_IOPLUG_HW_FORMAT, /**< format */
+ SND_PCM_IOPLUG_HW_CHANNELS, /**< channels */
+ SND_PCM_IOPLUG_HW_RATE, /**< rate */
+ SND_PCM_IOPLUG_HW_PERIOD_BYTES, /**< period bytes */
+ SND_PCM_IOPLUG_HW_BUFFER_BYTES, /**< buffer bytes */
+ SND_PCM_IOPLUG_HW_PERIODS, /**< number of periods */
+ SND_PCM_IOPLUG_HW_PARAMS /**< max number of hw constraints */
};
typedef struct snd_pcm_ioplug snd_pcm_ioplug_t;
typedef struct snd_pcm_ioplug_callback snd_pcm_ioplug_callback_t;
-#define SND_PCM_IOPLUG_FLAG_LISTED (1<<0)
+/**
+ * bit flags for additional conditions
+ */
+#define SND_PCM_IOPLUG_FLAG_LISTED (1<<0) /* list up this PCM */
-/* exported pcm data */
+/** handle of ioplug */
struct snd_pcm_ioplug {
- /* must be filled before calling snd_pcm_ioplug_create() */
+ /**
+ * name of this plugin; must be filled before calling #snd_pcm_ioplug_create()
+ */
const char *name;
- unsigned int flags; /* SND_PCM_IOPLUG_FLAG_XXX */
- int poll_fd;
- unsigned int poll_events;
- unsigned int mmap_rw; /* pseudo mmap */
+ unsigned int flags; /**< SND_PCM_IOPLUG_FLAG_XXX */
+ int poll_fd; /**< poll file descriptor */
+ unsigned int poll_events; /**< poll events */
+ unsigned int mmap_rw; /**< pseudo mmap mode */
+ /**
+ * callbacks of this plugin; must be filled before calling #snd_pcm_ioplug_create()
+ */
const snd_pcm_ioplug_callback_t *callback;
+ /**
+ * private data, which can be used freely in the driver callbacks
+ */
void *private_data;
- /* filled by snd_pcm_ioplug_open() */
+ /**
+ * PCM handle filled by #snd_pcm_extplug_create()
+ */
snd_pcm_t *pcm;
- /* read-only status */
- snd_pcm_stream_t stream;
- snd_pcm_state_t state;
- volatile snd_pcm_uframes_t appl_ptr;
- volatile snd_pcm_uframes_t hw_ptr;
- int nonblock;
- /* filled in hw_params */
- snd_pcm_access_t access;
- snd_pcm_format_t format;
- unsigned int channels;
- unsigned int rate;
- snd_pcm_uframes_t period_size;
- snd_pcm_uframes_t buffer_size;
+
+ snd_pcm_stream_t stream; /* stream direcion; read-only */
+ snd_pcm_state_t state; /* current PCM state; read-only */
+ volatile snd_pcm_uframes_t appl_ptr; /* application pointer; read-only */
+ volatile snd_pcm_uframes_t hw_ptr; /* hw pointer; read-only */
+ int nonblock; /* non-block mode; read-only */
+
+ snd_pcm_access_t access; /* access type; filled after hw_params is called */
+ snd_pcm_format_t format; /* format; filled after hw_params is called */
+ unsigned int channels; /* channels; filled after hw_params is called */
+ unsigned int rate; /* rate; filled after hw_params is called */
+ snd_pcm_uframes_t period_size; /* period size; filled after hw_params is called */
+ snd_pcm_uframes_t buffer_size; /* buffer size; filled after hw_params is called */
};
-/* callback table */
+/** callback table of ioplug */
struct snd_pcm_ioplug_callback {
- /* required */
+ /**
+ * start the PCM; required
+ */
int (*start)(snd_pcm_ioplug_t *io);
+ /**
+ * stop the PCM; required
+ */
int (*stop)(snd_pcm_ioplug_t *io);
+ /**
+ * get the current DMA position; required
+ */
snd_pcm_sframes_t (*pointer)(snd_pcm_ioplug_t *io);
- /* optional */
+ /**
+ * transfer the data; optional
+ */
snd_pcm_sframes_t (*transfer)(snd_pcm_ioplug_t *io,
const snd_pcm_channel_area_t *areas,
snd_pcm_uframes_t offset,
snd_pcm_uframes_t size);
+ /**
+ * close the PCM; optional
+ */
int (*close)(snd_pcm_ioplug_t *io);
+ /**
+ * hw_params; optional
+ */
int (*hw_params)(snd_pcm_ioplug_t *io, snd_pcm_hw_params_t *params);
+ /**
+ * hw_free; optional
+ */
int (*hw_free)(snd_pcm_ioplug_t *io);
+ /**
+ * sw_params; optional
+ */
int (*sw_params)(snd_pcm_ioplug_t *io, snd_pcm_sw_params_t *params);
+ /**
+ * prepare; optional
+ */
int (*prepare)(snd_pcm_ioplug_t *io);
+ /**
+ * drain; optional
+ */
int (*drain)(snd_pcm_ioplug_t *io);
+ /**
+ * toggle pause; optional
+ */
int (*pause)(snd_pcm_ioplug_t *io, int enable);
+ /**
+ * resume; optional
+ */
int (*resume)(snd_pcm_ioplug_t *io);
+ /**
+ * mangle poll events; optional
+ */
int (*poll_revents)(snd_pcm_ioplug_t *io, struct pollfd *pfd, unsigned int nfds, unsigned short *revents);
+ /**
+ * dump; optional
+ */
void (*dump)(snd_pcm_ioplug_t *io, snd_output_t *out);
};
snd_pcm_extplug_set_slave_param_list;
snd_pcm_extplug_set_slave_param_minmax;
+ snd_pcm_parse_control_id;
+
} ALSA_1.0.5;
/**
* \file pcm/pcm_extplug.c
* \ingroup Plugin_SDK
- * \brief External Plugin SDK
+ * \brief External Filter Plugin SDK
* \author Takashi Iwai <tiwai@suse.de>
* \date 2005
*/
#include "pcm_extplug.h"
#include "pcm_ext_parm.h"
+#ifndef DOC_HIDDEN
+
typedef struct snd_pcm_extplug_priv {
snd_pcm_plugin_t plug;
snd_pcm_extplug_t *data;
};
/*
+ * set min/max values for the given parameter
*/
-
int snd_ext_parm_set_minmax(struct snd_ext_parm *parm, unsigned int min, unsigned int max)
{
parm->num_list = 0;
return 0;
}
+/*
+ * set the list of available values for the given parameter
+ */
static int val_compar(const void *ap, const void *bp)
{
return *(const unsigned int *)ap - *(const unsigned int *)bp;
memset(parm, 0, sizeof(*parm));
}
+/*
+ * limit the interval to the given list
+ */
int snd_interval_list(snd_interval_t *ival, int num_list, unsigned int *list)
{
int imin, imax;
return changed;
}
+/*
+ * refine the interval parameter
+ */
int snd_ext_parm_interval_refine(snd_interval_t *ival, struct snd_ext_parm *parm, int type)
{
parm += type;
return 0;
}
+/*
+ * refine the mask parameter
+ */
int snd_ext_parm_mask_refine(snd_mask_t *mask, struct snd_ext_parm *parm, int type)
{
snd_mask_t bits;
/*
+ * hw_refine callback
*/
-
static int extplug_hw_refine(snd_pcm_hw_params_t *hw_params,
struct snd_ext_parm *parm)
{
snd_pcm_generic_hw_refine);
}
+/*
+ * hw_params callback
+ */
static int snd_pcm_extplug_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
{
return 0;
}
+/*
+ * hw_free callback
+ */
static int snd_pcm_extplug_hw_free(snd_pcm_t *pcm)
{
extplug_priv_t *ext = pcm->private_data;
return 0;
}
+/*
+ * write_areas skeleton - call transfer callback
+ */
static snd_pcm_uframes_t
snd_pcm_extplug_write_areas(snd_pcm_t *pcm,
const snd_pcm_channel_area_t *areas,
if (size > *slave_sizep)
size = *slave_sizep;
- ext->data->callback->transfer(ext->data, slave_areas, slave_offset,
- areas, offset, size);
+ size = ext->data->callback->transfer(ext->data, slave_areas, slave_offset,
+ areas, offset, size);
*slave_sizep = size;
return size;
}
+/*
+ * read_areas skeleton - call transfer callback
+ */
static snd_pcm_uframes_t
snd_pcm_extplug_read_areas(snd_pcm_t *pcm,
const snd_pcm_channel_area_t *areas,
if (size > *slave_sizep)
size = *slave_sizep;
- ext->data->callback->transfer(ext->data, areas, offset,
- slave_areas, slave_offset, size);
+ size = ext->data->callback->transfer(ext->data, areas, offset,
+ slave_areas, slave_offset, size);
*slave_sizep = size;
return size;
}
+/*
+ * dump setup
+ */
static void snd_pcm_extplug_dump(snd_pcm_t *pcm, snd_output_t *out)
{
extplug_priv_t *ext = pcm->private_data;
.munmap = snd_pcm_generic_munmap,
};
+#endif /* !DOC_HIDDEN */
+
/*
+ * Exported functions
*/
-void snd_pcm_extplug_params_reset(snd_pcm_extplug_t *extplug)
-{
- extplug_priv_t *ext = extplug->pcm->private_data;
- clear_ext_params(ext);
-}
-int snd_pcm_extplug_set_slave_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list)
-{
- extplug_priv_t *ext = extplug->pcm->private_data;
- if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
- SNDERR("EXTPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- return snd_ext_parm_set_list(&ext->sparams[type], num_list, list);
-}
+/*! \page pcm_external_plugins
-int snd_pcm_extplug_set_slave_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max)
-{
- extplug_priv_t *ext = extplug->pcm->private_data;
- if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
- SNDERR("EXTPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- if (is_mask_type(type)) {
- SNDERR("EXTPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- return snd_ext_parm_set_minmax(&ext->sparams[type], min, max);
-}
+\section pcm_extplug External Plugin: Filter-Type Plugin
-int snd_pcm_extplug_set_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list)
-{
- extplug_priv_t *ext = extplug->pcm->private_data;
- if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
- SNDERR("EXTPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- return snd_ext_parm_set_list(&ext->params[type], num_list, list);
-}
+The filter-type plugin is a plugin to convert the PCM signals from the input
+and feeds to the output. Thus, this plugin always needs a slave PCM as its output.
-int snd_pcm_extplug_set_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max)
-{
- extplug_priv_t *ext = extplug->pcm->private_data;
- if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
- SNDERR("EXTPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- if (is_mask_type(type)) {
- SNDERR("EXTPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- return snd_ext_parm_set_minmax(&ext->params[type], min, max);
-}
+The plugin can modify the format and the channels of the input/output PCM.
+It can <i>not</i> modify the sample rate (because of simplicity reason).
-/*
+*/
+
+/**
+ * \brief Create an extplug instance
+ * \param extplug the extplug handle
+ * \param name name of the PCM
+ * \param root configuration tree root
+ * \param slave_conf slave configuration root
+ * \param stream stream direction
+ * \param mode PCM open mode
+ * \return 0 if successful, or a negative error code
+ *
+ * Creates the extplug instance based on the given handle.
+ * The slave_conf argument is mandatory, and usually taken from the config tree of the
+ * PCM plugin as "slave" config value.
+ * name, root, stream and mode arguments are the values used for opening the PCM.
+ *
+ * The callback is the mandatory field of extplug handle. At least, transfer callback
+ * must be set before calling this function.
*/
int snd_pcm_extplug_create(snd_pcm_extplug_t *extplug, const char *name,
snd_config_t *root, snd_config_t *slave_conf,
snd_pcm_t *spcm, *pcm;
snd_config_t *sconf;
+ assert(root);
assert(extplug && extplug->callback);
assert(extplug->callback->transfer);
+ assert(slave_conf);
err = snd_pcm_slave_conf(root, slave_conf, &sconf, 0);
if (err < 0)
return 0;
}
+/**
+ * \brief Delete the extplug instance
+ * \param extplug the extplug handle to delete
+ * \return 0 if successful, or a negative error code
+ *
+ * The destructor of extplug instance.
+ * Closes the PCM and deletes the associated resources.
+ */
int snd_pcm_extplug_delete(snd_pcm_extplug_t *extplug)
{
return snd_pcm_close(extplug->pcm);
}
+
+
+/**
+ * \brief Reset extplug parameters
+ * \param extplug the extplug handle
+ *
+ * Resets the all parameters for the given extplug handle.
+ */
+void snd_pcm_extplug_params_reset(snd_pcm_extplug_t *extplug)
+{
+ extplug_priv_t *ext = extplug->pcm->private_data;
+ clear_ext_params(ext);
+}
+
+/**
+ * \brief Set slave parameter as the list
+ * \param extplug the extplug handle
+ * \param type parameter type
+ * \param num_list number of available values
+ * \param list the list of available values
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the slave parameter as the list.
+ * The available values of the given parameter type of the slave PCM is restricted
+ * to the ones of the given list.
+ */
+int snd_pcm_extplug_set_slave_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list)
+{
+ extplug_priv_t *ext = extplug->pcm->private_data;
+ if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
+ SNDERR("EXTPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ return snd_ext_parm_set_list(&ext->sparams[type], num_list, list);
+}
+
+/**
+ * \brief Set slave parameter as the min/max values
+ * \param extplug the extplug handle
+ * \param type parameter type
+ * \param min the minimum value
+ * \param max the maximum value
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the slave parameter as the min/max values.
+ * The available values of the given parameter type of the slave PCM is restricted
+ * between the given minimum and maximum values.
+ */
+int snd_pcm_extplug_set_slave_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max)
+{
+ extplug_priv_t *ext = extplug->pcm->private_data;
+ if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
+ SNDERR("EXTPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ if (is_mask_type(type)) {
+ SNDERR("EXTPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ return snd_ext_parm_set_minmax(&ext->sparams[type], min, max);
+}
+
+/**
+ * \brief Set master parameter as the list
+ * \param extplug the extplug handle
+ * \param type parameter type
+ * \param num_list number of available values
+ * \param list the list of available values
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the master parameter as the list.
+ * The available values of the given parameter type of this PCM (as input) is restricted
+ * to the ones of the given list.
+ */
+int snd_pcm_extplug_set_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list)
+{
+ extplug_priv_t *ext = extplug->pcm->private_data;
+ if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
+ SNDERR("EXTPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ return snd_ext_parm_set_list(&ext->params[type], num_list, list);
+}
+
+/**
+ * \brief Set master parameter as the min/max values
+ * \param extplug the extplug handle
+ * \param type parameter type
+ * \param min the minimum value
+ * \param max the maximum value
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the master parameter as the min/max values.
+ * The available values of the given parameter type of this PCM (as input) is restricted
+ * between the given minimum and maximum values.
+ */
+int snd_pcm_extplug_set_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max)
+{
+ extplug_priv_t *ext = extplug->pcm->private_data;
+ if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
+ SNDERR("EXTPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ if (is_mask_type(type)) {
+ SNDERR("EXTPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ return snd_ext_parm_set_minmax(&ext->params[type], min, max);
+}
+
#include "pcm_ioplug.h"
#include "pcm_ext_parm.h"
+#ifndef DOC_HIDDEN
+
/* hw_params */
typedef struct snd_pcm_ioplug_priv {
snd_pcm_ioplug_t *data;
.mmap_commit = snd_pcm_ioplug_mmap_commit,
};
-void snd_pcm_ioplug_params_reset(snd_pcm_ioplug_t *ioplug)
-{
- ioplug_priv_t *io = ioplug->pcm->private_data;
- clear_io_params(io);
-}
+#endif /* !DOC_HIDDEN */
-int snd_pcm_ioplug_set_param_list(snd_pcm_ioplug_t *ioplug, int type, unsigned int num_list, const unsigned int *list)
-{
- ioplug_priv_t *io = ioplug->pcm->private_data;
- if (type < 0 && type >= SND_PCM_IOPLUG_HW_PARAMS) {
- SNDERR("IOPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- if (type == SND_PCM_IOPLUG_HW_PERIODS)
- io->params[type].integer = 1;
- return snd_ext_parm_set_list(&io->params[type], num_list, list);
-}
+/*
+ * Exported functions
+ */
-int snd_pcm_ioplug_set_param_minmax(snd_pcm_ioplug_t *ioplug, int type, unsigned int min, unsigned int max)
-{
- ioplug_priv_t *io = ioplug->pcm->private_data;
- if (type < 0 && type >= SND_PCM_IOPLUG_HW_PARAMS) {
- SNDERR("IOPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- if (type == SND_PCM_IOPLUG_HW_ACCESS || type == SND_PCM_IOPLUG_HW_FORMAT) {
- SNDERR("IOPLUG: invalid parameter type %d", type);
- return -EINVAL;
- }
- if (type == SND_PCM_IOPLUG_HW_PERIODS)
- io->params[type].integer = 1;
- return snd_ext_parm_set_minmax(&io->params[type], min, max);
-}
+/*! \page pcm_external_plugins
-int snd_pcm_ioplug_reinit_status(snd_pcm_ioplug_t *ioplug)
-{
- ioplug->pcm->poll_fd = ioplug->poll_fd;
- ioplug->pcm->poll_events = ioplug->poll_events;
- ioplug->pcm->mmap_rw = ioplug->mmap_rw;
- return 0;
-}
+\section pcm_ioplug External Plugin: I/O Plugin
-const snd_pcm_channel_area_t *snd_pcm_ioplug_mmap_areas(snd_pcm_ioplug_t *ioplug)
-{
- if (ioplug->mmap_rw)
- return snd_pcm_mmap_areas(ioplug->pcm);
- return NULL;
-}
+The I/O-type plugin is a PCM plugin to work as the input or output terminal point,
+i.e. as a user-space PCM driver.
+*/
+
+/**
+ * \brief Create an ioplug instance
+ * \param ioplug the ioplug handle
+ * \param name name of PCM
+ * \param stream stream direction
+ * \param mode PCM open mode
+ * \return 0 if successful, or a negative error code
+ *
+ * Creates the ioplug instance.
+ *
+ * The callback is the mandatory field of ioplug handle. At least, start, stop and
+ * pointer callbacks must be set before calling this function.
+ *
+ */
int snd_pcm_ioplug_create(snd_pcm_ioplug_t *ioplug, const char *name,
snd_pcm_stream_t stream, int mode)
{
return 0;
}
+/**
+ * \brief Delete the ioplug instance
+ * \param ioplug the ioplug handle
+ * \return 0 if successful, or a negative error code
+ */
int snd_pcm_ioplug_delete(snd_pcm_ioplug_t *ioplug)
{
return snd_pcm_close(ioplug->pcm);
}
+
+/**
+ * \brief Reset ioplug parameters
+ * \param ioplug the ioplug handle
+ *
+ * Resets the all parameters for the given ioplug handle.
+ */
+void snd_pcm_ioplug_params_reset(snd_pcm_ioplug_t *ioplug)
+{
+ ioplug_priv_t *io = ioplug->pcm->private_data;
+ clear_io_params(io);
+}
+
+/**
+ * \brief Set parameter as the list
+ * \param ioplug the ioplug handle
+ * \param type parameter type
+ * \param num_list number of available values
+ * \param list the list of available values
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the parameter as the list.
+ * The available values of the given parameter type is restricted to the ones of the given list.
+ */
+int snd_pcm_ioplug_set_param_list(snd_pcm_ioplug_t *ioplug, int type, unsigned int num_list, const unsigned int *list)
+{
+ ioplug_priv_t *io = ioplug->pcm->private_data;
+ if (type < 0 && type >= SND_PCM_IOPLUG_HW_PARAMS) {
+ SNDERR("IOPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ if (type == SND_PCM_IOPLUG_HW_PERIODS)
+ io->params[type].integer = 1;
+ return snd_ext_parm_set_list(&io->params[type], num_list, list);
+}
+
+/**
+ * \brief Set parameter as the min/max values
+ * \param ioplug the ioplug handle
+ * \param type parameter type
+ * \param min the minimum value
+ * \param max the maximum value
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the parameter as the min/max values.
+ * The available values of the given parameter type is restricted between the given
+ * minimum and maximum values.
+ */
+int snd_pcm_ioplug_set_param_minmax(snd_pcm_ioplug_t *ioplug, int type, unsigned int min, unsigned int max)
+{
+ ioplug_priv_t *io = ioplug->pcm->private_data;
+ if (type < 0 && type >= SND_PCM_IOPLUG_HW_PARAMS) {
+ SNDERR("IOPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ if (type == SND_PCM_IOPLUG_HW_ACCESS || type == SND_PCM_IOPLUG_HW_FORMAT) {
+ SNDERR("IOPLUG: invalid parameter type %d", type);
+ return -EINVAL;
+ }
+ if (type == SND_PCM_IOPLUG_HW_PERIODS)
+ io->params[type].integer = 1;
+ return snd_ext_parm_set_minmax(&io->params[type], min, max);
+}
+
+/**
+ * \brief Reinitialize the poll and mmap status
+ * \param ioplug the ioplug handle
+ * \return 0 if successful, or a negative error code
+ *
+ * Reinitializes the poll and the mmap status of the PCM.
+ * Call this function to propagate the status change in the ioplug instance to
+ * its PCM internals.
+ */
+int snd_pcm_ioplug_reinit_status(snd_pcm_ioplug_t *ioplug)
+{
+ ioplug->pcm->poll_fd = ioplug->poll_fd;
+ ioplug->pcm->poll_events = ioplug->poll_events;
+ ioplug->pcm->mmap_rw = ioplug->mmap_rw;
+ return 0;
+}
+
+/**
+ * \brief Get mmap area of ioplug
+ * \param ioplug the ioplug handle
+ * \return the mmap channel areas if available, or NULL
+ *
+ * Returns the mmap channel areas if available. When mmap_rw field is not set,
+ * this function always returns NULL.
+ */
+const snd_pcm_channel_area_t *snd_pcm_ioplug_mmap_areas(snd_pcm_ioplug_t *ioplug)
+{
+ if (ioplug->mmap_rw)
+ return snd_pcm_mmap_areas(ioplug->pcm);
+ return NULL;
+}
git://git.alsa-project.org / alsa-lib.git / commitdiff