summaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt8
-rw-r--r--Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt9
-rw-r--r--Documentation/devicetree/bindings/sound/audio-graph-card.txt129
-rw-r--r--Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt122
-rw-r--r--Documentation/devicetree/bindings/sound/cs35l35.txt3
-rw-r--r--Documentation/devicetree/bindings/sound/nau8825.txt3
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,rsnd.txt37
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,pdm.txt39
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip-spdif.txt2
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,odroid.txt15
-rw-r--r--Documentation/devicetree/bindings/sound/simple-scu-card.txt67
-rw-r--r--Documentation/devicetree/bindings/sound/st,stm32-i2s.txt62
-rw-r--r--Documentation/devicetree/bindings/sound/st,stm32-sai.txt41
-rw-r--r--Documentation/devicetree/bindings/sound/st,stm32-spdifrx.txt56
-rw-r--r--Documentation/devicetree/bindings/sound/sun4i-codec.txt11
-rw-r--r--Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt1
-rw-r--r--Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt24
-rw-r--r--Documentation/sound/designs/index.rst1
-rw-r--r--Documentation/sound/designs/tracepoints.rst172
-rw-r--r--Documentation/sound/kernel-api/writing-an-alsa-driver.rst111
-rw-r--r--Documentation/sound/soc/dapm.rst18
21 files changed, 804 insertions, 127 deletions
diff --git a/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt
index 00ea670b8c4d..06668bca7ffc 100644
--- a/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt
+++ b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt
@@ -78,6 +78,7 @@ graph bindings specified in Documentation/devicetree/bindings/graph.txt.
remote endpoint phandle should be a reference to a valid mipi_dsi_host device
node.
- Video port 1 for the HDMI output
+- Audio port 2 for the HDMI audio input
Example
@@ -112,5 +113,12 @@ Example
remote-endpoint = <&hdmi_connector_in>;
};
};
+
+ port@2 {
+ reg = <2>;
+ codec_endpoint: endpoint {
+ remote-endpoint = <&i2s0_cpu_endpoint>;
+ };
+ };
};
};
diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt
index f6b3f36d422b..81b68580e199 100644
--- a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt
+++ b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt
@@ -25,7 +25,8 @@ Required properties:
- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt.
- ports: See dw_hdmi.txt. The DWC HDMI shall have one port numbered 0
corresponding to the video input of the controller and one port numbered 1
- corresponding to its HDMI output. Each port shall have a single endpoint.
+ corresponding to its HDMI output, and one port numbered 2 corresponding to
+ sound input of the controller. Each port shall have a single endpoint.
Optional properties:
@@ -59,6 +60,12 @@ Example:
remote-endpoint = <&hdmi0_con>;
};
};
+ port@2 {
+ reg = <2>;
+ rcar_dw_hdmi0_sound_in: endpoint {
+ remote-endpoint = <&hdmi_sound_out>;
+ };
+ };
};
};
diff --git a/Documentation/devicetree/bindings/sound/audio-graph-card.txt b/Documentation/devicetree/bindings/sound/audio-graph-card.txt
new file mode 100644
index 000000000000..6e6720aa33f1
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/audio-graph-card.txt
@@ -0,0 +1,129 @@
+Audio Graph Card:
+
+Audio Graph Card specifies audio DAI connections of SoC <-> codec.
+It is based on common bindings for device graphs.
+see ${LINUX}/Documentation/devicetree/bindings/graph.txt
+
+Basically, Audio Graph Card property is same as Simple Card.
+see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.txt
+
+Below are same as Simple-Card.
+
+- label
+- widgets
+- routing
+- dai-format
+- frame-master
+- bitclock-master
+- bitclock-inversion
+- frame-inversion
+- dai-tdm-slot-num
+- dai-tdm-slot-width
+- clocks / system-clock-frequency
+
+Required properties:
+
+- compatible : "audio-graph-card";
+- dais : list of CPU DAI port{s}
+
+Optional properties:
+- pa-gpios: GPIO used to control external amplifier.
+
+Example: Single DAI case
+
+ sound_card {
+ compatible = "audio-graph-card";
+
+ dais = <&cpu_port>;
+ };
+
+ dai-controller {
+ ...
+ cpu_port: port {
+ cpu_endpoint: endpoint {
+ remote-endpoint = <&codec_endpoint>;
+
+ dai-format = "left_j";
+ ...
+ };
+ };
+ };
+
+ audio-codec {
+ ...
+ port {
+ codec_endpoint: endpoint {
+ remote-endpoint = <&cpu_endpoint>;
+ };
+ };
+ };
+
+Example: Multi DAI case
+
+ sound-card {
+ compatible = "audio-graph-card";
+
+ label = "sound-card";
+
+ dais = <&cpu_port0
+ &cpu_port1
+ &cpu_port2>;
+ };
+
+ audio-codec@0 {
+ ...
+ port {
+ codec0_endpoint: endpoint {
+ remote-endpoint = <&cpu_endpoint0>;
+ };
+ };
+ };
+
+ audio-codec@1 {
+ ...
+ port {
+ codec1_endpoint: endpoint {
+ remote-endpoint = <&cpu_endpoint1>;
+ };
+ };
+ };
+
+ audio-codec@2 {
+ ...
+ port {
+ codec2_endpoint: endpoint {
+ remote-endpoint = <&cpu_endpoint2>;
+ };
+ };
+ };
+
+ dai-controller {
+ ...
+ ports {
+ cpu_port0: port@0 {
+ cpu_endpoint0: endpoint {
+ remote-endpoint = <&codec0_endpoint>;
+
+ dai-format = "left_j";
+ ...
+ };
+ };
+ cpu_port1: port@1 {
+ cpu_endpoint1: endpoint {
+ remote-endpoint = <&codec1_endpoint>;
+
+ dai-format = "i2s";
+ ...
+ };
+ };
+ cpu_port2: port@2 {
+ cpu_endpoint2: endpoint {
+ remote-endpoint = <&codec2_endpoint>;
+
+ dai-format = "i2s";
+ ...
+ };
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt b/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt
new file mode 100644
index 000000000000..8b8afe9fcb31
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt
@@ -0,0 +1,122 @@
+Audio-Graph-SCU-Card:
+
+Audio-Graph-SCU-Card is "Audio-Graph-Card" + "ALSA DPCM".
+
+It is based on common bindings for device graphs.
+see ${LINUX}/Documentation/devicetree/bindings/graph.txt
+
+Basically, Audio-Graph-SCU-Card property is same as
+Simple-Card / Simple-SCU-Card / Audio-Graph-Card.
+see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.txt
+ ${LINUX}/Documentation/devicetree/bindings/sound/simple-scu-card.txt
+ ${LINUX}/Documentation/devicetree/bindings/sound/audio-graph-card.txt
+
+Below are same as Simple-Card / Audio-Graph-Card.
+
+- label
+- dai-format
+- frame-master
+- bitclock-master
+- bitclock-inversion
+- frame-inversion
+- dai-tdm-slot-num
+- dai-tdm-slot-width
+- clocks / system-clock-frequency
+
+Below are same as Simple-SCU-Card.
+
+- convert-rate
+- convert-channels
+- prefix
+- routing
+
+Required properties:
+
+- compatible : "audio-graph-scu-card";
+- dais : list of CPU DAI port{s}
+
+Example 1. Sampling Rate Conversion
+
+ sound_card {
+ compatible = "audio-graph-scu-card";
+
+ label = "sound-card";
+ prefix = "codec";
+ routing = "codec Playback", "DAI0 Playback",
+ "codec Playback", "DAI1 Playback";
+ convert-rate = <48000>;
+
+ dais = <&cpu_port>;
+ };
+
+ audio-codec {
+ ...
+
+ port {
+ codec_endpoint: endpoint {
+ remote-endpoint = <&cpu_endpoint>;
+ };
+ };
+ };
+
+ dai-controller {
+ ...
+ cpu_port: port {
+ cpu_endpoint: endpoint {
+ remote-endpoint = <&codec_endpoint>;
+
+ dai-format = "left_j";
+ ...
+ };
+ };
+ };
+
+Example 2. 2 CPU 1 Codec (Mixing)
+
+ sound_card {
+ compatible = "audio-graph-scu-card";
+
+ label = "sound-card";
+ prefix = "codec";
+ routing = "codec Playback", "DAI0 Playback",
+ "codec Playback", "DAI1 Playback";
+ convert-rate = <48000>;
+
+ dais = <&cpu_port0
+ &cpu_port1>;
+ };
+
+ audio-codec {
+ ...
+
+ port {
+ codec_endpoint0: endpoint {
+ remote-endpoint = <&cpu_endpoint0>;
+ };
+ codec_endpoint1: endpoint {
+ remote-endpoint = <&cpu_endpoint1>;
+ };
+ };
+ };
+
+ dai-controller {
+ ...
+ ports {
+ cpu_port0: port {
+ cpu_endpoint0: endpoint {
+ remote-endpoint = <&codec_endpoint0>;
+
+ dai-format = "left_j";
+ ...
+ };
+ };
+ cpu_port1: port {
+ cpu_endpoint1: endpoint {
+ remote-endpoint = <&codec_endpoint1>;
+
+ dai-format = "left_j";
+ ...
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/cs35l35.txt b/Documentation/devicetree/bindings/sound/cs35l35.txt
index 016b768bc722..77ee75c39233 100644
--- a/Documentation/devicetree/bindings/sound/cs35l35.txt
+++ b/Documentation/devicetree/bindings/sound/cs35l35.txt
@@ -16,6 +16,9 @@ Required properties:
(See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
for further information relating to interrupt properties)
+ - cirrus,boost-ind-nanohenry: Inductor value for boost converter. The value is
+ in nH and they can be values of 1000nH, 1200nH, 1500nH, and 2200nH.
+
Optional properties:
- reset-gpios : gpio used to reset the amplifier
diff --git a/Documentation/devicetree/bindings/sound/nau8825.txt b/Documentation/devicetree/bindings/sound/nau8825.txt
index d3374231c871..2f5e973285a6 100644
--- a/Documentation/devicetree/bindings/sound/nau8825.txt
+++ b/Documentation/devicetree/bindings/sound/nau8825.txt
@@ -69,6 +69,8 @@ Optional properties:
- nuvoton,jack-insert-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms
- nuvoton,jack-eject-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms
+ - nuvoton,crosstalk-bypass: make crosstalk function bypass if set.
+
- clocks: list of phandle and clock specifier pairs according to common clock bindings for the
clocks described in clock-names
- clock-names: should include "mclk" for the MCLK master clock
@@ -96,6 +98,7 @@ Example:
nuvoton,short-key-debounce = <2>;
nuvoton,jack-insert-debounce = <7>;
nuvoton,jack-eject-debounce = <7>;
+ nuvoton,crosstalk-bypass;
clock-names = "mclk";
clocks = <&tegra_car TEGRA210_CLK_CLK_OUT_2>;
diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt
index 15a7316e4c91..7246bb268bf9 100644
--- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt
+++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt
@@ -83,11 +83,11 @@ SRC can convert [xx]Hz to [yy]Hz. Then, it has below 2 modes
** Asynchronous mode
------------------
-You need to use "renesas,rsrc-card" sound card for it.
+You need to use "simple-scu-audio-card" sound card for it.
example)
sound {
- compatible = "renesas,rsrc-card";
+ compatible = "simple-scu-audio-card";
...
/*
* SRC Asynchronous mode setting
@@ -97,12 +97,12 @@ example)
* Inputed 48kHz data will be converted to
* system specified Hz
*/
- convert-rate = <48000>;
+ simple-audio-card,convert-rate = <48000>;
...
- cpu {
+ simple-audio-card,cpu {
sound-dai = <&rcar_sound>;
};
- codec {
+ simple-audio-card,codec {
...
};
};
@@ -141,23 +141,23 @@ For more detail information, see below
${LINUX}/sound/soc/sh/rcar/ctu.c
- comment of header
-You need to use "renesas,rsrc-card" sound card for it.
+You need to use "simple-scu-audio-card" sound card for it.
example)
sound {
- compatible = "renesas,rsrc-card";
+ compatible = "simple-scu-audio-card";
...
/*
* CTU setting
* All input data will be converted to 2ch
* as output data
*/
- convert-channels = <2>;
+ simple-audio-card,convert-channels = <2>;
...
- cpu {
+ simple-audio-card,cpu {
sound-dai = <&rcar_sound>;
};
- codec {
+ simple-audio-card,codec {
...
};
};
@@ -190,22 +190,22 @@ and these sounds will be merged by MIX.
aplay -D plughw:0,0 xxxx.wav &
aplay -D plughw:0,1 yyyy.wav
-You need to use "renesas,rsrc-card" sound card for it.
+You need to use "simple-scu-audio-card" sound card for it.
Ex)
[MEM] -> [SRC1] -> [CTU02] -+-> [MIX0] -> [DVC0] -> [SSI0]
|
[MEM] -> [SRC2] -> [CTU03] -+
sound {
- compatible = "renesas,rsrc-card";
+ compatible = "simple-scu-audio-card";
...
- cpu@0 {
+ simple-audio-card,cpu@0 {
sound-dai = <&rcar_sound 0>;
};
- cpu@1 {
+ simple-audio-card,cpu@1 {
sound-dai = <&rcar_sound 1>;
};
- codec {
+ simple-audio-card,codec {
...
};
};
@@ -368,6 +368,10 @@ Required properties:
see below for detail.
- #sound-dai-cells : it must be 0 if your system is using single DAI
it must be 1 if your system is using multi DAI
+- clocks : References to SSI/SRC/MIX/CTU/DVC/AUDIO_CLK clocks.
+- clock-names : List of necessary clock names.
+ "ssi-all", "ssi.X", "src.X", "mix.X", "ctu.X",
+ "dvc.X", "clk_a", "clk_b", "clk_c", "clk_i"
Optional properties:
- #clock-cells : it must be 0 if your system has audio_clkout
@@ -375,6 +379,9 @@ Optional properties:
- clock-frequency : for all audio_clkout0/1/2/3
- clkout-lr-asynchronous : boolean property. it indicates that audio_clkoutn
is asynchronizes with lr-clock.
+- resets : References to SSI resets.
+- reset-names : List of valid reset names.
+ "ssi-all", "ssi.X"
SSI subnode properties:
- interrupts : Should contain SSI interrupt for PIO transfer
diff --git a/Documentation/devicetree/bindings/sound/rockchip,pdm.txt b/Documentation/devicetree/bindings/sound/rockchip,pdm.txt
new file mode 100644
index 000000000000..921729de7346
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/rockchip,pdm.txt
@@ -0,0 +1,39 @@
+* Rockchip PDM controller
+
+Required properties:
+
+- compatible: "rockchip,pdm"
+- reg: physical base address of the controller and length of memory mapped
+ region.
+- dmas: DMA specifiers for rx dma. See the DMA client binding,
+ Documentation/devicetree/bindings/dma/dma.txt
+- dma-names: should include "rx".
+- clocks: a list of phandle + clock-specifer pairs, one for each entry in clock-names.
+- clock-names: should contain following:
+ - "pdm_hclk": clock for PDM BUS
+ - "pdm_clk" : clock for PDM controller
+- pinctrl-names: Must contain a "default" entry.
+- pinctrl-N: One property must exist for each entry in
+ pinctrl-names. See ../pinctrl/pinctrl-bindings.txt
+ for details of the property values.
+
+Example for rk3328 PDM controller:
+
+pdm: pdm@ff040000 {
+ compatible = "rockchip,pdm";
+ reg = <0x0 0xff040000 0x0 0x1000>;
+ clocks = <&clk_pdm>, <&clk_gates28 0>;
+ clock-names = "pdm_clk", "pdm_hclk";
+ dmas = <&pdma 16>;
+ #dma-cells = <1>;
+ dma-names = "rx";
+ pinctrl-names = "default", "sleep";
+ pinctrl-0 = <&pdmm0_clk
+ &pdmm0_fsync
+ &pdmm0_sdi0
+ &pdmm0_sdi1
+ &pdmm0_sdi2
+ &pdmm0_sdi3>;
+ pinctrl-1 = <&pdmm0_sleep>;
+ status = "disabled";
+};
diff --git a/Documentation/devicetree/bindings/sound/rockchip-spdif.txt b/Documentation/devicetree/bindings/sound/rockchip-spdif.txt
index 11046429a118..4706b96d450b 100644
--- a/Documentation/devicetree/bindings/sound/rockchip-spdif.txt
+++ b/Documentation/devicetree/bindings/sound/rockchip-spdif.txt
@@ -9,7 +9,9 @@ Required properties:
- compatible: should be one of the following:
- "rockchip,rk3066-spdif"
- "rockchip,rk3188-spdif"
+ - "rockchip,rk3228-spdif"
- "rockchip,rk3288-spdif"
+ - "rockchip,rk3328-spdif"
- "rockchip,rk3366-spdif"
- "rockchip,rk3368-spdif"
- "rockchip,rk3399-spdif"
diff --git a/Documentation/devicetree/bindings/sound/samsung,odroid.txt b/Documentation/devicetree/bindings/sound/samsung,odroid.txt
index c1ac70cb0afb..c30934dd975b 100644
--- a/Documentation/devicetree/bindings/sound/samsung,odroid.txt
+++ b/Documentation/devicetree/bindings/sound/samsung,odroid.txt
@@ -5,11 +5,6 @@ Required properties:
- compatible - "samsung,odroidxu3-audio" - for Odroid XU3 board,
"samsung,odroidxu4-audio" - for Odroid XU4 board
- model - the user-visible name of this sound complex
- - 'cpu' subnode with a 'sound-dai' property containing the phandle of the I2S
- controller
- - 'codec' subnode with a 'sound-dai' property containing list of phandles
- to the CODEC nodes, first entry must be corresponding to the MAX98090
- CODEC and the second entry must be the phandle of the HDMI IP block node
- clocks - should contain entries matching clock names in the clock-names
property
- clock-names - should contain following entries:
@@ -32,12 +27,18 @@ Required properties:
For Odroid XU4:
no entries
+Required sub-nodes:
+
+ - 'cpu' subnode with a 'sound-dai' property containing the phandle of the I2S
+ controller
+ - 'codec' subnode with a 'sound-dai' property containing list of phandles
+ to the CODEC nodes, first entry must be corresponding to the MAX98090
+ CODEC and the second entry must be the phandle of the HDMI IP block node
+
Example:
sound {
compatible = "samsung,odroidxu3-audio";
- samsung,cpu-dai = <&i2s0>;
- samsung,codec-dai = <&max98090>;
model = "Odroid-XU3";
samsung,audio-routing =
"Headphone Jack", "HPL",
diff --git a/Documentation/devicetree/bindings/sound/simple-scu-card.txt b/Documentation/devicetree/bindings/sound/simple-scu-card.txt
index d6fe47ed09af..327d229a51b2 100644
--- a/Documentation/devicetree/bindings/sound/simple-scu-card.txt
+++ b/Documentation/devicetree/bindings/sound/simple-scu-card.txt
@@ -1,35 +1,29 @@
-ASoC simple SCU Sound Card
+ASoC Simple SCU Sound Card
-Simple-Card specifies audio DAI connections of SoC <-> codec.
+Simple SCU Sound Card is "Simple Sound Card" + "ALSA DPCM".
+For example, you can use this driver if you want to exchange sampling rate convert,
+Mixing, etc...
Required properties:
- compatible : "simple-scu-audio-card"
"renesas,rsrc-card"
-
Optional properties:
-- simple-audio-card,name : User specified audio sound card name, one string
- property.
-- simple-audio-card,cpu : CPU sub-node
-- simple-audio-card,codec : CODEC sub-node
+- simple-audio-card,name : see simple-audio-card.txt
+- simple-audio-card,cpu : see simple-audio-card.txt
+- simple-audio-card,codec : see simple-audio-card.txt
Optional subnode properties:
-- simple-audio-card,format : CPU/CODEC common audio format.
- "i2s", "right_j", "left_j" , "dsp_a"
- "dsp_b", "ac97", "pdm", "msb", "lsb"
-- simple-audio-card,frame-master : Indicates dai-link frame master.
- phandle to a cpu or codec subnode.
-- simple-audio-card,bitclock-master : Indicates dai-link bit clock master.
- phandle to a cpu or codec subnode.
-- simple-audio-card,bitclock-inversion : bool property. Add this if the
- dai-link uses bit clock inversion.
-- simple-audio-card,frame-inversion : bool property. Add this if the
- dai-link uses frame clock inversion.
+- simple-audio-card,format : see simple-audio-card.txt
+- simple-audio-card,frame-master : see simple-audio-card.txt
+- simple-audio-card,bitclock-master : see simple-audio-card.txt
+- simple-audio-card,bitclock-inversion : see simple-audio-card.txt
+- simple-audio-card,frame-inversion : see simple-audio-card.txt
- simple-audio-card,convert-rate : platform specified sampling rate convert
- simple-audio-card,convert-channels : platform specified converted channel size (2 - 8 ch)
-- simple-audio-card,prefix : see audio-routing
+- simple-audio-card,prefix : see routing
- simple-audio-card,routing : A list of the connections between audio components.
Each entry is a pair of strings, the first being the connection's sink,
the second being the connection's source. Valid names for sources.
@@ -38,32 +32,23 @@ Optional subnode properties:
Required CPU/CODEC subnodes properties:
-- sound-dai : phandle and port of CPU/CODEC
+- sound-dai : see simple-audio-card.txt
Optional CPU/CODEC subnodes properties:
-- clocks / system-clock-frequency : specify subnode's clock if needed.
- it can be specified via "clocks" if system has
- clock node (= common clock), or "system-clock-frequency"
- (if system doens't support common clock)
- If a clock is specified, it is
- enabled with clk_prepare_enable()
- in dai startup() and disabled with
- clk_disable_unprepare() in dai
- shutdown().
+- clocks / system-clock-frequency : see simple-audio-card.txt
-Example 1. Sampling Rate Covert
+Example 1. Sampling Rate Conversion
sound {
compatible = "simple-scu-audio-card";
simple-audio-card,name = "rsnd-ak4643";
simple-audio-card,format = "left_j";
- simple-audio-card,format = "left_j";
simple-audio-card,bitclock-master = <&sndcodec>;
simple-audio-card,frame-master = <&sndcodec>;
- simple-audio-card,convert-rate = <48000>; /* see audio_clk_a */
+ simple-audio-card,convert-rate = <48000>;
simple-audio-card,prefix = "ak4642";
simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback",
@@ -79,20 +64,18 @@ sound {
};
};
-Example 2. 2 CPU 1 Codec
+Example 2. 2 CPU 1 Codec (Mixing)
sound {
- compatible = "renesas,rsrc-card";
-
- card-name = "rsnd-ak4643";
- format = "left_j";
- bitclock-master = <&dpcmcpu>;
- frame-master = <&dpcmcpu>;
+ compatible = "simple-scu-audio-card";
- convert-rate = <48000>; /* see audio_clk_a */
+ simple-audio-card,name = "rsnd-ak4643";
+ simple-audio-card,format = "left_j";
+ simple-audio-card,bitclock-master = <&dpcmcpu>;
+ simple-audio-card,frame-master = <&dpcmcpu>;
- audio-prefix = "ak4642";
- audio-routing = "ak4642 Playback", "DAI0 Playback",
+ simple-audio-card,prefix = "ak4642";
+ simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback",
"ak4642 Playback", "DAI1 Playback";
dpcmcpu: cpu@0 {
diff --git a/Documentation/devicetree/bindings/sound/st,stm32-i2s.txt b/Documentation/devicetree/bindings/sound/st,stm32-i2s.txt
new file mode 100644
index 000000000000..4bda52042402
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/st,stm32-i2s.txt
@@ -0,0 +1,62 @@
+STMicroelectronics STM32 SPI/I2S Controller
+
+The SPI/I2S block supports I2S/PCM protocols when configured on I2S mode.
+Only some SPI instances support I2S.
+
+Required properties:
+ - compatible: Must be "st,stm32h7-i2s"
+ - reg: Offset and length of the device's register set.
+ - interrupts: Must contain the interrupt line id.
+ - clocks: Must contain phandle and clock specifier pairs for each entry
+ in clock-names.
+ - clock-names: Must contain "i2sclk", "pclk", "x8k" and "x11k".
+ "i2sclk": clock which feeds the internal clock generator
+ "pclk": clock which feeds the peripheral bus interface
+ "x8k": I2S parent clock for sampling rates multiple of 8kHz.
+ "x11k": I2S parent clock for sampling rates multiple of 11.025kHz.
+ - dmas: DMA specifiers for tx and rx dma.
+ See Documentation/devicetree/bindings/dma/stm32-dma.txt.
+ - dma-names: Identifier for each DMA request line. Must be "tx" and "rx".
+ - pinctrl-names: should contain only value "default"
+ - pinctrl-0: see Documentation/devicetree/bindings/pinctrl/pinctrl-stm32.txt
+
+Optional properties:
+ - resets: Reference to a reset controller asserting the reset controller
+
+The device node should contain one 'port' child node with one child 'endpoint'
+node, according to the bindings defined in Documentation/devicetree/bindings/
+graph.txt.
+
+Example:
+sound_card {
+ compatible = "audio-graph-card";
+ dais = <&i2s2_port>;
+};
+
+i2s2: audio-controller@40003800 {
+ compatible = "st,stm32h7-i2s";
+ reg = <0x40003800 0x400>;
+ interrupts = <36>;
+ clocks = <&rcc PCLK1>, <&rcc SPI2_CK>, <&rcc PLL1_Q>, <&rcc PLL2_P>;
+ clock-names = "pclk", "i2sclk", "x8k", "x11k";
+ dmas = <&dmamux2 2 39 0x400 0x1>,
+ <&dmamux2 3 40 0x400 0x1>;
+ dma-names = "rx", "tx";
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_i2s2>;
+
+ i2s2_port: port@0 {
+ cpu_endpoint: endpoint {
+ remote-endpoint = <&codec_endpoint>;
+ format = "i2s";
+ };
+ };
+};
+
+audio-codec {
+ codec_port: port@0 {
+ codec_endpoint: endpoint {
+ remote-endpoint = <&cpu_endpoint>;
+ };
+ };
+};
diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt
index c59a3d779e06..f1c5ae59e7c9 100644
--- a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt
+++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt
@@ -6,7 +6,7 @@ The SAI contains two independent audio sub-blocks. Each sub-block has
its own clock generator and I/O lines controller.
Required properties:
- - compatible: Should be "st,stm32f4-sai"
+ - compatible: Should be "st,stm32f4-sai" or "st,stm32h7-sai"
- reg: Base address and size of SAI common register set.
- clocks: Must contain phandle and clock specifier pairs for each entry
in clock-names.
@@ -36,6 +36,10 @@ SAI subnodes required properties:
- pinctrl-names: should contain only value "default"
- pinctrl-0: see Documentation/devicetree/bindings/pinctrl/pinctrl-stm32.txt
+The device node should contain one 'port' child node with one child 'endpoint'
+node, according to the bindings defined in Documentation/devicetree/bindings/
+graph.txt.
+
Example:
sound_card {
compatible = "audio-graph-card";
@@ -43,38 +47,29 @@ sound_card {
};
sai1: sai1@40015800 {
- compatible = "st,stm32f4-sai";
+ compatible = "st,stm32h7-sai";
#address-cells = <1>;
#size-cells = <1>;
- ranges;
+ ranges = <0 0x40015800 0x400>;
reg = <0x40015800 0x4>;
- clocks = <&rcc 1 CLK_SAIQ_PDIV>, <&rcc 1 CLK_I2SQ_PDIV>;
+ clocks = <&rcc PLL1_Q>, <&rcc PLL2_P>;
clock-names = "x8k", "x11k";
interrupts = <87>;
- sai1b: audio-controller@40015824 {
- #sound-dai-cells = <0>;
- compatible = "st,stm32-sai-sub-b";
- reg = <0x40015824 0x1C>;
- clocks = <&rcc 1 CLK_SAI2>;
+ sai1a: audio-controller@40015804 {
+ compatible = "st,stm32-sai-sub-a";
+ reg = <0x4 0x1C>;
+ clocks = <&rcc SAI1_CK>;
clock-names = "sai_ck";
- dmas = <&dma2 5 0 0x400 0x0>;
+ dmas = <&dmamux1 1 87 0x400 0x0>;
dma-names = "tx";
pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_sai1b>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
+ pinctrl-0 = <&pinctrl_sai1a>;
- sai1b_port: port@0 {
- reg = <0>;
- cpu_endpoint: endpoint {
- remote-endpoint = <&codec_endpoint>;
- audio-graph-card,format = "i2s";
- audio-graph-card,bitclock-master = <&codec_endpoint>;
- audio-graph-card,frame-master = <&codec_endpoint>;
- };
+ sai1b_port: port {
+ cpu_endpoint: endpoint {
+ remote-endpoint = <&codec_endpoint>;
+ format = "i2s";
};
};
};
diff --git a/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.txt b/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.txt
new file mode 100644
index 000000000000..33826f2459fa
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.txt
@@ -0,0 +1,56 @@
+STMicroelectronics STM32 S/PDIF receiver (SPDIFRX).
+
+The SPDIFRX peripheral, is designed to receive an S/PDIF flow compliant with
+IEC-60958 and IEC-61937.
+
+Required properties:
+ - compatible: should be "st,stm32h7-spdifrx"
+ - reg: cpu DAI IP base address and size
+ - clocks: must contain an entry for kclk (used as S/PDIF signal reference)
+ - clock-names: must contain "kclk"
+ - interrupts: cpu DAI interrupt line
+ - dmas: DMA specifiers for audio data DMA and iec control flow DMA
+ See STM32 DMA bindings, Documentation/devicetree/bindings/dma/stm32-dma.txt
+ - dma-names: two dmas have to be defined, "rx" and "rx-ctrl"
+
+Optional properties:
+ - resets: Reference to a reset controller asserting the SPDIFRX
+
+The device node should contain one 'port' child node with one child 'endpoint'
+node, according to the bindings defined in Documentation/devicetree/bindings/
+graph.txt.
+
+Example:
+spdifrx: spdifrx@40004000 {
+ compatible = "st,stm32h7-spdifrx";
+ reg = <0x40004000 0x400>;
+ clocks = <&rcc SPDIFRX_CK>;
+ clock-names = "kclk";
+ interrupts = <97>;
+ dmas = <&dmamux1 2 93 0x400 0x0>,
+ <&dmamux1 3 94 0x400 0x0>;
+ dma-names = "rx", "rx-ctrl";
+ pinctrl-0 = <&spdifrx_pins>;
+ pinctrl-names = "default";
+
+ spdifrx_port: port {
+ cpu_endpoint: endpoint {
+ remote-endpoint = <&codec_endpoint>;
+ };
+ };
+};
+
+spdif_in: spdif-in {
+ compatible = "linux,spdif-dir";
+
+ codec_port: port {
+ codec_endpoint: endpoint {
+ remote-endpoint = <&cpu_endpoint>;
+ };
+ };
+};
+
+soundcard {
+ compatible = "audio-graph-card";
+ dais = <&spdifrx_port>;
+};
diff --git a/Documentation/devicetree/bindings/sound/sun4i-codec.txt b/Documentation/devicetree/bindings/sound/sun4i-codec.txt
index 3863531d1e6d..2d4e10deb6f4 100644
--- a/Documentation/devicetree/bindings/sound/sun4i-codec.txt
+++ b/Documentation/devicetree/bindings/sound/sun4i-codec.txt
@@ -7,6 +7,7 @@ Required properties:
- "allwinner,sun7i-a20-codec"
- "allwinner,sun8i-a23-codec"
- "allwinner,sun8i-h3-codec"
+ - "allwinner,sun8i-v3s-codec"
- reg: must contain the registers location and length
- interrupts: must contain the codec interrupt
- dmas: DMA channels for tx and rx dma. See the DMA client binding,
@@ -25,6 +26,7 @@ Required properties for the following compatibles:
- "allwinner,sun6i-a31-codec"
- "allwinner,sun8i-a23-codec"
- "allwinner,sun8i-h3-codec"
+ - "allwinner,sun8i-v3s-codec"
- resets: phandle to the reset control for this device
- allwinner,audio-routing: A list of the connections between audio components.
Each entry is a pair of strings, the first being the
@@ -34,15 +36,15 @@ Required properties for the following compatibles:
Audio pins on the SoC:
"HP"
"HPCOM"
- "LINEIN"
- "LINEOUT" (not on sun8i-a23)
+ "LINEIN" (not on sun8i-v3s)
+ "LINEOUT" (not on sun8i-a23 or sun8i-v3s)
"MIC1"
- "MIC2"
+ "MIC2" (not on sun8i-v3s)
"MIC3" (sun6i-a31 only)
Microphone biases from the SoC:
"HBIAS"
- "MBIAS"
+ "MBIAS" (not on sun8i-v3s)
Board connectors:
"Headphone"
@@ -55,6 +57,7 @@ Required properties for the following compatibles:
Required properties for the following compatibles:
- "allwinner,sun8i-a23-codec"
- "allwinner,sun8i-h3-codec"
+ - "allwinner,sun8i-v3s-codec"
- allwinner,codec-analog-controls: A phandle to the codec analog controls
block in the PRCM.
diff --git a/Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt b/Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt
index 779b735781ba..1b6e7c4e50ab 100644
--- a/Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt
+++ b/Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt
@@ -4,6 +4,7 @@ Required properties:
- compatible: must be one of the following compatibles:
- "allwinner,sun8i-a23-codec-analog"
- "allwinner,sun8i-h3-codec-analog"
+ - "allwinner,sun8i-v3s-codec-analog"
Required properties if not a sub-node of the PRCM node:
- reg: must contain the registers location and length
diff --git a/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt b/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt
new file mode 100644
index 000000000000..41bb1040eb71
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt
@@ -0,0 +1,24 @@
+ZTE ZX AUD96P22 Audio Codec
+
+Required properties:
+ - compatible: Must be "zte,zx-aud96p22"
+ - #sound-dai-cells: Should be 0
+ - reg: I2C bus slave address of AUD96P22
+
+Example:
+
+ i2c0: i2c@1486000 {
+ compatible = "zte,zx296718-i2c";
+ reg = <0x01486000 0x1000>;
+ interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&audiocrm AUDIO_I2C0_WCLK>;
+ clock-frequency = <1600000>;
+
+ aud96p22: codec@22 {
+ compatible = "zte,zx-aud96p22";
+ #sound-dai-cells = <0>;
+ reg = <0x22>;
+ };
+ };
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)