From 7371ac9aadda7750705268024f3034c803c8e25a Mon Sep 17 00:00:00 2001
From: Jaroslav Kysela <perex@perex.cz>
Date: Tue, 6 Apr 2021 12:18:23 +0200
Subject: [PATCH] control: doc - create controls plugin page

Signed-off-by: Jaroslav Kysela <perex@perex.cz>
---
 doc/doxygen.cfg.in           | 11 ++++++-
 doc/index.doxygen            |  1 +
 include/control_plugin.h     | 49 +++++++++++++++++++++++++++
 src/control/Makefile.am      |  2 +-
 src/control/control_hw.c     | 53 +++++++++++++++++++++++++++++
 src/control/control_plugin.c | 64 ++++++++++++++++++++++++++++++++++++
 6 files changed, 178 insertions(+), 2 deletions(-)
 create mode 100644 include/control_plugin.h
 create mode 100644 src/control/control_plugin.c

diff --git a/doc/doxygen.cfg.in b/doc/doxygen.cfg.in
index 11740d34..c5ebdfab 100644
--- 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 b40c75a5..cde3b94b 100644
--- 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
index 00000000..3c0c8ae4
--- /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 eefe013b..50802699 100644
--- 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 febc9da9..680f0fec 100644
--- 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
index 00000000..e486c1ca
--- /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 */
-- 
2.47.1