Added description of shm, null and rate plugins

doc/doxygen.cfg

@@ -38,6 +38,8 @@ INPUT            = index.doxygen \
 		   ../src/pcm/pcm_mmap.c \
                    ../src/pcm/pcm_plugin.c \
 		   ../src/pcm/pcm_hw.c \
+		   ../src/pcm/pcm_shm.c \
+		   ../src/pcm/pcm_null.c \
 		   ../src/pcm/pcm_copy.c \
 		   ../src/pcm/pcm_linear.c \
 		   ../src/pcm/pcm_lfloat.c \
@@ -45,6 +47,7 @@ INPUT            = index.doxygen \
 		   ../src/pcm/pcm_alaw.c \
 		   ../src/pcm/pcm_adpcm.c \
 		   ../src/pcm/pcm_route.c \
+		   ../src/pcm/pcm_rate.c \
 		   ../src/pcm/pcm_plug.c \
 		   ../src/pcm/pcm_file.c \
 		   ../src/pcm/pcm_multi.c \

src/pcm/pcm_hw.c

@@ -827,7 +827,7 @@ int snd_pcm_hw_open(snd_pcm_t **pcmp, const char *name,
 
 This plugin communicates directly with the ALSA kernel driver. It is a raw
 communication without any conversions. The emulation of mmap access can be
-optionally enabled, but expect a worse latency in the case.
+optionally enabled, but expect worse latency in the case.
 
 \code
 pcm.name {

src/pcm/pcm_ladspa.c

@@ -1185,6 +1185,11 @@ This plugin allows to apply a set of LADPSA plugins.
 The input and output format is always #SND_PCM_FORMAT_FLOAT (note: this type
 can be either little or big-endian depending on architecture).
 
+The policy duplicate means that there must be only one binding definition for
+channel zero. This definition is automatically duplicated for all channels.
+
+Instances of LADSPA plugins are created dynamically.
+
 \code
 pcm.name {
         type ladspa             # ALSA<->LADSPA PCM
@@ -1195,15 +1200,15 @@ pcm.name {
                 # or
                 pcm { }         # Slave PCM definition
         }
-	path STR		# Path (directory) with LADSPA plugins
+	[path STR]		# Path (directory) with LADSPA plugins
 	plugins |		# Definition for both directions
         playback_plugins |	# Definition for playback direction
 	capture_plugins {	# Definition for capture direction
 		N {		# Configuration for LADPSA plugin N
-			id INT		# LADSPA plugin ID (for example 1043)
+			[id INT]	# LADSPA plugin ID (for example 1043)
-			label STR	# LADSPA plugin label (for example 'delay_5s')
+			[label STR]	# LADSPA plugin label (for example 'delay_5s')
-			filename STR	# Full filename of .so library with LADSPA plugin code
+			[filename STR]	# Full filename of .so library with LADSPA plugin code
-			policy STR	# Policy can be 'none' or 'duplicate'
+			[policy STR]	# Policy can be 'none' or 'duplicate'
 			input | output {
 				bindings {
 					C INT or STR	# C - channel, INT - audio port index, STR - audio port name

src/pcm/pcm_null.c

@@ -1,3 +1,10 @@
+/**
+ * \file pcm/pcm_null.c
+ * \ingroup PCM_Plugins
+ * \brief PCM Null Plugin Interface
+ * \author Abramo Bagnara <abramo@alsa-project.org>
+ * \date 2000-2001
+ */
 /*
  *  PCM - Null plugin
  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>
@@ -30,6 +37,7 @@
 const char *_snd_module_pcm_null = "";
 #endif
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	snd_timestamp_t trigger_tstamp;
 	snd_pcm_state_t state;
@@ -38,6 +46,7 @@ typedef struct {
 	snd_pcm_uframes_t hw_ptr;
 	int poll_fd;
 } snd_pcm_null_t;
+#endif
 
 static int snd_pcm_null_close(snd_pcm_t *pcm)
 {
@@ -295,7 +304,7 @@ static void snd_pcm_null_dump(snd_pcm_t *pcm, snd_output_t *out)
 	}
 }
 
-snd_pcm_ops_t snd_pcm_null_ops = {
+static snd_pcm_ops_t snd_pcm_null_ops = {
 	close: snd_pcm_null_close,
 	info: snd_pcm_null_info,
 	hw_refine: snd_pcm_null_hw_refine,
@@ -310,7 +319,7 @@ snd_pcm_ops_t snd_pcm_null_ops = {
 	munmap: snd_pcm_null_munmap,
 };
 
-snd_pcm_fast_ops_t snd_pcm_null_fast_ops = {
+static snd_pcm_fast_ops_t snd_pcm_null_fast_ops = {
 	status: snd_pcm_null_status,
 	state: snd_pcm_null_state,
 	delay: snd_pcm_null_delay,
@@ -330,6 +339,17 @@ snd_pcm_fast_ops_t snd_pcm_null_fast_ops = {
 	mmap_commit: snd_pcm_null_mmap_commit,
 };
 
+/**
+ * \brief Creates a new null PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param stream Stream type
+ * \param mode Stream mode
+ * \retval zero on success otherwise a negative error code
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int snd_pcm_null_open(snd_pcm_t **pcmp, const char *name, snd_pcm_stream_t stream, int mode)
 {
 	snd_pcm_t *pcm;
@@ -375,6 +395,44 @@ int snd_pcm_null_open(snd_pcm_t **pcmp, const char *name, snd_pcm_stream_t strea
 	return 0;
 }
 
+/*! \page pcm_plugins
+
+\section pcm_plugins_null Plugin: Null
+
+This plugin discards contents of a PCM stream or creates a stream with zero
+samples.
+
+Note: This implementation uses devices /dev/null (playback, must be writeable)
+and /dev/full (capture, must be readable).
+
+\code
+pcm.name {
+        type null               # Null PCM
+}
+\endcode
+
+\subsection pcm_plugins_null_funcref Function reference
+
+<UL>
+  <LI>snd_pcm_null_open()
+  <LI>_snd_pcm_null_open()
+</UL>
+
+*/
+
+/**
+ * \brief Creates a new Null PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param root Root configuration node
+ * \param conf Configuration node with Null PCM description
+ * \param stream Stream type
+ * \param mode Stream mode
+ * \retval zero on success otherwise a negative error code
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int _snd_pcm_null_open(snd_pcm_t **pcmp, const char *name,
 		       snd_config_t *conf, 
 		       snd_pcm_stream_t stream, int mode)
@@ -392,4 +450,6 @@ int _snd_pcm_null_open(snd_pcm_t **pcmp, const char *name,
 	}
 	return snd_pcm_null_open(pcmp, name, stream, mode);
 }
+#ifndef DOC_HIDDEN
 SND_DLSYM_BUILD_VERSION(_snd_pcm_null_open, SND_PCM_DLSYM_VERSION);
+#endif

src/pcm/pcm_rate.c

@@ -1,3 +1,10 @@
+/**
+ * \file pcm/pcm_rate.c
+ * \ingroup PCM_Plugins
+ * \brief PCM Rate Plugin Interface
+ * \author Abramo Bagnara <abramo@alsa-project.org>
+ * \date 2000-2001
+ */
 /*
  *  PCM - Rate conversion
  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>
@@ -29,6 +36,8 @@
 const char *_snd_module_pcm_rate = "";
 #endif
 
+#ifndef DOC_HIDDEN
+
 #define DIV (1<<16)
 
 typedef struct {
@@ -212,6 +221,8 @@ static snd_pcm_uframes_t snd_pcm_rate_shrink(const snd_pcm_channel_area_t *dst_a
 	return src_frames1;
 }
 
+#endif /* DOC_HIDDEN */
+
 static int snd_pcm_rate_hw_refine_cprepare(snd_pcm_t *pcm ATTRIBUTE_UNUSED, snd_pcm_hw_params_t *params)
 {
 	int err;
@@ -479,7 +490,7 @@ static void snd_pcm_rate_dump(snd_pcm_t *pcm, snd_output_t *out)
 	snd_pcm_dump(rate->plug.slave, out);
 }
 
-snd_pcm_ops_t snd_pcm_rate_ops = {
+static snd_pcm_ops_t snd_pcm_rate_ops = {
 	close: snd_pcm_plugin_close,
 	info: snd_pcm_plugin_info,
 	hw_refine: snd_pcm_rate_hw_refine,
@@ -494,6 +505,20 @@ snd_pcm_ops_t snd_pcm_rate_ops = {
 	munmap: snd_pcm_plugin_munmap,
 };
 
+
+/**
+ * \brief Creates a new rate PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param sformat Slave format
+ * \param srate Slave rate
+ * \param slave Slave PCM handle
+ * \param close_slave When set, the slave PCM handle is closed with copy PCM
+ * \retval zero on success otherwise a negative error code
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sformat, unsigned int srate, snd_pcm_t *slave, int close_slave)
 {
 	snd_pcm_t *pcm;
@@ -533,6 +558,47 @@ int snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sform
 	return 0;
 }
 
+/*! \page pcm_plugins
+
+\section pcm_plugins_rate Plugin: Rate
+
+This plugin converts a stream rate. The input and output formats must be linear.
+
+\code
+pcm.name {
+	type rate               # Rate PCM
+        slave STR               # Slave name
+        # or
+        slave {                 # Slave definition
+                pcm STR         # Slave PCM name
+                # or
+                pcm { }         # Slave PCM definition
+        }
+}
+\endcode
+
+\subsection pcm_plugins_rate_funcref Function reference
+
+<UL>
+  <LI>snd_pcm_rate_open()
+  <LI>_snd_pcm_rate_open()
+</UL>
+
+*/
+
+/**
+ * \brief Creates a new rate PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param root Root configuration node
+ * \param conf Configuration node with rate PCM description
+ * \param stream Stream type
+ * \param mode Stream mode
+ * \retval zero on success otherwise a negative error code
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int _snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name,
 		       snd_config_t *root, snd_config_t *conf, 
 		       snd_pcm_stream_t stream, int mode)
@@ -582,4 +648,6 @@ int _snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name,
 		snd_pcm_close(spcm);
 	return err;
 }
+#ifndef DOC_HIDDEN
 SND_DLSYM_BUILD_VERSION(_snd_pcm_rate_open, SND_PCM_DLSYM_VERSION);
+#endif

src/pcm/pcm_shm.c

@@ -1,5 +1,12 @@
+/**
+ * \file pcm/pcm_shm.c
+ * \ingroup PCM_Plugins
+ * \brief PCM Shared Memory Plugin Interface
+ * \author Abramo Bagnara <abramo@alsa-project.org>
+ * \date 2000-2001
+ */
 /*
- *  PCM - SHM Client
+ *  PCM - Shared Memory Client
  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>
  *
  *
@@ -43,11 +50,14 @@
 const char *_snd_module_pcm_shm = "";
 #endif
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	int socket;
 	volatile snd_pcm_shm_ctrl_t *ctrl;
 } snd_pcm_shm_t;
+#endif
 
+#ifndef DOC_HIDDEN
 int receive_fd(int sock, void *data, size_t len, int *fd)
 {
     int ret;
@@ -81,6 +91,7 @@ int receive_fd(int sock, void *data, size_t len, int *fd)
     *fd = *fds;
     return ret;
 }
+#endif
 
 static int snd_pcm_shm_action(snd_pcm_t *pcm)
 {
@@ -493,7 +504,7 @@ static void snd_pcm_shm_dump(snd_pcm_t *pcm, snd_output_t *out)
 	}
 }
 
-snd_pcm_ops_t snd_pcm_shm_ops = {
+static snd_pcm_ops_t snd_pcm_shm_ops = {
 	close: snd_pcm_shm_close,
 	info: snd_pcm_shm_info,
 	hw_refine: snd_pcm_shm_hw_refine,
@@ -508,7 +519,7 @@ snd_pcm_ops_t snd_pcm_shm_ops = {
 	munmap: snd_pcm_shm_munmap,
 };
 
-snd_pcm_fast_ops_t snd_pcm_shm_fast_ops = {
+static snd_pcm_fast_ops_t snd_pcm_shm_fast_ops = {
 	status: snd_pcm_shm_status,
 	state: snd_pcm_shm_state,
 	delay: snd_pcm_shm_delay,
@@ -578,7 +589,22 @@ static int make_inet_socket(const char *host, int port)
 }
 #endif
 
-int snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name, const char *sockname, const char *sname, snd_pcm_stream_t stream, int mode)
+/**
+ * \brief Creates a new shared memory PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param sockname Unix socket name
+ * \param sname Server name
+ * \param stream PCM Stream
+ * \param mode PCM Mode
+ * \retval zero on success otherwise a negative error code
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
+int snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name,
+		     const char *sockname, const char *sname,
+		     snd_pcm_stream_t stream, int mode)
 {
 	snd_pcm_t *pcm;
 	snd_pcm_shm_t *shm = NULL;
@@ -679,6 +705,7 @@ int snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name, const char *sockname, c
 	return result;
 }
 
+#ifndef DOC_HIDDEN
 int is_local(struct hostent *hent)
 {
 	int s;
@@ -723,7 +750,45 @@ int is_local(struct hostent *hent)
 	free(conf.ifc_buf);
 	return i < numreqs;
 }
+#endif
 
+/*! \page pcm_plugins
+
+\section pcm_plugins_shm Plugin: shm
+
+This plugin communicates with aserver via shared memory. It is a raw
+communication without any conversions, but it can be expected worse
+performance.
+
+\code
+pcm.name {
+        type shm                # Shared memory PCM
+	server STR		# Server name
+	pcm STR			# PCM name
+}
+\endcode
+
+\subsection pcm_plugins_shm_funcref Function reference
+
+<UL>
+  <LI>snd_pcm_shm_open()
+  <LI>_snd_pcm_shm_open()
+</UL>
+
+*/
+
+/**
+ * \brief Creates a new shm PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param root Root configuration node
+ * \param conf Configuration node with hw PCM description
+ * \param stream PCM Stream
+ * \param mode PCM Mode
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int _snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name,
 		      snd_config_t *root, snd_config_t *conf,
 		      snd_pcm_stream_t stream, int mode)
@@ -841,4 +906,6 @@ int _snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name,
 	snd_config_delete(sconfig);
 	return err;
 }
+#ifndef DOC_HIDDEN
 SND_DLSYM_BUILD_VERSION(_snd_pcm_shm_open, SND_PCM_DLSYM_VERSION);
+#endif