More updates regarding configuration

5 files changed, 175 insertions, 4 deletions

diff --git a/doc/conf.doxygen b/doc/conf.doxygen
index 866f341d..8c835c25 100644
--- a/doc/conf.doxygen
+++ b/doc/conf.doxygen
@@ -41,7 +41,7 @@ strings, int which case they are protected from the normal parsing process
 parses to two tokens, including the single literal-string token "John
 Smith".
 
-\section conf_linesplicing Line splicing with \\
+\section conf_linesplicing Line splicing with \
 
 A special case occurs, if the final newline character encountered is
 preceded by a backslash (\) in the string value definition. The backslash
@@ -49,7 +49,7 @@ and new line are both discarded, allowing two physical lines of text to be
 treated as one unit.
 
 \code
-"John \\
+"John \
 Smith"
 \endcode
 
@@ -217,5 +217,4 @@ name.0 [=] value0 [,|;]
 name.1 [=] value1 [,|;]
 \endcode
 
-
 */
diff --git a/doc/confarg.doxygen b/doc/confarg.doxygen
new file mode 100644
index 00000000..baccd0db
--- /dev/null
+++ b/doc/confarg.doxygen
@@ -0,0 +1,56 @@
+/*! \page confarg Configuration - runtime arguments
+
+<P>The ALSA library can accept runtime arguments for some configuration
+blocks. This extension is on top of the basic syntax of the configuration
+files.<P>
+
+\section confarg_define Defining arguments
+
+Arguments are specified by id (key) @args and array values containing
+the string names of arguments:
+
+\code
+@args [ CARD ]	# or
+@args.0 CARD
+\endcode
+
+\section confarg_type Defining argument type and default value
+
+Arguments type is specified by id (key) @args and argument name. The type
+and default value is specified in the compound:
+
+\code
+@args.CARD {
+  type string
+  default "abcd"
+}
+\endcode
+
+\section confarg_refer Refering argument
+
+Arguments are refered by dollar-sign ($) and name of argument:
+
+\code
+  card $CARD
+\endcode
+
+\section confarg_example Example
+
+\code
+pcm.demo {
+	@args [ CARD DEVICE ]
+	@args.CARD {
+		type string
+		default "supersonic"
+	}
+	@args.DEVICE {
+		type integer
+		default 0
+	}
+	type hw
+	card $CARD
+	device $DEVICE
+}
+\endcode
+
+*/
diff --git a/doc/conffunc.doxygen b/doc/conffunc.doxygen
new file mode 100644
index 00000000..7d5dfc16
--- /dev/null
+++ b/doc/conffunc.doxygen
@@ -0,0 +1,106 @@
+/*! \page conffunc Configuration - runtime functions
+
+<P>The ALSA library accepts the runtime modification of configuration.
+The several build-in functions are available.</P>
+
+<P>The function is refered using id @func and function name. All other
+values in the current compound are used as configuration for the function.
+If compound func.<function_name> is defined in the root leafs, then library
+and function from this compound configuration is used, otherwise the prefix
+'snd_func_' is added to string and the code from the ALSA library is used.
+The definition of function looks like:</P> 
+
+\code
+func.remove_first_char {
+	lib "/usr/lib/libasoundextend.so"
+	func "extend_remove_first_char"
+}
+\endcode
+
+\section conffunc_getenv The getenv function
+
+The getenv function allows to get an environment value. The vars values
+(array) defined the order and names for the environment values. When the
+first environment value is found, then the function replaces the whole
+compound by this result. If no value is found, then the default value is
+used, if defined.
+
+\code
+	card {
+		@func getenv
+		vars [ MY_CARD CARD C ]
+		default 0
+	}
+\endcode
+
+\section conffunc_igetenv The igetenv function
+
+This function is same as getenv function, but the result value is converted
+to integer.
+
+\section conffunc_concat The concat function
+
+The concat function merges all given string in the array named string into
+one.
+
+\code
+	filename {
+		@func concat
+		strings [
+			"/usr/share"
+			"/sound"
+			"/a.wav"
+		]
+	}
+\endcode
+
+\section conffunc_datadir The datadir function
+
+This function return the configuration data directory (usually /usr/share/alsa)
+as string as result. This function requires no other values.
+
+
+\section conffunc_refer The refer function
+
+This function substitutes the current compound with the compound named (key
+name, value string) and filename (key file - optional, value string).
+
+\code
+	{
+		@func refer
+		file /etc/my-alsa.conf
+		name pcm.lastone
+	}
+\endcode
+
+\section conffunc_card_strtype The card_strtype function
+
+This function converts the given card number (key card, value integer) to card type
+(string).
+
+\section conffunc_card_id The card_id function
+
+This function returns the card id string for the given card number (key card, value
+integer).
+
+\section conffunc_pcm_id The pcm_id function
+
+This function returns the pcm id string for the given PCM device (key card,
+value integer; key device, value integer; key subdevice (optional), value
+integer).
+
+\section conffunc_private_string The private_string function
+
+This function returns the private data as string as result.
+
+\section conffunc_private_card_strtype The private_card_strtype function
+
+This function converts the private data (int) with card number to card type
+(string).
+
+\section conffunc_private_pcm_subdevice The private_pcm_subdevice function
+
+This functions returns the subdevice number for the pcm handle specified by
+the private data.
+
+*/
diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg
index 096274cf..ebd4fe67 100644
--- a/doc/doxygen.cfg
+++ b/doc/doxygen.cfg
@@ -5,7 +5,9 @@ GENERATE_MAN     = NO
 GENERATE_RTF	 = NO
 
 CASE_SENSE_NAMES = NO
-INPUT            = index.doxygen conf.doxygen pcm.doxygen ../include ../src
+INPUT            = index.doxygen conf.doxygen confarg.doxygen \
+		   conffunc.doxygen pcm.doxygen \
+		   ../include ../src
 EXCLUDE		 = ../src/control/control_local.h \
 		   ../src/pcm/atomic.h \
 		   ../src/pcm/interval.h \
diff --git a/doc/index.doxygen b/doc/index.doxygen
index e4ae00bc..7842214c 100644
--- a/doc/index.doxygen
+++ b/doc/index.doxygen
@@ -33,4 +33,12 @@ may be placed in the library code instead of the kernel driver.</P>
   <LI>Page \ref pcm explains the design of PCM (digital audio) API
 </UL>
 
+<H2>Configuration</H2>
+
+<UL>
+  <LI>Page \ref conf explains the syntax of library configuration files.
+  <LI>Page \ref confarg explains the run-time argument syntax.
+  <LI>Page \ref conffunc explains the run-time function definition and usage.
+</UL>
+
 */