add snd_device_name_hint() function and initial implementation

- add snd_device_name_hint() and snd_device_name_free_hint() functions
- add snd_ctl_iface_conf_name() functions
- do not accept parameters for the plugin definition without @args section
- add defaults.pcm.dmix.card/device and dsnoop.card/device definitions
- add hints for HDA-Intel.conf, pcm/dmix.conf, pcm/dsnoop.conf and alsa.conf
- add test/namehint test utility
- doxygen related cleanups

doc/doxygen.cfg

@@ -109,6 +109,7 @@ EXPAND_ONLY_PREDEF = YES
 PREDEFINED	 = DOXYGEN PIC "DOC_HIDDEN" \
 		   "ATTRIBUTE_UNUSED=" \
 		   ALSA_PCM_NEW_HW_PARAMS_API \
+		   _POSIX_C_SOURCE \
 		   "use_default_symbol_version(x,y,z)=" \
 		   "link_warning(x,y)="
 

include/control.h

@@ -214,6 +214,9 @@ int snd_card_get_index(const char *name);
 int snd_card_get_name(int card, char **name);
 int snd_card_get_longname(int card, char **name);
 
+int snd_device_name_hint(int card, snd_ctl_elem_iface_t iface, char ***hints);
+int snd_device_name_free_hint(char **hints);
+
 int snd_ctl_open(snd_ctl_t **ctl, const char *name, int mode);
 int snd_ctl_open_lconf(snd_ctl_t **ctl, const char *name, int mode, snd_config_t *lconf);
 int snd_ctl_close(snd_ctl_t *ctl);
@@ -256,6 +259,7 @@ snd_ctl_type_t snd_ctl_type(snd_ctl_t *ctl);
 
 const char *snd_ctl_elem_type_name(snd_ctl_elem_type_t type);
 const char *snd_ctl_elem_iface_name(snd_ctl_elem_iface_t iface);
+const char *snd_ctl_iface_conf_name(snd_ctl_elem_iface_t iface);
 const char *snd_ctl_event_type_name(snd_ctl_event_type_t type);
 
 unsigned int snd_ctl_event_elem_get_mask(const snd_ctl_event_t *obj);

include/local.h

@@ -259,4 +259,8 @@ void snd_config_set_hop(snd_config_t *conf, int hop);
 int snd_config_check_hop(snd_config_t *conf);
 #define SND_CONF_MAX_HOPS	64
 
+int snd_config_search_alias_hooks(snd_config_t *config,
+                                  const char *base, const char *key,
+				  snd_config_t **result);
+
 #endif

src/Versions

@@ -288,3 +288,11 @@ ALSA_1.0.12 {
     snd_hctl_elem_tlv_write;
     snd_hctl_elem_tlv_command;
 } ALSA_1.0.11;
+
+ALSA_1.0.14 {
+  global:
+
+    snd_device_name_hint;
+    snd_device_name_free_hint;
+    snd_ctl_iface_conf_name;
+} ALSA_1.0.12;

src/conf.c

@@ -3935,6 +3935,10 @@ int snd_config_expand(snd_config_t *config, snd_config_t *root, const char *args
 	snd_config_t *defs, *subs = NULL, *res;
 	err = snd_config_search(config, "@args", &defs);
 	if (err < 0) {
+		if (args != NULL) {
+			SNDERR("Unknown parameters %s", args);
+			return -EINVAL;
+		}
 		err = snd_config_copy(&res, config);
 		if (err < 0)
 			return err;

src/conf/alsa.conf

@@ -57,9 +57,13 @@ defaults.pcm.nonblock 1
 defaults.pcm.ipc_key 5678293
 defaults.pcm.ipc_gid audio
 defaults.pcm.ipc_perm 0660
-defaults.pcm.dmix_max_periods 0
-defaults.pcm.dmix_rate 48000
-defaults.pcm.dmix_format S16_LE
+defaults.pcm.dmix.max_periods 0
+defaults.pcm.dmix.rate 48000
+defaults.pcm.dmix.format S16_LE
+defaults.pcm.dmix.card defaults.pcm.card
+defaults.pcm.dmix.device defaults.pcm.device
+defaults.pcm.dsnoop.card defaults.pcm.card
+defaults.pcm.dsnoop.device defaults.pcm.device
 defaults.pcm.front.card defaults.pcm.card
 defaults.pcm.front.device defaults.pcm.device
 defaults.pcm.rear.card defaults.pcm.card
@@ -137,6 +141,7 @@ pcm.hw {
 	card $CARD
 	device $DEV
 	subdevice $SUBDEV
+	hint 0
 }
 
 pcm.plughw {
@@ -182,6 +187,7 @@ pcm.plughw {
 		device $DEV
 		subdevice $SUBDEV
 	}
+	hint 0
 }
 
 pcm.plug {
@@ -240,6 +246,7 @@ pcm.file {
 }
 
 pcm.null {
+	hint.description "Discard all samples (playback) or generate zero samples (capture)"
 	type null
 }
 
@@ -357,6 +364,10 @@ rawmidi.hw {
 	card $CARD
 	device $DEV
 	subdevice $SUBDEV
+	hint {
+		description "Direct rawmidi driver device"
+		device $DEV
+	}
 }
 
 rawmidi.default {
@@ -548,4 +559,5 @@ timer.default {
 		@func refer
 		name defaults.timer.subdevice
 	}
+	hint.description "Default direct hardware timer device"
 }

src/conf/cards/ATIIXP-MODEM.conf

@@ -19,4 +19,5 @@ ATIIXP-MODEM.pcm.modem.0 {
 	slave.format S16_LE
 	ttable.0.1 1
 	ttable.1.0 0
+	hint 0
 }

src/conf/cards/HDA-Intel.conf

@@ -19,6 +19,10 @@ HDA-Intel.pcm.front.0 {
 		name "PCM Playback Volume"
 		card $CARD
 	}
+	hint {
+		description "Front speakers and multichannel output"
+		device 0
+	}
 }	
 
 # default with dmix+softvol & dsnoop
@@ -49,6 +53,17 @@ HDA-Intel.pcm.default {
 			strings [ "dsnoop:" $CARD ]
 		}
 	}
+	hint {
+		description "Default dmix+softvol + dsnoop device"
+		device_output {
+			@func refer
+			name defaults.pcm.dmix.device
+		}
+		device_input {
+			@func refer
+			name defaults.pcm.dsnoop.device
+		}
+	}
 }
 
 <confdir:pcm/surround40.conf>
@@ -125,6 +140,10 @@ HDA-Intel.pcm.iec958.0 {
 			]
 		}
 	}
+	hint {
+		description "IEC958 (S/PDIF) Output"
+		device 1
+	}
 }
 
 <confdir:pcm/modem.conf>
@@ -137,4 +156,5 @@ HDA-Intel.pcm.modem.0 {
 	type hw
 	card $CARD
 	device 6
+	hint 0
 }

src/conf/cards/ICH-MODEM.conf

@@ -12,4 +12,5 @@ ICH-MODEM.pcm.modem.0 {
 	type hw
 	card $CARD
 	device 0
+	hint 0
 }

src/conf/pcm/dmix.conf

@@ -6,11 +6,17 @@ pcm.!dmix {
 	@args [ CARD DEV SUBDEV FORMAT RATE ]
 	@args.CARD {
 		type string
-		default 0
+		default {
+			@func refer
+			name defaults.pcm.dmix.card
+		}
 	}
 	@args.DEV {
 		type string
-		default 0
+		default {
+			@func refer
+			name defaults.pcm.dmix.device
+		}
 	}
 	@args.SUBDEV {
 		type string
@@ -20,14 +26,14 @@ pcm.!dmix {
 		type string
 		default {
 			@func refer
-			name defaults.pcm.dmix_format
+			name defaults.pcm.dmix.format
 		}
 	}
 	@args.RATE {
 		type integer
 		default {
 			@func refer
-			name defaults.pcm.dmix_rate
+			name defaults.pcm.dmix.rate
 		}
 	}
 	type dmix
@@ -98,4 +104,8 @@ pcm.!dmix {
 			default 16
 		}
 	}
+	hint {
+		description "Direct sample mixing device"
+		device $DEV
+	}
 }

src/conf/pcm/dsnoop.conf

@@ -6,11 +6,17 @@ pcm.!dsnoop {
 	@args [ CARD DEV SUBDEV FORMAT RATE ]
 	@args.CARD {
 		type string
-		default 0
+		default {
+			@func refer
+			name defaults.pcm.dsnoop.card
+		}
 	}
 	@args.DEV {
 		type string
-		default 0
+		default {
+			@func refer
+			name defaults.pcm.dsnoop.device
+		}
 	}
 	@args.SUBDEV {
 		type string
@@ -20,14 +26,14 @@ pcm.!dsnoop {
 		type string
 		default {
 			@func refer
-			name defaults.pcm.dmix_format
+			name defaults.pcm.dmix.format
 		}
 	}
 	@args.RATE {
 		type integer
 		default {
 			@func refer
-			name defaults.pcm.dmix_rate
+			name defaults.pcm.dmix.rate
 		}
 	}
 	type dsnoop
@@ -98,4 +104,8 @@ pcm.!dsnoop {
 			default 16
 		}
 	}
+	hint {
+		description "Direct sample snooping device"
+		device $DEV
+	}
 }

src/conf/pcm/modem.conf

@@ -44,6 +44,7 @@ pcm.!phoneline {
 			".pcm.modem." $DEV ":CARD=" $CARD
 		]
 	}
+	hint 0
 }
 
 #
@@ -101,4 +102,5 @@ pcm.!modem {
 		}
 		]
 	}
+	hint 0
 }

src/control/Makefile.am

@@ -1,6 +1,6 @@
 EXTRA_LTLIBRARIES = libcontrol.la
 
-libcontrol_la_SOURCES = cards.c hcontrol.c \
+libcontrol_la_SOURCES = cards.c namehint.c hcontrol.c \
                         control.c control_hw.c control_shm.c \
 			control_ext.c setup.c control_symbols.c
 

src/control/control.c

@@ -950,6 +950,7 @@ int snd_ctl_open_lconf(snd_ctl_t **ctlp, const char *name,
 #ifndef DOC_HIDDEN
 #define TYPE(v) [SND_CTL_ELEM_TYPE_##v] = #v
 #define IFACE(v) [SND_CTL_ELEM_IFACE_##v] = #v
+#define IFACE1(v, n) [SND_CTL_ELEM_IFACE_##v] = #n
 #define EVENT(v) [SND_CTL_EVENT_##v] = #v
 
 static const char *snd_ctl_elem_type_names[] = {
@@ -972,6 +973,16 @@ static const char *snd_ctl_elem_iface_names[] = {
 	IFACE(SEQUENCER),
 };
 
+static const char *snd_ctl_iface_conf_names[] = {
+	IFACE1(CARD, card),
+	IFACE1(HWDEP, hwdep),
+	IFACE1(MIXER, mixer),
+	IFACE1(PCM, pcm),
+	IFACE1(RAWMIDI, rawmidi),
+	IFACE1(TIMER, timer),
+	IFACE1(SEQUENCER, seq),
+};
+
 static const char *snd_ctl_event_type_names[] = {
 	EVENT(ELEM),
 };
@@ -999,6 +1010,17 @@ const char *snd_ctl_elem_iface_name(snd_ctl_elem_iface_t iface)
 	return snd_ctl_elem_iface_names[iface];
 }
 
+/**
+ * \brief get configuration name of related interface
+ * \param iface ala CTL interface identification
+ * \return ascii name of configuration interface
+ */
+const char *snd_ctl_iface_conf_name(snd_ctl_elem_iface_t iface)
+{
+	assert(iface <= SND_CTL_ELEM_IFACE_LAST);
+	return snd_ctl_iface_conf_names[iface];
+}
+
 /**
  * \brief get name of a CTL event type
  * \param type CTL event type

src/control/namehint.c

@@ -0,0 +1,500 @@
+/**
+ * \file control/namehint.c
+ * \brief Give device name hints
+ * \author Jaroslav Kysela <perex@suse.cz>
+ * \date 2006
+ */
+/*
+ *  Give device name hints  - main file
+ *  Copyright (c) 2006 by Jaroslav Kysela <perex@suse.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., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
+ *
+ */
+
+#include "local.h"
+
+#ifndef DOC_HIDDEN
+struct hint_list {
+	char **list;
+	unsigned int count;
+	unsigned int allocated;
+	snd_ctl_elem_iface_t iface;
+	snd_ctl_t *ctl;
+	snd_ctl_card_info_t *info;	
+	int card;
+	int device;
+	long device_input;
+	long device_output;
+	int stream;
+};
+#endif
+
+static int hint_list_add(struct hint_list *list,
+			 const char *name,
+			 const char *description)
+{
+	char *x;
+
+	if (list->count == list->allocated) {
+		char **n = realloc(list->list, (list->allocated + 10) * sizeof(char *));
+		if (n == NULL)
+			return -ENOMEM;
+		list->allocated += 10;
+		list->list = n;
+	}
+	if (name == NULL) {
+		x = NULL;
+	} else {
+		x = malloc(strlen(name) + (description != NULL ? (strlen(description) + 1) : 0) + 1);
+		if (x == NULL)
+			return -ENOMEM;
+		strcpy(x, name);
+		if (description != NULL) {
+			strcat(x, "|");
+			strcat(x, description);
+		}
+	}
+	list->list[list->count++] = x;
+	return 0;
+}
+
+static void zero_handler(const char *file ATTRIBUTE_UNUSED,
+			 int line ATTRIBUTE_UNUSED,
+			 const char *function ATTRIBUTE_UNUSED,
+			 int err ATTRIBUTE_UNUSED,
+			 const char *fmt ATTRIBUTE_UNUSED, ...)
+{
+}
+
+static char *get_dev_name1(struct hint_list *list)
+{
+	if (list->device < 0)
+		return NULL;
+	switch (list->iface) {
+	case SND_CTL_ELEM_IFACE_HWDEP:
+		{
+			snd_hwdep_info_t *info;
+			snd_hwdep_info_alloca(&info);
+			snd_hwdep_info_set_device(info, list->device);
+			if (snd_ctl_hwdep_info(list->ctl, info) < 0)
+				return NULL;
+			return strdup(snd_hwdep_info_get_name(info));
+		}
+	case SND_CTL_ELEM_IFACE_PCM:
+		{
+			snd_pcm_info_t *info;
+			snd_pcm_info_alloca(&info);
+			snd_pcm_info_set_device(info, list->device);
+			snd_pcm_info_set_stream(info, list->stream ? SND_PCM_STREAM_CAPTURE : SND_PCM_STREAM_PLAYBACK);
+			if (snd_ctl_pcm_info(list->ctl, info) < 0)
+				return NULL;
+			switch (snd_pcm_info_get_class(info)) {
+			case SND_PCM_CLASS_MODEM:
+			case SND_PCM_CLASS_DIGITIZER:
+				return NULL;
+			default:
+				break;
+			}
+			return strdup(snd_pcm_info_get_name(info));
+		}
+	case SND_CTL_ELEM_IFACE_RAWMIDI:
+		{
+			snd_rawmidi_info_t *info;
+			snd_rawmidi_info_alloca(&info);
+			snd_rawmidi_info_set_device(info, list->device);
+			snd_rawmidi_info_set_stream(info, list->stream ? SND_RAWMIDI_STREAM_INPUT : SND_RAWMIDI_STREAM_OUTPUT);
+			if (snd_ctl_rawmidi_info(list->ctl, info) < 0)
+				return NULL;
+			return strdup(snd_rawmidi_info_get_name(info));
+		}
+	default:
+		return NULL;
+	}
+}
+
+static char *get_dev_name(struct hint_list *list)
+{
+	char *str1, *str2, *res;
+	
+	list->device = list->device_input >= 0 ? list->device_input : list->device;
+	list->stream = 1;
+	str1 = get_dev_name1(list);
+	list->device = list->device_output >= 0 ? list->device_input : list->device;
+	list->stream = 0;
+	str2 = get_dev_name1(list);
+	if (str1 != NULL || str2 != NULL) {
+		if (str1 != NULL && str2 != NULL) {
+			if (strcmp(str1, str2) == 0) {
+				free(str1);
+				return str2;
+			}
+			res = realloc(str2, strlen(str2) + strlen(str1) + 4);
+			if (res != NULL) {
+				strcat(res, " / ");
+				strcat(res, str1);
+				free(str1);
+				return res;
+			} else {
+				free(str2);
+				free(str1);
+			}
+		} else {
+			if (str1 != NULL) {
+				res = realloc(str1, strlen(str1) + 16);
+				if (res == NULL) {
+					free(str1);
+					return NULL;
+				}
+				strcat(res, " {");
+				strcat(res, list->iface == SND_CTL_ELEM_IFACE_PCM ? "Capture" : "Input");
+				strcat(res, "}");
+				return res;
+			} else {
+				res = realloc(str2, strlen(str2) + 16);
+				if (res == NULL) {
+					free(str2);
+					return NULL;
+				}
+				strcat(res, " {");
+				strcat(res, list->iface == SND_CTL_ELEM_IFACE_PCM ? "Playback" : "Output");
+				strcat(res, "}");
+				return res;
+			}
+		}
+	}
+	return NULL;
+}
+
+#ifndef DOC_HIDDEN
+#define BUF_SIZE 128
+#endif
+
+static int try_config(struct hint_list *list,
+		      const char *base,
+		      const char *name)
+{
+	snd_lib_error_handler_t eh;
+	snd_config_t *res, *cfg, *n;
+	snd_config_iterator_t i, next;
+	char *buf, *buf1 = NULL, *buf2;
+	const char *str;
+	int err;
+	long dev = list->device;
+
+	list->device_input = -1;
+	list->device_output = -1;
+	buf = malloc(BUF_SIZE);
+	if (buf == NULL)
+		return -ENOMEM;
+	if (list->card >= 0 && list->device >= 0)
+		sprintf(buf, "%s:CARD=%s,DEV=%i", name, snd_ctl_card_info_get_id(list->info), list->device);
+	else if (list->card >= 0)
+		sprintf(buf, "%s:CARD=%s", name, snd_ctl_card_info_get_id(list->info));
+	else
+		strcpy(buf, name);
+	eh = snd_lib_error;
+	snd_lib_error_set_handler(&zero_handler);
+	err = snd_config_search_definition(snd_config, base, buf, &res);
+	snd_lib_error_set_handler(eh);
+	if (err < 0)
+		return err;
+	err = -EINVAL;
+	if (snd_config_get_type(res) != SND_CONFIG_TYPE_COMPOUND)
+		goto __cleanup;
+	if (snd_config_search(res, "type", NULL) < 0)
+		goto __cleanup;
+	cfg = res;
+      __hint:
+	if (snd_config_search(cfg, "hint", &cfg) >= 0) {
+		if (snd_config_get_type(cfg) == SND_CONFIG_TYPE_COMPOUND) {
+			if (snd_config_search(cfg, "description", &n) >= 0 &&
+			    snd_config_get_string(n, &str) >= 0) {
+				buf1 = strdup(str);
+				if (buf1 == NULL) {
+					err = -ENOMEM;
+					goto __cleanup;
+				}
+			}
+			if (snd_config_search(cfg, "device", &n) >= 0) {
+				if (snd_config_get_integer(n, &dev) < 0) {
+					err = -EINVAL;
+					goto __cleanup;
+				}
+			}
+			if (snd_config_search(cfg, "device_input", &n) >= 0) {
+				if (snd_config_get_integer(n, &list->device_input) < 0) {
+					err = -EINVAL;
+					goto __cleanup;
+				}
+			}
+			if (snd_config_search(cfg, "device_output", &n) >= 0) {
+				if (snd_config_get_integer(n, &list->device_output) < 0) {
+					err = -EINVAL;
+					goto __cleanup;
+				}
+			}
+		} else if (snd_config_get_bool(cfg) == 0) {
+			err = -EXDEV;
+			goto __cleanup;
+		}
+		goto __hint_ok;
+	}
+	if (snd_config_search(cfg, "slave", &cfg) >= 0 &&
+	    snd_config_search(cfg, base, &cfg) >= 0)
+	    	goto __hint;
+      __hint_ok:
+#if 0	/* for debug purposes */
+		{
+			snd_output_t *out;
+			fprintf(stderr, "********* PCM '%s':\n", buf);
+			snd_output_stdio_attach(&out, stderr, 0);
+			snd_config_save(res, out);
+			snd_output_close(out);
+			printf("\n");
+		}
+#endif
+	snd_config_delete(res);
+	res = NULL;
+	if (strchr(buf, ':') != NULL)
+		goto __ok;
+	/* find, if all parameters have a default, */
+	/* otherwise filter this definition */
+	eh = snd_lib_error;
+	snd_lib_error_set_handler(&zero_handler);
+	err = snd_config_search_alias_hooks(snd_config, base, buf, &res);
+	snd_lib_error_set_handler(eh);
+	if (err < 0)
+		goto __cleanup;
+	if (snd_config_search(res, "@args", &cfg) >= 0) {
+		snd_config_for_each(i, next, cfg) {
+			if (snd_config_search(snd_config_iterator_entry(i),
+					      "default", NULL) < 0) {
+				err = -EINVAL;
+				goto __cleanup;
+			}
+		}
+	}
+      __ok:
+	err = 0;
+      __cleanup:
+      	if (res)
+	      	snd_config_delete(res);
+      	if (err >= 0) {
+      		list->device = dev;
+ 		str = get_dev_name(list);
+      		if (str != NULL) {
+      			buf2 = realloc((char *)str, (buf1 == NULL ? 0 : strlen(buf1)) + 2 + strlen(str) + 1);
+      			if (buf2 != NULL) {
+      				if (buf1 != NULL) {
+	      				strcat(buf2, ": ");
+	      				strcat(buf2, buf1);
+					free(buf1);
+				}
+				buf1 = buf2;
+			} else {
+				free((char *)str);
+			}
+      		} else if (list->device >= 0)
+      			goto __skip_add;
+	      	err = hint_list_add(list, buf, buf1);
+	}
+      __skip_add:
+	if (buf1)
+		free(buf1);
+      	free(buf);
+	return err;
+}
+
+#ifndef DOC_HIDDEN
+#define IFACE(v, fcn) [SND_CTL_ELEM_IFACE_##v] = (next_devices_t)fcn
+
+typedef int (*next_devices_t)(snd_ctl_t *, int *);
+
+static next_devices_t next_devices[] = {
+	IFACE(CARD, NULL),
+	IFACE(HWDEP, snd_ctl_hwdep_next_device),
+	IFACE(MIXER, NULL),
+	IFACE(PCM, snd_ctl_pcm_next_device),
+	IFACE(RAWMIDI, snd_ctl_rawmidi_next_device),
+	IFACE(TIMER, NULL),
+	IFACE(SEQUENCER, NULL)
+};
+#endif
+
+static int add_card(struct hint_list *list, int card, snd_ctl_elem_iface_t iface)
+{
+	int err, ok;
+	snd_config_t *conf, *n;
+	snd_config_iterator_t i, next;
+	const char *str, *base;
+	char ctl_name[16];
+	snd_ctl_card_info_t *info;
+	
+	snd_ctl_card_info_alloca(&info);
+	list->info = info;
+	if (iface > SND_CTL_ELEM_IFACE_LAST)
+		return -EINVAL;
+	if (snd_card_get_name(card, (char **)&str) < 0)
+		return 0;
+	base = snd_ctl_iface_conf_name(iface);
+	err = snd_config_search(snd_config, base, &conf);
+	if (err < 0)
+		return err;
+	sprintf(ctl_name, "hw:%i", card);
+	err = snd_ctl_open(&list->ctl, ctl_name, 0);
+	if (err < 0)
+		return err;
+	err = snd_ctl_card_info(list->ctl, info);
+	if (err < 0)
+		goto __error;
+	snd_config_for_each(i, next, conf) {
+		n = snd_config_iterator_entry(i);
+		if (snd_config_get_id(n, &str) < 0)
+			continue;
+		if (next_devices[iface] != NULL) {
+			list->card = card;
+			list->device = -1;
+			err = next_devices[iface](list->ctl, &list->device);
+			if (list->device < 0)
+				err = -EINVAL;
+			ok = 0;
+			while (err >= 0 && list->device >= 0) {
+				err = try_config(list, base, str);
+				if (err < 0)
+					break;
+				err = next_devices[iface](list->ctl, &list->device);
+				ok++;
+			}
+			if (ok)
+				continue;
+		} else {
+			err = -EINVAL;
+		}
+		if (err == -EXDEV)
+			continue;
+		if (err < 0) {
+			list->device = -1;
+			err = try_config(list, base, str);
+		}
+		if (err < 0) {
+			list->card = -1;
+			err = try_config(list, base, str);
+		}
+		if (err == -ENOMEM)
+			goto __error;
+	}
+	err = 0;
+      __error:
+      	if (err < 0)
+      		snd_ctl_close(list->ctl);
+	return err;
+}
+
+/**
+ * \brief Return string list with device name hints.
+ * \param card Card number or -1 (means all cards)
+ * \param iface Interface identification
+ * \param hints Result - array of string with device name hints
+ * \result zero if success, otherwise a negative error code
+ *
+ * Note: The device description is separated with '|' char.
+ *
+ * User defined hints are gathered from namehint.IFACE tree like:
+ *
+ * <code>
+ * namehint.pcm {<br>
+ *   myfile "file:FILE=/tmp/soundwave.raw|Save sound output to /tmp/soundwave.raw"<br>
+ *   myplug "plug:front:Do all conversions for front speakers"<br>
+ * }
+ * </code>
+ */
+int snd_device_name_hint(int card, snd_ctl_elem_iface_t iface, char ***hints)
+{
+	struct hint_list list;
+	char ehints[16];
+	const char *str;
+	snd_config_t *conf;
+	snd_config_iterator_t i, next;
+	int err;
+
+	if (hints == NULL)
+		return -EINVAL;
+	err = snd_config_update();
+	if (err < 0)
+		return err;
+	list.list = NULL;
+	list.count = list.allocated = 0;
+	list.iface = iface;
+	if (card >= 0) {
+		err = add_card(&list, card, iface);
+	} else {
+		err = snd_card_next(&card);
+		if (err < 0)
+			goto __error;
+		while (card >= 0) {
+			err = add_card(&list, card, iface);
+			if (err < 0)
+				goto __error;
+			err = snd_card_next(&card);
+			if (err < 0)
+				goto __error;
+		}
+	}
+	sprintf(ehints, "namehint.%s", snd_ctl_iface_conf_name(iface));
+	err = snd_config_search(snd_config, ehints, &conf);
+	if (err >= 0) {
+		snd_config_for_each(i, next, conf) {
+			if (snd_config_get_string(snd_config_iterator_entry(i),
+						  &str) < 0)
+				continue;
+			err = hint_list_add(&list, str, NULL);
+			if (err < 0)
+				goto __error;
+		}
+	}
+      __error:
+      	if (err < 0) {
+      		snd_device_name_free_hint(list.list);
+      		return err;
+      	} else {
+      		err = hint_list_add(&list, NULL, NULL);
+      		if (err < 0)
+      			goto __error;
+      		*hints = list.list;
+	}
+      	return 0;
+}
+
+/**
+ * \brief Free a string list with device name hints.
+ * \param hints A string list to free
+ * \result zero if success, otherwise a negative error code
+ */
+int snd_device_name_free_hint(char **hints)
+{
+	char **h;
+
+	if (hints == NULL)
+		return 0;
+	h = hints;
+	while (*h) {
+		free(*h);
+		h++;
+	}
+	free(hints);
+	return 0;
+}

src/mixer/simple_none.c

@@ -982,10 +982,14 @@ static int get_volume_ops(snd_mixer_elem_t *elem, int dir,
 static int init_db_range(snd_hctl_elem_t *ctl, struct selem_str *rec);
 
 /* convert to index of integer array */
+#ifndef DOC_HIDDEN
 #define int_index(size)	(((size) + sizeof(int) - 1) / sizeof(int))
+#endif
 
 /* max size of a TLV entry for dB information (including compound one) */
+#ifndef DOC_HIDDEN
 #define MAX_TLV_RANGE_SIZE	256
+#endif
 
 /* parse TLV stream and retrieve dB information
  * return 0 if successly found and stored to rec,

src/pcm/pcm.c

@@ -6681,7 +6681,7 @@ int snd_pcm_slave_conf(snd_config_t *root, snd_config_t *conf,
 
 int snd_pcm_conf_generic_id(const char *id)
 {
-	static const char *ids[] = { "comment", "type" };
+	static const char *ids[] = { "comment", "type", "hint" };
 	unsigned int k;
 	for (k = 0; k < sizeof(ids) / sizeof(ids[0]); ++k) {
 		if (strcmp(id, ids[k]) == 0)

test/Makefile.am

@@ -1,6 +1,6 @@
 check_PROGRAMS=control pcm pcm_min latency seq \
 	       playmidi1 timer rawmidi midiloop \
-	       oldapi queue_timer
+	       oldapi queue_timer namehint
 
 control_LDADD=../src/libasound.la
 pcm_LDADD=../src/libasound.la
@@ -13,6 +13,7 @@ rawmidi_LDADD=../src/libasound.la
 midiloop_LDADD=../src/libasound.la
 oldapi_LDADD=../src/libasound.la
 queue_timer_LDADD=../src/libasound.la
+namehint_LDADD=../src/libasound.la
 code_CFLAGS=-Wall -pipe -g -O2
 
 INCLUDES=-I$(top_srcdir)/include

test/namehint.c

@@ -0,0 +1,28 @@
+#include "../include/asoundlib.h"
+#include <err.h>
+
+int main(int argc, char *argv[])
+{
+	const char *iface = "pcm";
+	snd_ctl_elem_iface_t niface;
+	char **hints, **n;
+	int err;
+
+	if (argc > 1)
+		iface = argv[1];
+	for (niface = 0; niface < SND_CTL_ELEM_IFACE_LAST; niface++)
+		if (strcmp(snd_ctl_iface_conf_name(niface), iface) == 0)
+			break;
+	if (niface > SND_CTL_ELEM_IFACE_LAST)
+		errx(1, "interface %s dnoes not exist", iface);
+	err = snd_device_name_hint(-1, niface, &hints);
+	if (err < 0)
+		errx(1, "snd_device_name_hint error: %s", snd_strerror(err));
+	n = hints;
+	while (*n != NULL) {
+		printf("%s\n", *n);
+		n++;
+	}
+	snd_device_name_free_hint(hints);
+	return 0;
+}