ALSA: PCM: channel mapping API implementation

This patch implements the basic data types for the standard channel
mapping API handling.

- The definitions of the channel positions and the new TLV types are
  added in sound/asound.h and sound/tlv.h, so that they can be
  referred from user-space.

- Introduced a new helper function snd_pcm_add_chmap_ctls() to create
  control elements representing the channel maps for each PCM
  (sub)stream.

- Some standard pre-defined channel maps are provided for
  convenience.

Signed-off-by: Takashi Iwai <tiwai@suse.de>

3 files changed, 86 insertions, 0 deletions

diff --git a/include/sound/asound.h b/include/sound/asound.h
index 0876a1e76aef..376e75632e07 100644
--- a/include/sound/asound.h
+++ b/include/sound/asound.h
@@ -472,6 +472,36 @@ enum {
         SNDRV_PCM_TSTAMP_TYPE_LAST = SNDRV_PCM_TSTAMP_TYPE_MONOTONIC,
 };
 
+/* channel positions */
+enum {
+        SNDRV_CHMAP_UNKNOWN = 0,
+        SNDRV_CHMAP_FL,         /* front left */
+        SNDRV_CHMAP_FC,         /* front center */
+        SNDRV_CHMAP_FR,         /* front right */
+        SNDRV_CHMAP_FLC,        /* front left center */
+        SNDRV_CHMAP_FRC,        /* front right center */
+        SNDRV_CHMAP_RL,         /* rear left */
+        SNDRV_CHMAP_RC,         /* rear center */
+        SNDRV_CHMAP_RR,         /* rear right */
+        SNDRV_CHMAP_RLC,        /* rear left center */
+        SNDRV_CHMAP_RRC,        /* rear right center */
+        SNDRV_CHMAP_SL,         /* side left */
+        SNDRV_CHMAP_SR,         /* side right */
+        SNDRV_CHMAP_LFE,        /* LFE */
+        SNDRV_CHMAP_FLW,        /* front left wide */
+        SNDRV_CHMAP_FRW,        /* front right wide */
+        SNDRV_CHMAP_FLH,        /* front left high */
+        SNDRV_CHMAP_FCH,        /* front center high */
+        SNDRV_CHMAP_FRH,        /* front right high */
+        SNDRV_CHMAP_TC,         /* top center */
+        SNDRV_CHMAP_NA,         /* N/A, silent */
+        SNDRV_CHMAP_LAST = SNDRV_CHMAP_NA,
+};
+
+#define SNDRV_CHMAP_POSITION_MASK       0xffff
+#define SNDRV_CHMAP_PHASE_INVERSE       (0x01 << 16)
+#define SNDRV_CHMAP_DRIVER_SPEC         (0x02 << 16)
+
 #define SNDRV_PCM_IOCTL_PVERSION        _IOR('A', 0x00, int)
 #define SNDRV_PCM_IOCTL_INFO            _IOR('A', 0x01, struct snd_pcm_info)
 #define SNDRV_PCM_IOCTL_TSTAMP          _IOW('A', 0x02, int)
diff --git a/include/sound/pcm.h b/include/sound/pcm.h
index cdca2ab1e711..669c85a7fb03 100644
--- a/include/sound/pcm.h
+++ b/include/sound/pcm.h
@@ -437,6 +437,7 @@ struct snd_pcm_str {
         struct snd_info_entry *proc_xrun_debug_entry;
 #endif
 #endif
+        struct snd_kcontrol *chmap_kctl; /* channel-mapping controls */
 };
 
 struct snd_pcm {
@@ -1086,4 +1087,51 @@ static inline const char *snd_pcm_stream_str(struct snd_pcm_substream *substream
                 return "Capture";
 }
 
+/*
+ * PCM channel-mapping control API
+ */
+/* array element of channel maps */
+struct snd_pcm_chmap_elem {
+        unsigned char channels;
+        unsigned char map[15];
+};
+
+/* channel map information; retrieved via snd_kcontrol_chip() */
+struct snd_pcm_chmap {
+        struct snd_pcm *pcm;    /* assigned PCM instance */
+        int stream;             /* PLAYBACK or CAPTURE */
+        struct snd_kcontrol *kctl;
+        const struct snd_pcm_chmap_elem *chmap;
+        unsigned int max_channels;
+        unsigned int channel_mask;      /* optional: active channels bitmask */
+        void *private_data;     /* optional: private data pointer */
+};
+
+/* get the PCM substream assigned to the given chmap info */
+static inline struct snd_pcm_substream *
+snd_pcm_chmap_substream(struct snd_pcm_chmap *info, unsigned int idx)
+{
+        struct snd_pcm_substream *s;
+        for (s = info->pcm->streams[info->stream].substream; s; s = s->next)
+                if (s->number == idx)
+                        return s;
+        return NULL;
+}
+
+/* ALSA-standard channel maps (RL/RR prior to C/LFE) */
+extern const struct snd_pcm_chmap_elem snd_pcm_std_chmaps[];
+/* Other world's standard channel maps (C/LFE prior to RL/RR) */
+extern const struct snd_pcm_chmap_elem snd_pcm_alt_chmaps[];
+
+/* bit masks to be passed to snd_pcm_chmap.channel_mask field */
+#define SND_PCM_CHMAP_MASK_24   ((1U << 2) | (1U << 4))
+#define SND_PCM_CHMAP_MASK_246  (SND_PCM_CHMAP_MASK_24 | (1U << 6))
+#define SND_PCM_CHMAP_MASK_2468 (SND_PCM_CHMAP_MASK_246 | (1U << 8))
+
+int snd_pcm_add_chmap_ctls(struct snd_pcm *pcm, int stream,
+                           const struct snd_pcm_chmap_elem *chmap,
+                           int max_channels,
+                           unsigned long private_value,
+                           struct snd_pcm_chmap **info_ret);
+
 #endif /* __SOUND_PCM_H */
diff --git a/include/sound/tlv.h b/include/sound/tlv.h
index a64d8fe3f855..28c65e1ada21 100644
--- a/include/sound/tlv.h
+++ b/include/sound/tlv.h
@@ -86,4 +86,12 @@
 
 #define TLV_DB_GAIN_MUTE        -9999999
 
+/*
+ * channel-mapping TLV items
+ *  TLV length must match with num_channels
+ */
+#define SNDRV_CTL_TLVT_CHMAP_FIXED      0x101   /* fixed channel position */
+#define SNDRV_CTL_TLVT_CHMAP_VAR        0x102   /* channels freely swappable */
+#define SNDRV_CTL_TLVT_CHMAP_PAIRED     0x103   /* pair-wise swappable */
+
 #endif /* __SOUND_TLV_H */