Merge tag 'sound-4.13-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound

Pull sound updates from Takashi Iwai:
 "This development cycle resulted in a fair amount of changes in both
  core and driver sides. The most significant change in ALSA core is
  about PCM. Also the support of of-graph card and the new DAPM widget
  for DSP are noteworthy changes in ASoC core. And there're lots of
  small changes splat over the tree, as you can see in diffstat.

  Below are a few highlights:

  ALSA core:
   - Removal of set_fs() hackery from PCM core stuff, and the code
     reorganization / optimization thereafter
   - Improved support of PCM ack ops, and a new ABI for improved
     control/status mmap handling
   - Lots of constifications in various codes

  ASoC core:
   - The support of of-graph card, which may work as a better generic
     device for a replacement of simple-card
   - New widget types intended mainly for use with DSPs

  ASoC drivers:
   - New drivers for Allwinner V3s SoCs
   - Ensonic ES8316 codec support
   - More Intel SKL and KBL works
   - More device support for Intel SST Atom (mostly for cheap tablets
     and 2-in-1 devices)
   - Support for Rockchip PDM controllers
   - Support for STM32 I2S and S/PDIF controllers
   - Support for ZTE AUD96P22 codecs

  HD-audio:
   - Support of new Realtek codecs (ALC215/ALC285/ALC289), more quirks
     for HP and Dell machines
   - A few more fixes for i915 component binding"

* tag 'sound-4.13-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound: (418 commits)
  ALSA: hda - Fix unbalance of i915 module refcount
  ASoC: Intel: Skylake: Remove driver debugfs exit
  ASoC: Intel: Skylake: explicitly add the headers sst-dsp.h
  ALSA: hda/realtek - Remove GPIO_MASK
  ALSA: hda/realtek - Fix typo of pincfg for Dell quirk
  ALSA: pcm: add a documentation for tracepoints
  ALSA: atmel: ac97c: fix error return code in atmel_ac97c_probe()
  ALSA: x86: fix error return code in hdmi_lpe_audio_probe()
  ASoC: Intel: Skylake: Add support to read firmware registers
  ASoC: Intel: Skylake: Add sram address to sst_addr structure
  ASoC: Intel: Skylake: Debugfs facility to dump module config
  ASoC: Intel: Skylake: Add debugfs support
  ASoC: fix semicolon.cocci warnings
  ASoC: rt5645: Add quirk override by module option
  ASoC: rsnd: make arrays path and cmd_case static const
  ASoC: audio-graph-card: add widgets and routing for external amplifier support
  ASoC: audio-graph-card: update bindings for amplifier support
  ASoC: rt5665: calibration should be done before jack detection
  ASoC: rsnd: constify dev_pm_ops structures.
  ASoC: nau8825: change crosstalk-bypass property to bool type
  ...

4 files changed, 267 insertions, 35 deletions

diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index 04dcdae3e4f2..f0749943ccb2 100644
--- a/Documentation/sound/designs/index.rst
+++ b/Documentation/sound/designs/index.rst
@@ -9,6 +9,7 @@ Designs and Implementations
    compress-offload
    timestamping
    jack-controls
+   tracepoints
    procfile
    powersave
    oss-emulation
diff --git a/Documentation/sound/designs/tracepoints.rst b/Documentation/sound/designs/tracepoints.rst
new file mode 100644
index 000000000000..78bc5572f829
--- /dev/null
+++ b/Documentation/sound/designs/tracepoints.rst
@@ -0,0 +1,172 @@
+===================
+Tracepoints in ALSA
+===================
+
+2017/07/02
+Takasahi Sakamoto
+
+Tracepoints in ALSA PCM core
+============================
+
+ALSA PCM core registers ``snd_pcm`` subsystem to kernel tracepoint system.
+This subsystem includes two categories of tracepoints; for state of PCM buffer
+and for processing of PCM hardware parameters. These tracepoints are available
+when corresponding kernel configurations are enabled. When ``CONFIG_SND_DEBUG``
+is enabled, the latter tracepoints are available. When additional
+``SND_PCM_XRUN_DEBUG`` is enabled too, the former trace points are enabled.
+
+Tracepoints for state of PCM buffer
+------------------------------------
+
+This category includes four tracepoints; ``hwptr``, ``applptr``, ``xrun`` and
+``hw_ptr_error``.
+
+Tracepoints for processing of PCM hardware parameters
+-----------------------------------------------------
+
+This category includes two tracepoints; ``hw_mask_param`` and
+``hw_interval_param``.
+
+In a design of ALSA PCM core, data transmission is abstracted as PCM substream.
+Applications manage PCM substream to maintain data transmission for PCM frames.
+Before starting the data transmission, applications need to configure PCM
+substream. In this procedure, PCM hardware parameters are decided by
+interaction between applications and ALSA PCM core. Once decided, runtime of
+the PCM substream keeps the parameters.
+
+The parameters are described in :c:type:`struct snd_pcm_hw_params`. This
+structure includes several types of parameters. Applications set preferable
+value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE
+or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available
+set of parameters. The latter is used for an actual decision of the parameters.
+
+The :c:type:`struct snd_pcm_hw_params` structure has below members:
+
+``flags``
+        Configurable. ALSA PCM core and some drivers handle this flag to select
+        convenient parameters or change their behaviour.
+``masks``
+        Configurable. This type of parameter is described in
+        :c:type:`struct snd_mask` and represent mask values. As of PCM protocol
+        v2.0.13, three types are defined.
+
+        - SNDRV_PCM_HW_PARAM_ACCESS
+        - SNDRV_PCM_HW_PARAM_FORMAT
+        - SNDRV_PCM_HW_PARAM_SUBFORMAT
+``intervals``
+        Configurable. This type of parameter is described in
+        :c:type:`struct snd_interval` and represent values with a range. As of
+        PCM protocol v2.0.13, twelve types are defined.
+
+        - SNDRV_PCM_HW_PARAM_SAMPLE_BITS
+        - SNDRV_PCM_HW_PARAM_FRAME_BITS
+        - SNDRV_PCM_HW_PARAM_CHANNELS
+        - SNDRV_PCM_HW_PARAM_RATE
+        - SNDRV_PCM_HW_PARAM_PERIOD_TIME
+        - SNDRV_PCM_HW_PARAM_PERIOD_SIZE
+        - SNDRV_PCM_HW_PARAM_PERIOD_BYTES
+        - SNDRV_PCM_HW_PARAM_PERIODS
+        - SNDRV_PCM_HW_PARAM_BUFFER_TIME
+        - SNDRV_PCM_HW_PARAM_BUFFER_SIZE
+        - SNDRV_PCM_HW_PARAM_BUFFER_BYTES
+        - SNDRV_PCM_HW_PARAM_TICK_TIME
+``rmask``
+        Configurable. This is evaluated at ioctl(2) with
+        SNDRV_PCM_IOCTL_HW_REFINE only. Applications can select which
+        mask/interval parameter can be changed by ALSA PCM core. For
+        SNDRV_PCM_IOCTL_HW_PARAMS, this mask is ignored and all of parameters
+        are going to be changed.
+``cmask``
+        Read-only. After returning from ioctl(2), buffer in user space for
+        :c:type:`struct snd_pcm_hw_params` includes result of each operation.
+        This mask represents which mask/interval parameter is actually changed.
+``info``
+        Read-only. This represents hardware/driver capabilities as bit flags
+        with SNDRV_PCM_INFO_XXX. Typically, applications execute ioctl(2) with
+        SNDRV_PCM_IOCTL_HW_REFINE to retrieve this flag, then decide candidates
+        of parameters and execute ioctl(2) with SNDRV_PCM_IOCTL_HW_PARAMS to
+        configure PCM substream.
+``msbits``
+        Read-only. This value represents available bit width in MSB side of
+        a PCM sample. When a parameter of SNDRV_PCM_HW_PARAM_SAMPLE_BITS was
+        decided as a fixed number, this value is also calculated according to
+        it. Else, zero. But this behaviour depends on implementations in driver
+        side.
+``rate_num``
+        Read-only. This value represents numerator of sampling rate in fraction
+        notation. Basically, when a parameter of SNDRV_PCM_HW_PARAM_RATE was
+        decided as a single value, this value is also calculated according to
+        it. Else, zero. But this behaviour depends on implementations in driver
+        side.
+``rate_den``
+        Read-only. This value represents denominator of sampling rate in
+        fraction notation. Basically, when a parameter of
+        SNDRV_PCM_HW_PARAM_RATE was decided as a single value, this value is
+        also calculated according to it. Else, zero. But this behaviour depends
+        on implementations in driver side.
+``fifo_size``
+        Read-only. This value represents the size of FIFO in serial sound
+        interface of hardware. Basically, each driver can assigns a proper
+        value to this parameter but some drivers intentionally set zero with
+        a care of hardware design or data transmission protocol.
+
+ALSA PCM core handles buffer of :c:type:`struct snd_pcm_hw_params` when
+applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.
+Parameters in the buffer are changed according to
+:c:type:`struct snd_pcm_hardware` and rules of constraints in the runtime. The
+structure describes capabilities of handled hardware. The rules describes
+dependencies on which a parameter is decided according to several parameters.
+A rule has a callback function, and drivers can register arbitrary functions
+to compute the target parameter. ALSA PCM core registers some rules to the
+runtime as a default.
+
+Each driver can join in the interaction as long as it prepared for two stuffs
+in a callback of :c:type:`struct snd_pcm_ops.open`.
+
+1. In the callback, drivers are expected to change a member of
+   :c:type:`struct snd_pcm_hardware` type in the runtime, according to
+   capacities of corresponding hardware.
+2. In the same callback, drivers are also expected to register additional rules
+   of constraints into the runtime when several parameters have dependencies
+   due to hardware design.
+
+The driver can refers to result of the interaction in a callback of
+:c:type:`struct snd_pcm_ops.hw_params`, however it should not change the
+content.
+
+Tracepoints in this category are designed to trace changes of the
+mask/interval parameters. When ALSA PCM core changes them, ``hw_mask_param`` or
+``hw_interval_param`` event is probed according to type of the changed parameter.
+
+ALSA PCM core also has a pretty print format for each of the tracepoints. Below
+is an example for ``hw_mask_param``.
+
+::
+
+    hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044
+
+
+Below is an example for ``hw_interval_param``.
+
+::
+
+    hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295]
+
+The first three fields are common. They represent name of ALSA PCM character
+device, rules of constraint and name of the changed parameter, in order. The
+field for rules of constraint consists of two sub-fields; index of applied rule
+and total number of rules added to the runtime. As an exception, the index 000
+means that the parameter is changed by ALSA PCM core, regardless of the rules.
+
+The rest of field represent state of the parameter before/after changing. These
+fields are different according to type of the parameter. For parameters of mask
+type, the fields represent hexadecimal dump of content of the parameter. For
+parameters of interval type, the fields represent values of each member of
+``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in
+:c:type:`struct snd_interval` in this order.
+
+Tracepoints in drivers
+======================
+
+Some drivers have tracepoints for developers' convenience. For them, please
+refer to each documentation or implementation.
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 95c5443eff38..58ffa3f5bda7 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -2080,8 +2080,8 @@ sleeping poll threads, etc.
 
 This callback is also atomic as default.
 
-copy and silence callbacks
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+copy_user, copy_kernel and fill_silence ops
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These callbacks are not mandatory, and can be omitted in most cases.
 These callbacks are used when the hardware buffer cannot be in the
@@ -3532,8 +3532,9 @@ external hardware buffer in interrupts (or in tasklets, preferably).
 
 The first case works fine if the external hardware buffer is large
 enough. This method doesn't need any extra buffers and thus is more
-effective. You need to define the ``copy`` and ``silence`` callbacks
-for the data transfer. However, there is a drawback: it cannot be
+effective. You need to define the ``copy_user`` and ``copy_kernel``
+callbacks for the data transfer, in addition to ``fill_silence``
+callback for playback. However, there is a drawback: it cannot be
 mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
 
 The second case allows for mmap on the buffer, although you have to
@@ -3545,30 +3546,34 @@ Another case is when the chip uses a PCI memory-map region for the
 buffer instead of the host memory. In this case, mmap is available only
 on certain architectures like the Intel one. In non-mmap mode, the data
 cannot be transferred as in the normal way. Thus you need to define the
-``copy`` and ``silence`` callbacks as well, as in the cases above. The
-examples are found in ``rme32.c`` and ``rme96.c``.
+``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
+as in the cases above. The examples are found in ``rme32.c`` and
+``rme96.c``.
 
-The implementation of the ``copy`` and ``silence`` callbacks depends
-upon whether the hardware supports interleaved or non-interleaved
-samples. The ``copy`` callback is defined like below, a bit
-differently depending whether the direction is playback or capture:
+The implementation of the ``copy_user``, ``copy_kernel`` and
+``silence`` callbacks depends upon whether the hardware supports
+interleaved or non-interleaved samples. The ``copy_user`` callback is
+defined like below, a bit differently depending whether the direction
+is playback or capture:
 
 ::
 
-  static int playback_copy(struct snd_pcm_substream *substream, int channel,
-               snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
-  static int capture_copy(struct snd_pcm_substream *substream, int channel,
-               snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
+  static int playback_copy_user(struct snd_pcm_substream *substream,
+               int channel, unsigned long pos,
+               void __user *src, unsigned long count);
+  static int capture_copy_user(struct snd_pcm_substream *substream,
+               int channel, unsigned long pos,
+               void __user *dst, unsigned long count);
 
 In the case of interleaved samples, the second argument (``channel``) is
 not used. The third argument (``pos``) points the current position
-offset in frames.
+offset in bytes.
 
 The meaning of the fourth argument is different between playback and
 capture. For playback, it holds the source data pointer, and for
 capture, it's the destination data pointer.
 
-The last argument is the number of frames to be copied.
+The last argument is the number of bytes to be copied.
 
 What you have to do in this callback is again different between playback
 and capture directions. In the playback case, you copy the given amount
@@ -3578,8 +3583,7 @@ way, the copy would be like:
 
 ::
 
-  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
-            frames_to_bytes(runtime, count));
+  my_memcpy_from_user(my_buffer + pos, src, count);
 
 For the capture direction, you copy the given amount of data (``count``)
 at the specified offset (``pos``) on the hardware buffer to the
@@ -3587,31 +3591,68 @@ specified pointer (``dst``).
 
 ::
 
-  my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
-            frames_to_bytes(runtime, count));
+  my_memcpy_to_user(dst, my_buffer + pos, count);
+
+Here the functions are named as ``from_user`` and ``to_user`` because
+it's the user-space buffer that is passed to these callbacks.  That
+is, the callback is supposed to copy from/to the user-space data
+directly to/from the hardware buffer.
 
-Note that both the position and the amount of data are given in frames.
+Careful readers might notice that these callbacks receive the
+arguments in bytes, not in frames like other callbacks.  It's because
+it would make coding easier like the examples above, and also it makes
+easier to unify both the interleaved and non-interleaved cases, as
+explained in the following.
 
 In the case of non-interleaved samples, the implementation will be a bit
-more complicated.
+more complicated.  The callback is called for each channel, passed by
+the second argument, so totally it's called for N-channels times per
+transfer.
+
+The meaning of other arguments are almost same as the interleaved
+case.  The callback is supposed to copy the data from/to the given
+user-space buffer, but only for the given channel.  For the detailed
+implementations, please check ``isa/gus/gus_pcm.c`` or
+"pci/rme9652/rme9652.c" as examples.
+
+The above callbacks are the copy from/to the user-space buffer.  There
+are some cases where we want copy from/to the kernel-space buffer
+instead.  In such a case, ``copy_kernel`` callback is called.  It'd
+look like:
+
+::
+
+  static int playback_copy_kernel(struct snd_pcm_substream *substream,
+               int channel, unsigned long pos,
+               void *src, unsigned long count);
+  static int capture_copy_kernel(struct snd_pcm_substream *substream,
+               int channel, unsigned long pos,
+               void *dst, unsigned long count);
+
+As found easily, the only difference is that the buffer pointer is
+without ``__user`` prefix; that is, a kernel-buffer pointer is passed
+in the fourth argument.  Correspondingly, the implementation would be
+a version without the user-copy, such as:
 
-You need to check the channel argument, and if it's -1, copy the whole
-channels. Otherwise, you have to copy only the specified channel. Please
-check ``isa/gus/gus_pcm.c`` as an example.
+::
+
+  my_memcpy(my_buffer + pos, src, count);
 
-The ``silence`` callback is also implemented in a similar way
+Usually for the playback, another callback ``fill_silence`` is
+defined.  It's implemented in a similar way as the copy callbacks
+above:
 
 ::
 
   static int silence(struct snd_pcm_substream *substream, int channel,
-                     snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
+                     unsigned long pos, unsigned long count);
 
-The meanings of arguments are the same as in the ``copy`` callback,
-although there is no ``src/dst`` argument. In the case of interleaved
-samples, the channel argument has no meaning, as well as on ``copy``
-callback.
+The meanings of arguments are the same as in the ``copy_user`` and
+``copy_kernel`` callbacks, although there is no buffer pointer
+argument. In the case of interleaved samples, the channel argument has
+no meaning, as well as on ``copy_*`` callbacks.
 
-The role of ``silence`` callback is to set the given amount
+The role of ``fill_silence`` callback is to set the given amount
 (``count``) of silence data at the specified offset (``pos``) on the
 hardware buffer. Suppose that the data format is signed (that is, the
 silent-data is 0), and the implementation using a memset-like function
@@ -3619,11 +3660,11 @@ would be like:
 
 ::
 
-  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
-            frames_to_bytes(runtime, count));
+  my_memset(my_buffer + pos, 0, count);
 
 In the case of non-interleaved samples, again, the implementation
-becomes a bit more complicated. See, for example, ``isa/gus/gus_pcm.c``.
+becomes a bit more complicated, as it's called N-times per transfer
+for each channel. See, for example, ``isa/gus/gus_pcm.c``.
 
 Non-Contiguous Buffers
 ----------------------
diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst
index a27f42befa4d..8e44107933ab 100644
--- a/Documentation/sound/soc/dapm.rst
+++ b/Documentation/sound/soc/dapm.rst
@@ -105,6 +105,24 @@ Pre
         Special PRE widget (exec before all others)
 Post
         Special POST widget (exec after all others)
+Buffer
+        Inter widget audio data buffer within a DSP.
+Scheduler
+        DSP internal scheduler that schedules component/pipeline processing
+        work.
+Effect
+        Widget that performs an audio processing effect.
+SRC
+        Sample Rate Converter within DSP or CODEC
+ASRC
+        Asynchronous Sample Rate Converter within DSP or CODEC
+Encoder
+        Widget that encodes audio data from one format (usually PCM) to another
+        usually more compressed format.
+Decoder
+        Widget that decodes audio data from a compressed format to an
+        uncompressed format like PCM.
+
 
 (Widgets are defined in include/sound/soc-dapm.h)