rebase to upstream master

README.md

@@ -12,3 +12,14 @@ http://www.alsa-project.org/alsa-doc/alsa-lib/
 
 You may give a look for more information about the ALSA project to URL
 http://www.alsa-project.org.
+
+### Submitting patches
+
+The preferred way to submit patches is by sending them by email to the
+alsa-devel mailing list. Sending mail to the list requires subscription,
+subscribe here: https://mailman.alsa-project.org/mailman/listinfo/alsa-devel
+
+Add Takashi Iwai `<tiwai@suse.de>` and/or Jaroslav Kysela `<perex@perex.cz>` to
+Cc so that your patch won't be missed.
+
+Patches are also accepted as GitHub pull requests.

configure.ac

@@ -1,6 +1,6 @@
 dnl Process this file with autoconf to produce a configure script.
 AC_PREREQ(2.59)
-AC_INIT(alsa-lib, 1.2.3.2)
+AC_INIT(alsa-lib, 1.2.4)
 
 AC_CONFIG_SRCDIR([src/control/control.c])
 AC_CONFIG_MACRO_DIR([m4])

include/control.h

@@ -56,13 +56,127 @@ typedef struct _snd_ctl_card_info snd_ctl_card_info_t;
 /** CTL element identifier container */
 typedef struct _snd_ctl_elem_id snd_ctl_elem_id_t;
 
-/** CTL element identifier list container */
+/** CTL element list container
+ *
+ * This is a list of CTL elements. The list contains management
+ * information (e.g. how many elements the sound card has) as well as
+ * the element identifiers. All functions which operate on the list
+ * are named snd_ctl_elem_list_*().
+ *
+ * \par Memory management
+ *
+ * There are two memory areas to deal with: The list container itself
+ * and the memory for the element identifiers.
+ *
+ * To manage the area for the list container, the following functions
+ * are used:
+ *
+ * - snd_ctl_elem_list_malloc() / snd_ctl_elem_list_free() to allocate
+ *   and free memory on the heap, or
+ * - snd_ctl_elem_list_alloca() to allocate the memory on the
+ *   stack. This memory is auto-released when the stack is unwound.
+ *
+ * To manage the space for the element identifiers, the
+ * snd_ctl_elem_list_alloc_space() and snd_ctl_elem_list_free_space()
+ * are used. Allocating the right amount of space can be achieved by
+ * first obtaining the number of elements and then calling
+ * snd_ctl_elem_list_alloc_space():
+ *
+ * \code
+ *   snd_ctl_elem_list_t* list;
+ *   int count;
+ *
+ *   // Initialise list
+ *   snd_ctl_elem_list_malloc(&list);
+ *
+ *   // Get number of elements
+ *   snd_ctl_elem_list(ctl, list);
+ *   count = snd_ctl_elem_list_get_count(list);
+ *
+ *   // Allocate space for identifiers
+ *   snd_ctl_elem_list_alloc_space(list, count);
+ *
+ *   // Get identifiers
+ *   snd_ctl_elem_list(ctl, list); // yes, this is same as above :)
+ *
+ *   // Do something useful with the list...
+ *
+ *   // Cleanup
+ *   snd_ctl_elem_list_free_space(list);
+ *   snd_ctl_elem_list_free(list);
+ * \endcode
+ *
+ *
+ * \par The Elements
+ *
+ * The elements in the list are accessed using an index. This index is
+ * the location in the list; Don't confuse it with the 'index' of the
+ * element identifier. For example:
+ *
+ * \code
+ *     snd_ctl_elem_list_t list;
+ *     unsigned int element_index;
+ *
+ *     // Allocate space, fill list ...
+ *
+ *     element_index = snd_ctl_elem_list_get_index(&list, 2);
+ * \endcode
+ *
+ * This will access the 3rd element in the list (index=2) and get the
+ * elements index from the driver (which might be 13, for example).
+ */
 typedef struct _snd_ctl_elem_list snd_ctl_elem_list_t;
 
 /** CTL element info container */
 typedef struct _snd_ctl_elem_info snd_ctl_elem_info_t;
 
-/** CTL element value container */
+/** CTL element value container
+ *
+ * Contains the value(s) (i.e. members) of a single element. All
+ * values of a given element are of the same type.
+ *
+ * \par Memory management
+ *
+ * To access a value, a snd_ctl_elem_value_t must be allocated using
+ * snd_ctl_elem_value_alloca() or snd_ctl_elem_value_malloc(). When
+ * using the latter, it must be freed again using
+ * snd_ctl_elem_value_free().
+ *
+ * \par Identifier
+ *
+ * Then, the ID must be filled. It is sufficient to fill only the
+ * numid, if known. Otherwise, interface type, device, subdevice,
+ * name, index must all be given.  The following functions can be used
+ * to fill the ID:
+ *
+ * - snd_ctl_elem_value_set_id(): Set the ID. Requires an
+ *   snd_ctl_elem_id_t object.
+ * - snd_ctl_elem_value_set_numid(): Set the numid.
+ * - Or use all of the following:
+ *
+ *   - snd_ctl_elem_value_set_interface()
+ *   - snd_ctl_elem_value_set_device()
+ *   - snd_ctl_elem_value_set_subdevice()
+ *   - snd_ctl_elem_value_set_name()
+ *   - snd_ctl_elem_value_set_index()
+ *
+ * When communicating with the driver (snd_ctl_elem_read(),
+ * snd_ctl_elem_write()), and the numid was given, the interface,
+ * device, ... are filled (even if you set the before). When the numid
+ * is unset (i.e. it is 0), it is filled.
+ *
+ * \par Communicating with the driver
+ *
+ * After the value container was created and filled with the ID of the
+ * desired element, the value(s) can be fetched from the driver (and
+ * thus from the hardware) or written to the driver.
+ *
+ * To fetch a value, use snd_ctl_elem_read(). Thereafter, use the
+ * snd_ctl_elem_value_get_*() functions to obtain the actual value.
+ *
+ * To write a new value, first use a snd_ctl_elem_value_set_*() to set
+ * it, then call snd_ctl_elem_write() to write it to the driver.
+ */
 typedef struct _snd_ctl_elem_value snd_ctl_elem_value_t;
 
 /** CTL event container */
@@ -354,11 +468,18 @@ void snd_ctl_event_copy(snd_ctl_event_t *dst, const snd_ctl_event_t *src);
 snd_ctl_event_type_t snd_ctl_event_get_type(const snd_ctl_event_t *obj);
 
 size_t snd_ctl_elem_list_sizeof(void);
+
 /** \hideinitializer
- * \brief allocate an invalid #snd_ctl_elem_list_t using standard alloca
- * \param ptr returned pointer
+ *
+ * \brief Allocate a #snd_ctl_elem_list_t using standard alloca.
+ *
+ * The memory is allocated on the stack and will automatically be
+ * released when the stack unwinds (i.e. no free() is needed).
+ *
+ * \param ptr Pointer to allocated memory.
  */
 #define snd_ctl_elem_list_alloca(ptr) __snd_alloca(ptr, snd_ctl_elem_list)
+
 int snd_ctl_elem_list_malloc(snd_ctl_elem_list_t **ptr);
 void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj);
 void snd_ctl_elem_list_clear(snd_ctl_elem_list_t *obj);
@@ -454,11 +575,20 @@ int snd_ctl_elem_add_iec958(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id);
 int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id);
 
 size_t snd_ctl_elem_value_sizeof(void);
+
 /** \hideinitializer
- * \brief allocate an invalid #snd_ctl_elem_value_t using standard alloca
- * \param ptr returned pointer
+ * \brief Allocate an invalid #snd_ctl_elem_value_t on the stack.
+ *
+ * Allocate space for a value object on the stack. The allocated
+ * memory need not be freed, because is on the stack.
+ *
+ * See snd_ctl_elem_value_t for details.
+ *
+ * \param ptr Pointer to a snd_ctl_elem_value_t pointer. The address
+ *            of the allocated space will returned here.
  */
 #define snd_ctl_elem_value_alloca(ptr) __snd_alloca(ptr, snd_ctl_elem_value)
+
 int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr);
 void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj);
 void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj);

include/sound/uapi/asoc.h

@@ -169,16 +169,22 @@
 #define SND_SOC_TPLG_LNK_FLGBIT_VOICE_WAKEUP            (1 << 3)
 
 /* DAI topology BCLK parameter
- * For the backwards capability, by default codec is bclk master
+ * For the backwards capability, by default codec is bclk provider
  */
-#define SND_SOC_TPLG_BCLK_CM         0 /* codec is bclk master */
-#define SND_SOC_TPLG_BCLK_CS         1 /* codec is bclk slave */
+#define SND_SOC_TPLG_BCLK_CP         0 /* codec is bclk provider */
+#define SND_SOC_TPLG_BCLK_CC         1 /* codec is bclk consumer */
+/* keep previous definitions for compatibility */
+#define SND_SOC_TPLG_BCLK_CM         SND_SOC_TPLG_BCLK_CP
+#define SND_SOC_TPLG_BCLK_CS         SND_SOC_TPLG_BCLK_CC
 
 /* DAI topology FSYNC parameter
- * For the backwards capability, by default codec is fsync master
+ * For the backwards capability, by default codec is fsync provider
  */
-#define SND_SOC_TPLG_FSYNC_CM         0 /* codec is fsync master */
-#define SND_SOC_TPLG_FSYNC_CS         1 /* codec is fsync slave */
+#define SND_SOC_TPLG_FSYNC_CP         0 /* codec is fsync provider */
+#define SND_SOC_TPLG_FSYNC_CC         1 /* codec is fsync consumer */
+/* keep previous definitions for compatibility */
+#define SND_SOC_TPLG_FSYNC_CM         SND_SOC_TPLG_FSYNC_CP
+#define SND_SOC_TPLG_FSYNC_CS         SND_SOC_TPLG_FSYNC_CC
 
 /*
  * Block Header.
@@ -335,8 +341,8 @@ struct snd_soc_tplg_hw_config {
 	__u8 clock_gated;	/* SND_SOC_TPLG_DAI_CLK_GATE_ value */
 	__u8 invert_bclk;	/* 1 for inverted BCLK, 0 for normal */
 	__u8 invert_fsync;	/* 1 for inverted frame clock, 0 for normal */
-	__u8 bclk_master;	/* SND_SOC_TPLG_BCLK_ value */
-	__u8 fsync_master;	/* SND_SOC_TPLG_FSYNC_ value */
+	__u8 bclk_provider;	/* SND_SOC_TPLG_BCLK_ value */
+	__u8 fsync_provider;	/* SND_SOC_TPLG_FSYNC_ value */
 	__u8 mclk_direction;    /* SND_SOC_TPLG_MCLK_ value */
 	__le16 reserved;	/* for 32bit alignment */
 	__le32 mclk_rate;	/* MCLK or SYSCLK freqency in Hz */

include/topology.h

@@ -658,8 +658,8 @@ extern "C" {
  *
  *	id "1"				# used for binding to the config
  *	format "I2S"			# physical audio format.
- *	bclk   "master"			# Platform is master of bit clock
- *	fsync  "slave"			# Platform is slave of fsync
+ *	bclk   "codec_provider"		# Codec provides the bit clock
+ *	fsync  "codec_consumer"		# Codec follows the fsync
  * }
  * </pre>
  *
@@ -1028,8 +1028,8 @@ struct snd_tplg_hw_config_template {
 	unsigned char clock_gated;      /* SND_SOC_TPLG_DAI_CLK_GATE_ value */
 	unsigned char  invert_bclk;     /* 1 for inverted BCLK, 0 for normal */
 	unsigned char  invert_fsync;    /* 1 for inverted frame clock, 0 for normal */
-	unsigned char  bclk_master;     /* SND_SOC_TPLG_BCLK_ value */
-	unsigned char  fsync_master;    /* SND_SOC_TPLG_FSYNC_ value */
+	unsigned char  bclk_provider;   /* SND_SOC_TPLG_BCLK_ value */
+	unsigned char  fsync_provider;  /* SND_SOC_TPLG_FSYNC_ value */
 	unsigned char  mclk_direction;  /* SND_SOC_TPLG_MCLK_ value */
 	unsigned short reserved;        /* for 32bit alignment */
 	unsigned int mclk_rate;	        /* MCLK or SYSCLK freqency in Hz */

src/conf.c

@@ -1536,6 +1536,8 @@ static void string_print(char *str, int id, snd_output_t *out)
 	case ']':
 	case '\'':
 	case '"':
+	case '*':
+	case '#':
 		goto quoted;
 	default:
 		if (*p <= 31 || *p >= 127)

src/conf/cards/USB-Audio.conf

@@ -63,6 +63,8 @@ USB-Audio.pcm.iec958_device {
 	"Scarlett 2i4 USB" 999
 	"Sennheiser USB headset" 999
 	"SWTOR Gaming Headset by Razer" 999
+	"ThinkStation P620 Main" 999
+	"ThinkStation P620 Rear" 999
 	"Thunderbolt Dock Audio Headset" 999
 	"Thunderbolt Dock Audio Module" 999
 	"USB Device 0x46d_0x821" 999