control: doc - create controls plugin page

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

diff --git a/doc/doxygen.cfg.in b/doc/doxygen.cfg.in
index 11740d3425964dad8269908ceb2eeb30b435b350..c5ebdfab7a7c12af7ffd91689178c926fe7ff90a 100644 (file)
--- a/doc/doxygen.cfg.in
+++ b/doc/doxygen.cfg.in
@@ -40,7 +40,16 @@ INPUT            = @top_srcdir@/doc/index.doxygen \
                   @top_srcdir@/src/names.c \
                   @top_srcdir@/src/shmarea.c \
                   @top_srcdir@/src/userfile.c \
-                  @top_srcdir@/src/control \
+                  @top_srcdir@/src/control/cards.c \
+                  @top_srcdir@/src/control/control.c \
+                  @top_srcdir@/src/control/control_plugin.c \
+                  @top_srcdir@/src/control/control_hw.c \
+                  @top_srcdir@/src/control/control_remap.c \
+                  @top_srcdir@/src/control/control_shm.c \
+                  @top_srcdir@/src/control/ctlparse.c \
+                  @top_srcdir@/src/control/hcontrol.c \
+                  @top_srcdir@/src/control/setup.c \
+                  @top_srcdir@/src/control/tlv.c \
                   @top_srcdir@/src/mixer \
                   @top_srcdir@/src/pcm/pcm.c \
                   @top_srcdir@/src/pcm/pcm_mmap.c \

diff --git a/doc/index.doxygen b/doc/index.doxygen
index b40c75a5239b6e54c4eb487d8fe5a1a96d1e4e37..cde3b94b6eca0182dd83383c4c87e60006bf64b1 100644 (file)
--- a/doc/index.doxygen
+++ b/doc/index.doxygen
@@ -31,6 +31,7 @@ may be placed in the library code instead of the kernel driver.</P>
 
 <UL>
   <LI>Page \ref control explains the primitive controls API.
+  <LI>Page \ref control_plugins explains the design of primitive control plugins.
   <LI>Page \ref hcontrol explains the high-level primitive controls API.
   <LI>Page \ref mixer explains the mixer controls API.
   <LI>Page \ref pcm explains the design of the PCM (digital audio) API.

diff --git a/include/control_plugin.h b/include/control_plugin.h
new file mode 100644 (file)
index 0000000..3c0c8ae
--- /dev/null
+++ b/include/control_plugin.h
@@ -0,0 +1,49 @@
+/**
+ * \file include/control_plugin.h
+ * \brief Common control plugin code
+ * \author Jaroslav Kysela <perex@perex.cz>
+ * \date 2021
+ *
+ * Application interface library for the ALSA driver.
+ * See the \ref control_plugins page for more details.
+ *
+ * \warning Using of contents of this header file might be dangerous
+ *         in the sense of compatibility reasons. The contents might be
+ *         freely changed in future.
+ */
+/*
+ *   This library is free software; you can redistribute it and/or modify
+ *   it under the terms of the GNU Lesser General Public License as
+ *   published by the Free Software Foundation; either version 2.1 of
+ *   the License, or (at your option) any later version.
+ *
+ *   This program is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU Lesser General Public License for more details.
+ *
+ *   You should have received a copy of the GNU Lesser General Public
+ *   License along with this library; if not, write to the Free Software
+ *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ */
+
+#ifndef __ALSA_CONTROL_PLUGIN_H
+#define __ALSA_CONTROL_PLUGIN_H
+
+/**
+ * \defgroup Control_Plugins Primitive Control Plugins
+ * \ingroup Control
+ * See the \ref control_plugins page for more details.
+ * \{
+ */
+
+/*
+ * Control HW
+ */
+int snd_ctl_hw_open(snd_ctl_t **handle, const char *name, int card, int mode);
+int _snd_ctl_hw_open(snd_ctl_t **handlep, char *name, snd_config_t *root ATTRIBUTE_UNUSED, snd_config_t *conf, int mode);
+
+/** \} */
+
+#endif /* __ALSA_CONTROL_PLUGIN_H */

diff --git a/src/control/Makefile.am b/src/control/Makefile.am
index eefe013b0d71ce7c13c58b0e547e59efcdbad2a4..50802699dda00def85e8452dcff8597108076048 100644 (file)
--- a/src/control/Makefile.am
+++ b/src/control/Makefile.am
@@ -2,7 +2,7 @@ EXTRA_LTLIBRARIES = libcontrol.la
 
 libcontrol_la_SOURCES = cards.c tlv.c namehint.c hcontrol.c \
                         control.c control_hw.c setup.c ctlparse.c \
-                        control_symbols.c
+                       control_plugin.c control_symbols.c
 if BUILD_CTL_PLUGIN_REMAP
 libcontrol_la_SOURCES += control_remap.c
 endif

diff --git a/src/control/control_hw.c b/src/control/control_hw.c
index febc9da94ee011dff75b4b0723d161258d75cdc6..680f0fecdc0ee90de65d59a05d05ed85f3c79c49 100644 (file)
--- a/src/control/control_hw.c
+++ b/src/control/control_hw.c
@@ -1,3 +1,9 @@
+/**
+ * \file control/control_hw.c
+ * \brief CTL HW Plugin Interface
+ * \author Jaroslav Kysela <perex@perex.cz>
+ * \date 2000
+ */
 /*
  *  Control Interface - Hardware
  *  Copyright (c) 1998,1999,2000 by Jaroslav Kysela <perex@perex.cz>
@@ -375,6 +381,17 @@ static const snd_ctl_ops_t snd_ctl_hw_ops = {
        .read = snd_ctl_hw_read,
 };
 
+/**
+ * \brief Creates a new hw control
+ * \param handle Returns created control handle
+ * \param name Name of control device
+ * \param card Number of card
+ * \param mode Control 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_ctl_hw_open(snd_ctl_t **handle, const char *name, int card, int mode)
 {
        int fd, ver;
@@ -437,6 +454,40 @@ int snd_ctl_hw_open(snd_ctl_t **handle, const char *name, int card, int mode)
        return 0;
 }
 
+/*! \page control_plugins
+
+\section control_plugins_hw Plugin: hw
+
+This plugin communicates directly with the ALSA kernel driver. It is a raw
+communication without any conversions.
+
+\code
+control.name {
+       type hw                 # Kernel PCM
+       card INT/STR            # Card name (string) or number (integer)
+}
+\endcode
+
+\subsection control_plugins_hw_funcref Function reference
+
+<UL>
+  <LI>snd_ctl_hw_open()
+  <LI>_snd_ctl_hw_open()
+</UL>
+
+*/
+
+/**
+ * \brief Creates a new hw control handle
+ * \param handlep Returns created control handle
+ * \param name Name of control device
+ * \param root Root configuration node
+ * \param conf Configuration node with hw PCM description
+ * \param mode Control 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_ctl_hw_open(snd_ctl_t **handlep, char *name, snd_config_t *root ATTRIBUTE_UNUSED, snd_config_t *conf, int mode)
 {
        snd_config_iterator_t i, next;
@@ -462,4 +513,6 @@ int _snd_ctl_hw_open(snd_ctl_t **handlep, char *name, snd_config_t *root ATTRIBU
                return -EINVAL;
        return snd_ctl_hw_open(handlep, name, card, mode);
 }
+#ifndef DOC_HIDDEN
 SND_DLSYM_BUILD_VERSION(_snd_ctl_hw_open, SND_CONTROL_DLSYM_VERSION);
+#endif

diff --git a/src/control/control_plugin.c b/src/control/control_plugin.c
new file mode 100644 (file)
index 0000000..e486c1c
--- /dev/null
+++ b/src/control/control_plugin.c
@@ -0,0 +1,64 @@
+/**
+ * \file control/control_plugin.c
+ * \ingroup Control
+ * \brief Control Interface
+ * \author Jaroslav Kysela <perex@perex.cz>
+ * \date 2021
+ */
+/*
+ *  Control - Common plugin code
+ *  Copyright (c) 2021 by Jaroslav Kysela <perex@perex.cz>
+ *
+ *
+ *   This library is free software; you can redistribute it and/or modify
+ *   it under the terms of the GNU Lesser General Public License as
+ *   published by the Free Software Foundation; either version 2.1 of
+ *   the License, or (at your option) any later version.
+ *
+ *   This program is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU Lesser General Public License for more details.
+ *
+ *   You should have received a copy of the GNU Lesser General Public
+ *   License along with this library; if not, write to the Free Software
+ *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ */
+
+/*!
+
+\page control_plugins Primitive control plugins
+
+Control plugins extends functionality and features of control devices.
+The plugins take care about various control mapping or so.
+
+The child configuration (in one compound):
+
+\code
+ctl.test {
+       type remap
+       child "hw:0"
+       ... map/remap configuration ...
+}
+\endcode
+
+The child may be defined as compound containing the full specification:
+
+\code
+ctl.test {
+       type remap
+       child {
+               type hw
+               card 0
+       }
+       ... map/remap configuration ...
+}
+\endcode
+
+*/
+
+#include "control_local.h"
+#include "control_plugin.h"
+
+/* move the common plugin code from control_remap.c here on demand */