summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2023-04-27 10:58:37 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2023-04-27 10:58:37 -0700
commit1c15ca4e4efaddb78f83eed31eeee34c522c3ae2 (patch)
treea528054028d13fb3361ec72663c7fce7b619564b /Documentation
parent34b62f186db9614e55d021f8c58d22fc44c57911 (diff)
parentbaa6584a24494fbbd2862270d39e61b86987cc91 (diff)
Merge tag 'sound-6.4-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound
Pull sound updates from Takashi Iwai: "At this time, it's an interesting mixture of changes for both old and new stuff. Majority of changes are about ASoC (lots of systematic changes for converting remove callbacks to void, and cleanups), while we got the fixes and the enhancements of very old PCI cards, too. Here are some highlights: ALSA/ASoC Core: - Continued effort of more ASoC core cleanups - Minor improvements for XRUN handling in indirect PCM helpers - Code refactoring of PCM core code ASoC: - Continued feature and simplification work on SOF, including addition of a no-DSP mode for bringup, HDA MLink and extensions to the IPC4 protocol - Hibernation support for CS35L45 - More DT binding conversions - Support for Cirrus Logic CS35L56, Freescale QMC, Maxim MAX98363, nVidia systems with MAX9809x and RT5631, Realtek RT712, Renesas R-Car Gen4, Rockchip RK3588 and TI TAS5733 ALSA: - Lots of works for legacy emu10k1 and ymfpci PCI drivers - PCM kselftest fixes and enhancements" * tag 'sound-6.4-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound: (586 commits) ALSA: emu10k1: use high-level I/O in set_filterQ() ALSA: emu10k1: use high-level I/O functions also during init ALSA: emu10k1: fix error handling in snd_audigy_i2c_volume_put() ALSA: emu10k1: don't stop DSP in _snd_emu10k1_{,audigy_}init_efx() ALSA: emu10k1: fix SNDRV_EMU10K1_IOCTL_SINGLE_STEP ALSA: emu10k1: skip Sound Blaster-specific hacks for E-MU cards ALSA: emu10k1: fixup DSP defines ALSA: emu10k1: pull in some register definitions from kX-project ALSA: emu10k1: remove some bogus defines ALSA: emu10k1: eliminate some unused defines ALSA: emu10k1: fix lineup of EMU_HANA_* defines ALSA: emu10k1: comment updates ALSA: emu10k1: fix snd_emu1010_fpga_read() input masking for rev2 cards ALSA: emu10k1: remove unused emu->pcm_playback_efx_substream field ALSA: emu10k1: remove unused `resume` parameter from snd_emu10k1_init() ALSA: emu10k1: minor optimizations ALSA: emu10k1: remove remaining cruft from snd_emu10k1_emu1010_init() ALSA: emu10k1: remove apparently pointless EMU_HANA_OPTION_CARDS reads ALSA: emu10k1: remove apparently pointless FPGA reads ALSA: emu10k1: stop doing weird things with HCFG in snd_emu10k1_emu1010_init() ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml162
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-tsa.yaml205
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau1372.yaml2
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau17x1.txt32
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau17x1.yaml52
-rw-r--r--Documentation/devicetree/bindings/sound/adi,max98363.yaml60
-rw-r--r--Documentation/devicetree/bindings/sound/adi,max98396.yaml8
-rw-r--r--Documentation/devicetree/bindings/sound/ak4458.txt28
-rw-r--r--Documentation/devicetree/bindings/sound/ak5558.txt24
-rw-r--r--Documentation/devicetree/bindings/sound/alc5632.txt43
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak4458.yaml73
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak5558.yaml48
-rw-r--r--Documentation/devicetree/bindings/sound/audio-graph-port.yaml22
-rw-r--r--Documentation/devicetree/bindings/sound/audio-graph.yaml8
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml10
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml80
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml12
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,ep9301-i2s.yaml66
-rw-r--r--Documentation/devicetree/bindings/sound/everest,es8316.yaml4
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml117
-rw-r--r--Documentation/devicetree/bindings/sound/max98371.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/max9867.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max9759.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max9759.yaml45
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98371.yaml42
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max9867.yaml60
-rw-r--r--Documentation/devicetree/bindings/sound/mt8186-afe-pcm.yaml6
-rw-r--r--Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml2
-rw-r--r--Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml2
-rw-r--r--Documentation/devicetree/bindings/sound/mt8192-afe-pcm.yaml6
-rw-r--r--Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml4
-rw-r--r--Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml2
-rw-r--r--Documentation/devicetree/bindings/sound/mt8195-mt6359.yaml8
-rw-r--r--Documentation/devicetree/bindings/sound/nau8825.txt3
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml8
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml4
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml90
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml8
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml85
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml6
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml26
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml6
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml6
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml8
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml8
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml77
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml81
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml86
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml23
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml2
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd9335.txt123
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd9335.yaml156
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml1
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,alc5632.yaml63
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,rsnd.yaml129
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml21
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml7
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip-i2s.yaml5
-rw-r--r--Documentation/devicetree/bindings/sound/sgtl5000.yaml6
-rw-r--r--Documentation/devicetree/bindings/sound/simple-card.yaml2
-rw-r--r--Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml2
-rw-r--r--Documentation/devicetree/bindings/sound/tas571x.txt1
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8510.yaml41
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8523.yaml40
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8524.yaml40
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8580.yaml42
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8711.yaml40
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8728.yaml40
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8737.yaml40
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8753.yaml62
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8960.yaml88
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8994.yaml194
-rw-r--r--Documentation/devicetree/bindings/sound/wm8510.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8523.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/wm8524.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/wm8580.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/wm8711.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8728.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8737.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8753.txt40
-rw-r--r--Documentation/devicetree/bindings/sound/wm8960.txt42
-rw-r--r--Documentation/devicetree/bindings/sound/wm8994.txt112
-rw-r--r--Documentation/sound/alsa-configuration.rst5
-rw-r--r--Documentation/sound/cards/audigy-mixer.rst27
-rw-r--r--Documentation/sound/cards/sb-live-mixer.rst17
-rw-r--r--Documentation/sound/hd-audio/index.rst1
-rw-r--r--Documentation/sound/hd-audio/intel-multi-link.rst312
-rw-r--r--Documentation/sound/kernel-api/writing-an-alsa-driver.rst1088
88 files changed, 3250 insertions, 1469 deletions
diff --git a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml
new file mode 100644
index 000000000000..ec888f48cac8
--- /dev/null
+++ b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml
@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: PowerQUICC CPM QUICC Multichannel Controller (QMC)
+
+maintainers:
+ - Herve Codina <herve.codina@bootlin.com>
+
+description:
+ The QMC (QUICC Multichannel Controller) emulates up to 64 channels within one
+ serial controller using the same TDM physical interface routed from TSA.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - fsl,mpc885-scc-qmc
+ - fsl,mpc866-scc-qmc
+ - const: fsl,cpm1-scc-qmc
+
+ reg:
+ items:
+ - description: SCC (Serial communication controller) register base
+ - description: SCC parameter ram base
+ - description: Dual port ram base
+
+ reg-names:
+ items:
+ - const: scc_regs
+ - const: scc_pram
+ - const: dpram
+
+ interrupts:
+ maxItems: 1
+ description: SCC interrupt line in the CPM interrupt controller
+
+ fsl,tsa-serial:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to TSA node
+ - enum: [1, 2, 3]
+ description: |
+ TSA serial interface (dt-bindings/soc/cpm1-fsl,tsa.h defines these
+ values)
+ - 1: SCC2
+ - 2: SCC3
+ - 3: SCC4
+ description:
+ Should be a phandle/number pair. The phandle to TSA node and the TSA
+ serial interface to use.
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ '^channel@([0-9]|[1-5][0-9]|6[0-3])$':
+ description:
+ A channel managed by this controller
+ type: object
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 63
+ description:
+ The channel number
+
+ fsl,operational-mode:
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [transparent, hdlc]
+ default: transparent
+ description: |
+ The channel operational mode
+ - hdlc: The channel handles HDLC frames
+ - transparent: The channel handles raw data without any processing
+
+ fsl,reverse-data:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ The bit order as seen on the channels is reversed,
+ transmitting/receiving the MSB of each octet first.
+ This flag is used only in 'transparent' mode.
+
+ fsl,tx-ts-mask:
+ $ref: /schemas/types.yaml#/definitions/uint64
+ description:
+ Channel assigned Tx time-slots within the Tx time-slots routed by the
+ TSA to this cell.
+
+ fsl,rx-ts-mask:
+ $ref: /schemas/types.yaml#/definitions/uint64
+ description:
+ Channel assigned Rx time-slots within the Rx time-slots routed by the
+ TSA to this cell.
+
+ required:
+ - reg
+ - fsl,tx-ts-mask
+ - fsl,rx-ts-mask
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - fsl,tsa-serial
+ - '#address-cells'
+ - '#size-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/soc/cpm1-fsl,tsa.h>
+
+ qmc@a60 {
+ compatible = "fsl,mpc885-scc-qmc", "fsl,cpm1-scc-qmc";
+ reg = <0xa60 0x20>,
+ <0x3f00 0xc0>,
+ <0x2000 0x1000>;
+ reg-names = "scc_regs", "scc_pram", "dpram";
+ interrupts = <27>;
+ interrupt-parent = <&CPM_PIC>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fsl,tsa-serial = <&tsa FSL_CPM_TSA_SCC4>;
+
+ channel@16 {
+ /* Ch16 : First 4 even TS from all routed from TSA */
+ reg = <16>;
+ fsl,mode = "transparent";
+ fsl,reverse-data;
+ fsl,tx-ts-mask = <0x00000000 0x000000aa>;
+ fsl,rx-ts-mask = <0x00000000 0x000000aa>;
+ };
+
+ channel@17 {
+ /* Ch17 : First 4 odd TS from all routed from TSA */
+ reg = <17>;
+ fsl,mode = "transparent";
+ fsl,reverse-data;
+ fsl,tx-ts-mask = <0x00000000 0x00000055>;
+ fsl,rx-ts-mask = <0x00000000 0x00000055>;
+ };
+
+ channel@19 {
+ /* Ch19 : 8 TS (TS 8..15) from all routed from TSA */
+ reg = <19>;
+ fsl,mode = "hdlc";
+ fsl,tx-ts-mask = <0x00000000 0x0000ff00>;
+ fsl,rx-ts-mask = <0x00000000 0x0000ff00>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-tsa.yaml b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-tsa.yaml
new file mode 100644
index 000000000000..7e51c639a79a
--- /dev/null
+++ b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-tsa.yaml
@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/soc/fsl/cpm_qe/fsl,cpm1-tsa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: PowerQUICC CPM Time-slot assigner (TSA) controller
+
+maintainers:
+ - Herve Codina <herve.codina@bootlin.com>
+
+description:
+ The TSA is the time-slot assigner that can be found on some PowerQUICC SoC.
+ Its purpose is to route some TDM time-slots to other internal serial
+ controllers.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - fsl,mpc885-tsa
+ - fsl,mpc866-tsa
+ - const: fsl,cpm1-tsa
+
+ reg:
+ items:
+ - description: SI (Serial Interface) register base
+ - description: SI RAM base
+
+ reg-names:
+ items:
+ - const: si_regs
+ - const: si_ram
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ '^tdm@[0-1]$':
+ description:
+ The TDM managed by this controller
+ type: object
+
+ additionalProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 1
+ description:
+ The TDM number for this TDM, 0 for TDMa and 1 for TDMb
+
+ fsl,common-rxtx-pins:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ The hardware can use four dedicated pins for Tx clock, Tx sync, Rx
+ clock and Rx sync or use only two pins, Tx/Rx clock and Tx/Rx sync.
+ Without the 'fsl,common-rxtx-pins' property, the four pins are used.
+ With the 'fsl,common-rxtx-pins' property, two pins are used.
+
+ clocks:
+ minItems: 2
+ items:
+ - description: External clock connected to L1RSYNC pin
+ - description: External clock connected to L1RCLK pin
+ - description: External clock connected to L1TSYNC pin
+ - description: External clock connected to L1TCLK pin
+
+ clock-names:
+ minItems: 2
+ items:
+ - const: l1rsync
+ - const: l1rclk
+ - const: l1tsync
+ - const: l1tclk
+
+ fsl,rx-frame-sync-delay-bits:
+ enum: [0, 1, 2, 3]
+ default: 0
+ description: |
+ Receive frame sync delay in number of bits.
+ Indicates the delay between the Rx sync and the first bit of the Rx
+ frame. 0 for no bit delay. 1, 2 or 3 for 1, 2 or 3 bits delay.
+
+ fsl,tx-frame-sync-delay-bits:
+ enum: [0, 1, 2, 3]
+ default: 0
+ description: |
+ Transmit frame sync delay in number of bits.
+ Indicates the delay between the Tx sync and the first bit of the Tx
+ frame. 0 for no bit delay. 1, 2 or 3 for 1, 2 or 3 bits delay.
+
+ fsl,clock-falling-edge:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Data is sent on falling edge of the clock (and received on the rising
+ edge). If 'clock-falling-edge' is not present, data is sent on the
+ rising edge (and received on the falling edge).
+
+ fsl,fsync-rising-edge:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Frame sync pulses are sampled with the rising edge of the channel
+ clock. If 'fsync-rising-edge' is not present, pulses are sampled with
+ the falling edge.
+
+ fsl,double-speed-clock:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ The channel clock is twice the data rate.
+
+ patternProperties:
+ '^fsl,[rt]x-ts-routes$':
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ description: |
+ A list of tuple that indicates the Tx or Rx time-slots routes.
+ items:
+ items:
+ - description:
+ The number of time-slots
+ minimum: 1
+ maximum: 64
+ - description: |
+ The source (Tx) or destination (Rx) serial interface
+ (dt-bindings/soc/cpm1-fsl,tsa.h defines these values)
+ - 0: No destination
+ - 1: SCC2
+ - 2: SCC3
+ - 3: SCC4
+ - 4: SMC1
+ - 5: SMC2
+ enum: [0, 1, 2, 3, 4, 5]
+ minItems: 1
+ maxItems: 64
+
+ allOf:
+ # If fsl,common-rxtx-pins is present, only 2 clocks are needed.
+ # Else, the 4 clocks must be present.
+ - if:
+ required:
+ - fsl,common-rxtx-pins
+ then:
+ properties:
+ clocks:
+ maxItems: 2
+ clock-names:
+ maxItems: 2
+ else:
+ properties:
+ clocks:
+ minItems: 4
+ clock-names:
+ minItems: 4
+
+ required:
+ - reg
+ - clocks
+ - clock-names
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - '#address-cells'
+ - '#size-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/soc/cpm1-fsl,tsa.h>
+
+ tsa@ae0 {
+ compatible = "fsl,mpc885-tsa", "fsl,cpm1-tsa";
+ reg = <0xae0 0x10>,
+ <0xc00 0x200>;
+ reg-names = "si_regs", "si_ram";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ tdm@0 {
+ /* TDMa */
+ reg = <0>;
+
+ clocks = <&clk_l1rsynca>, <&clk_l1rclka>;
+ clock-names = "l1rsync", "l1rclk";
+
+ fsl,common-rxtx-pins;
+ fsl,fsync-rising-edge;
+
+ fsl,tx-ts-routes = <2 0>, /* TS 0..1 */
+ <24 FSL_CPM_TSA_SCC4>, /* TS 2..25 */
+ <1 0>, /* TS 26 */
+ <5 FSL_CPM_TSA_SCC3>; /* TS 27..31 */
+
+ fsl,rx-ts-routes = <2 0>, /* TS 0..1 */
+ <24 FSL_CPM_TSA_SCC4>, /* 2..25 */
+ <1 0>, /* TS 26 */
+ <5 FSL_CPM_TSA_SCC3>; /* TS 27..31 */
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/adi,adau1372.yaml b/Documentation/devicetree/bindings/sound/adi,adau1372.yaml
index 044bcd370d49..ea62e51aba90 100644
--- a/Documentation/devicetree/bindings/sound/adi,adau1372.yaml
+++ b/Documentation/devicetree/bindings/sound/adi,adau1372.yaml
@@ -32,7 +32,7 @@ properties:
maxItems: 1
clock-names:
- const: "mclk"
+ const: mclk
powerdown-gpios:
description: GPIO used for hardware power-down.
diff --git a/Documentation/devicetree/bindings/sound/adi,adau17x1.txt b/Documentation/devicetree/bindings/sound/adi,adau17x1.txt
deleted file mode 100644
index 1447dec28125..000000000000
--- a/Documentation/devicetree/bindings/sound/adi,adau17x1.txt
+++ /dev/null
@@ -1,32 +0,0 @@
-Analog Devices ADAU1361/ADAU1461/ADAU1761/ADAU1961/ADAU1381/ADAU1781
-
-Required properties:
-
- - compatible: Should contain one of the following:
- "adi,adau1361"
- "adi,adau1461"
- "adi,adau1761"
- "adi,adau1961"
- "adi,adau1381"
- "adi,adau1781"
-
- - reg: The i2c address. Value depends on the state of ADDR0
- and ADDR1, as wired in hardware.
-
-Optional properties:
- - clock-names: If provided must be "mclk".
- - clocks: phandle + clock-specifiers for the clock that provides
- the audio master clock for the device.
-
-Examples:
-#include <dt-bindings/sound/adau17x1.h>
-
- i2c_bus {
- adau1361@38 {
- compatible = "adi,adau1761";
- reg = <0x38>;
-
- clock-names = "mclk";
- clocks = <&audio_clock>;
- };
- };
diff --git a/Documentation/devicetree/bindings/sound/adi,adau17x1.yaml b/Documentation/devicetree/bindings/sound/adi,adau17x1.yaml
new file mode 100644
index 000000000000..8ef1e7f6ec91
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/adi,adau17x1.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/adi,adau17x1.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADAU1361/ADAU1461/ADAU1761/ADAU1961/ADAU1381/ADAU1781 Codec
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+
+properties:
+ compatible:
+ enum:
+ - adi,adau1361
+ - adi,adau1381
+ - adi,adau1461
+ - adi,adau1761
+ - adi,adau1781
+ - adi,adau1961
+
+ reg:
+ maxItems: 1
+ description:
+ The i2c address. Value depends on the state of ADDR0 and ADDR1,
+ as wired in hardware.
+
+ clock-names:
+ const: mclk
+
+ clocks:
+ items:
+ - description: provides the audio master clock for the device.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ audio-codec@38 {
+ compatible = "adi,adau1761";
+ reg = <0x38>;
+ clock-names = "mclk";
+ clocks = <&audio_clock>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/adi,max98363.yaml b/Documentation/devicetree/bindings/sound/adi,max98363.yaml
new file mode 100644
index 000000000000..a844b63f3930
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/adi,max98363.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/adi,max98363.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices MAX98363 SoundWire Amplifier
+
+maintainers:
+ - Ryan Lee <ryans.lee@analog.com>
+
+description:
+ The MAX98363 is a SoundWire input Class D mono amplifier that
+ supports MIPI SoundWire v1.2-compatible digital interface for
+ audio and control data.
+ SoundWire peripheral device ID of MAX98363 is 0x3*019f836300
+ where * is the peripheral device unique ID decoded from pin.
+ It supports up to 10 peripheral devices(0x0 to 0x9).
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: sdw3019f836300
+
+ reg:
+ maxItems: 1
+
+ '#sound-dai-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - "#sound-dai-cells"
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ soundwire-controller@3250000 {
+ #address-cells = <2>;
+ #size-cells = <0>;
+ reg = <0x3250000 0x2000>;
+
+ speaker@0,0 {
+ compatible = "sdw3019f836300";
+ reg = <0 0>;
+ #sound-dai-cells = <0>;
+ sound-name-prefix = "Speaker Left";
+ };
+
+ speaker@0,1 {
+ compatible = "sdw3019f836300";
+ reg = <0 1>;
+ #sound-dai-cells = <0>;
+ sound-name-prefix = "Speaker Right";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/adi,max98396.yaml b/Documentation/devicetree/bindings/sound/adi,max98396.yaml
index fd5aa61b467f..bdc10d4204ec 100644
--- a/Documentation/devicetree/bindings/sound/adi,max98396.yaml
+++ b/Documentation/devicetree/bindings/sound/adi,max98396.yaml
@@ -41,21 +41,21 @@ properties:
adi,vmon-slot-no:
description: slot number of the voltage sense monitor
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 15
default: 0
adi,imon-slot-no:
description: slot number of the current sense monitor
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 15
default: 1
adi,spkfb-slot-no:
description: slot number of speaker DSP monitor
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 15
default: 2
@@ -64,7 +64,7 @@ properties:
description:
Selects the PCM data input channel that is routed to the speaker
audio processing bypass path.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 15
default: 0
diff --git a/Documentation/devicetree/bindings/sound/ak4458.txt b/Documentation/devicetree/bindings/sound/ak4458.txt
deleted file mode 100644
index 0416c14895d6..000000000000
--- a/Documentation/devicetree/bindings/sound/ak4458.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-AK4458 audio DAC
-
-This device supports I2C mode.
-
-Required properties:
-
-- compatible : "asahi-kasei,ak4458" or "asahi-kasei,ak4497"
-- reg : The I2C address of the device for I2C
-
-Optional properties:
-- reset-gpios: A GPIO specifier for the power down & reset pin
-- mute-gpios: A GPIO specifier for the soft mute pin
-- AVDD-supply: Analog power supply
-- DVDD-supply: Digital power supply
-- dsd-path: Select DSD input pins for ak4497
- 0: select #16, #17, #19 pins
- 1: select #3, #4, #5 pins
-
-Example:
-
-&i2c {
- ak4458: dac@10 {
- compatible = "asahi-kasei,ak4458";
- reg = <0x10>;
- reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>
- mute-gpios = <&gpio1 11 GPIO_ACTIVE_HIGH>
- };
-};
diff --git a/Documentation/devicetree/bindings/sound/ak5558.txt b/Documentation/devicetree/bindings/sound/ak5558.txt
deleted file mode 100644
index e28708db6686..000000000000
--- a/Documentation/devicetree/bindings/sound/ak5558.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-AK5558 8 channel differential 32-bit delta-sigma ADC
-
-This device supports I2C mode only.
-
-Required properties:
-
-- compatible : "asahi-kasei,ak5558" or "asahi-kasei,ak5552".
-- reg : The I2C address of the device.
-
-Optional properties:
-
-- reset-gpios: A GPIO specifier for the power down & reset pin.
-- AVDD-supply: Analog power supply
-- DVDD-supply: Digital power supply
-
-Example:
-
-&i2c {
- ak5558: adc@10 {
- compatible = "asahi-kasei,ak5558";
- reg = <0x10>;
- reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
- };
-};
diff --git a/Documentation/devicetree/bindings/sound/alc5632.txt b/Documentation/devicetree/bindings/sound/alc5632.txt
deleted file mode 100644
index ffd886d110bd..000000000000
--- a/Documentation/devicetree/bindings/sound/alc5632.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-ALC5632 audio CODEC
-
-This device supports I2C only.
-
-Required properties:
-
- - compatible : "realtek,alc5632"
-
- - reg : the I2C address of the device.
-
- - gpio-controller : Indicates this device is a GPIO controller.
-
- - #gpio-cells : Should be two. The first cell is the pin number and the
- second cell is used to specify optional parameters (currently unused).
-
-Pins on the device (for linking into audio routes):
-
- * SPK_OUTP
- * SPK_OUTN
- * HP_OUT_L
- * HP_OUT_R
- * AUX_OUT_P
- * AUX_OUT_N
- * LINE_IN_L
- * LINE_IN_R
- * PHONE_P
- * PHONE_N
- * MIC1_P
- * MIC1_N
- * MIC2_P
- * MIC2_N
- * MICBIAS1
- * DMICDAT
-
-Example:
-
-alc5632: alc5632@1e {
- compatible = "realtek,alc5632";
- reg = <0x1a>;
-
- gpio-controller;
- #gpio-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/sound/asahi-kasei,ak4458.yaml b/Documentation/devicetree/bindings/sound/asahi-kasei,ak4458.yaml
new file mode 100644
index 000000000000..4477f84b7acc
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/asahi-kasei,ak4458.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/asahi-kasei,ak4458.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AK4458 audio DAC
+
+maintainers:
+ - Shengjiu Wang <shengjiu.wang@nxp.com>
+
+properties:
+ compatible:
+ enum:
+ - asahi-kasei,ak4458
+ - asahi-kasei,ak4497
+
+ reg:
+ maxItems: 1
+
+ avdd-supply:
+ description: Analog power supply
+
+ dvdd-supply:
+ description: Digital power supply
+
+ reset-gpios:
+ maxItems: 1
+
+ mute-gpios:
+ maxItems: 1
+ description:
+ GPIO used to mute all the outputs
+
+ dsd-path:
+ description: Select DSD input pins for ak4497
+ $ref: /schemas/types.yaml#/definitions/uint32
+ oneOf:
+ - const: 0
+ description: "select #16, #17, #19 pins"
+ - const: 1
+ description: "select #3, #4, #5 pins"
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: asahi-kasei,ak4458
+
+ then:
+ properties:
+ dsd-path: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@10 {
+ compatible = "asahi-kasei,ak4458";
+ reg = <0x10>;
+ reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
+ mute-gpios = <&gpio1 11 GPIO_ACTIVE_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/asahi-kasei,ak5558.yaml b/Documentation/devicetree/bindings/sound/asahi-kasei,ak5558.yaml
new file mode 100644
index 000000000000..d3d494ae8abf
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/asahi-kasei,ak5558.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/asahi-kasei,ak5558.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AK5558 8 channel differential 32-bit delta-sigma ADC
+
+maintainers:
+ - Junichi Wakasugi <wakasugi.jb@om.asahi-kasei.co.jp>
+ - Mihai Serban <mihai.serban@nxp.com>
+
+properties:
+ compatible:
+ enum:
+ - asahi-kasei,ak5552
+ - asahi-kasei,ak5558
+
+ reg:
+ maxItems: 1
+
+ avdd-supply:
+ description: A 1.8V supply that powers up the AVDD pin.
+
+ dvdd-supply:
+ description: A 1.2V supply that powers up the DVDD pin.
+
+ reset-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ ak5558: codec@10 {
+ compatible = "asahi-kasei,ak5558";
+ reg = <0x10>;
+ reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml
index 6b4e02a0695a..fa9f9a853365 100644
--- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml
+++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml
@@ -16,19 +16,19 @@ definitions:
$ref: /schemas/graph.yaml#/$defs/port-base
properties:
convert-rate:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-rate"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate
convert-channels:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-channels"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels
convert-sample-format:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-format"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format
mclk-fs:
- $ref: "simple-card.yaml#/definitions/mclk-fs"
+ $ref: simple-card.yaml#/definitions/mclk-fs
endpoint-base:
$ref: /schemas/graph.yaml#/$defs/endpoint-base
properties:
mclk-fs:
- $ref: "simple-card.yaml#/definitions/mclk-fs"
+ $ref: simple-card.yaml#/definitions/mclk-fs
frame-inversion:
description: dai-link uses frame clock inversion
$ref: /schemas/types.yaml#/definitions/flag
@@ -49,11 +49,11 @@ definitions:
description: Indicates system clock
$ref: /schemas/types.yaml#/definitions/phandle
system-clock-frequency:
- $ref: "simple-card.yaml#/definitions/system-clock-frequency"
+ $ref: simple-card.yaml#/definitions/system-clock-frequency
system-clock-direction-out:
- $ref: "simple-card.yaml#/definitions/system-clock-direction-out"
+ $ref: simple-card.yaml#/definitions/system-clock-direction-out
system-clock-fixed:
- $ref: "simple-card.yaml#/definitions/system-clock-fixed"
+ $ref: simple-card.yaml#/definitions/system-clock-fixed
dai-format:
description: audio format.
@@ -69,11 +69,11 @@ definitions:
- msb
- lsb
convert-rate:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-rate"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate
convert-channels:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-channels"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels
convert-sample-format:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-format"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format
dai-tdm-slot-num:
description: Number of slots in use.
diff --git a/Documentation/devicetree/bindings/sound/audio-graph.yaml b/Documentation/devicetree/bindings/sound/audio-graph.yaml
index d59baedee180..c87eb91de159 100644
--- a/Documentation/devicetree/bindings/sound/audio-graph.yaml
+++ b/Documentation/devicetree/bindings/sound/audio-graph.yaml
@@ -15,7 +15,7 @@ properties:
label:
maxItems: 1
prefix:
- description: "device name prefix"
+ description: device name prefix
$ref: /schemas/types.yaml#/definitions/string
routing:
description: |
@@ -27,11 +27,11 @@ properties:
description: User specified audio sound widgets.
$ref: /schemas/types.yaml#/definitions/non-unique-string-array
convert-rate:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-rate"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate
convert-channels:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-channels"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels
convert-sample-format:
- $ref: "/schemas/sound/dai-params.yaml#/$defs/dai-sample-format"
+ $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format
pa-gpios:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml
index 18fb471aa891..14dea1feefc5 100644
--- a/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml
+++ b/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml
@@ -85,11 +85,19 @@ properties:
boost-cap-microfarad.
External Boost must have GPIO1 as GPIO output. GPIO1 will be set high to
enable boost voltage.
+ Shared boost allows two amplifiers to share a single boost circuit by
+ communicating on the MDSYNC bus. The active amplifier controls the boost
+ circuit using combined data from both amplifiers. GPIO1 should be
+ configured for Sync when shared boost is used. Shared boost is not
+ compatible with External boost. Active amplifier requires
+ boost-peak-milliamp, boost-ind-nanohenry and boost-cap-microfarad.
0 = Internal Boost
1 = External Boost
+ 2 = Shared Boost Active
+ 3 = Shared Boost Passive
$ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
- maximum: 1
+ maximum: 3
cirrus,gpio1-polarity-invert:
description:
diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml
index 88a0ca474c3d..2ab74f995685 100644
--- a/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml
+++ b/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml
@@ -45,11 +45,79 @@ properties:
Audio serial port SDOUT Hi-Z control. Sets the Hi-Z
configuration for SDOUT pin of amplifier. Logical OR of
CS35L45_ASP_TX_HIZ_xxx values.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 3
default: 2
+patternProperties:
+ "^cirrus,gpio-ctrl[1-3]$":
+ description:
+ GPIO pins configuration.
+ type: object
+ additionalProperties: false
+ properties:
+ gpio-dir:
+ description:
+ GPIO pin direction. Valid only when 'gpio-ctrl' is 1
+ 0 = Output
+ 1 = Input
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ minimum: 0
+ maximum: 1
+ default: 1
+ gpio-lvl:
+ description:
+ GPIO level. Valid only when 'gpio-ctrl' is 1 and 'gpio-dir' is 0
+ 0 = Low
+ 1 = High
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ minimum: 0
+ maximum: 1
+ default: 0
+ gpio-op-cfg:
+ description:
+ GPIO level. Valid only when 'gpio-ctrl' is 1 and 'gpio-dir' is 0
+ 0 = CMOS
+ 1 = Open Drain
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ minimum: 0
+ maximum: 1
+ default: 0
+ gpio-pol:
+ description:
+ GPIO output polarity select. Valid only when 'gpio-ctrl' is 1
+ and 'gpio-dir' is 0
+ 0 = Non-inverted, Active High
+ 1 = Inverted, Active Low
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ minimum: 0
+ maximum: 1
+ default: 0
+ gpio-ctrl:
+ description:
+ Defines the function of the GPIO pin.
+ GPIO1
+ 0 = High impedance input
+ 1 = Pin acts as a GPIO, direction controlled by 'gpio-dir'
+ 2 = Pin acts as MDSYNC, direction controlled by MDSYNC
+ 3-7 = Reserved
+ GPIO2
+ 0 = High impedance input
+ 1 = Pin acts as a GPIO, direction controlled by 'gpio-dir'
+ 2 = Pin acts as open drain INT
+ 3 = Reserved
+ 4 = Pin acts as push-pull output INT. Active low.
+ 5 = Pin acts as push-pull output INT. Active high.
+ 6,7 = Reserved
+ GPIO3
+ 0 = High impedance input
+ 1 = Pin acts as a GPIO, direction controlled by 'gpio-dir'
+ 2-7 = Reserved
+ $ref: "/schemas/types.yaml#/definitions/uint32"
+ minimum: 0
+ maximum: 7
+ default: 0
required:
- compatible
- reg
@@ -74,5 +142,15 @@ examples:
reset-gpios = <&gpio 110 0>;
cirrus,asp-sdout-hiz-ctrl = <(CS35L45_ASP_TX_HIZ_UNUSED |
CS35L45_ASP_TX_HIZ_DISABLED)>;
+ cirrus,gpio-ctrl1 {
+ gpio-ctrl = <0x2>;
+ };
+ cirrus,gpio-ctrl2 {
+ gpio-ctrl = <0x2>;
+ };
+ cirrus,gpio-ctrl3 {
+ gpio-ctrl = <0x1>;
+ gpio-dir = <0x1>;
+ };
};
};
diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml
index 7356084a2ca2..af599d8735e2 100644
--- a/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml
+++ b/Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml
@@ -68,7 +68,7 @@ properties:
This is "normal tip sense (TS)" in the datasheet.
The CS42L42_TS_INV_* defines are available for this.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 1
@@ -87,7 +87,7 @@ properties:
7 - 1.5s
The CS42L42_TS_DBNCE_* defines are available for this.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 7
@@ -106,7 +106,7 @@ properties:
7 - 1.5s
The CS42L42_TS_DBNCE_* defines are available for this.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 7
@@ -120,7 +120,7 @@ properties:
0ms - 200ms,
Default = 100ms
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 200
@@ -133,7 +133,7 @@ properties:
0ms - 20ms,
Default = 10ms
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 20
@@ -169,7 +169,7 @@ properties:
3 - Slowest
The CS42L42_HSBIAS_RAMP_* defines are available for this.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 3
diff --git a/Documentation/devicetree/bindings/sound/cirrus,ep9301-i2s.yaml b/Documentation/devicetree/bindings/sound/cirrus,ep9301-i2s.yaml
new file mode 100644
index 000000000000..453d493c941f
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/cirrus,ep9301-i2s.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/cirrus,ep9301-i2s.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cirrus EP93xx I2S Controller
+
+description: |
+ The I2S controller is used to stream serial audio data between the external
+ I2S CODECs’, ADCs/DACs, and the ARM Core. The controller supports I2S, Left-
+ and Right-Justified DSP formats.
+
+maintainers:
+ - Alexander Sverdlin <alexander.sverdlin@gmail.com>
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: cirrus,ep9301-i2s
+
+ '#sound-dai-cells':
+ const: 0
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 3
+ maxItems: 3
+
+ clock-names:
+ items:
+ - const: mclk
+ - const: sclk
+ - const: lrclk
+
+required:
+ - compatible
+ - '#sound-dai-cells'
+ - reg
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ i2s: i2s@80820000 {
+ compatible = "cirrus,ep9301-i2s";
+ #sound-dai-cells = <0>;
+ reg = <0x80820000 0x100>;
+ interrupt-parent = <&vic1>;
+ interrupts = <28>;
+ clocks = <&syscon 29>,
+ <&syscon 30>,
+ <&syscon 31>;
+ clock-names = "mclk", "sclk", "lrclk";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.yaml b/Documentation/devicetree/bindings/sound/everest,es8316.yaml
index 9f2b111818ea..b6079b3c440d 100644
--- a/Documentation/devicetree/bindings/sound/everest,es8316.yaml
+++ b/Documentation/devicetree/bindings/sound/everest,es8316.yaml
@@ -28,6 +28,10 @@ properties:
items:
- const: mclk
+ port:
+ $ref: audio-graph-port.yaml#
+ unevaluatedProperties: false
+
"#sound-dai-cells":
const: 0
diff --git a/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml b/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml
new file mode 100644
index 000000000000..ff5cd9241941
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml
@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/fsl,qmc-audio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: QMC audio
+
+maintainers:
+ - Herve Codina <herve.codina@bootlin.com>
+
+description: |
+ The QMC audio is an ASoC component which uses QMC (QUICC Multichannel
+ Controller) channels to transfer the audio data.
+ It provides as many DAI as the number of QMC channel used.
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: fsl,qmc-audio
+
+ '#address-cells':
+ const: 1
+ '#size-cells':
+ const: 0
+ '#sound-dai-cells':
+ const: 1
+
+patternProperties:
+ '^dai@([0-9]|[1-5][0-9]|6[0-3])$':
+ description:
+ A DAI managed by this controller
+ type: object
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 63
+ description:
+ The DAI number
+
+ fsl,qmc-chan:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to QMC node
+ - description: Channel number
+ description:
+ Should be a phandle/number pair. The phandle to QMC node and the QMC
+ channel to use for this DAI.
+
+ required:
+ - reg
+ - fsl,qmc-chan
+
+required:
+ - compatible
+ - '#address-cells'
+ - '#size-cells'
+ - '#sound-dai-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ audio_controller: audio-controller {
+ compatible = "fsl,qmc-audio";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #sound-dai-cells = <1>;
+ dai@16 {
+ reg = <16>;
+ fsl,qmc-chan = <&qmc 16>;
+ };
+ dai@17 {
+ reg = <17>;
+ fsl,qmc-chan = <&qmc 17>;
+ };
+ };
+
+ sound {
+ compatible = "simple-audio-card";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ simple-audio-card,dai-link@0 {
+ reg = <0>;
+ format = "dsp_b";
+ cpu {
+ sound-dai = <&audio_controller 16>;
+ };
+ codec {
+ sound-dai = <&codec1>;
+ dai-tdm-slot-num = <4>;
+ dai-tdm-slot-width = <8>;
+ /* TS 3, 5, 7, 9 */
+ dai-tdm-slot-tx-mask = <0 0 0 1 0 1 0 1 0 1>;
+ dai-tdm-slot-rx-mask = <0 0 0 1 0 1 0 1 0 1>;
+ };
+ };
+ simple-audio-card,dai-link@1 {
+ reg = <1>;
+ format = "dsp_b";
+ cpu {
+ sound-dai = <&audio_controller 17>;
+ };
+ codec {
+ sound-dai = <&codec2>;
+ dai-tdm-slot-num = <4>;
+ dai-tdm-slot-width = <8>;
+ /* TS 2, 4, 6, 8 */
+ dai-tdm-slot-tx-mask = <0 0 1 0 1 0 1 0 1>;
+ dai-tdm-slot-rx-mask = <0 0 1 0 1 0 1 0 1>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/max98371.txt b/Documentation/devicetree/bindings/sound/max98371.txt
deleted file mode 100644
index 8b2b2704b574..000000000000
--- a/Documentation/devicetree/bindings/sound/max98371.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-max98371 codec
-
-This device supports I2C mode only.
-
-Required properties:
-
-- compatible : "maxim,max98371"
-- reg : The chip select number on the I2C bus
-
-Example:
-
-&i2c {
- max98371: max98371@31 {
- compatible = "maxim,max98371";
- reg = <0x31>;
- };
-};
diff --git a/Documentation/devicetree/bindings/sound/max9867.txt b/Documentation/devicetree/bindings/sound/max9867.txt
deleted file mode 100644
index b8bd914ee697..000000000000
--- a/Documentation/devicetree/bindings/sound/max9867.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-max9867 codec
-
-This device supports I2C mode only.
-
-Required properties:
-
-- compatible : "maxim,max9867"
-- reg : The chip select number on the I2C bus
-
-Example:
-
-&i2c {
- max9867: max9867@18 {
- compatible = "maxim,max9867";
- reg = <0x18>;
- };
-};
diff --git a/Documentation/devicetree/bindings/sound/maxim,max9759.txt b/Documentation/devicetree/bindings/sound/maxim,max9759.txt
deleted file mode 100644
index 737a996374d3..000000000000
--- a/Documentation/devicetree/bindings/sound/maxim,max9759.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-Maxim MAX9759 Speaker Amplifier
-===============================
-
-Required properties:
-- compatible : "maxim,max9759"
-- shutdown-gpios : the gpio connected to the shutdown pin
-- mute-gpios : the gpio connected to the mute pin
-- gain-gpios : the 2 gpios connected to the g1 and g2 pins
-
-Example:
-
-max9759: analog-amplifier {
- compatible = "maxim,max9759";
- shutdown-gpios = <&gpio3 20 GPIO_ACTIVE_LOW>;
- mute-gpios = <&gpio3 19 GPIO_ACTIVE_LOW>;
- gain-gpios = <&gpio3 23 GPIO_ACTIVE_LOW>,
- <&gpio3 25 GPIO_ACTIVE_LOW>;
-};
diff --git a/Documentation/devicetree/bindings/sound/maxim,max9759.yaml b/Documentation/devicetree/bindings/sound/maxim,max9759.yaml
new file mode 100644
index 000000000000..a76ee6a635af
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/maxim,max9759.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/maxim,max9759.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX9759 Speaker Amplifier
+
+maintainers:
+ - Otabek Nazrullaev <otabeknazrullaev1998@gmail.com>
+
+properties:
+ compatible:
+ const: maxim,max9759
+
+ shutdown-gpios:
+ maxItems: 1
+ description: the gpio connected to the shutdown pin
+
+ mute-gpios:
+ maxItems: 1
+ description: the gpio connected to the mute pin
+
+ gain-gpios:
+ maxItems: 2
+ description: the 2 gpios connected to the g1 and g2 pins
+
+required:
+ - compatible
+ - shutdown-gpios
+ - mute-gpios
+ - gain-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ amplifier {
+ compatible = "maxim,max9759";
+ shutdown-gpios = <&gpio3 20 GPIO_ACTIVE_LOW>;
+ mute-gpios = <&gpio3 19 GPIO_ACTIVE_LOW>;
+ gain-gpios = <&gpio3 23 GPIO_ACTIVE_LOW>,
+ <&gpio3 25 GPIO_ACTIVE_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/sound/maxim,max98371.yaml b/Documentation/devicetree/bindings/sound/maxim,max98371.yaml
new file mode 100644
index 000000000000..14fba34ef81a
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/maxim,max98371.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/maxim,max98371.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX98371 audio codec
+
+maintainers:
+ - anish kumar <yesanishhere@gmail.com>
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: maxim,max98371
+
+ '#sound-dai-cells':
+ const: 0
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ codec@31 {
+ compatible = "maxim,max98371";
+ reg = <0x31>;
+ #sound-dai-cells = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/maxim,max9867.yaml b/Documentation/devicetree/bindings/sound/maxim,max9867.yaml
new file mode 100644
index 000000000000..0b9a84d33b6c
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/maxim,max9867.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/maxim,max9867.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim Integrated MAX9867 CODEC
+
+description: |
+ This device supports I2C only.
+ Pins on the device (for linking into audio routes):
+ * LOUT
+ * ROUT
+ * LINL
+ * LINR
+ * MICL
+ * MICR
+ * DMICL
+ * DMICR
+
+maintainers:
+ - Ladislav Michl <ladis@linux-mips.org>
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - maxim,max9867
+
+ '#sound-dai-cells':
+ const: 0
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@18 {
+ compatible = "maxim,max9867";
+ #sound-dai-cells = <0>;
+ reg = <0x18>;
+ clocks = <&codec_clk>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/sound/mt8186-afe-pcm.yaml b/Documentation/devicetree/bindings/sound/mt8186-afe-pcm.yaml
index 88f82d096443..7fe85b08f9df 100644
--- a/Documentation/devicetree/bindings/sound/mt8186-afe-pcm.yaml
+++ b/Documentation/devicetree/bindings/sound/mt8186-afe-pcm.yaml
@@ -26,15 +26,15 @@ properties:
const: audiosys
mediatek,apmixedsys:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of the mediatek apmixedsys controller
mediatek,infracfg:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of the mediatek infracfg controller
mediatek,topckgen:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of the mediatek topckgen controller
clocks:
diff --git a/Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml b/Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml
index d427f7f623db..9853c11a1330 100644
--- a/Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml
+++ b/Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml
@@ -18,7 +18,7 @@ properties:
- mediatek,mt8186-mt6366-da7219-max98357-sound
mediatek,platform:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of MT8186 ASoC platform.
headset-codec:
diff --git a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml
index aa23b0024c46..d80083df03eb 100644
--- a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml
+++ b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml
@@ -19,7 +19,7 @@ properties:
- mediatek,mt8186-mt6366-rt5682s-max98360-sound
mediatek,platform:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of MT8186 ASoC platform.
dmic-gpios:
diff --git a/Documentation/devicetree/bindings/sound/mt8192-afe-pcm.yaml b/Documentation/devicetree/bindings/sound/mt8192-afe-pcm.yaml
index 7a25bc9b8060..064ef172bef4 100644
--- a/Documentation/devicetree/bindings/sound/mt8192-afe-pcm.yaml
+++ b/Documentation/devicetree/bindings/sound/mt8192-afe-pcm.yaml
@@ -24,15 +24,15 @@ properties:
const: audiosys
mediatek,apmixedsys:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of the mediatek apmixedsys controller
mediatek,infracfg:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of the mediatek infracfg controller
mediatek,topckgen:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of the mediatek topckgen controller
power-domains:
diff --git a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml
index c6e614c1c30b..7e50f5d65c8f 100644
--- a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml
+++ b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml
@@ -21,11 +21,11 @@ properties:
- mediatek,mt8192_mt6359_rt1015p_rt5682s
mediatek,platform:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of MT8192 ASoC platform.
mediatek,hdmi-codec:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of HDMI codec.
headset-codec:
diff --git a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml
index 4452a4070eff..d5adf07d46e0 100644
--- a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml
+++ b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml
@@ -32,7 +32,7 @@ properties:
See ../reserved-memory/reserved-memory.txt for details.
mediatek,topckgen:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of the mediatek topckgen controller
power-domains:
diff --git a/Documentation/devicetree/bindings/sound/mt8195-mt6359.yaml b/Documentation/devicetree/bindings/sound/mt8195-mt6359.yaml
index ad3447ff8b2c..c1ddbf672ca3 100644
--- a/Documentation/devicetree/bindings/sound/mt8195-mt6359.yaml
+++ b/Documentation/devicetree/bindings/sound/mt8195-mt6359.yaml
@@ -24,19 +24,19 @@ properties:
description: User specified audio sound card name
mediatek,platform:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of MT8195 ASoC platform.
mediatek,dptx-codec:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of MT8195 Display Port Tx codec node.
mediatek,hdmi-codec:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of MT8195 HDMI codec node.
mediatek,adsp:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description: The phandle of MT8195 ADSP platform.
mediatek,dai-link:
diff --git a/Documentation/devicetree/bindings/sound/nau8825.txt b/Documentation/devicetree/bindings/sound/nau8825.txt
index cb861aca8d40..a9c34526f4cb 100644
--- a/Documentation/devicetree/bindings/sound/nau8825.txt
+++ b/Documentation/devicetree/bindings/sound/nau8825.txt
@@ -74,6 +74,9 @@ Optional properties:
- nuvoton,adcout-drive-strong: make the drive strength of ADCOUT IO PIN strong if set.
Otherwise, the drive keeps normal strength.
+ - nuvoton,adc-delay-ms: Delay (in ms) to make input path stable and avoid pop noise. The
+ default value is 125 and range between 125 to 500 ms.
+
- 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
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml
index 7ef774910e5c..96f2f927a6f5 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml
@@ -31,10 +31,10 @@ properties:
items:
enum:
# Board Connectors
- - "Headset Stereophone"
- - "Int Spk"
- - "Headset Mic"
- - "Digital Mic"
+ - Headset Stereophone
+ - Int Spk
+ - Headset Mic
+ - Digital Mic
# CODEC Pins
- SPKOUT
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml
index 82801b4f46dd..7c1e9895ce85 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml
@@ -80,4 +80,8 @@ properties:
type: boolean
description: The Mic Jack represents state of the headset microphone pin
+ nvidia,coupled-mic-hp-det:
+ type: boolean
+ description: The Mic detect GPIO is viable only if HP detect GPIO is active
+
additionalProperties: true
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml
new file mode 100644
index 000000000000..fc89dbd6bf24
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-max9808x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra audio complex with MAX9808x CODEC
+
+maintainers:
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: nvidia,tegra-audio-common.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - pattern: '^[a-z0-9]+,tegra-audio-max98088(-[a-z0-9]+)+$'
+ - const: nvidia,tegra-audio-max98088
+ - items:
+ - pattern: '^[a-z0-9]+,tegra-audio-max98089(-[a-z0-9]+)+$'
+ - const: nvidia,tegra-audio-max98089
+
+ nvidia,audio-routing:
+ $ref: /schemas/types.yaml#/definitions/non-unique-string-array
+ description: |
+ 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 and
+ sinks are the pins (documented in the binding document),
+ and the jacks on the board.
+ minItems: 2
+ items:
+ enum:
+ # Board Connectors
+ - "Int Spk"
+ - "Headphone Jack"
+ - "Earpiece"
+ - "Headset Mic"
+ - "Internal Mic 1"
+ - "Internal Mic 2"
+
+ # CODEC Pins
+ - HPL
+ - HPR
+ - SPKL
+ - SPKR
+ - RECL
+ - RECR
+ - INA1
+ - INA2
+ - INB1
+ - INB2
+ - MIC1
+ - MIC2
+ - MICBIAS
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/tegra30-car.h>
+ #include <dt-bindings/soc/tegra-pmc.h>
+ sound {
+ compatible = "lge,tegra-audio-max98089-p895",
+ "nvidia,tegra-audio-max98089";
+ nvidia,model = "LG Optimus Vu MAX98089";
+
+ nvidia,audio-routing =
+ "Headphone Jack", "HPL",
+ "Headphone Jack", "HPR",
+ "Int Spk", "SPKL",
+ "Int Spk", "SPKR",
+ "Earpiece", "RECL",
+ "Earpiece", "RECR",
+ "INA1", "Headset Mic",
+ "MIC1", "MICBIAS",
+ "MICBIAS", "Internal Mic 1",
+ "MIC2", "Internal Mic 2";
+
+ nvidia,i2s-controller = <&tegra_i2s0>;
+ nvidia,audio-codec = <&codec>;
+
+ clocks = <&tegra_car TEGRA30_CLK_PLL_A>,
+ <&tegra_car TEGRA30_CLK_PLL_A_OUT0>,
+ <&tegra_pmc TEGRA_PMC_CLK_OUT_1>;
+ clock-names = "pll_a", "pll_a_out0", "mclk";
+ };
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml
index ccc2ee77ca30..4d912458b18b 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml
@@ -38,10 +38,10 @@ properties:
items:
enum:
# Board Connectors
- - "Headphones"
- - "Speakers"
- - "Mic Jack"
- - "Int Mic"
+ - Headphones
+ - Speakers
+ - Mic Jack
+ - Int Mic
# CODEC Pins
- MIC1
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml
new file mode 100644
index 000000000000..a04487002e88
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-rt5631.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra audio complex with RT5631 CODEC
+
+maintainers:
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+allOf:
+ - $ref: nvidia,tegra-audio-common.yaml#
+
+properties:
+ compatible:
+ items:
+ - pattern: '^[a-z0-9]+,tegra-audio-rt5631(-[a-z0-9]+)+$'
+ - const: nvidia,tegra-audio-rt5631
+
+ nvidia,audio-routing:
+ $ref: /schemas/types.yaml#/definitions/non-unique-string-array
+ description: |
+ 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 and
+ sinks are the pins (documented in the binding document),
+ and the jacks on the board.
+ minItems: 2
+ items:
+ enum:
+ # Board Connectors
+ - "Int Spk"
+ - "Headphone Jack"
+ - "Mic Jack"
+ - "Int Mic"
+
+ # CODEC Pins
+ - MIC1
+ - MIC2
+ - AXIL
+ - AXIR
+ - MONOIN_RXN
+ - MONOIN_RXP
+ - DMIC
+ - MIC Bias1
+ - MIC Bias2
+ - MONO_IN
+ - AUXO1
+ - AUXO2
+ - SPOL
+ - SPOR
+ - HPOL
+ - HPOR
+ - MONO
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/tegra30-car.h>
+ #include <dt-bindings/soc/tegra-pmc.h>
+ sound {
+ compatible = "asus,tegra-audio-rt5631-tf700t",
+ "nvidia,tegra-audio-rt5631";
+ nvidia,model = "Asus Transformer Infinity TF700T RT5631";
+
+ nvidia,audio-routing =
+ "Headphone Jack", "HPOL",
+ "Headphone Jack", "HPOR",
+ "Int Spk", "SPOL",
+ "Int Spk", "SPOR",
+ "MIC1", "MIC Bias1",
+ "MIC Bias1", "Mic Jack",
+ "DMIC", "Int Mic";
+
+ nvidia,i2s-controller = <&tegra_i2s1>;
+ nvidia,audio-codec = <&rt5631>;
+
+ clocks = <&tegra_car TEGRA30_CLK_PLL_A>,
+ <&tegra_car TEGRA30_CLK_PLL_A_OUT0>,
+ <&tegra_pmc TEGRA_PMC_CLK_OUT_1>;
+ clock-names = "pll_a", "pll_a_out0", "mclk";
+ };
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml
index b1deaf271afa..2638592435b2 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml
@@ -31,9 +31,9 @@ properties:
items:
enum:
# Board Connectors
- - "Headphones"
- - "Speakers"
- - "Mic Jack"
+ - Headphones
+ - Speakers
+ - Mic Jack
# CODEC Pins
- DMIC1
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml
index a49997d6028b..09e1d0b18d27 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml
@@ -31,11 +31,11 @@ properties:
items:
enum:
# Board Connectors
- - "Headphone"
- - "Speaker"
- - "Headset Mic"
- - "Internal Mic 1"
- - "Internal Mic 2"
+ - Headphone
+ - Speaker
+ - Headset Mic
+ - Internal Mic 1
+ - Internal Mic 2
# CODEC Pins
- IN1P
@@ -47,14 +47,14 @@ properties:
- DMIC2
- DMIC3
- DMIC4
- - "DMIC L1"
- - "DMIC L2"
- - "DMIC L3"
- - "DMIC L4"
- - "DMIC R1"
- - "DMIC R2"
- - "DMIC R3"
- - "DMIC R4"
+ - DMIC L1
+ - DMIC L2
+ - DMIC L3
+ - DMIC L4
+ - DMIC R1
+ - DMIC R2
+ - DMIC R3
+ - DMIC R4
- LOUT1
- LOUT2
- LOUT3
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml
index 943e7c01741c..e5bc6a6ade24 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml
@@ -31,9 +31,9 @@ properties:
items:
enum:
# Board Connectors
- - "Headphone Jack"
- - "Line In Jack"
- - "Mic Jack"
+ - Headphone Jack
+ - Line In Jack
+ - Mic Jack
# CODEC Pins
- HP_OUT
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml
index a5b431d7d0c2..3323d6a438f5 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml
@@ -31,8 +31,8 @@ properties:
items:
enum:
# Board Connectors
- - "Headphone Jack"
- - "Mic Jack"
+ - Headphone Jack
+ - Mic Jack
# CODEC Pins
- LOUT1
@@ -53,7 +53,7 @@ properties:
- MIC1
- MIC2N
- MIC2
- - "Mic Bias"
+ - Mic Bias
required:
- nvidia,i2s-controller
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml
index 1b836acab980..1be25ce4514b 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml
@@ -35,10 +35,10 @@ properties:
items:
enum:
# Board Connectors
- - "Headphone Jack"
- - "Int Spk"
- - "Mic Jack"
- - "Int Mic"
+ - Headphone Jack
+ - Int Spk
+ - Mic Jack
+ - Int Mic
# CODEC Pins
- IN1L
diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml
index a1448283344b..397306b8800d 100644
--- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml
+++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml
@@ -31,9 +31,9 @@ properties:
items:
enum:
# Board Connectors
- - "Headphone"
- - "LineIn"
- - "Mic"
+ - Headphone
+ - LineIn
+ - Mic
# CODEC Pins
- MONOOUT
@@ -48,7 +48,7 @@ properties:
- PCBEEP
- MIC1
- MIC2
- - "Mic Bias"
+ - Mic Bias
required:
- nvidia,ac97-controller
diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml
index e6fcf542cf87..ec4b0ac8ad68 100644
--- a/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml
+++ b/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml
@@ -9,15 +9,13 @@ title: LPASS(Low Power Audio Subsystem) RX Macro audio codec
maintainers:
- Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
-allOf:
- - $ref: dai-common.yaml#
-
properties:
compatible:
enum:
- qcom,sc7280-lpass-rx-macro
- qcom,sm8250-lpass-rx-macro
- qcom,sm8450-lpass-rx-macro
+ - qcom,sm8550-lpass-rx-macro
- qcom,sc8280xp-lpass-rx-macro
reg:
@@ -30,20 +28,12 @@ properties:
const: 0
clocks:
+ minItems: 3
maxItems: 5
clock-names:
- oneOf:
- - items: # for ADSP based platforms
- - const: mclk
- - const: npl
- - const: macro
- - const: dcodec
- - const: fsgen
- - items: # for ADSP bypass based platforms
- - const: mclk
- - const: npl
- - const: fsgen
+ minItems: 3
+ maxItems: 5
clock-output-names:
maxItems: 1
@@ -61,6 +51,65 @@ required:
- reg
- "#sound-dai-cells"
+allOf:
+ - $ref: dai-common.yaml#
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sc7280-lpass-rx-macro
+ then:
+ properties:
+ clock-names:
+ oneOf:
+ - items: # for ADSP based platforms
+ - const: mclk
+ - const: npl
+ - const: macro
+ - const: dcodec
+ - const: fsgen
+ - items: # for ADSP bypass based platforms
+ - const: mclk
+ - const: npl
+ - const: fsgen
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sc8280xp-lpass-rx-macro
+ - qcom,sm8250-lpass-rx-macro
+ - qcom,sm8450-lpass-rx-macro
+ then:
+ properties:
+ clocks:
+ minItems: 5
+ maxItems: 5
+ clock-names:
+ items:
+ - const: mclk
+ - const: npl
+ - const: macro
+ - const: dcodec
+ - const: fsgen
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sm8550-lpass-rx-macro
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ maxItems: 4
+ clock-names:
+ items:
+ - const: mclk
+ - const: macro
+ - const: dcodec
+ - const: fsgen
+
unevaluatedProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml
index 6c8751497d36..4156981fe02b 100644
--- a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml
+++ b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml
@@ -9,15 +9,13 @@ title: LPASS(Low Power Audio Subsystem) TX Macro audio codec
maintainers:
- Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
-allOf:
- - $ref: dai-common.yaml#
-
properties:
compatible:
enum:
- qcom,sc7280-lpass-tx-macro
- qcom,sm8250-lpass-tx-macro
- qcom,sm8450-lpass-tx-macro
+ - qcom,sm8550-lpass-tx-macro
- qcom,sc8280xp-lpass-tx-macro
reg:
@@ -30,22 +28,12 @@ properties:
const: 0
clocks:
- oneOf:
- - maxItems: 3
- - maxItems: 5
+ minItems: 3
+ maxItems: 5
clock-names:
- oneOf:
- - items: # for ADSP based platforms
- - const: mclk
- - const: npl
- - const: macro
- - const: dcodec
- - const: fsgen
- - items: # for ADSP bypass based platforms
- - const: mclk
- - const: npl
- - const: fsgen
+ minItems: 3
+ maxItems: 5
clock-output-names:
maxItems: 1
@@ -67,6 +55,65 @@ required:
- reg
- "#sound-dai-cells"
+allOf:
+ - $ref: dai-common.yaml#
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sc7280-lpass-tx-macro
+ then:
+ properties:
+ clock-names:
+ oneOf:
+ - items: # for ADSP based platforms
+ - const: mclk
+ - const: npl
+ - const: macro
+ - const: dcodec
+ - const: fsgen
+ - items: # for ADSP bypass based platforms
+ - const: mclk
+ - const: npl
+ - const: fsgen
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sc8280xp-lpass-tx-macro
+ - qcom,sm8250-lpass-tx-macro
+ - qcom,sm8450-lpass-tx-macro
+ then:
+ properties:
+ clocks:
+ minItems: 5
+ maxItems: 5
+ clock-names:
+ items:
+ - const: mclk
+ - const: npl
+ - const: macro
+ - const: dcodec
+ - const: fsgen
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sm8550-lpass-tx-macro
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ maxItems: 4
+ clock-names:
+ items:
+ - const: mclk
+ - const: macro
+ - const: dcodec
+ - const: fsgen
+
unevaluatedProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml
index 61cdfc265b0f..4a56108c444b 100644
--- a/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml
+++ b/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml
@@ -9,15 +9,13 @@ title: LPASS(Low Power Audio Subsystem) VA Macro audio codec
maintainers:
- Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
-allOf:
- - $ref: dai-common.yaml#
-
properties:
compatible:
enum:
- qcom,sc7280-lpass-va-macro
- qcom,sm8250-lpass-va-macro
- qcom,sm8450-lpass-va-macro
+ - qcom,sm8550-lpass-va-macro
- qcom,sc8280xp-lpass-va-macro
reg:
@@ -30,16 +28,12 @@ properties:
const: 0
clocks:
- maxItems: 3
+ minItems: 1
+ maxItems: 4
clock-names:
- oneOf:
- - items: # for ADSP based platforms
- - const: mclk
- - const: macro
- - const: dcodec
- - items: # for ADSP bypass based platforms
- - const: mclk
+ minItems: 1
+ maxItems: 4
clock-output-names:
maxItems: 1
@@ -63,6 +57,76 @@ required:
- compatible
- reg
- "#sound-dai-cells"
+ - clock-names
+ - clocks
+
+allOf:
+ - $ref: dai-common.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,sc7280-lpass-va-macro
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ items:
+ - const: mclk
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,sm8250-lpass-va-macro
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ maxItems: 3
+ clock-names:
+ items:
+ - const: mclk
+ - const: macro
+ - const: dcodec
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sc8280xp-lpass-va-macro
+ - qcom,sm8450-lpass-va-macro
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ maxItems: 4
+ clock-names:
+ items:
+ - const: mclk
+ - const: macro
+ - const: dcodec
+ - const: npl
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8550-lpass-va-macro
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ maxItems: 3
+ clock-names:
+ items:
+ - const: mclk
+ - const: macro
+ - const: dcodec
unevaluatedProperties: false
diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml
index 66cbb1f5e31a..eea7609d1b33 100644
--- a/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml
+++ b/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml
@@ -15,6 +15,7 @@ properties:
- qcom,sc7280-lpass-wsa-macro
- qcom,sm8250-lpass-wsa-macro
- qcom,sm8450-lpass-wsa-macro
+ - qcom,sm8550-lpass-wsa-macro
- qcom,sc8280xp-lpass-wsa-macro
reg:
@@ -27,11 +28,11 @@ properties:
const: 0
clocks:
- minItems: 5
+ minItems: 4
maxItems: 6
clock-names:
- minItems: 5
+ minItems: 4
maxItems: 6
clock-output-names:
@@ -62,6 +63,7 @@ allOf:
then:
properties:
clocks:
+ minItems: 5
maxItems: 5
clock-names:
items:
@@ -89,6 +91,23 @@ allOf:
- const: va
- const: fsgen
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sm8550-lpass-wsa-macro
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ maxItems: 4
+ clock-names:
+ items:
+ - const: mclk
+ - const: macro
+ - const: dcodec
+ - const: fsgen
+
unevaluatedProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml b/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml
index 0110b38f6de9..ce811942a9f1 100644
--- a/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml
+++ b/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml
@@ -56,7 +56,7 @@ patternProperties:
Compress offload dai.
dependencies:
- is-compress-dai: ["direction"]
+ is-compress-dai: [ direction ]
required:
- reg
diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt b/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt
deleted file mode 100644
index 1f75feec3dec..000000000000
--- a/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt
+++ /dev/null
@@ -1,123 +0,0 @@
-QCOM WCD9335 Codec
-
-Qualcomm WCD9335 Codec is a standalone Hi-Fi audio codec IC, supports
-Qualcomm Technologies, Inc. (QTI) multimedia solutions, including
-the MSM8996, MSM8976, and MSM8956 chipsets. It has in-built
-Soundwire controller, interrupt mux. It supports both I2S/I2C and
-SLIMbus audio interfaces.
-
-Required properties with SLIMbus Interface:
-
-- compatible:
- Usage: required
- Value type: <stringlist>
- Definition: For SLIMbus interface it should be "slimMID,PID",
- textual representation of Manufacturer ID, Product Code,
- shall be in lower case hexadecimal with leading zeroes
- suppressed. Refer to slimbus/bus.txt for details.
- Should be:
- "slim217,1a0" for MSM8996 and APQ8096 SoCs with SLIMbus.
-
-- reg
- Usage: required
- Value type: <u32 u32>
- Definition: Should be ('Device index', 'Instance ID')
-
-- interrupts
- Usage: required
- Value type: <prop-encoded-array>
- Definition: Interrupts via WCD INTR1 and INTR2 pins
-
-- interrupt-names:
- Usage: required
- Value type: <String array>
- Definition: Interrupt names of WCD INTR1 and INTR2
- Should be: "intr1", "intr2"
-
-- reset-gpios:
- Usage: required
- Value type: <String Array>
- Definition: Reset gpio line
-
-- slim-ifc-dev:
- Usage: required
- Value type: <phandle>
- Definition: SLIM interface device
-
-- clocks:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: See clock-bindings.txt section "consumers". List of
- three clock specifiers for mclk, mclk2 and slimbus clock.
-
-- clock-names:
- Usage: required
- Value type: <string>
- Definition: Must contain "mclk", "mclk2" and "slimbus" strings.
-
-- vdd-buck-supply:
- Usage: required
- Value type: <phandle>
- Definition: Should contain a reference to the 1.8V buck supply
-
-- vdd-buck-sido-supply:
- Usage: required
- Value type: <phandle>
- Definition: Should contain a reference to the 1.8V SIDO buck supply
-
-- vdd-rx-supply:
- Usage: required
- Value type: <phandle>
- Definition: Should contain a reference to the 1.8V rx supply
-
-- vdd-tx-supply:
- Usage: required
- Value type: <phandle>
- Definition: Should contain a reference to the 1.8V tx supply
-
-- vdd-vbat-supply:
- Usage: Optional
- Value type: <phandle>
- Definition: Should contain a reference to the vbat supply
-
-- vdd-micbias-supply:
- Usage: required
- Value type: <phandle>
- Definition: Should contain a reference to the micbias supply
-
-- vdd-io-supply:
- Usage: required
- Value type: <phandle>
- Definition: Should contain a reference to the 1.8V io supply
-
-- interrupt-controller:
- Usage: required
- Definition: Indicating that this is a interrupt controller
-
-- #interrupt-cells:
- Usage: required
- Value type: <int>
- Definition: should be 1
-
-#sound-dai-cells
- Usage: required
- Value type: <u32>
- Definition: Must be 1
-
-audio-codec@1{
- compatible = "slim217,1a0";
- reg = <1 0>;
- interrupts = <&msmgpio 54 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "intr2"
- reset-gpios = <&msmgpio 64 GPIO_ACTIVE_LOW>;
- slim-ifc-dev = <&wc9335_ifd>;
- clock-names = "mclk", "native";
- clocks = <&rpmcc RPM_SMD_DIV_CLK1>,
- <&rpmcc RPM_SMD_BB_CLK1>;
- vdd-buck-supply = <&pm8994_s4>;
- vdd-rx-supply = <&pm8994_s4>;
- vdd-buck-sido-supply = <&pm8994_s4>;
- vdd-tx-supply = <&pm8994_s4>;
- vdd-io-supply = <&pm8994_s4>;
- #sound-dai-cells = <1>;
-}
diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd9335.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd9335.yaml
new file mode 100644
index 000000000000..34f8fe4da9d4
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/qcom,wcd9335.yaml
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/qcom,wcd9335.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm WCD9335 Audio Codec
+
+maintainers:
+ - Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
+
+description:
+ Qualcomm WCD9335 Codec is a standalone Hi-Fi audio codec IC with in-built
+ Soundwire controller and interrupt mux. It supports both I2S/I2C and SLIMbus
+ audio interfaces.
+
+properties:
+ compatible:
+ const: slim217,1a0
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: mclk
+ - const: slimbus
+
+ interrupts:
+ maxItems: 2
+
+ interrupt-names:
+ items:
+ - const: intr1
+ - const: intr2
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ slim-ifc-dev:
+ description: SLIM IFC device interface
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ '#sound-dai-cells':
+ const: 1
+
+ vdd-buck-supply:
+ description: 1.8V buck supply
+
+ vdd-buck-sido-supply:
+ description: 1.8V SIDO buck supply
+
+ vdd-io-supply:
+ description: 1.8V I/O supply
+
+ vdd-micbias-supply:
+ description: micbias supply
+
+ vdd-rx-supply:
+ description: 1.8V rx supply
+
+ vdd-tx-supply:
+ description: 1.8V tx supply
+
+ vdd-vbat-supply:
+ description: vbat supply
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: dai-common.yaml#
+ - if:
+ required:
+ - slim-ifc-dev
+ then:
+ required:
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - interrupt-controller
+ - '#interrupt-cells'
+ - reset-gpios
+ - slim-ifc-dev
+ - '#sound-dai-cells'
+ - vdd-buck-supply
+ - vdd-buck-sido-supply
+ - vdd-io-supply
+ - vdd-rx-supply
+ - vdd-tx-supply
+ else:
+ properties:
+ clocks: false
+ clock-names: false
+ interrupts: false
+ interrupt-names: false
+ interrupt-controller: false
+ '#interrupt-cells': false
+ reset-gpios: false
+ slim-ifc-dev: false
+ '#sound-dai-cells': false
+ vdd-buck-supply: false
+ vdd-buck-sido-supply: false
+ vdd-io-supply: false
+ vdd-micbias-supply: false
+ vdd-rx-supply: false
+ vdd-tx-supply: false
+ vdd-vbat-supply: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmcc.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ tasha_ifd: codec@0,0 {
+ compatible = "slim217,1a0";
+ reg = <0 0>;
+ };
+
+ codec@1,0 {
+ compatible = "slim217,1a0";
+ reg = <1 0>;
+
+ clock-names = "mclk", "slimbus";
+ clocks = <&div1_mclk>, <&rpmcc RPM_SMD_BB_CLK1>;
+
+ interrupt-parent = <&tlmm>;
+ interrupts = <54 IRQ_TYPE_LEVEL_HIGH>,
+ <53 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "intr1", "intr2";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+
+ reset-gpios = <&tlmm 64 GPIO_ACTIVE_LOW>;
+ slim-ifc-dev = <&tasha_ifd>;
+ #sound-dai-cells = <1>;
+
+ vdd-buck-supply = <&vreg_s4a_1p8>;
+ vdd-buck-sido-supply = <&vreg_s4a_1p8>;
+ vdd-tx-supply = <&vreg_s4a_1p8>;
+ vdd-rx-supply = <&vreg_s4a_1p8>;
+ vdd-io-supply = <&vreg_s4a_1p8>;
+ };
diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml
index 30506d91fddd..4df59f3b7b01 100644
--- a/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml
+++ b/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml
@@ -152,6 +152,7 @@ required:
- reg
allOf:
+ - $ref: dai-common.yaml#
- if:
required:
- slim-ifc-dev
diff --git a/Documentation/devicetree/bindings/sound/realtek,alc5632.yaml b/Documentation/devicetree/bindings/sound/realtek,alc5632.yaml
new file mode 100644
index 000000000000..fb05988ff7ea
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/realtek,alc5632.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/realtek,alc5632.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ALC5632 audio CODEC
+
+description: |
+ Pins on the device (for linking into audio routes):
+ * SPK_OUTP
+ * SPK_OUTN
+ * HP_OUT_L
+ * HP_OUT_R
+ * AUX_OUT_P
+ * AUX_OUT_N
+ * LINE_IN_L
+ * LINE_IN_R
+ * PHONE_P
+ * PHONE_N
+ * MIC1_P
+ * MIC1_N
+ * MIC2_P
+ * MIC2_N
+ * MICBIAS1
+ * DMICDAT
+
+maintainers:
+ - Leon Romanovsky <leon@leon.nu>
+
+properties:
+ compatible:
+ const: realtek,alc5632
+
+ reg:
+ maxItems: 1
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-controller: true
+
+required:
+ - compatible
+ - reg
+ - '#gpio-cells'
+ - gpio-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@1a {
+ compatible = "realtek,alc5632";
+ reg = <0x1a>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml
index 12ccf29338d9..8a821dec9526 100644
--- a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml
+++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml
@@ -101,17 +101,7 @@ properties:
clock-names:
description: List of necessary clock names.
- minItems: 1
- maxItems: 31
- items:
- oneOf:
- - const: ssi-all
- - pattern: '^ssi\.[0-9]$'
- - pattern: '^src\.[0-9]$'
- - pattern: '^mix\.[0-1]$'
- - pattern: '^ctu\.[0-1]$'
- - pattern: '^dvc\.[0-1]$'
- - pattern: '^clk_(a|b|c|i)$'
+ # details are defined below
ports:
$ref: audio-graph-port.yaml#/definitions/port-base
@@ -155,7 +145,7 @@ properties:
dmas:
maxItems: 1
dma-names:
- const: "tx"
+ const: tx
required:
- dmas
- dma-names
@@ -288,6 +278,11 @@ required:
allOf:
- $ref: dai-common.yaml#
+
+ # --------------------
+ # reg/reg-names
+ # --------------------
+ # for Gen1
- if:
properties:
compatible:
@@ -303,7 +298,15 @@ allOf:
- scu
- ssi
- adg
- else:
+ # for Gen2/Gen3
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,rcar_sound-gen2
+ - renesas,rcar_sound-gen3
+ then:
properties:
reg:
minItems: 5
@@ -315,35 +318,87 @@ allOf:
- ssiu
- ssi
- audmapp
+ # for Gen4
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,rcar_sound-gen4
+ then:
+ properties:
+ reg:
+ maxItems: 4
+ reg-names:
+ items:
+ enum:
+ - adg
+ - ssiu
+ - ssi
+ - sdmc
+
+ # --------------------
+ # clock-names
+ # --------------------
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,rcar_sound-gen4
+ then:
+ properties:
+ clock-names:
+ maxItems: 3
+ items:
+ enum:
+ - ssi.0
+ - ssiu.0
+ - clkin
+ else:
+ properties:
+ clock-names:
+ minItems: 1
+ maxItems: 31
+ items:
+ oneOf:
+ - const: ssi-all
+ - pattern: '^ssi\.[0-9]$'
+ - pattern: '^src\.[0-9]$'
+ - pattern: '^mix\.[0-1]$'
+ - pattern: '^ctu\.[0-1]$'
+ - pattern: '^dvc\.[0-1]$'
+ - pattern: '^clk_(a|b|c|i)$'
unevaluatedProperties: false
examples:
- |
+ #include <dt-bindings/clock/r8a7790-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/r8a7790-sysc.h>
rcar_sound: sound@ec500000 {
#sound-dai-cells = <1>;
compatible = "renesas,rcar_sound-r8a7790", "renesas,rcar_sound-gen2";
reg = <0xec500000 0x1000>, /* SCU */
<0xec5a0000 0x100>, /* ADG */
<0xec540000 0x1000>, /* SSIU */
- <0xec541000 0x1280>, /* SSI */
+ <0xec541000 0x280>, /* SSI */
<0xec740000 0x200>; /* Audio DMAC peri peri*/
reg-names = "scu", "adg", "ssiu", "ssi", "audmapp";
- clocks = <&mstp10_clks 1005>, /* SSI-ALL */
- <&mstp10_clks 1006>, <&mstp10_clks 1007>, /* SSI9, SSI8 */
- <&mstp10_clks 1008>, <&mstp10_clks 1009>, /* SSI7, SSI6 */
- <&mstp10_clks 1010>, <&mstp10_clks 1011>, /* SSI5, SSI4 */
- <&mstp10_clks 1012>, <&mstp10_clks 1013>, /* SSI3, SSI2 */
- <&mstp10_clks 1014>, <&mstp10_clks 1015>, /* SSI1, SSI0 */
- <&mstp10_clks 1022>, <&mstp10_clks 1023>, /* SRC9, SRC8 */
- <&mstp10_clks 1024>, <&mstp10_clks 1025>, /* SRC7, SRC6 */
- <&mstp10_clks 1026>, <&mstp10_clks 1027>, /* SRC5, SRC4 */
- <&mstp10_clks 1028>, <&mstp10_clks 1029>, /* SRC3, SRC2 */
- <&mstp10_clks 1030>, <&mstp10_clks 1031>, /* SRC1, SRC0 */
- <&mstp10_clks 1020>, <&mstp10_clks 1021>, /* MIX1, MIX0 */
- <&mstp10_clks 1020>, <&mstp10_clks 1021>, /* CTU1, CTU0 */
- <&mstp10_clks 1019>, <&mstp10_clks 1018>, /* DVC0, DVC1 */
+ clocks = <&cpg CPG_MOD 1005>, /* SSI-ALL */
+ <&cpg CPG_MOD 1006>, <&cpg CPG_MOD 1007>, /* SSI9, SSI8 */
+ <&cpg CPG_MOD 1008>, <&cpg CPG_MOD 1009>, /* SSI7, SSI6 */
+ <&cpg CPG_MOD 1010>, <&cpg CPG_MOD 1011>, /* SSI5, SSI4 */
+ <&cpg CPG_MOD 1012>, <&cpg CPG_MOD 1013>, /* SSI3, SSI2 */
+ <&cpg CPG_MOD 1014>, <&cpg CPG_MOD 1015>, /* SSI1, SSI0 */
+ <&cpg CPG_MOD 1022>, <&cpg CPG_MOD 1023>, /* SRC9, SRC8 */
+ <&cpg CPG_MOD 1024>, <&cpg CPG_MOD 1025>, /* SRC7, SRC6 */
+ <&cpg CPG_MOD 1026>, <&cpg CPG_MOD 1027>, /* SRC5, SRC4 */
+ <&cpg CPG_MOD 1028>, <&cpg CPG_MOD 1029>, /* SRC3, SRC2 */
+ <&cpg CPG_MOD 1030>, <&cpg CPG_MOD 1031>, /* SRC1, SRC0 */
+ <&cpg CPG_MOD 1020>, <&cpg CPG_MOD 1021>, /* MIX1, MIX0 */
+ <&cpg CPG_MOD 1020>, <&cpg CPG_MOD 1021>, /* CTU1, CTU0 */
+ <&cpg CPG_MOD 1019>, <&cpg CPG_MOD 1018>, /* DVC0, DVC1 */
<&audio_clk_a>, <&audio_clk_b>, /* CLKA, CLKB */
<&audio_clk_c>, <&audio_clk_i>; /* CLKC, CLKI */
@@ -364,6 +419,17 @@ examples:
"clk_a", "clk_b",
"clk_c", "clk_i";
+ power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
+
+ resets = <&cpg 1005>,
+ <&cpg 1006>, <&cpg 1007>, <&cpg 1008>, <&cpg 1009>,
+ <&cpg 1010>, <&cpg 1011>, <&cpg 1012>, <&cpg 1013>,
+ <&cpg 1014>, <&cpg 1015>;
+ reset-names = "ssi-all",
+ "ssi.9", "ssi.8", "ssi.7", "ssi.6",
+ "ssi.5", "ssi.4", "ssi.3", "ssi.2",
+ "ssi.1", "ssi.0";
+
rcar_sound,dvc {
dvc0: dvc-0 {
dmas = <&audma0 0xbc>;
@@ -396,7 +462,7 @@ examples:
status = "disabled";
};
src1: src-1 {
- interrupts = <0 353 0>;
+ interrupts = <GIC_SPI 353 IRQ_TYPE_LEVEL_HIGH>;
dmas = <&audma0 0x87>, <&audma1 0x9c>;
dma-names = "rx", "tx";
};
@@ -417,12 +483,12 @@ examples:
rcar_sound,ssi {
ssi0: ssi-0 {
- interrupts = <0 370 1>;
+ interrupts = <GIC_SPI 370 IRQ_TYPE_LEVEL_HIGH>;
dmas = <&audma0 0x01>, <&audma1 0x02>;
dma-names = "rx", "tx";
};
ssi1: ssi-1 {
- interrupts = <0 371 1>;
+ interrupts = <GIC_SPI 371 IRQ_TYPE_LEVEL_HIGH>;
dmas = <&audma0 0x03>, <&audma1 0x04>;
dma-names = "rx", "tx";
};
@@ -464,7 +530,6 @@ examples:
};
};
-
/* assume audio-graph */
codec {
port {
diff --git a/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml b/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml
index 196881d94396..3b5ae45eee4a 100644
--- a/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml
+++ b/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml
@@ -25,14 +25,18 @@ properties:
maxItems: 1
interrupts:
- maxItems: 4
+ minItems: 2
+ maxItems: 3
interrupt-names:
- items:
- - const: int_req
- - const: dma_rx
- - const: dma_tx
- - const: dma_rt
+ oneOf:
+ - items:
+ - const: int_req
+ - const: dma_rx
+ - const: dma_tx
+ - items:
+ - const: int_req
+ - const: dma_rt
clocks:
maxItems: 4
@@ -106,9 +110,8 @@ examples:
reg = <0x10049c00 0x400>;
interrupts = <GIC_SPI 326 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 327 IRQ_TYPE_EDGE_RISING>,
- <GIC_SPI 328 IRQ_TYPE_EDGE_RISING>,
- <GIC_SPI 329 IRQ_TYPE_EDGE_RISING>;
- interrupt-names = "int_req", "dma_rx", "dma_tx", "dma_rt";
+ <GIC_SPI 328 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "int_req", "dma_rx", "dma_tx";
clocks = <&cpg CPG_MOD R9A07G044_SSI0_PCLK2>,
<&cpg CPG_MOD R9A07G044_SSI0_PCLK_SFR>,
<&audio_clk1>,
diff --git a/Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml b/Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml
index 4c95895de75e..7bb6c5dff786 100644
--- a/Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml
+++ b/Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml
@@ -86,6 +86,13 @@ properties:
- tx-m
- rx-m
+ port:
+ $ref: audio-graph-port.yaml#
+ unevaluatedProperties: false
+
+ power-domains:
+ maxItems: 1
+
rockchip,grf:
$ref: /schemas/types.yaml#/definitions/phandle
description:
diff --git a/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml b/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml
index 1cb4da300607..fcb01abffa97 100644
--- a/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml
+++ b/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml
@@ -34,6 +34,7 @@ properties:
- rockchip,rk3366-i2s
- rockchip,rk3368-i2s
- rockchip,rk3399-i2s
+ - rockchip,rk3588-i2s
- rockchip,rv1126-i2s
- const: rockchip,rk3066-i2s
@@ -82,6 +83,10 @@ properties:
resets:
maxItems: 2
+ port:
+ $ref: audio-graph-port.yaml#
+ unevaluatedProperties: false
+
rockchip,capture-channels:
$ref: /schemas/types.yaml#/definitions/uint32
default: 2
diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.yaml b/Documentation/devicetree/bindings/sound/sgtl5000.yaml
index 02059d66b084..1353c051488f 100644
--- a/Documentation/devicetree/bindings/sound/sgtl5000.yaml
+++ b/Documentation/devicetree/bindings/sound/sgtl5000.yaml
@@ -50,7 +50,7 @@ properties:
description: The bias voltage to be used in mVolts. The voltage can take
values from 1.25V to 3V by 250mV steps. If this node is not mentioned
or the value is unknown, then the value is set to 1.25V.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
enum: [ 1250, 1500, 1750, 2000, 2250, 2500, 2750, 3000 ]
lrclk-strength:
@@ -63,7 +63,7 @@ properties:
1 = 1.66 mA 2.87 mA 4.02 mA
2 = 3.33 mA 5.74 mA 8.03 mA
3 = 4.99 mA 8.61 mA 12.05 mA
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
enum: [ 0, 1, 2, 3 ]
sclk-strength:
@@ -76,7 +76,7 @@ properties:
1 = 1.66 mA 2.87 mA 4.02 mA
2 = 3.33 mA 5.74 mA 8.03 mA
3 = 4.99 mA 8.61 mA 12.05 mA
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
enum: [ 0, 1, 2, 3 ]
port:
diff --git a/Documentation/devicetree/bindings/sound/simple-card.yaml b/Documentation/devicetree/bindings/sound/simple-card.yaml
index 806e2fff165f..b05e05c81cc4 100644
--- a/Documentation/devicetree/bindings/sound/simple-card.yaml
+++ b/Documentation/devicetree/bindings/sound/simple-card.yaml
@@ -78,7 +78,7 @@ definitions:
$ref: /schemas/types.yaml#/definitions/uint32
prefix:
- description: "device name prefix"
+ description: device name prefix
$ref: /schemas/types.yaml#/definitions/string
label:
diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml
index 9cf0efaed88e..8600520d7c47 100644
--- a/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml
+++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml
@@ -42,7 +42,7 @@ properties:
Specifies a phandle to soc-glue, which is used for changing mode of S/PDIF
signal pin to output from Hi-Z. This property is optional if you use I2S
signal pins only.
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
"#sound-dai-cells":
const: 1
diff --git a/Documentation/devicetree/bindings/sound/tas571x.txt b/Documentation/devicetree/bindings/sound/tas571x.txt
index 7c8fd37c2f9e..1addc75989d5 100644
--- a/Documentation/devicetree/bindings/sound/tas571x.txt
+++ b/Documentation/devicetree/bindings/sound/tas571x.txt
@@ -12,6 +12,7 @@ Required properties:
- "ti,tas5717",
- "ti,tas5719",
- "ti,tas5721"
+ - "ti,tas5733"
- reg: The I2C address of the device
- #sound-dai-cells: must be equal to 0
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8510.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8510.yaml
new file mode 100644
index 000000000000..6d12b0ac37e2
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8510.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8510.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: WM8510 audio CODEC
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: wlf,wm8510
+
+ reg:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ codec@1a {
+ compatible = "wlf,wm8510";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8523.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8523.yaml
new file mode 100644
index 000000000000..decc395bb873
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8523.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8523.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: WM8523 audio CODEC
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: wlf,wm8523
+
+ reg:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@1a {
+ compatible = "wlf,wm8523";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8524.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8524.yaml
new file mode 100644
index 000000000000..4d951ece394e
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8524.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8524.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Wolfson WM8524 24-bit 192KHz Stereo DAC
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: wlf,wm8524
+
+ "#sound-dai-cells":
+ const: 0
+
+ wlf,mute-gpios:
+ maxItems: 1
+ description:
+ a GPIO spec for the MUTE pin.
+
+required:
+ - compatible
+ - wlf,mute-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ wm8524: codec {
+ compatible = "wlf,wm8524";
+ wlf,mute-gpios = <&gpio1 8 GPIO_ACTIVE_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8580.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8580.yaml
new file mode 100644
index 000000000000..2f27852cdc20
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8580.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8580.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: WM8580 and WM8581 audio CODEC
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - wlf,wm8580
+ - wlf,wm8581
+
+ reg:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@1a {
+ compatible = "wlf,wm8580";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8711.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8711.yaml
new file mode 100644
index 000000000000..ecaac2818b44
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8711.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8711.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: WM8711 audio CODEC
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: wlf,wm8711
+
+ reg:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@1a {
+ compatible = "wlf,wm8711";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8728.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8728.yaml
new file mode 100644
index 000000000000..fc89475a051e
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8728.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8728.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: WM8728 audio CODEC
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: wlf,wm8728
+
+ reg:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@1a {
+ compatible = "wlf,wm8728";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8737.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8737.yaml
new file mode 100644
index 000000000000..12d8765726d8
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8737.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8737.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: WM8737 audio CODEC
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: wlf,wm8737
+
+ reg:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@1a {
+ compatible = "wlf,wm8737";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8753.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8753.yaml
new file mode 100644
index 000000000000..9eebe7d7f0b7
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8753.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8753.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: WM8753 audio CODEC
+
+description: |
+ Pins on the device (for linking into audio routes):
+ * LOUT1
+ * LOUT2
+ * ROUT1
+ * ROUT2
+ * MONO1
+ * MONO2
+ * OUT3
+ * OUT4
+ * LINE1
+ * LINE2
+ * RXP
+ * RXN
+ * ACIN
+ * ACOP
+ * MIC1N
+ * MIC1
+ * MIC2N
+ * MIC2
+ * Mic Bias
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+allOf:
+ - $ref: dai-common.yaml#
+
+properties:
+ compatible:
+ const: wlf,wm8753
+
+ reg:
+ maxItems: 1
+
+ "#sound-dai-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ codec@1a {
+ compatible = "wlf,wm8753";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml
new file mode 100644
index 000000000000..ee8eba7f0104
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8960.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Wolfson WM8960 audio codec
+
+maintainers:
+ - patches@opensource.cirrus.com
+
+properties:
+ compatible:
+ const: wlf,wm8960
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: mclk
+
+ '#sound-dai-cells':
+ const: 0
+
+ wlf,capless:
+ type: boolean
+ description:
+ If present, OUT3 pin will be enabled and disabled together with HP_L and
+ HP_R pins in response to jack detect events.
+
+ wlf,gpio-cfg:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 2
+ description: |
+ A list of GPIO configuration register values.
+ - gpio-cfg[0]: ALRCGPIO of R9 (Audio interface)
+ - gpio-cfg[1]: {GPIOPOL:GPIOSEL[2:0]} of R48 (Additional Control 4).
+
+ wlf,hp-cfg:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 3
+ description: |
+ A list of headphone jack detect configuration register values:
+ - hp-cfg[0]: HPSEL[1:0] of R48 (Additional Control 4).
+ - hp-cfg[1]: {HPSWEN:HPSWPOL} of R24 (Additional Control 2).
+ - hp-cfg[2]: {TOCLKSEL:TOEN} of R23 (Additional Control 1).
+
+ wlf,shared-lrclk:
+ type: boolean
+ description:
+ If present, the LRCM bit of R24 (Additional control 2) gets set,
+ indicating that ADCLRC and DACLRC pins will be disabled only when ADC
+ (Left and Right) and DAC (Left and Right) are disabled.
+ When WM8960 works on synchronize mode and DACLRC pin is used to supply
+ frame clock, it will no frame clock for captrue unless enable DAC to
+ enable DACLRC pin. If shared-lrclk is present, no need to enable DAC for
+ captrue.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: dai-common.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ audio-codec@1a {
+ compatible = "wlf,wm8960";
+ reg = <0x1a>;
+ clocks = <&clks 0>;
+ clock-names = "mclk";
+ #sound-dai-cells = <0>;
+ wlf,hp-cfg = <3 2 3>;
+ wlf,gpio-cfg = <1 3>;
+ wlf,shared-lrclk;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8994.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8994.yaml
new file mode 100644
index 000000000000..8f045de02850
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wlf,wm8994.yaml
@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/wlf,wm8994.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Wolfson WM1811/WM8994/WM8958 audio codecs
+
+maintainers:
+ - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
+ - patches@opensource.cirrus.com
+
+description: |
+ These devices support both I2C and SPI (configured with pin strapping on the
+ board).
+
+ Pins on the device (for linking into audio routes):
+ IN1LN, IN1LP, IN2LN, IN2LP:VXRN, IN1RN, IN1RP, IN2RN, IN2RP:VXRP, SPKOUTLP,
+ SPKOUTLN, SPKOUTRP, SPKOUTRN, HPOUT1L, HPOUT1R, HPOUT2P, HPOUT2N, LINEOUT1P,
+ LINEOUT1N, LINEOUT2P, LINEOUT2N.
+
+properties:
+ compatible:
+ enum:
+ - wlf,wm1811
+ - wlf,wm8994
+ - wlf,wm8958
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: MCLK1
+ - const: MCLK2
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+ description:
+ The first cell is the IRQ number. The second cell is the flags, encoded
+ as the trigger masks.
+
+ AVDD1-supply: true
+ AVDD2-supply: true
+ CPVDD-supply: true
+ DBVDD-supply: true
+ DBVDD1-supply: true
+ DBVDD2-supply: true
+ DBVDD3-supply: true
+ DCVDD-supply: true
+ LDO1VDD-supply: true
+ LDO2VDD-supply: true
+ SPKVDD1-supply: true
+ SPKVDD2-supply: true
+
+ '#sound-dai-cells':
+ const: 0
+
+ wlf,gpio-cfg:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 11
+ description:
+ A list of GPIO configuration register values. If absent, no configuration
+ of these registers is performed. If any value is over 0xffff then the
+ register will be left as default. If present 11 values must be supplied.
+
+ wlf,micbias-cfg:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 2
+ description:
+ Two MICBIAS register values for WM1811 or WM8958. If absent the register
+ defaults will be used.
+
+ wlf,ldo1ena-gpios:
+ maxItems: 1
+ description:
+ Control of LDO1ENA input to device.
+
+ wlf,ldo2ena-gpios:
+ maxItems: 1
+ description:
+ Control of LDO2ENA input to device.
+
+ wlf,lineout1-se:
+ type: boolean
+ description:
+ LINEOUT1 is in single ended mode.
+
+ wlf,lineout2-se:
+ type: boolean
+ description:
+ INEOUT2 is in single ended mode.
+
+ wlf,lineout1-feedback:
+ type: boolean
+ description:
+ LINEOUT1 has common mode feedback connected.
+
+ wlf,lineout2-feedback:
+ type: boolean
+ description:
+ LINEOUT2 has common mode feedback connected.
+
+ wlf,ldoena-always-driven:
+ type: boolean
+ description:
+ LDOENA is always driven.
+
+ wlf,spkmode-pu:
+ type: boolean
+ description:
+ Enable the internal pull-up resistor on the SPKMODE pin.
+
+ wlf,csnaddr-pd:
+ type: boolean
+ description:
+ Enable the internal pull-down resistor on the CS/ADDR pin.
+
+required:
+ - compatible
+ - reg
+ - AVDD2-supply
+ - CPVDD-supply
+ - SPKVDD1-supply
+ - SPKVDD2-supply
+
+allOf:
+ - $ref: dai-common.yaml#
+ - if:
+ properties:
+ compatible:
+ enum:
+ - wlf,wm1811
+ - wlf,wm8958
+ then:
+ properties:
+ DBVDD-supply: false
+ LDO2VDD-supply: false
+ required:
+ - DBVDD1-supply
+ - DBVDD2-supply
+ - DBVDD3-supply
+ else:
+ properties:
+ DBVDD1-supply: false
+ DBVDD2-supply: false
+ DBVDD3-supply: false
+ required:
+ - DBVDD-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ audio-codec@1a {
+ compatible = "wlf,wm1811";
+ reg = <0x1a>;
+ clocks = <&i2s0 0>;
+ clock-names = "MCLK1";
+
+ AVDD2-supply = <&main_dc_reg>;
+ CPVDD-supply = <&main_dc_reg>;
+ DBVDD1-supply = <&main_dc_reg>;
+ DBVDD2-supply = <&main_dc_reg>;
+ DBVDD3-supply = <&main_dc_reg>;
+ LDO1VDD-supply = <&main_dc_reg>;
+ SPKVDD1-supply = <&main_dc_reg>;
+ SPKVDD2-supply = <&main_dc_reg>;
+
+ wlf,ldo1ena-gpios = <&gpb0 0 GPIO_ACTIVE_HIGH>;
+ wlf,ldo2ena-gpios = <&gpb0 1 GPIO_ACTIVE_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/sound/wm8510.txt b/Documentation/devicetree/bindings/sound/wm8510.txt
deleted file mode 100644
index e6b6cc041f89..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8510.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-WM8510 audio CODEC
-
-This device supports both I2C and SPI (configured with pin strapping
-on the board).
-
-Required properties:
-
- - compatible : "wlf,wm8510"
-
- - reg : the I2C address of the device for I2C, the chip select
- number for SPI.
-
-Example:
-
-wm8510: codec@1a {
- compatible = "wlf,wm8510";
- reg = <0x1a>;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8523.txt b/Documentation/devicetree/bindings/sound/wm8523.txt
deleted file mode 100644
index f3a6485f4b8a..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8523.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-WM8523 audio CODEC
-
-This device supports I2C only.
-
-Required properties:
-
- - compatible : "wlf,wm8523"
-
- - reg : the I2C address of the device.
-
-Example:
-
-wm8523: codec@1a {
- compatible = "wlf,wm8523";
- reg = <0x1a>;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8524.txt b/Documentation/devicetree/bindings/sound/wm8524.txt
deleted file mode 100644
index f6c0c263b135..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8524.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-WM8524 audio CODEC
-
-This device does not use I2C or SPI but a simple Hardware Control Interface.
-
-Required properties:
-
- - compatible : "wlf,wm8524"
-
- - wlf,mute-gpios: a GPIO spec for the MUTE pin.
-
-Example:
-
-wm8524: codec {
- compatible = "wlf,wm8524";
- wlf,mute-gpios = <&gpio1 8 GPIO_ACTIVE_LOW>;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8580.txt b/Documentation/devicetree/bindings/sound/wm8580.txt
deleted file mode 100644
index ff3f9f5f2111..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8580.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-WM8580 and WM8581 audio CODEC
-
-This device supports I2C only.
-
-Required properties:
-
- - compatible : "wlf,wm8580", "wlf,wm8581"
-
- - reg : the I2C address of the device.
-
-Example:
-
-wm8580: codec@1a {
- compatible = "wlf,wm8580";
- reg = <0x1a>;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8711.txt b/Documentation/devicetree/bindings/sound/wm8711.txt
deleted file mode 100644
index c30a1387c4bf..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8711.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-WM8711 audio CODEC
-
-This device supports both I2C and SPI (configured with pin strapping
-on the board).
-
-Required properties:
-
- - compatible : "wlf,wm8711"
-
- - reg : the I2C address of the device for I2C, the chip select
- number for SPI.
-
-Example:
-
-wm8711: codec@1a {
- compatible = "wlf,wm8711";
- reg = <0x1a>;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8728.txt b/Documentation/devicetree/bindings/sound/wm8728.txt
deleted file mode 100644
index a3608b4c78b9..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8728.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-WM8728 audio CODEC
-
-This device supports both I2C and SPI (configured with pin strapping
-on the board).
-
-Required properties:
-
- - compatible : "wlf,wm8728"
-
- - reg : the I2C address of the device for I2C, the chip select
- number for SPI.
-
-Example:
-
-wm8728: codec@1a {
- compatible = "wlf,wm8728";
- reg = <0x1a>;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8737.txt b/Documentation/devicetree/bindings/sound/wm8737.txt
deleted file mode 100644
index eda1ec6a7563..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8737.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-WM8737 audio CODEC
-
-This device supports both I2C and SPI (configured with pin strapping
-on the board).
-
-Required properties:
-
- - compatible : "wlf,wm8737"
-
- - reg : the I2C address of the device for I2C, the chip select
- number for SPI.
-
-Example:
-
-wm8737: codec@1a {
- compatible = "wlf,wm8737";
- reg = <0x1a>;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8753.txt b/Documentation/devicetree/bindings/sound/wm8753.txt
deleted file mode 100644
index eca9e5a825a9..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8753.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-WM8753 audio CODEC
-
-This device supports both I2C and SPI (configured with pin strapping
-on the board).
-
-Required properties:
-
- - compatible : "wlf,wm8753"
-
- - reg : the I2C address of the device for I2C, the chip select
- number for SPI.
-
-Pins on the device (for linking into audio routes):
-
- * LOUT1
- * LOUT2
- * ROUT1
- * ROUT2
- * MONO1
- * MONO2
- * OUT3
- * OUT4
- * LINE1
- * LINE2
- * RXP
- * RXN
- * ACIN
- * ACOP
- * MIC1N
- * MIC1
- * MIC2N
- * MIC2
- * Mic Bias
-
-Example:
-
-wm8753: codec@1a {
- compatible = "wlf,wm8753";
- reg = <0x1a>;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8960.txt b/Documentation/devicetree/bindings/sound/wm8960.txt
deleted file mode 100644
index 85d3b287108c..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8960.txt
+++ /dev/null
@@ -1,42 +0,0 @@
-WM8960 audio CODEC
-
-This device supports I2C only.
-
-Required properties:
-
- - compatible : "wlf,wm8960"
-
- - reg : the I2C address of the device.
-
-Optional properties:
- - wlf,shared-lrclk: This is a boolean property. If present, the LRCM bit of
- R24 (Additional control 2) gets set, indicating that ADCLRC and DACLRC pins
- will be disabled only when ADC (Left and Right) and DAC (Left and Right)
- are disabled.
- When wm8960 works on synchronize mode and DACLRC pin is used to supply
- frame clock, it will no frame clock for captrue unless enable DAC to enable
- DACLRC pin. If shared-lrclk is present, no need to enable DAC for captrue.
-
- - wlf,capless: This is a boolean property. If present, OUT3 pin will be
- enabled and disabled together with HP_L and HP_R pins in response to jack
- detect events.
-
- - wlf,hp-cfg: A list of headphone jack detect configuration register values.
- The list must be 3 entries long.
- hp-cfg[0]: HPSEL[1:0] of R48 (Additional Control 4).
- hp-cfg[1]: {HPSWEN:HPSWPOL} of R24 (Additional Control 2).
- hp-cfg[2]: {TOCLKSEL:TOEN} of R23 (Additional Control 1).
-
- - wlf,gpio-cfg: A list of GPIO configuration register values.
- The list must be 2 entries long.
- gpio-cfg[0]: ALRCGPIO of R9 (Audio interface)
- gpio-cfg[1]: {GPIOPOL:GPIOSEL[2:0]} of R48 (Additional Control 4).
-
-Example:
-
-wm8960: codec@1a {
- compatible = "wlf,wm8960";
- reg = <0x1a>;
-
- wlf,shared-lrclk;
-};
diff --git a/Documentation/devicetree/bindings/sound/wm8994.txt b/Documentation/devicetree/bindings/sound/wm8994.txt
deleted file mode 100644
index 8fa947509c10..000000000000
--- a/Documentation/devicetree/bindings/sound/wm8994.txt
+++ /dev/null
@@ -1,112 +0,0 @@
-WM1811/WM8994/WM8958 audio CODEC
-
-These devices support both I2C and SPI (configured with pin strapping
-on the board).
-
-Required properties:
-
- - compatible : One of "wlf,wm1811", "wlf,wm8994" or "wlf,wm8958".
-
- - reg : the I2C address of the device for I2C, the chip select
- number for SPI.
-
- - gpio-controller : Indicates this device is a GPIO controller.
- - #gpio-cells : Must be 2. The first cell is the pin number and the
- second cell is used to specify optional parameters (currently unused).
-
- - power supplies for the device, as covered in
- Documentation/devicetree/bindings/regulator/regulator.txt, depending
- on compatible:
- - for wlf,wm1811 and wlf,wm8958:
- AVDD1-supply, AVDD2-supply, DBVDD1-supply, DBVDD2-supply, DBVDD3-supply,
- DCVDD-supply, CPVDD-supply, SPKVDD1-supply, SPKVDD2-supply
- - for wlf,wm8994:
- AVDD1-supply, AVDD2-supply, DBVDD-supply, DCVDD-supply, CPVDD-supply,
- SPKVDD1-supply, SPKVDD2-supply
-
-Optional properties:
-
- - interrupts : The interrupt line the IRQ signal for the device is
- connected to. This is optional, if it is not connected then none
- of the interrupt related properties should be specified.
- - interrupt-controller : These devices contain interrupt controllers
- and may provide interrupt services to other devices if they have an
- interrupt line connected.
- - #interrupt-cells: the number of cells to describe an IRQ, this should be 2.
- The first cell is the IRQ number.
- The second cell is the flags, encoded as the trigger masks from
- Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-
- - clocks : A list of up to two phandle and clock specifier pairs
- - clock-names : A list of clock names sorted in the same order as clocks.
- Valid clock names are "MCLK1" and "MCLK2".
-
- - wlf,gpio-cfg : A list of GPIO configuration register values. If absent,
- no configuration of these registers is performed. If any value is
- over 0xffff then the register will be left as default. If present 11
- values must be supplied.
-
- - wlf,micbias-cfg : Two MICBIAS register values for WM1811 or
- WM8958. If absent the register defaults will be used.
-
- - wlf,ldo1ena : GPIO specifier for control of LDO1ENA input to device.
- - wlf,ldo2ena : GPIO specifier for control of LDO2ENA input to device.
-
- - wlf,lineout1-se : If present LINEOUT1 is in single ended mode.
- - wlf,lineout2-se : If present LINEOUT2 is in single ended mode.
-
- - wlf,lineout1-feedback : If present LINEOUT1 has common mode feedback
- connected.
- - wlf,lineout2-feedback : If present LINEOUT2 has common mode feedback
- connected.
-
- - wlf,ldoena-always-driven : If present LDOENA is always driven.
-
- - wlf,spkmode-pu : If present enable the internal pull-up resistor on
- the SPKMODE pin.
-
- - wlf,csnaddr-pd : If present enable the internal pull-down resistor on
- the CS/ADDR pin.
-
-Pins on the device (for linking into audio routes):
-
- * IN1LN
- * IN1LP
- * IN2LN
- * IN2LP:VXRN
- * IN1RN
- * IN1RP
- * IN2RN
- * IN2RP:VXRP
- * SPKOUTLP
- * SPKOUTLN
- * SPKOUTRP
- * SPKOUTRN
- * HPOUT1L
- * HPOUT1R
- * HPOUT2P
- * HPOUT2N
- * LINEOUT1P
- * LINEOUT1N
- * LINEOUT2P
- * LINEOUT2N
-
-Example:
-
-wm8994: codec@1a {
- compatible = "wlf,wm8994";
- reg = <0x1a>;
-
- gpio-controller;
- #gpio-cells = <2>;
-
- lineout1-se;
-
- AVDD1-supply = <&regulator>;
- AVDD2-supply = <&regulator>;
- CPVDD-supply = <&regulator>;
- DBVDD-supply = <&regulator>;
- DCVDD-supply = <&regulator>;
- SPKVDD1-supply = <&regulator>;
- SPKVDD2-supply = <&regulator>;
-};
diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst
index 5f31fa5e2435..af71c68f1e4e 100644
--- a/Documentation/sound/alsa-configuration.rst
+++ b/Documentation/sound/alsa-configuration.rst
@@ -723,9 +723,10 @@ Module for EMU10K1/EMU10k2 based PCI sound cards.
* Sound Blaster Live!
* Sound Blaster PCI 512
-* Emu APS (partially supported)
* Sound Blaster Audigy
-
+* E-MU APS (partially supported)
+* E-MU DAS
+
extin
bitmap of available external inputs for FX8010 (see below)
extout
diff --git a/Documentation/sound/cards/audigy-mixer.rst b/Documentation/sound/cards/audigy-mixer.rst
index c506f8d16f2e..aa176451d5b5 100644
--- a/Documentation/sound/cards/audigy-mixer.rst
+++ b/Documentation/sound/cards/audigy-mixer.rst
@@ -19,9 +19,9 @@ Digital mixer controls
These controls are built using the DSP instructions. They offer extended
functionality. Only the default built-in code in the ALSA driver is described
here. Note that the controls work as attenuators: the maximum value is the
-neutral position leaving the signal unchanged. Note that if the same destination
-is mentioned in multiple controls, the signal is accumulated and can be wrapped
-(set to maximal or minimal value without checking of overflow).
+neutral position leaving the signal unchanged. Note that if the same destination
+is mentioned in multiple controls, the signal is accumulated and can be clipped
+(set to maximal or minimal value without checking for overflow).
Explanation of used abbreviations:
@@ -32,17 +32,17 @@ ADC
analog to digital converter
I2S
one-way three wire serial bus for digital sound by Philips Semiconductors
- (this standard is used for connecting standalone DAC and ADC converters)
+ (this standard is used for connecting standalone D/A and A/D converters)
LFE
- low frequency effects (subwoofer signal)
+ low frequency effects (used as subwoofer signal)
AC97
- a chip containing an analog mixer, DAC and ADC converters
+ a chip containing an analog mixer, D/A and A/D converters
IEC958
S/PDIF
FX-bus
the EMU10K2 chip has an effect bus containing 64 accumulators.
- Each of the synthesizer voices can feed its output to these accumulators
- and the DSP microcontroller can operate with the resulting sum.
+ Each of the synthesizer voices can feed its output to these accumulators
+ and the DSP microcontroller can operate with the resulting sum.
name='PCM Front Playback Volume',index=0
----------------------------------------
@@ -218,8 +218,8 @@ LFE outputs.
name='IEC958 Optical Raw Playback Switch',index=0
-------------------------------------------------
If this switch is on, then the samples for the IEC958 (S/PDIF) digital
-output are taken only from the raw FX8010 PCM, otherwise standard front
-PCM samples are taken.
+output are taken only from the raw iec958 ALSA PCM device (which uses
+accumulators 20 and 21 for left and right PCM by default).
PCM stream related controls
@@ -237,8 +237,8 @@ as follows:
name='EMU10K1 PCM Send Routing',index 0-31
------------------------------------------
-This control specifies the destination - FX-bus accumulators. There 24
-values with this mapping:
+This control specifies the destination - FX-bus accumulators. There are 24
+values in this mapping:
* 0 - mono, A destination (FX-bus 0-63), default 0
* 1 - mono, B destination (FX-bus 0-63), default 1
@@ -306,6 +306,9 @@ MANUALS/PATENTS
ftp://opensource.creative.com/pub/doc
-------------------------------------
+Note that the site is defunct, but the documents are available
+from various other locations.
+
LM4545.pdf
AC97 Codec
diff --git a/Documentation/sound/cards/sb-live-mixer.rst b/Documentation/sound/cards/sb-live-mixer.rst
index 357fcd619d39..819886634400 100644
--- a/Documentation/sound/cards/sb-live-mixer.rst
+++ b/Documentation/sound/cards/sb-live-mixer.rst
@@ -15,7 +15,7 @@ The ALSA driver programs this portion of chip by default code
IEC958 (S/PDIF) raw PCM
=======================
-This PCM device (it's the 4th PCM device (index 3!) and first subdevice
+This PCM device (it's the 3rd PCM device (index 2!) and first subdevice
(index 0) for a given card) allows to forward 48kHz, stereo, 16-bit
little endian streams without any modifications to the digital output
(coaxial or optical). The universal interface allows the creation of up
@@ -33,9 +33,9 @@ Digital mixer controls
These controls are built using the DSP instructions. They offer extended
functionality. Only the default built-in code in the ALSA driver is described
here. Note that the controls work as attenuators: the maximum value is the
-neutral position leaving the signal unchanged. Note that if the same destination
-is mentioned in multiple controls, the signal is accumulated and can be wrapped
-(set to maximal or minimal value without checking of overflow).
+neutral position leaving the signal unchanged. Note that if the same destination
+is mentioned in multiple controls, the signal is accumulated and can be clipped
+(set to maximal or minimal value without checking for overflow).
Explanation of used abbreviations:
@@ -46,11 +46,11 @@ ADC
analog to digital converter
I2S
one-way three wire serial bus for digital sound by Philips Semiconductors
- (this standard is used for connecting standalone DAC and ADC converters)
+ (this standard is used for connecting standalone D/A and A/D converters)
LFE
- low frequency effects (subwoofer signal)
+ low frequency effects (used as subwoofer signal)
AC97
- a chip containing an analog mixer, DAC and ADC converters
+ a chip containing an analog mixer, D/A and A/D converters
IEC958
S/PDIF
FX-bus
@@ -313,6 +313,9 @@ MANUALS/PATENTS
ftp://opensource.creative.com/pub/doc
-------------------------------------
+Note that the site is defunct, but the documents are available
+from various other locations.
+
LM4545.pdf
AC97 Codec
m2049.pdf
diff --git a/Documentation/sound/hd-audio/index.rst b/Documentation/sound/hd-audio/index.rst
index 6e12de9fc34e..baefe4a5d165 100644
--- a/Documentation/sound/hd-audio/index.rst
+++ b/Documentation/sound/hd-audio/index.rst
@@ -9,3 +9,4 @@ HD-Audio
controls
dp-mst
realtek-pc-beep
+ intel-multi-link
diff --git a/Documentation/sound/hd-audio/intel-multi-link.rst b/Documentation/sound/hd-audio/intel-multi-link.rst
new file mode 100644
index 000000000000..bf0bb78833e7
--- /dev/null
+++ b/Documentation/sound/hd-audio/intel-multi-link.rst
@@ -0,0 +1,312 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-3-Clause)
+.. include:: <isonum.txt>
+
+================================================
+HDAudio multi-link extensions on Intel platforms
+================================================
+
+:Copyright: |copy| 2023 Intel Corporation
+
+This file documents the 'multi-link structure' introduced in 2015 with
+the Skylake processor and recently extended in newer Intel platforms
+
+HDaudio existing link mapping (2015 addition in SkyLake)
+========================================================
+
+External HDAudio codecs are handled with link #0, while iDISP codec
+for HDMI/DisplayPort is handled with link #1.
+
+The only change to the 2015 definitions is the declaration of the
+LCAP.ALT=0x0 - since the ALT bit was previously reserved, this is a
+backwards-compatible change.
+
+LCTL.SPA and LCTL.CPA are automatically set when exiting reset. They
+are only used in existing drivers when the SCF value needs to be
+corrected.
+
+Basic structure for HDaudio codecs
+----------------------------------
+
+::
+
+ +-----------+
+ | ML cap #0 |
+ +-----------+
+ | ML cap #1 |---+
+ +-----------+ |
+ |
+ +--> 0x0 +---------------+ LCAP
+ | ALT=0 |
+ +---------------+
+ | S192 |
+ +---------------+
+ | S96 |
+ +---------------+
+ | S48 |
+ +---------------+
+ | S24 |
+ +---------------+
+ | S12 |
+ +---------------+
+ | S6 |
+ +---------------+
+
+ 0x4 +---------------+ LCTL
+ | INTSTS |
+ +---------------+
+ | CPA |
+ +---------------+
+ | SPA |
+ +---------------+
+ | SCF |
+ +---------------+
+
+ 0x8 +---------------+ LOSIDV
+ | L1OSIVD15 |
+ +---------------+
+ | L1OSIDV.. |
+ +---------------+
+ | L1OSIDV1 |
+ +---------------+
+
+ 0xC +---------------+ LSDIID
+ | SDIID14 |
+ +---------------+
+ | SDIID... |
+ +---------------+
+ | SDIID0 |
+ +---------------+
+
+SoundWire HDaudio extended link mapping
+=======================================
+
+A SoundWire extended link is identified when LCAP.ALT=1 and
+LEPTR.ID=0.
+
+DMA control uses the existing LOSIDV register.
+
+Changes include additional descriptions for enumeration that were not
+present in earlier generations.
+
+- multi-link synchronization: capabilities in LCAP.LSS and control in LSYNC
+- number of sublinks (manager IP) in LCAP.LSCOUNT
+- power management moved from SHIM to LCTL.SPA bits
+- hand-over to the DSP for access to multi-link registers, SHIM/IP with LCTL.OFLEN
+- mapping of SoundWire codecs to SDI ID bits
+- move of SHIM and Cadence registers to different offsets, with no
+ change in functionality. The LEPTR.PTR value is an offset from the
+ ML address, with a default value of 0x30000.
+
+Extended structure for SoundWire (assuming 4 Manager IP)
+--------------------------------------------------------
+
+::
+
+ +-----------+
+ | ML cap #0 |
+ +-----------+
+ | ML cap #1 |
+ +-----------+
+ | ML cap #2 |---+
+ +-----------+ |
+ |
+ +--> 0x0 +---------------+ LCAP
+ | ALT=1 |
+ +---------------+
+ | INTC |
+ +---------------+
+ | OFLS |
+ +---------------+
+ | LSS |
+ +---------------+
+ | SLCOUNT=4 |-----------+
+ +---------------+ |
+ |
+ 0x4 +---------------+ LCTL |
+ | INTSTS | |
+ +---------------+ |
+ | CPA (x bits) | |
+ +---------------+ |
+ | SPA (x bits) | |
+ +---------------+ for each sublink x
+ | INTEN | |
+ +---------------+ |
+ | OFLEN | |
+ +---------------+ |
+ |
+ 0x8 +---------------+ LOSIDV |
+ | L1OSIVD15 | |
+ +---------------+ |
+ | L1OSIDV.. | |
+ +---------------+ |
+ | L1OSIDV1 | +---+----------------------------------------------------------+
+ +---------------+ | |
+ v |
+ 0xC + 0x2 * x +---------------+ LSDIIDx +---> 0x30000 +-----------------+ 0x00030000 |
+ | SDIID14 | | | SoundWire SHIM | |
+ +---------------+ | | generic | |
+ | SDIID... | | +-----------------+ 0x00030100 |
+ +---------------+ | | SoundWire IP | |
+ | SDIID0 | | +-----------------+ 0x00036000 |
+ +---------------+ | | SoundWire SHIM | |
+ | | vendor-specific | |
+ 0x1C +---------------+ LSYNC | +-----------------+ |
+ | CMDSYNC | | v
+ +---------------+ | +-----------------+ 0x00030000 + 0x8000 * x
+ | SYNCGO | | | SoundWire SHIM |
+ +---------------+ | | generic |
+ | SYNCPU | | +-----------------+ 0x00030100 + 0x8000 * x
+ +---------------+ | | SoundWire IP |
+ | SYNPRD | | +-----------------+ 0x00036000 + 0x8000 * x
+ +---------------+ | | SoundWire SHIM |
+ | | vendor-specific |
+ 0x20 +---------------+ LEPTR | +-----------------+
+ | ID = 0 | |
+ +---------------+ |
+ | VER | |
+ +---------------+ |
+ | PTR |------------+
+ +---------------+
+
+
+DMIC HDaudio extended link mapping
+==================================
+
+A DMIC extended link is identified when LCAP.ALT=1 and
+LEPTR.ID=0xC1 are set.
+
+DMA control uses the existing LOSIDV register
+
+Changes include additional descriptions for enumeration that were not
+present in earlier generations.
+
+- multi-link synchronization: capabilities in LCAP.LSS and control in LSYNC
+- power management with LCTL.SPA bits
+- hand-over to the DSP for access to multi-link registers, SHIM/IP with LCTL.OFLEN
+
+- move of DMIC registers to different offsets, with no change in
+ functionality. The LEPTR.PTR value is an offset from the ML
+ address, with a default value of 0x10000.
+
+Extended structure for DMIC
+---------------------------
+
+::
+
+ +-----------+
+ | ML cap #0 |
+ +-----------+
+ | ML cap #1 |
+ +-----------+
+ | ML cap #2 |---+
+ +-----------+ |
+ |
+ +--> 0x0 +---------------+ LCAP
+ | ALT=1 |
+ +---------------+
+ | INTC |
+ +---------------+
+ | OFLS |
+ +---------------+
+ | SLCOUNT=1 |
+ +---------------+
+
+ 0x4 +---------------+ LCTL
+ | INTSTS |
+ +---------------+
+ | CPA |
+ +---------------+
+ | SPA |
+ +---------------+
+ | INTEN |
+ +---------------+
+ | OFLEN |
+ +---------------+ +---> 0x10000 +-----------------+ 0x00010000
+ | | DMIC SHIM |
+ 0x8 +---------------+ LOSIDV | | generic |
+ | L1OSIVD15 | | +-----------------+ 0x00010100
+ +---------------+ | | DMIC IP |
+ | L1OSIDV.. | | +-----------------+ 0x00016000
+ +---------------+ | | DMIC SHIM |
+ | L1OSIDV1 | | | vendor-specific |
+ +---------------+ | +-----------------+
+ |
+ 0x20 +---------------+ LEPTR |
+ | ID = 0xC1 | |
+ +---------------+ |
+ | VER | |
+ +---------------+ |
+ | PTR |-----------+
+ +---------------+
+
+
+SSP HDaudio extended link mapping
+=================================
+
+A DMIC extended link is identified when LCAP.ALT=1 and
+LEPTR.ID=0xC0 are set.
+
+DMA control uses the existing LOSIDV register
+
+Changes include additional descriptions for enumeration and control that were not
+present in earlier generations:
+- number of sublinks (SSP IP instances) in LCAP.LSCOUNT
+- power management moved from SHIM to LCTL.SPA bits
+- hand-over to the DSP for access to multi-link registers, SHIM/IP
+with LCTL.OFLEN
+- move of SHIM and SSP IP registers to different offsets, with no
+change in functionality. The LEPTR.PTR value is an offset from the ML
+address, with a default value of 0x28000.
+
+Extended structure for SSP (assuming 3 instances of the IP)
+-----------------------------------------------------------
+
+::
+
+ +-----------+
+ | ML cap #0 |
+ +-----------+
+ | ML cap #1 |
+ +-----------+
+ | ML cap #2 |---+
+ +-----------+ |
+ |
+ +--> 0x0 +---------------+ LCAP
+ | ALT=1 |
+ +---------------+
+ | INTC |
+ +---------------+
+ | OFLS |
+ +---------------+
+ | SLCOUNT=3 |-------------------------for each sublink x -------------------------+
+ +---------------+ |
+ |
+ 0x4 +---------------+ LCTL |
+ | INTSTS | |
+ +---------------+ |
+ | CPA (x bits) | |
+ +---------------+ |
+ | SPA (x bits) | |
+ +---------------+ |
+ | INTEN | |
+ +---------------+ |
+ | OFLEN | |
+ +---------------+ +---> 0x28000 +-----------------+ 0x00028000 |
+ | | SSP SHIM | |
+ 0x8 +---------------+ LOSIDV | | generic | |
+ | L1OSIVD15 | | +-----------------+ 0x00028100 |
+ +---------------+ | | SSP IP | |
+ | L1OSIDV.. | | +-----------------+ 0x00028C00 |
+ +---------------+ | | SSP SHIM | |
+ | L1OSIDV1 | | | vendor-specific | |
+ +---------------+ | +-----------------+ |
+ | v
+ 0x20 +---------------+ LEPTR | +-----------------+ 0x00028000 + 0x1000 * x
+ | ID = 0xC0 | | | SSP SHIM |
+ +---------------+ | | generic |
+ | VER | | +-----------------+ 0x00028100 + 0x1000 * x
+ +---------------+ | | SSP IP |
+ | PTR |-----------+ +-----------------+ 0x00028C00 + 0x1000 * x
+ +---------------+ | SSP SHIM |
+ | vendor-specific |
+ +-----------------+
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 5c9523b7d55c..c0f97b5e4249 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -19,18 +19,13 @@ explain the general topic of linux kernel coding and doesn't cover
low-level driver implementation details. It only describes the standard
way to write a PCI sound driver on ALSA.
-This document is still a draft version. Any feedback and corrections,
-please!!
-
File Tree Structure
===================
General
-------
-The file tree structure of ALSA driver is depicted below.
-
-::
+The file tree structure of ALSA driver is depicted below::
sound
/core
@@ -68,8 +63,8 @@ kernel config.
core/oss
~~~~~~~~
-The codes for PCM and mixer OSS emulation modules are stored in this
-directory. The rawmidi OSS emulation is included in the ALSA rawmidi
+The code for OSS PCM and mixer emulation modules is stored in this
+directory. The OSS rawmidi emulation is included in the ALSA rawmidi
code since it's quite small. The sequencer code is stored in
``core/seq/oss`` directory (see `below <core/seq/oss_>`__).
@@ -78,19 +73,19 @@ core/seq
This directory and its sub-directories are for the ALSA sequencer. This
directory contains the sequencer core and primary sequencer modules such
-like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
+as snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
``CONFIG_SND_SEQUENCER`` is set in the kernel config.
core/seq/oss
~~~~~~~~~~~~
-This contains the OSS sequencer emulation codes.
+This contains the OSS sequencer emulation code.
include directory
-----------------
This is the place for the public header files of ALSA drivers, which are
-to be exported to user-space, or included by several files at different
+to be exported to user-space, or included by several files in different
directories. Basically, the private header files should not be placed in
this directory, but you may still find files there, due to historical
reasons :)
@@ -100,7 +95,7 @@ drivers directory
This directory contains code shared among different drivers on different
architectures. They are hence supposed not to be architecture-specific.
-For example, the dummy pcm driver and the serial MIDI driver are found
+For example, the dummy PCM driver and the serial MIDI driver are found
in this directory. In the sub-directories, there is code for components
which are independent from bus and cpu architectures.
@@ -156,8 +151,8 @@ these architectures.
usb directory
-------------
-This directory contains the USB-audio driver. In the latest version, the
-USB MIDI driver is integrated in the usb-audio driver.
+This directory contains the USB-audio driver.
+The USB MIDI driver is integrated in the usb-audio driver.
pcmcia directory
----------------
@@ -175,9 +170,9 @@ layer including ASoC core, codec and machine drivers.
oss directory
-------------
-Here contains OSS/Lite codes.
-All codes have been deprecated except for dmasound on m68k as of
-writing this.
+This contains OSS/Lite code.
+At the time of writing, all code has been removed except for dmasound
+on m68k.
Basic Flow for PCI Drivers
@@ -341,7 +336,7 @@ to details explained in the following section.
error:
snd_card_free(card);
- return err;
+ return err;
}
/* destructor -- see the "Destructor" sub-section */
@@ -381,7 +376,7 @@ where ``enable[dev]`` is the module option.
Each time the ``probe`` callback is called, check the availability of
the device. If not available, simply increment the device index and
-returns. dev will be incremented also later (`step 7
+return. dev will be incremented also later (`step 7
<7) Set the PCI driver data and return zero._>`__).
2) Create a card instance
@@ -402,9 +397,7 @@ Components`_.
3) Create a main component
~~~~~~~~~~~~~~~~~~~~~~~~~~
-In this part, the PCI resources are allocated.
-
-::
+In this part, the PCI resources are allocated::
struct mychip *chip;
....
@@ -417,13 +410,11 @@ Management`_.
When something goes wrong, the probe function needs to deal with the
error. In this example, we have a single error handling path placed
-at the end of the function.
-
-::
+at the end of the function::
error:
snd_card_free(card);
- return err;
+ return err;
Since each component can be properly freed, the single
:c:func:`snd_card_free()` call should suffice in most cases.
@@ -483,13 +474,11 @@ remove callback and power-management callbacks, too.
Destructor
----------
-The destructor, remove callback, simply releases the card instance. Then
-the ALSA middle layer will release all the attached components
+The destructor, the remove callback, simply releases the card instance.
+Then the ALSA middle layer will release all the attached components
automatically.
-It would be typically just calling :c:func:`snd_card_free()`:
-
-::
+It would be typically just calling :c:func:`snd_card_free()`::
static void snd_mychip_remove(struct pci_dev *pci)
{
@@ -504,9 +493,7 @@ Header Files
------------
For the above example, at least the following include files are
-necessary.
-
-::
+necessary::
#include <linux/init.h>
#include <linux/pci.h>
@@ -544,9 +531,7 @@ list on the card record is used to manage the correct release of
resources at destruction.
As mentioned above, to create a card instance, call
-:c:func:`snd_card_new()`.
-
-::
+:c:func:`snd_card_new()`::
struct snd_card *card;
int err;
@@ -572,10 +557,8 @@ struct snd_device object. A component
can be a PCM instance, a control interface, a raw MIDI interface, etc.
Each such instance has one component entry.
-A component can be created via :c:func:`snd_device_new()`
-function.
-
-::
+A component can be created via the :c:func:`snd_device_new()`
+function::
snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
@@ -591,7 +574,7 @@ allocated manually beforehand, and its pointer is passed as the
argument. This pointer (``chip`` in the above example) is used as the
identifier for the instance.
-Each pre-defined ALSA component such as ac97 and pcm calls
+Each pre-defined ALSA component such as AC97 and PCM calls
:c:func:`snd_device_new()` inside its constructor. The destructor
for each component is defined in the callback pointers. Hence, you don't
need to take care of calling a destructor for such a component.
@@ -605,9 +588,7 @@ Chip-Specific Data
------------------
Chip-specific information, e.g. the I/O port address, its resource
-pointer, or the irq number, is stored in the chip-specific record.
-
-::
+pointer, or the irq number, is stored in the chip-specific record::
struct mychip {
....
@@ -620,9 +601,7 @@ In general, there are two ways of allocating the chip record.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As mentioned above, you can pass the extra-data-length to the 5th
-argument of :c:func:`snd_card_new()`, i.e.
-
-::
+argument of :c:func:`snd_card_new()`, e.g.::
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
sizeof(struct mychip), &card);
@@ -642,9 +621,7 @@ released together with the card instance.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After allocating a card instance via :c:func:`snd_card_new()`
-(with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
-
-::
+(with ``0`` on the 4th arg), call :c:func:`kzalloc()`::
struct snd_card *card;
struct mychip *chip;
@@ -663,16 +640,12 @@ The chip record should have the field to hold the card pointer at least,
};
-Then, set the card pointer in the returned chip instance.
-
-::
+Then, set the card pointer in the returned chip instance::
chip->card = card;
Next, initialize the fields, and register this chip record as a
-low-level device with a specified ``ops``,
-
-::
+low-level device with a specified ``ops``::
static const struct snd_device_ops ops = {
.dev_free = snd_mychip_dev_free,
@@ -681,9 +654,7 @@ low-level device with a specified ``ops``,
snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
:c:func:`snd_mychip_dev_free()` is the device-destructor
-function, which will call the real destructor.
-
-::
+function, which will call the real destructor::
static int snd_mychip_dev_free(struct snd_device *device)
{
@@ -692,10 +663,10 @@ function, which will call the real destructor.
where :c:func:`snd_mychip_free()` is the real destructor.
-The demerit of this method is the obviously more amount of codes.
-The merit is, however, you can trigger the own callback at registering
-and disconnecting the card via setting in snd_device_ops.
-About the registering and disconnecting the card, see the subsections
+The demerit of this method is the obviously larger amount of code.
+The merit is, however, that you can trigger your own callback at
+registering and disconnecting the card via a setting in snd_device_ops.
+About registering and disconnecting the card, see the subsections
below.
@@ -724,9 +695,7 @@ Full Code Example
-----------------
In this section, we'll complete the chip-specific constructor,
-destructor and PCI entries. Example code is shown first, below.
-
-::
+destructor and PCI entries. Example code is shown first, below::
struct mychip {
struct snd_card *card;
@@ -866,9 +835,7 @@ resources. Also, you need to set the proper PCI DMA mask to limit the
accessed I/O range. In some cases, you might need to call
:c:func:`pci_set_master()` function, too.
-Suppose the 28bit mask, and the code to be added would be like:
-
-::
+Suppose a 28bit mask, the code to be added would look like::
err = pci_enable_device(pci);
if (err < 0)
@@ -890,9 +857,7 @@ function (see below).
Now assume that the PCI device has an I/O port with 8 bytes and an
interrupt. Then struct mychip will have the
-following fields:
-
-::
+following fields::
struct mychip {
struct snd_card *card;
@@ -905,14 +870,12 @@ following fields:
For an I/O port (and also a memory region), you need to have the
resource pointer for the standard resource management. For an irq, you
have to keep only the irq number (integer). But you need to initialize
-this number as -1 before actual allocation, since irq 0 is valid. The
+this number to -1 before actual allocation, since irq 0 is valid. The
port address and its resource pointer can be initialized as null by
:c:func:`kzalloc()` automatically, so you don't have to take care of
resetting them.
-The allocation of an I/O port is done like this:
-
-::
+The allocation of an I/O port is done like this::
err = pci_request_regions(pci, "My Chip");
if (err < 0) {
@@ -928,9 +891,7 @@ The returned value, ``chip->res_port``, is allocated via
must be released via :c:func:`kfree()`, but there is a problem with
this. This issue will be explained later.
-The allocation of an interrupt source is done like this:
-
-::
+The allocation of an interrupt source is done like this::
if (request_irq(pci->irq, snd_mychip_interrupt,
IRQF_SHARED, KBUILD_MODNAME, chip)) {
@@ -954,9 +915,7 @@ used for that, but you can use what you like, too.
I won't give details about the interrupt handler at this point, but at
least its appearance can be explained now. The interrupt handler looks
-usually like the following:
-
-::
+usually as follows::
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
{
@@ -966,13 +925,12 @@ usually like the following:
}
After requesting the IRQ, you can passed it to ``card->sync_irq``
-field:
-::
+field::
card->irq = chip->irq;
-This allows PCM core automatically performing
-:c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
+This allows the PCM core to automatically call
+:c:func:`synchronize_irq()` at the right time, like before ``hw_free``.
See the later section `sync_stop callback`_ for details.
Now let's write the corresponding destructor for the resources above.
@@ -981,9 +939,7 @@ activated) and release the resources. So far, we have no hardware part,
so the disabling code is not written here.
To release the resources, the “check-and-release” method is a safer way.
-For the interrupt, do like this:
-
-::
+For the interrupt, do like this::
if (chip->irq >= 0)
free_irq(chip->irq, chip);
@@ -997,9 +953,7 @@ When you requested I/O ports or memory regions via
:c:func:`pci_request_regions()` like in this example, release the
resource(s) using the corresponding function,
:c:func:`pci_release_region()` or
-:c:func:`pci_release_regions()`.
-
-::
+:c:func:`pci_release_regions()`::
pci_release_regions(chip->pci);
@@ -1007,39 +961,32 @@ When you requested manually via :c:func:`request_region()` or
:c:func:`request_mem_region()`, you can release it via
:c:func:`release_resource()`. Suppose that you keep the resource
pointer returned from :c:func:`request_region()` in
-chip->res_port, the release procedure looks like:
-
-::
+chip->res_port, the release procedure looks like::
release_and_free_resource(chip->res_port);
Don't forget to call :c:func:`pci_disable_device()` before the
end.
-And finally, release the chip-specific record.
-
-::
+And finally, release the chip-specific record::
kfree(chip);
-We didn't implement the hardware disabling part in the above. If you
+We didn't implement the hardware disabling part above. If you
need to do this, please note that the destructor may be called even
before the initialization of the chip is completed. It would be better
to have a flag to skip hardware disabling if the hardware was not
initialized yet.
When the chip-data is assigned to the card using
-:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
-destructor is called at the last. That is, it is assured that all other
+:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL``, its
+destructor is called last. That is, it is assured that all other
components like PCMs and controls have already been released. You don't
have to stop PCMs, etc. explicitly, but just call low-level hardware
stopping.
The management of a memory-mapped region is almost as same as the
-management of an I/O port. You'll need three fields like the
-following:
-
-::
+management of an I/O port. You'll need two fields as follows::
struct mychip {
....
@@ -1047,9 +994,7 @@ following:
void __iomem *iobase_virt;
};
-and the allocation would be like below:
-
-::
+and the allocation would look like below::
err = pci_request_regions(pci, "My Chip");
if (err < 0) {
@@ -1060,9 +1005,7 @@ and the allocation would be like below:
chip->iobase_virt = ioremap(chip->iobase_phys,
pci_resource_len(pci, 0));
-and the corresponding destructor would be:
-
-::
+and the corresponding destructor would be::
static int snd_mychip_free(struct mychip *chip)
{
@@ -1075,9 +1018,7 @@ and the corresponding destructor would be:
}
Of course, a modern way with :c:func:`pci_iomap()` will make things a
-bit easier, too.
-
-::
+bit easier, too::
err = pci_request_regions(pci, "My Chip");
if (err < 0) {
@@ -1097,9 +1038,7 @@ struct pci_device_id table for
this chipset. It's a table of PCI vendor/device ID number, and some
masks.
-For example,
-
-::
+For example::
static struct pci_device_id snd_mychip_ids[] = {
{ PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
@@ -1120,9 +1059,7 @@ The last entry of this list is the terminator. You must specify this
all-zero entry.
Then, prepare the struct pci_driver
-record:
-
-::
+record::
static struct pci_driver driver = {
.name = KBUILD_MODNAME,
@@ -1133,11 +1070,9 @@ record:
The ``probe`` and ``remove`` functions have already been defined in
the previous sections. The ``name`` field is the name string of this
-device. Note that you must not use a slash “/” in this string.
-
-And at last, the module entries:
+device. Note that you must not use slashes (“/”) in this string.
-::
+And at last, the module entries::
static int __init alsa_card_mychip_init(void)
{
@@ -1167,22 +1102,22 @@ The PCM middle layer of ALSA is quite powerful and it is only necessary
for each driver to implement the low-level functions to access its
hardware.
-For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
+To access the PCM layer, you need to include ``<sound/pcm.h>``
first. In addition, ``<sound/pcm_params.h>`` might be needed if you
-access to some functions related with hw_param.
+access some functions related with hw_param.
-Each card device can have up to four pcm instances. A pcm instance
-corresponds to a pcm device file. The limitation of number of instances
-comes only from the available bit size of the Linux's device numbers.
-Once when 64bit device number is used, we'll have more pcm instances
+Each card device can have up to four PCM instances. A PCM instance
+corresponds to a PCM device file. The limitation of number of instances
+comes only from the available bit size of Linux' device numbers.
+Once 64bit device numbers are used, we'll have more PCM instances
available.
-A pcm instance consists of pcm playback and capture streams, and each
-pcm stream consists of one or more pcm substreams. Some soundcards
+A PCM instance consists of PCM playback and capture streams, and each
+PCM stream consists of one or more PCM substreams. Some soundcards
support multiple playback functions. For example, emu10k1 has a PCM
playback of 32 stereo substreams. In this case, at each open, a free
substream is (usually) automatically chosen and opened. Meanwhile, when
-only one substream exists and it was already opened, the successful open
+only one substream exists and it was already opened, a subsequent open
will either block or error with ``EAGAIN`` according to the file open
mode. But you don't have to care about such details in your driver. The
PCM middle layer will take care of such work.
@@ -1191,9 +1126,7 @@ Full Code Example
-----------------
The example code below does not include any hardware access routines but
-shows only the skeleton, how to build up the PCM interfaces.
-
-::
+shows only the skeleton, how to build up the PCM interfaces::
#include <sound/pcm.h>
....
@@ -1399,10 +1332,8 @@ shows only the skeleton, how to build up the PCM interfaces.
PCM Constructor
---------------
-A pcm instance is allocated by the :c:func:`snd_pcm_new()`
-function. It would be better to create a constructor for pcm, namely,
-
-::
+A PCM instance is allocated by the :c:func:`snd_pcm_new()`
+function. It would be better to create a constructor for the PCM, namely::
static int snd_mychip_new_pcm(struct mychip *chip)
{
@@ -1415,16 +1346,16 @@ function. It would be better to create a constructor for pcm, namely,
pcm->private_data = chip;
strcpy(pcm->name, "My Chip");
chip->pcm = pcm;
- ....
+ ...
return 0;
}
-The :c:func:`snd_pcm_new()` function takes four arguments. The
-first argument is the card pointer to which this pcm is assigned, and
+The :c:func:`snd_pcm_new()` function takes six arguments. The
+first argument is the card pointer to which this PCM is assigned, and
the second is the ID string.
The third argument (``index``, 0 in the above) is the index of this new
-pcm. It begins from zero. If you create more than one pcm instances,
+PCM. It begins from zero. If you create more than one PCM instances,
specify the different numbers in this argument. For example, ``index =
1`` for the second PCM device.
@@ -1437,26 +1368,20 @@ If a chip supports multiple playbacks or captures, you can specify more
numbers, but they must be handled properly in open/close, etc.
callbacks. When you need to know which substream you are referring to,
then it can be obtained from struct snd_pcm_substream data passed to each
-callback as follows:
-
-::
+callback as follows::
struct snd_pcm_substream *substream;
int index = substream->number;
-After the pcm is created, you need to set operators for each pcm stream.
-
-::
+After the PCM is created, you need to set operators for each PCM stream::
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
&snd_mychip_playback_ops);
snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
&snd_mychip_capture_ops);
-The operators are defined typically like this:
-
-::
+The operators are defined typically like this::
static struct snd_pcm_ops snd_mychip_playback_ops = {
.open = snd_mychip_pcm_open,
@@ -1472,25 +1397,21 @@ All the callbacks are described in the Operators_ subsection.
After setting the operators, you probably will want to pre-allocate the
buffer and set up the managed allocation mode.
-For that, simply call the following:
-
-::
+For that, simply call the following::
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
&chip->pci->dev,
64*1024, 64*1024);
-It will allocate a buffer up to 64kB as default. Buffer management
+It will allocate a buffer up to 64kB by default. Buffer management
details will be described in the later section `Buffer and Memory
Management`_.
-Additionally, you can set some extra information for this pcm in
+Additionally, you can set some extra information for this PCM in
``pcm->info_flags``. The available values are defined as
``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
hardware definition (described later). When your soundchip supports only
-half-duplex, specify like this:
-
-::
+half-duplex, specify it like this::
pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
@@ -1498,15 +1419,13 @@ half-duplex, specify like this:
... And the Destructor?
-----------------------
-The destructor for a pcm instance is not always necessary. Since the pcm
+The destructor for a PCM instance is not always necessary. Since the PCM
device will be released by the middle layer code automatically, you
don't have to call the destructor explicitly.
The destructor would be necessary if you created special records
internally and needed to release them. In such a case, set the
-destructor function to ``pcm->private_free``:
-
-::
+destructor function to ``pcm->private_free``::
static void mychip_pcm_free(struct snd_pcm *pcm)
{
@@ -1537,13 +1456,11 @@ Runtime Pointer - The Chest of PCM Information
When the PCM substream is opened, a PCM runtime instance is allocated
and assigned to the substream. This pointer is accessible via
``substream->runtime``. This runtime pointer holds most information you
-need to control the PCM: the copy of hw_params and sw_params
+need to control the PCM: a copy of hw_params and sw_params
configurations, the buffer pointers, mmap records, spinlocks, etc.
The definition of runtime instance is found in ``<sound/pcm.h>``. Here
-are the contents of this file:
-
-::
+is the relevant part of this file::
struct _snd_pcm_runtime {
/* -- Status -- */
@@ -1577,14 +1494,19 @@ are the contents of this file:
unsigned int period_step;
unsigned int sleep_min; /* min ticks to sleep */
snd_pcm_uframes_t start_threshold;
- snd_pcm_uframes_t stop_threshold;
- snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
- noise is nearest than this */
- snd_pcm_uframes_t silence_size; /* Silence filling size */
+ /*
+ * The following two thresholds alleviate playback buffer underruns; when
+ * hw_avail drops below the threshold, the respective action is triggered:
+ */
+ snd_pcm_uframes_t stop_threshold; /* - stop playback */
+ snd_pcm_uframes_t silence_threshold; /* - pre-fill buffer with silence */
+ snd_pcm_uframes_t silence_size; /* max size of silence pre-fill; when >= boundary,
+ * fill played area with silence immediately */
snd_pcm_uframes_t boundary; /* pointers wrap point */
- snd_pcm_uframes_t silenced_start;
- snd_pcm_uframes_t silenced_size;
+ /* internal data of auto-silencer */
+ snd_pcm_uframes_t silence_start; /* starting pointer to silence area */
+ snd_pcm_uframes_t silence_filled; /* size filled with silence */
snd_pcm_sync_id_t sync; /* hardware synchronization ID */
@@ -1638,14 +1560,12 @@ Hardware Description
The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
the fundamental hardware configuration. Above all, you'll need to define this
-in the `PCM open callback`_. Note that the runtime instance holds the copy of
-the descriptor, not the pointer to the existing descriptor. That is,
+in the `PCM open callback`_. Note that the runtime instance holds a copy of
+the descriptor, not a pointer to the existing descriptor. That is,
in the open callback, you can modify the copied descriptor
(``runtime->hw``) as you need. For example, if the maximum number of
channels is 1 only on some chip models, you can still use the same
-hardware descriptor and change the channels_max later:
-
-::
+hardware descriptor and change the channels_max later::
struct snd_pcm_runtime *runtime = substream->runtime;
...
@@ -1653,9 +1573,7 @@ hardware descriptor and change the channels_max later:
if (chip->model == VERY_OLD_ONE)
runtime->hw.channels_max = 1;
-Typically, you'll have a hardware descriptor as below:
-
-::
+Typically, you'll have a hardware descriptor as below::
static struct snd_pcm_hardware snd_mychip_playback_hw = {
.info = (SNDRV_PCM_INFO_MMAP |
@@ -1676,51 +1594,51 @@ Typically, you'll have a hardware descriptor as below:
};
- The ``info`` field contains the type and capabilities of this
- pcm. The bit flags are defined in ``<sound/asound.h>`` as
+ PCM. The bit flags are defined in ``<sound/asound.h>`` as
``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
- the mmap is supported and which interleaved format is
+ mmap is supported and which interleaving formats are
supported. When the hardware supports mmap, add the
``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
- interleaved or the non-interleaved formats,
+ interleaved or the non-interleaved formats, the
``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
flag must be set, respectively. If both are supported, you can set
both, too.
In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
specified for the OSS mmap mode. Usually both are set. Of course,
- ``MMAP_VALID`` is set only if the mmap is really supported.
+ ``MMAP_VALID`` is set only if mmap is really supported.
The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
- ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
+ ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the PCM
supports the “pause” operation, while the ``RESUME`` bit means that
- the pcm supports the full “suspend/resume” operation. If the
+ the PCM supports the full “suspend/resume” operation. If the
``PAUSE`` flag is set, the ``trigger`` callback below must handle
the corresponding (pause push/release) commands. The suspend/resume
trigger commands can be defined even without the ``RESUME``
- flag. See `Power Management`_ section for details.
+ flag. See the `Power Management`_ section for details.
When the PCM substreams can be synchronized (typically,
- synchronized start/stop of a playback and a capture streams), you
+ synchronized start/stop of a playback and a capture stream), you
can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
need to check the linked-list of PCM substreams in the trigger
- callback. This will be described in the later section.
+ callback. This will be described in a later section.
-- ``formats`` field contains the bit-flags of supported formats
+- The ``formats`` field contains the bit-flags of supported formats
(``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
format, give all or'ed bits. In the example above, the signed 16bit
little-endian format is specified.
-- ``rates`` field contains the bit-flags of supported rates
+- The ``rates`` field contains the bit-flags of supported rates
(``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
- pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
- provided only for typical rates. If your chip supports
+ pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits
+ are provided only for typical rates. If your chip supports
unconventional rates, you need to add the ``KNOT`` bit and set up
the hardware constraint manually (explained later).
- ``rate_min`` and ``rate_max`` define the minimum and maximum sample
rate. This should correspond somehow to ``rates`` bits.
-- ``channels_min`` and ``channels_max`` define, as you might already
+- ``channels_min`` and ``channels_max`` define, as you might have already
expected, the minimum and maximum number of channels.
- ``buffer_bytes_max`` defines the maximum buffer size in
@@ -1732,15 +1650,16 @@ Typically, you'll have a hardware descriptor as below:
number of periods in the buffer.
The “period” is a term that corresponds to a fragment in the OSS
- world. The period defines the size at which a PCM interrupt is
- generated. This size strongly depends on the hardware. Generally,
- the smaller period size will give you more interrupts, that is,
- more controls. In the case of capture, this size defines the input
- latency. On the other hand, the whole buffer size defines the
- output latency for the playback direction.
+ world. The period defines the point at which a PCM interrupt is
+ generated. This point strongly depends on the hardware. Generally,
+ a smaller period size will give you more interrupts, which results
+ in being able to fill/drain the buffer more timely. In the case of
+ capture, this size defines the input latency. On the other hand,
+ the whole buffer size defines the output latency for the playback
+ direction.
- There is also a field ``fifo_size``. This specifies the size of the
- hardware FIFO, but currently it is neither used in the driver nor
+ hardware FIFO, but currently it is neither used by the drivers nor
in the alsa-lib. So, you can ignore this field.
PCM Configurations
@@ -1759,34 +1678,32 @@ One thing to be noted is that the configured buffer and period sizes
are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
channels \* samples-size``. For conversion between frames and bytes,
you can use the :c:func:`frames_to_bytes()` and
-:c:func:`bytes_to_frames()` helper functions.
-
-::
+:c:func:`bytes_to_frames()` helper functions::
period_bytes = frames_to_bytes(runtime, runtime->period_size);
Also, many software parameters (sw_params) are stored in frames, too.
-Please check the type of the field. ``snd_pcm_uframes_t`` is for the
-frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
+Please check the type of the field. ``snd_pcm_uframes_t`` is for
+frames as unsigned integer while ``snd_pcm_sframes_t`` is for
frames as signed integer.
DMA Buffer Information
~~~~~~~~~~~~~~~~~~~~~~
-The DMA buffer is defined by the following four fields, ``dma_area``,
-``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
+The DMA buffer is defined by the following four fields: ``dma_area``,
+``dma_addr``, ``dma_bytes`` and ``dma_private``. ``dma_area``
holds the buffer pointer (the logical address). You can call
:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
the physical address of the buffer. This field is specified only when
-the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
-in bytes. ``dma_private`` is used for the ALSA DMA allocator.
+the buffer is a linear buffer. ``dma_bytes`` holds the size of the
+buffer in bytes. ``dma_private`` is used for the ALSA DMA allocator.
If you use either the managed buffer allocation mode or the standard
API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
these fields are set by the ALSA middle layer, and you should *not*
change them by yourself. You can read them but not write them. On the
other hand, if you want to allocate the buffer by yourself, you'll
-need to manage it in hw_params callback. At least, ``dma_bytes`` is
+need to manage it in the hw_params callback. At least, ``dma_bytes`` is
mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
your driver doesn't support mmap, this field is not
necessary. ``dma_addr`` is also optional. You can use dma_private as
@@ -1796,13 +1713,13 @@ Running Status
~~~~~~~~~~~~~~
The running status can be referred via ``runtime->status``. This is
-the pointer to the struct snd_pcm_mmap_status record.
+a pointer to a struct snd_pcm_mmap_status record.
For example, you can get the current
DMA hardware pointer via ``runtime->status->hw_ptr``.
The DMA application pointer can be referred via ``runtime->control``,
-which points to the struct snd_pcm_mmap_control record.
-However, accessing directly to this value is not recommended.
+which points to a struct snd_pcm_mmap_control record.
+However, accessing this value directly is not recommended.
Private Data
~~~~~~~~~~~~
@@ -1811,11 +1728,10 @@ You can allocate a record for the substream and store it in
``runtime->private_data``. Usually, this is done in the `PCM open
callback`_. Don't mix this with ``pcm->private_data``. The
``pcm->private_data`` usually points to the chip instance assigned
-statically at the creation of PCM, while the ``runtime->private_data``
-points to a dynamic data structure created at the PCM open
-callback.
-
-::
+statically at creation time of the PCM device, while
+``runtime->private_data``
+points to a dynamic data structure created in the PCM open
+callback::
static int snd_xxx_open(struct snd_pcm_substream *substream)
{
@@ -1832,20 +1748,18 @@ The allocated object must be released in the `close callback`_.
Operators
---------
-OK, now let me give details about each pcm callback (``ops``). In
+OK, now let me give details about each PCM callback (``ops``). In
general, every callback must return 0 if successful, or a negative
error number such as ``-EINVAL``. To choose an appropriate error
number, it is advised to check what value other parts of the kernel
return when the same kind of request fails.
-The callback function takes at least the argument with
+Each callback function takes at least one argument containing a
struct snd_pcm_substream pointer. To retrieve the chip
record from the given substream instance, you can use the following
-macro.
-
-::
+macro::
- int xxx() {
+ int xxx(...) {
struct mychip *chip = snd_pcm_substream_chip(substream);
....
}
@@ -1864,12 +1778,10 @@ PCM open callback
static int snd_xxx_open(struct snd_pcm_substream *substream);
-This is called when a pcm substream is opened.
+This is called when a PCM substream is opened.
At least, here you have to initialize the ``runtime->hw``
-record. Typically, this is done by like this:
-
-::
+record. Typically, this is done like this::
static int snd_xxx_open(struct snd_pcm_substream *substream)
{
@@ -1883,7 +1795,7 @@ record. Typically, this is done by like this:
where ``snd_mychip_playback_hw`` is the pre-defined hardware
description.
-You can allocate a private data in this callback, as described in
+You can allocate private data in this callback, as described in the
`Private Data`_ section.
If the hardware configuration needs more constraints, set the hardware
@@ -1897,12 +1809,10 @@ close callback
static int snd_xxx_close(struct snd_pcm_substream *substream);
-Obviously, this is called when a pcm substream is closed.
-
-Any private instance for a pcm substream allocated in the ``open``
-callback will be released here.
+Obviously, this is called when a PCM substream is closed.
-::
+Any private instance for a PCM substream allocated in the ``open``
+callback will be released here::
static int snd_xxx_close(struct snd_pcm_substream *substream)
{
@@ -1914,9 +1824,9 @@ callback will be released here.
ioctl callback
~~~~~~~~~~~~~~
-This is used for any special call to pcm ioctls. But usually you can
-leave it as NULL, then PCM core calls the generic ioctl callback
-function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with the
+This is used for any special call to PCM ioctls. But usually you can
+leave it NULL, then the PCM core calls the generic ioctl callback
+function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with a
unique setup of channel info or reset procedure, you can pass your own
callback function here.
@@ -1928,22 +1838,20 @@ hw_params callback
static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
struct snd_pcm_hw_params *hw_params);
-This is called when the hardware parameter (``hw_params``) is set up
+This is called when the hardware parameters (``hw_params``) are set up
by the application, that is, once when the buffer size, the period
-size, the format, etc. are defined for the pcm substream.
+size, the format, etc. are defined for the PCM substream.
Many hardware setups should be done in this callback, including the
allocation of buffers.
-Parameters to be initialized are retrieved by
+Parameters to be initialized are retrieved by the
:c:func:`params_xxx()` macros.
-When you set up the managed buffer allocation mode for the substream,
+When you choose managed buffer allocation mode for the substream,
a buffer is already allocated before this callback gets
called. Alternatively, you can call a helper function below for
-allocating the buffer, too.
-
-::
+allocating the buffer::
snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
@@ -1951,8 +1859,8 @@ allocating the buffer, too.
DMA buffers have been pre-allocated. See the section `Buffer Types`_
for more details.
-Note that this and ``prepare`` callbacks may be called multiple times
-per initialization. For example, the OSS emulation may call these
+Note that this one and the ``prepare`` callback may be called multiple
+times per initialization. For example, the OSS emulation may call these
callbacks at each change via its ioctl.
Thus, you need to be careful not to allocate the same buffers many
@@ -1960,10 +1868,10 @@ times, which will lead to memory leaks! Calling the helper function
above many times is OK. It will release the previous buffer
automatically when it was already allocated.
-Another note is that this callback is non-atomic (schedulable) as
+Another note is that this callback is non-atomic (schedulable) by
default, i.e. when no ``nonatomic`` flag set. This is important,
because the ``trigger`` callback is atomic (non-schedulable). That is,
-mutexes or any schedule-related functions are not available in
+mutexes or any schedule-related functions are not available in the
``trigger`` callback. Please see the subsection Atomicity_ for
details.
@@ -1979,16 +1887,14 @@ This is called to release the resources allocated via
This function is always called before the close callback is called.
Also, the callback may be called multiple times, too. Keep track
-whether the resource was already released.
+whether each resource was already released.
-When you have set up the managed buffer allocation mode for the PCM
+When you have chosen managed buffer allocation mode for the PCM
substream, the allocated PCM buffer will be automatically released
after this callback gets called. Otherwise you'll have to release the
buffer manually. Typically, when the buffer was allocated from the
pre-allocated pool, you can use the standard API function
-:c:func:`snd_pcm_lib_malloc_pages()` like:
-
-::
+:c:func:`snd_pcm_lib_malloc_pages()` like::
snd_pcm_lib_free_pages(substream);
@@ -1999,13 +1905,13 @@ prepare callback
static int snd_xxx_prepare(struct snd_pcm_substream *substream);
-This callback is called when the pcm is “prepared”. You can set the
+This callback is called when the PCM is “prepared”. You can set the
format type, sample rate, etc. here. The difference from ``hw_params``
is that the ``prepare`` callback will be called each time
:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
underruns, etc.
-Note that this callback is now non-atomic. You can use
+Note that this callback is non-atomic. You can use
schedule-related functions safely in this callback.
In this and the following callbacks, you can refer to the values via
@@ -2026,13 +1932,11 @@ trigger callback
static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
-This is called when the pcm is started, stopped or paused.
-
-Which action is specified in the second argument,
-``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
-and ``STOP`` commands must be defined in this callback.
+This is called when the PCM is started, stopped or paused.
-::
+The action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX``
+defined in ``<sound/pcm.h>``. At least, the ``START``
+and ``STOP`` commands must be defined in this callback::
switch (cmd) {
case SNDRV_PCM_TRIGGER_START:
@@ -2045,23 +1949,23 @@ and ``STOP`` commands must be defined in this callback.
return -EINVAL;
}
-When the pcm supports the pause operation (given in the info field of
+When the PCM supports the pause operation (given in the info field of
the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
-must be handled here, too. The former is the command to pause the pcm,
-and the latter to restart the pcm again.
+must be handled here, too. The former is the command to pause the PCM,
+and the latter to restart the PCM again.
-When the pcm supports the suspend/resume operation, regardless of full
+When the PCM supports the suspend/resume operation, regardless of full
or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
commands must be handled, too. These commands are issued when the
power-management status is changed. Obviously, the ``SUSPEND`` and
-``RESUME`` commands suspend and resume the pcm substream, and usually,
+``RESUME`` commands suspend and resume the PCM substream, and usually,
they are identical to the ``STOP`` and ``START`` commands, respectively.
See the `Power Management`_ section for details.
-As mentioned, this callback is atomic as default unless ``nonatomic``
+As mentioned, this callback is atomic by default unless the ``nonatomic``
flag set, and you cannot call functions which may sleep. The
``trigger`` callback should be as minimal as possible, just really
-triggering the DMA. The other stuff should be initialized
+triggering the DMA. The other stuff should be initialized in
``hw_params`` and ``prepare`` callbacks properly beforehand.
sync_stop callback
@@ -2072,22 +1976,22 @@ sync_stop callback
static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
This callback is optional, and NULL can be passed. It's called after
-the PCM core stops the stream and changes the stream state
+the PCM core stops the stream, before it changes the stream state via
``prepare``, ``hw_params`` or ``hw_free``.
Since the IRQ handler might be still pending, we need to wait until
the pending task finishes before moving to the next step; otherwise it
-might lead to a crash due to resource conflicts or access to the freed
+might lead to a crash due to resource conflicts or access to freed
resources. A typical behavior is to call a synchronization function
like :c:func:`synchronize_irq()` here.
-For majority of drivers that need only a call of
+For the majority of drivers that need only a call of
:c:func:`synchronize_irq()`, there is a simpler setup, too.
-While keeping NULL to ``sync_stop`` PCM callback, the driver can set
-``card->sync_irq`` field to store the valid interrupt number after
-requesting an IRQ, instead. Then PCM core will look call
+While keeping the ``sync_stop`` PCM callback NULL, the driver can set
+the ``card->sync_irq`` field to the returned interrupt number after
+requesting an IRQ, instead. Then PCM core will call
:c:func:`synchronize_irq()` with the given IRQ appropriately.
-If the IRQ handler is released at the card destructor, you don't need
+If the IRQ handler is released by the card destructor, you don't need
to clear ``card->sync_irq``, as the card itself is being released.
So, usually you'll need to add just a single line for assigning
``card->sync_irq`` in the driver code unless the driver re-acquires
@@ -2103,30 +2007,30 @@ pointer callback
static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
This callback is called when the PCM middle layer inquires the current
-hardware position on the buffer. The position must be returned in
+hardware position in the buffer. The position must be returned in
frames, ranging from 0 to ``buffer_size - 1``.
-This is called usually from the buffer-update routine in the pcm
+This is usually called from the buffer-update routine in the PCM
middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
-is called in the interrupt routine. Then the pcm middle layer updates
+is called by the interrupt routine. Then the PCM middle layer updates
the position and calculates the available space, and wakes up the
sleeping poll threads, etc.
-This callback is also atomic as default.
+This callback is also atomic by default.
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
-normal memory space. Some chips have their own buffer on the hardware
+normal memory space. Some chips have their own buffer in the hardware
which is not mappable. In such a case, you have to transfer the data
manually from the memory buffer to the hardware buffer. Or, if the
buffer is non-contiguous on both physical and virtual memory spaces,
these callbacks must be defined, too.
If these two callbacks are defined, copy and set-silence operations
-are done by them. The detailed will be described in the later section
+are done by them. The details will be described in the later section
`Buffer and Memory Management`_.
ack callback
@@ -2137,7 +2041,11 @@ This callback is also not mandatory. This callback is called when the
emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
internal buffer, and this callback is useful only for such a purpose.
-This callback is atomic as default.
+The callback function may return 0 or a negative error. When the
+return value is ``-EPIPE``, PCM core treats that as a buffer XRUN,
+and changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically.
+
+This callback is atomic by default.
page callback
~~~~~~~~~~~~~
@@ -2145,16 +2053,15 @@ page callback
This callback is optional too. The mmap calls this callback to get the
page fault address.
-Since the recent changes, you need no special callback any longer for
-the standard SG-buffer or vmalloc-buffer. Hence this callback should
-be rarely used.
+You need no special callback for the standard SG-buffer or vmalloc-
+buffer. Hence this callback should be rarely used.
-mmap calllback
-~~~~~~~~~~~~~~
+mmap callback
+~~~~~~~~~~~~~
This is another optional callback for controlling mmap behavior.
-Once when defined, PCM core calls this callback when a page is
-memory-mapped instead of dealing via the standard helper.
+When defined, the PCM core calls this callback when a page is
+memory-mapped, instead of using the standard helper.
If you need special handling (due to some architecture or
device-specific issues), implement everything here as you like.
@@ -2162,13 +2069,14 @@ device-specific issues), implement everything here as you like.
PCM Interrupt Handler
---------------------
-The rest of pcm stuff is the PCM interrupt handler. The role of PCM
+The remainder of the PCM stuff is the PCM interrupt handler. The role
+of the PCM
interrupt handler in the sound driver is to update the buffer position
and to tell the PCM middle layer when the buffer position goes across
-the prescribed period size. To inform this, call the
+the specified period boundary. To inform about this, call the
:c:func:`snd_pcm_period_elapsed()` function.
-There are several types of sound chips to generate the interrupts.
+There are several ways sound chips can generate interrupts.
Interrupts at the period (fragment) boundary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2184,14 +2092,12 @@ chip record to hold the current running substream pointer, and set the
pointer value at ``open`` callback (and reset at ``close`` callback).
If you acquire a spinlock in the interrupt handler, and the lock is used
-in other pcm callbacks, too, then you have to release the lock before
+in other PCM callbacks, too, then you have to release the lock before
calling :c:func:`snd_pcm_period_elapsed()`, because
-:c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
+:c:func:`snd_pcm_period_elapsed()` calls other PCM callbacks
inside.
-Typical code would be like:
-
-::
+Typical code would look like::
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
@@ -2211,6 +2117,12 @@ Typical code would be like:
return IRQ_HANDLED;
}
+Also, when the device can detect a buffer underrun/overrun, the driver
+can notify the XRUN status to the PCM core by calling
+:c:func:`snd_pcm_stop_xrun()`. This function stops the stream and sets
+the PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called
+outside the PCM stream lock, hence it can't be called from the atomic
+callback.
High frequency timer interrupts
@@ -2223,9 +2135,7 @@ position and accumulate the processed sample length at each interrupt.
When the accumulated size exceeds the period size, call
:c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
-Typical code would be like the following.
-
-::
+Typical code would look as follows::
static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
@@ -2270,9 +2180,9 @@ Typical code would be like the following.
On calling :c:func:`snd_pcm_period_elapsed()`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In both cases, even if more than one period are elapsed, you don't have
+In both cases, even if more than one period has elapsed, you don't have
to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
-once. And the pcm layer will check the current hardware pointer and
+once. And the PCM layer will check the current hardware pointer and
update to the latest status.
Atomicity
@@ -2283,15 +2193,16 @@ kernel programming are race conditions. In the Linux kernel, they are
usually avoided via spin-locks, mutexes or semaphores. In general, if a
race condition can happen in an interrupt handler, it has to be managed
atomically, and you have to use a spinlock to protect the critical
-session. If the critical section is not in interrupt handler code and if
+section. If the critical section is not in interrupt handler code and if
taking a relatively long time to execute is acceptable, you should use
mutexes or semaphores instead.
-As already seen, some pcm callbacks are atomic and some are not. For
-example, the ``hw_params`` callback is non-atomic, while ``trigger``
+As already seen, some PCM callbacks are atomic and some are not. For
+example, the ``hw_params`` callback is non-atomic, while the ``trigger``
callback is atomic. This means, the latter is called already in a
-spinlock held by the PCM middle layer. Please take this atomicity into
-account when you choose a locking scheme in the callbacks.
+spinlock held by the PCM middle layer, the PCM stream lock. Please
+take this atomicity into account when you choose a locking scheme in
+the callbacks.
In the atomic callbacks, you cannot use functions which may call
:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
@@ -2302,29 +2213,34 @@ callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
All three atomic callbacks (trigger, pointer, and ack) are called with
local interrupts disabled.
-The recent changes in PCM core code, however, allow all PCM operations
-to be non-atomic. This assumes that the all caller sides are in
+However, it is possible to request all PCM operations to be non-atomic.
+This assumes that all call sites are in
non-atomic contexts. For example, the function
:c:func:`snd_pcm_period_elapsed()` is called typically from the
interrupt handler. But, if you set up the driver to use a threaded
interrupt handler, this call can be in non-atomic context, too. In such
-a case, you can set ``nonatomic`` filed of struct snd_pcm object
+a case, you can set the ``nonatomic`` field of the struct snd_pcm object
after creating it. When this flag is set, mutex and rwsem are used internally
in the PCM core instead of spin and rwlocks, so that you can call all PCM
functions safely in a non-atomic
context.
+Also, in some cases, you might need to call
+:c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the
+period gets elapsed during ``ack`` or other callback). There is a
+variant that can be called inside the PCM stream lock
+:c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose,
+too.
+
Constraints
-----------
-If your chip supports unconventional sample rates, or only the limited
-samples, you need to set a constraint for the condition.
+Due to physical limitations, hardware is not infinitely configurable.
+These limitations are expressed by setting constraints.
-For example, in order to restrict the sample rates in the some supported
+For example, in order to restrict the sample rates to some supported
values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
-call this function in the open callback.
-
-::
+call this function in the open callback::
static unsigned int rates[] =
{4000, 10000, 22050, 44100};
@@ -2346,16 +2262,12 @@ call this function in the open callback.
....
}
-
-
There are many different constraints. Look at ``sound/pcm.h`` for a
complete list. You can even define your own constraint rules. For
example, let's suppose my_chip can manage a substream of 1 channel if
and only if the format is ``S16_LE``, otherwise it supports any format
-specified in struct snd_pcm_hardware> (or in any other
-constraint_list). You can build a rule like this:
-
-::
+specified in struct snd_pcm_hardware (or in any other
+constraint_list). You can build a rule like this::
static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
struct snd_pcm_hw_rule *rule)
@@ -2375,9 +2287,7 @@ constraint_list). You can build a rule like this:
}
-Then you need to call this function to add your rule:
-
-::
+Then you need to call this function to add your rule::
snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
hw_rule_channels_by_format, NULL,
@@ -2386,9 +2296,7 @@ Then you need to call this function to add your rule:
The rule function is called when an application sets the PCM format, and
it refines the number of channels accordingly. But an application may
set the number of channels before setting the format. Thus you also need
-to define the inverse rule:
-
-::
+to define the inverse rule::
static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
struct snd_pcm_hw_rule *rule)
@@ -2407,16 +2315,14 @@ to define the inverse rule:
}
-... and in the open callback:
-
-::
+... and in the open callback::
snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
hw_rule_format_by_channels, NULL,
SNDRV_PCM_HW_PARAM_CHANNELS, -1);
One typical usage of the hw constraints is to align the buffer size
-with the period size. As default, ALSA PCM core doesn't enforce the
+with the period size. By default, ALSA PCM core doesn't enforce the
buffer size to be aligned with the period size. For example, it'd be
possible to have a combination like 256 period bytes with 999 buffer
bytes.
@@ -2424,9 +2330,7 @@ bytes.
Many device chips, however, require the buffer to be a multiple of
periods. In such a case, call
:c:func:`snd_pcm_hw_constraint_integer()` for
-``SNDRV_PCM_HW_PARAM_PERIODS``.
-
-::
+``SNDRV_PCM_HW_PARAM_PERIODS``::
snd_pcm_hw_constraint_integer(substream->runtime,
SNDRV_PCM_HW_PARAM_PERIODS);
@@ -2434,7 +2338,7 @@ periods. In such a case, call
This assures that the number of periods is integer, hence the buffer
size is aligned with the period size.
-The hw constraint is a very much powerful mechanism to define the
+The hw constraint is a very powerful mechanism to define the
preferred PCM configuration, and there are relevant helpers.
I won't give more details here, rather I would like to say, “Luke, use
the source.”
@@ -2461,9 +2365,7 @@ Definition of Controls
To create a new control, you need to define the following three
callbacks: ``info``, ``get`` and ``put``. Then, define a
-struct snd_kcontrol_new record, such as:
-
-::
+struct snd_kcontrol_new record, such as::
static struct snd_kcontrol_new my_control = {
@@ -2506,7 +2408,7 @@ The ``private_value`` field contains an arbitrary long integer value
for this record. When using the generic ``info``, ``get`` and ``put``
callbacks, you can pass a value through this field. If several small
numbers are necessary, you can combine them in bitwise. Or, it's
-possible to give a pointer (casted to unsigned long) of some record to
+possible to store a pointer (casted to unsigned long) of some record in
this field, too.
The ``tlv`` field can be used to provide metadata about the control;
@@ -2573,7 +2475,7 @@ The access flag is the bitmask which specifies the access type of the
given control. The default access type is
``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
allowed to this control. When the access flag is omitted (i.e. = 0), it
-is considered as ``READWRITE`` access as default.
+is considered as ``READWRITE`` access by default.
When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
instead. In this case, you don't have to define the ``put`` callback.
@@ -2586,8 +2488,11 @@ If the control value changes frequently (e.g. the VU meter),
changed without `Change notification`_. Applications should poll such
a control constantly.
-When the control is inactive, set the ``INACTIVE`` flag, too. There are
-``LOCK`` and ``OWNER`` flags to change the write permissions.
+When the control may be updated, but currently has no effect on anything,
+setting the ``INACTIVE`` flag may be appropriate. For example, PCM
+controls should be inactive while no PCM device is open.
+
+There are ``LOCK`` and ``OWNER`` flags to change the write permissions.
Control Callbacks
-----------------
@@ -2598,9 +2503,7 @@ info callback
The ``info`` callback is used to get detailed information on this
control. This must store the values of the given
struct snd_ctl_elem_info object. For example,
-for a boolean control with a single element:
-
-::
+for a boolean control with a single element::
static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
@@ -2619,13 +2522,11 @@ The ``type`` field specifies the type of the control. There are
``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
``INTEGER64``. The ``count`` field specifies the number of elements in
this control. For example, a stereo volume would have count = 2. The
-``value`` field is a union, and the values stored are depending on the
+``value`` field is a union, and the values stored depend on the
type. The boolean and integer types are identical.
-The enumerated type is a bit different from others. You'll need to set
-the string for the currently given item index.
-
-::
+The enumerated type is a bit different from the others. You'll need to
+set the string for the selectec item index::
static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_info *uinfo)
@@ -2670,13 +2571,10 @@ stereo channel boolean item.
get callback
~~~~~~~~~~~~
-This callback is used to read the current value of the control and to
-return to user-space.
-
-For example,
-
-::
+This callback is used to read the current value of the control, so it
+can be returned to user-space.
+For example::
static int snd_myctl_get(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_value *ucontrol)
@@ -2691,15 +2589,11 @@ For example,
The ``value`` field depends on the type of control as well as on the
info callback. For example, the sb driver uses this field to store the
register offset, the bit-shift and the bit-mask. The ``private_value``
-field is set as follows:
-
-::
+field is set as follows::
.private_value = reg | (shift << 16) | (mask << 24)
-and is retrieved in callbacks like
-
-::
+and is retrieved in callbacks like::
static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_value *ucontrol)
@@ -2711,19 +2605,16 @@ and is retrieved in callbacks like
}
In the ``get`` callback, you have to fill all the elements if the
-control has more than one elements, i.e. ``count > 1``. In the example
+control has more than one element, i.e. ``count > 1``. In the example
above, we filled only one element (``value.integer.value[0]``) since
-it's assumed as ``count = 1``.
+``count = 1`` is assumed.
put callback
~~~~~~~~~~~~
-This callback is used to write a value from user-space.
-
-For example,
-
-::
+This callback is used to write a value coming from user-space.
+For example::
static int snd_myctl_put(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_value *ucontrol)
@@ -2746,12 +2637,12 @@ value is not changed, return 0 instead. If any fatal error happens,
return a negative error code as usual.
As in the ``get`` callback, when the control has more than one
-elements, all elements must be evaluated in this callback, too.
+element, all elements must be evaluated in this callback, too.
Callbacks are not atomic
~~~~~~~~~~~~~~~~~~~~~~~~
-All these three callbacks are basically not atomic.
+All these three callbacks are not-atomic.
Control Constructor
-------------------
@@ -2760,9 +2651,7 @@ When everything is ready, finally we can create a new control. To create
a control, there are two functions to be called,
:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
-In the simplest way, you can do like this:
-
-::
+In the simplest way, you can do it like this::
err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
if (err < 0)
@@ -2780,9 +2669,7 @@ Change Notification
-------------------
If you need to change and update a control in the interrupt routine, you
-can call :c:func:`snd_ctl_notify()`. For example,
-
-::
+can call :c:func:`snd_ctl_notify()`. For example::
snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
@@ -2796,13 +2683,11 @@ for hardware volume interrupts.
Metadata
--------
-To provide information about the dB values of a mixer control, use on of
+To provide information about the dB values of a mixer control, use one of
the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
variable containing this information, set the ``tlv.p`` field to point to
this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
-in the ``access`` field; like this:
-
-::
+in the ``access`` field; like this::
static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
@@ -2892,9 +2777,7 @@ AC97 Constructor
----------------
To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
-with an ``ac97_bus_ops_t`` record with callback functions.
-
-::
+with an ``ac97_bus_ops_t`` record with callback functions::
struct snd_ac97_bus *bus;
static struct snd_ac97_bus_ops ops = {
@@ -2906,10 +2789,8 @@ with an ``ac97_bus_ops_t`` record with callback functions.
The bus record is shared among all belonging ac97 instances.
-And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
-record together with the bus pointer created above.
-
-::
+And then call :c:func:`snd_ac97_mixer()` with a struct snd_ac97_template
+record together with the bus pointer created above::
struct snd_ac97_template ac97;
int err;
@@ -2934,9 +2815,7 @@ correspond to the functions for read and write accesses to the
hardware low-level codes.
The ``read`` callback returns the register value specified in the
-argument.
-
-::
+argument::
static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
unsigned short reg)
@@ -2949,9 +2828,7 @@ argument.
Here, the chip can be cast from ``ac97->private_data``.
Meanwhile, the ``write`` callback is used to set the register
-value
-
-::
+value::
static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
unsigned short reg, unsigned short val)
@@ -2984,32 +2861,24 @@ Both :c:func:`snd_ac97_write()` and
the given register (``AC97_XXX``). The difference between them is that
:c:func:`snd_ac97_update()` doesn't write a value if the given
value has been already set, while :c:func:`snd_ac97_write()`
-always rewrites the value.
-
-::
+always rewrites the value::
snd_ac97_write(ac97, AC97_MASTER, 0x8080);
snd_ac97_update(ac97, AC97_MASTER, 0x8080);
:c:func:`snd_ac97_read()` is used to read the value of the given
-register. For example,
-
-::
+register. For example::
value = snd_ac97_read(ac97, AC97_MASTER);
:c:func:`snd_ac97_update_bits()` is used to update some bits in
-the given register.
-
-::
+the given register::
snd_ac97_update_bits(ac97, reg, mask, value);
Also, there is a function to change the sample rate (of a given register
such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
-codec: :c:func:`snd_ac97_set_rate()`.
-
-::
+codec: :c:func:`snd_ac97_set_rate()`::
snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
@@ -3064,9 +2933,7 @@ mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
MIDI Constructor
----------------
-To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
-
-::
+To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`::
struct snd_rawmidi *rmidi;
snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
@@ -3111,16 +2978,12 @@ corresponds to the data port. If not, you may change the ``cport``
field of struct snd_mpu401 manually afterward.
However, struct snd_mpu401 pointer is
not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
-need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
-
-::
+need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly::
struct snd_mpu401 *mpu;
mpu = rmidi->private_data;
-and reset the ``cport`` as you like:
-
-::
+and reset the ``cport`` as you like::
mpu->cport = my_own_control_port;
@@ -3144,9 +3007,7 @@ occurred.
In this case, you need to pass the private_data of the returned rawmidi
object from :c:func:`snd_mpu401_uart_new()` as the second
-argument of :c:func:`snd_mpu401_uart_interrupt()`.
-
-::
+argument of :c:func:`snd_mpu401_uart_interrupt()`::
snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
@@ -3170,9 +3031,7 @@ RawMIDI Constructor
-------------------
To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
-function:
-
-::
+function::
struct snd_rawmidi *rmidi;
err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
@@ -3202,16 +3061,12 @@ output and input at the same time.
After the rawmidi device is created, you need to set the operators
(callbacks) for each substream. There are helper functions to set the
-operators for all the substreams of a device:
-
-::
+operators for all the substreams of a device::
snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
-The operators are usually defined like this:
-
-::
+The operators are usually defined like this::
static struct snd_rawmidi_ops snd_mymidi_output_ops = {
.open = snd_mymidi_output_open,
@@ -3222,9 +3077,7 @@ The operators are usually defined like this:
These callbacks are explained in the `RawMIDI Callbacks`_ section.
If there are more than one substream, you should give a unique name to
-each of them:
-
-::
+each of them::
struct snd_rawmidi_substream *substream;
list_for_each_entry(substream,
@@ -3242,9 +3095,7 @@ device can be accessed as ``substream->rmidi->private_data``.
If there is more than one port, your callbacks can determine the port
index from the struct snd_rawmidi_substream data passed to each
-callback:
-
-::
+callback::
struct snd_rawmidi_substream *substream;
int index = substream->number;
@@ -3289,9 +3140,7 @@ of bytes that have been read; this will be less than the number of bytes
requested when there are no more data in the buffer. After the data have
been transmitted successfully, call
:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
-substream buffer:
-
-::
+substream buffer::
unsigned char data;
while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
@@ -3303,9 +3152,7 @@ substream buffer:
If you know beforehand that the hardware will accept data, you can use
the :c:func:`snd_rawmidi_transmit()` function which reads some
-data and removes them from the buffer at once:
-
-::
+data and removes them from the buffer at once::
while (snd_mychip_transmit_possible()) {
unsigned char data;
@@ -3340,9 +3187,7 @@ The ``trigger`` callback must not sleep; the actual reading of data
from the device is usually done in an interrupt handler.
When data reception is enabled, your interrupt handler should call
-:c:func:`snd_rawmidi_receive()` for all received data:
-
-::
+:c:func:`snd_rawmidi_receive()` for all received data::
void snd_mychip_midi_interrupt(...)
{
@@ -3388,9 +3233,7 @@ whereas in OSS compatible mode, FM registers can be accessed with the
OSS direct-FM compatible API in ``/dev/dmfmX`` device.
To create the OPL3 component, you have two functions to call. The first
-one is a constructor for the ``opl3_t`` instance.
-
-::
+one is a constructor for the ``opl3_t`` instance::
struct snd_opl3 *opl3;
snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
@@ -3408,9 +3251,7 @@ the opl3 module will allocate the specified ports by itself.
When the accessing the hardware requires special method instead of the
standard I/O access, you can create opl3 instance separately with
-:c:func:`snd_opl3_new()`.
-
-::
+:c:func:`snd_opl3_new()`::
struct snd_opl3 *opl3;
snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
@@ -3427,9 +3268,7 @@ proper state. Note that :c:func:`snd_opl3_create()` always calls
it internally.
If the opl3 instance is created successfully, then create a hwdep device
-for this opl3.
-
-::
+for this opl3::
struct snd_hwdep *opl3hwdep;
snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
@@ -3451,9 +3290,7 @@ the micro code. In such a case, you can create a hwdep
``isa/sb/sb16_csp.c``.
The creation of the ``hwdep`` instance is done via
-:c:func:`snd_hwdep_new()`.
-
-::
+:c:func:`snd_hwdep_new()`::
struct snd_hwdep *hw;
snd_hwdep_new(card, "My HWDEP", 0, &hw);
@@ -3461,18 +3298,14 @@ The creation of the ``hwdep`` instance is done via
where the third argument is the index number.
You can then pass any pointer value to the ``private_data``. If you
-assign a private data, you should define the destructor, too. The
-destructor function is set in the ``private_free`` field.
-
-::
+assign private data, you should define a destructor, too. The
+destructor function is set in the ``private_free`` field::
struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
hw->private_data = p;
hw->private_free = mydata_free;
-and the implementation of the destructor would be:
-
-::
+and the implementation of the destructor would be::
static void mydata_free(struct snd_hwdep *hw)
{
@@ -3482,9 +3315,7 @@ and the implementation of the destructor would be:
The arbitrary file operations can be defined for this instance. The file
operators are defined in the ``ops`` table. For example, assume that
-this chip needs an ioctl.
-
-::
+this chip needs an ioctl::
hw->ops.open = mydata_open;
hw->ops.ioctl = mydata_ioctl;
@@ -3534,31 +3365,30 @@ Buffer Types
ALSA provides several different buffer allocation functions depending on
the bus and the architecture. All these have a consistent API. The
-allocation of physically-contiguous pages is done via
+allocation of physically-contiguous pages is done via the
:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
type.
-The allocation of pages with fallback is
-:c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
-to allocate the specified pages but if the pages are not available, it
-tries to reduce the page sizes until enough space is found.
+The allocation of pages with fallback is done via
+:c:func:`snd_dma_alloc_pages_fallback()`. This function tries
+to allocate the specified number of pages, but if not enough pages are
+available, it tries to reduce the request size until enough space
+is found, down to one page.
-The release the pages, call :c:func:`snd_free_xxx_pages()`
+To release the pages, call the :c:func:`snd_dma_free_pages()`
function.
Usually, ALSA drivers try to allocate and reserve a large contiguous
-physical space at the time the module is loaded for the later use. This
+physical space at the time the module is loaded for later use. This
is called “pre-allocation”. As already written, you can call the
-following function at pcm instance construction time (in the case of PCI
-bus).
-
-::
+following function at PCM instance construction time (in the case of PCI
+bus)::
snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
&pci->dev, size, max);
-where ``size`` is the byte size to be pre-allocated and the ``max`` is
-the maximum size to be changed via the ``prealloc`` proc file. The
+where ``size`` is the byte size to be pre-allocated and ``max`` is
+the maximum size settable via the ``prealloc`` proc file. The
allocator will try to get an area as large as possible within the
given size.
@@ -3567,10 +3397,10 @@ dependent on the bus. For normal devices, pass the device pointer
(typically identical as ``card->dev``) to the third argument with
``SNDRV_DMA_TYPE_DEV`` type.
-For the continuous buffer unrelated to the
+A continuous buffer unrelated to the
bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
You can pass NULL to the device pointer in that case, which is the
-default mode implying to allocate with ``GFP_KERNEL`` flag.
+default mode implying to allocate with the ``GFP_KERNEL`` flag.
If you need a restricted (lower) address, set up the coherent DMA mask
bits for the device, and pass the device pointer, like the normal
device memory allocations. For this type, it's still allowed to pass
@@ -3580,37 +3410,33 @@ For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
device pointer (see the `Non-Contiguous Buffers`_ section).
Once the buffer is pre-allocated, you can use the allocator in the
-``hw_params`` callback:
-
-::
+``hw_params`` callback::
snd_pcm_lib_malloc_pages(substream, size);
Note that you have to pre-allocate to use this function.
-Most of drivers use, though, rather the newly introduced "managed
-buffer allocation mode" instead of the manual allocation or release.
+But most drivers use the "managed buffer allocation mode" instead
+of manual allocation and release.
This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
-instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`.
-
-::
+instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`::
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
&pci->dev, size, max);
-where passed arguments are identical in both functions.
+where the passed arguments are identical for both functions.
The difference in the managed mode is that PCM core will call
:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
after the PCM ``hw_free`` callback automatically. So the driver
doesn't have to call these functions explicitly in its callback any
-longer. This made many driver code having NULL ``hw_params`` and
+longer. This allows many drivers to have NULL ``hw_params`` and
``hw_free`` entries.
External Hardware Buffers
-------------------------
-Some chips have their own hardware buffers and the DMA transfer from the
+Some chips have their own hardware buffers and DMA transfer from the
host memory is not available. In such a case, you need to either 1)
copy/set the audio data directly to the external hardware buffer, or 2)
make an intermediate buffer and copy/set the data from it to the
@@ -3618,8 +3444,8 @@ 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_user`` and ``copy_kernel``
-callbacks for the data transfer, in addition to ``fill_silence``
+efficient. You need to define the ``copy_user`` and ``copy_kernel``
+callbacks for the data transfer, in addition to the ``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.
@@ -3633,16 +3459,14 @@ 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_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
-as in the cases above. The examples are found in ``rme32.c`` and
+as in the cases above. Examples are found in ``rme32.c`` and
``rme96.c``.
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:
-
-::
+defined like below, a bit differently depending on whether the direction
+is playback or capture::
static int playback_copy_user(struct snd_pcm_substream *substream,
int channel, unsigned long pos,
@@ -3652,8 +3476,7 @@ is playback or capture:
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 bytes.
+not used. The third argument (``pos``) specifies the position in bytes.
The meaning of the fourth argument is different between playback and
capture. For playback, it holds the source data pointer, and for
@@ -3664,49 +3487,42 @@ 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
of data (``count``) at the specified pointer (``src``) to the specified
-offset (``pos``) on the hardware buffer. When coded like memcpy-like
-way, the copy would be like:
-
-::
+offset (``pos``) in the hardware buffer. When coded like memcpy-like
+way, the copy would look like::
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
-specified pointer (``dst``).
-
-::
+at the specified offset (``pos``) in the hardware buffer to the
+specified pointer (``dst``)::
my_memcpy_to_user(dst, my_buffer + pos, count);
-Here the functions are named as ``from_user`` and ``to_user`` because
+Here the functions are named ``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
+is, the callback is supposed to copy data from/to the user-space
directly to/from the hardware buffer.
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.
+this makes coding easier like in the examples above, and also it makes
+it easier to unify both the interleaved and non-interleaved cases, as
+explained below.
In the case of non-interleaved samples, the implementation will be a bit
-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.
+more complicated. The callback is called for each channel, passed in
+the second argument, so in total it's called N times per transfer.
-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:
+The meaning of the other arguments are almost the same as in 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
+details, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c``
+as examples.
-::
+The above callbacks are the copies from/to the user-space buffer. There
+are some cases where we want to copy from/to the kernel-space buffer
+instead. In such a case, the ``copy_kernel`` callback is called. It'd
+look like::
static int playback_copy_kernel(struct snd_pcm_substream *substream,
int channel, unsigned long pos,
@@ -3716,19 +3532,15 @@ look like:
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
+without a ``__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:
-
-::
+a version without the user-copy, such as::
my_memcpy(my_buffer + pos, src, count);
Usually for the playback, another callback ``fill_silence`` is
defined. It's implemented in a similar way as the copy callbacks
-above:
-
-::
+above::
static int silence(struct snd_pcm_substream *substream, int channel,
unsigned long pos, unsigned long count);
@@ -3736,54 +3548,47 @@ above:
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.
+no meaning, as for the ``copy_*`` callbacks.
-The role of ``fill_silence`` callback is to set the given amount
-(``count``) of silence data at the specified offset (``pos``) on the
+The role of the ``fill_silence`` callback is to set the given amount
+(``count``) of silence data at the specified offset (``pos``) in 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
-would be like:
-
-::
+would look like::
my_memset(my_buffer + pos, 0, count);
In the case of non-interleaved samples, again, the implementation
-becomes a bit more complicated, as it's called N-times per transfer
+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
----------------------
-If your hardware supports the page table as in emu10k1 or the buffer
-descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
+If your hardware supports a page table as in emu10k1 or buffer
+descriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA
provides an interface for handling SG-buffers. The API is provided in
``<sound/pcm.h>``.
For creating the SG-buffer handler, call
:c:func:`snd_pcm_set_managed_buffer()` or
:c:func:`snd_pcm_set_managed_buffer_all()` with
-``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
-pre-allocator. You need to pass ``&pci->dev``, where pci is
-the struct pci_dev pointer of the chip as
-well.
-
-::
+``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like for other PCI
+pre-allocations. You need to pass ``&pci->dev``, where pci is
+the struct pci_dev pointer of the chip as well::
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
&pci->dev, size, max);
The ``struct snd_sg_buf`` instance is created as
-``substream->dma_private`` in turn. You can cast the pointer like:
-
-::
+``substream->dma_private`` in turn. You can cast the pointer like::
struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
-Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
+Then in the :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
handler will allocate the non-contiguous kernel pages of the given size
-and map them onto the virtually contiguous memory. The virtual pointer
-is addressed in runtime->dma_area. The physical address
+and map them as virtually contiguous memory. The virtual pointer
+is addressed via runtime->dma_area. The physical address
(``runtime->dma_addr``) is set to zero, because the buffer is
physically non-contiguous. The physical address table is set up in
``sgbuf->table``. You can get the physical address at a certain offset
@@ -3796,22 +3601,20 @@ Vmalloc'ed Buffers
------------------
It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
-example, for an intermediate buffer. In the recent version of kernel,
-you can simply allocate it via standard
-:c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the
-buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type.
-
-::
+example, for an intermediate buffer.
+You can simply allocate it via the standard
+:c:func:`snd_pcm_lib_malloc_pages()` and co. after setting up the
+buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type::
snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
NULL, 0, 0);
-The NULL is passed to the device pointer argument, which indicates
-that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be
+NULL is passed as the device pointer argument, which indicates
+that default pages (GFP_KERNEL and GFP_HIGHMEM) will be
allocated.
-Also, note that zero is passed to both the size and the max size
-arguments here. Since each vmalloc call should succeed at any time,
+Also, note that zero is passed as both the size and the max size
+argument here. Since each vmalloc call should succeed at any time,
we don't need to pre-allocate the buffers like other continuous
pages.
@@ -3823,9 +3626,7 @@ useful for debugging. I recommend you set up proc files if you write a
driver and want to get a running status or register dumps. The API is
found in ``<sound/info.h>``.
-To create a proc file, call :c:func:`snd_card_proc_new()`.
-
-::
+To create a proc file, call :c:func:`snd_card_proc_new()`::
struct snd_info_entry *entry;
int err = snd_card_proc_new(card, "my-file", &entry);
@@ -3841,28 +3642,22 @@ automatically in the card registration and release functions.
When the creation is successful, the function stores a new instance in
the pointer given in the third argument. It is initialized as a text
proc file for read only. To use this proc file as a read-only text file
-as it is, set the read callback with a private data via
-:c:func:`snd_info_set_text_ops()`.
-
-::
+as-is, set the read callback with private data via
+:c:func:`snd_info_set_text_ops()`::
snd_info_set_text_ops(entry, chip, my_proc_read);
where the second argument (``chip``) is the private data to be used in
-the callbacks. The third parameter specifies the read buffer size and
+the callback. The third parameter specifies the read buffer size and
the fourth (``my_proc_read``) is the callback function, which is
-defined like
-
-::
+defined like::
static void my_proc_read(struct snd_info_entry *entry,
struct snd_info_buffer *buffer);
In the read callback, use :c:func:`snd_iprintf()` for output
strings, which works just like normal :c:func:`printf()`. For
-example,
-
-::
+example::
static void my_proc_read(struct snd_info_entry *entry,
struct snd_info_buffer *buffer)
@@ -3873,28 +3668,22 @@ example,
snd_iprintf(buffer, "Port = %ld\n", chip->port);
}
-The file permissions can be changed afterwards. As default, it's set as
+The file permissions can be changed afterwards. By default, they are
read only for all users. If you want to add write permission for the
-user (root as default), do as follows:
-
-::
+user (root by default), do as follows::
entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
-and set the write buffer size and the callback
-
-::
+and set the write buffer size and the callback::
entry->c.text.write = my_proc_write;
-For the write callback, you can use :c:func:`snd_info_get_line()`
+In the write callback, you can use :c:func:`snd_info_get_line()`
to get a text line, and :c:func:`snd_info_get_str()` to retrieve
a string from the line. Some examples are found in
``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
-For a raw-data proc-file, set the attributes as follows:
-
-::
+For a raw-data proc-file, set the attributes as follows::
static const struct snd_info_entry_ops my_file_io_ops = {
.read = my_file_io_read,
@@ -3906,14 +3695,13 @@ For a raw-data proc-file, set the attributes as follows:
entry->size = 4096;
entry->mode = S_IFREG | S_IRUGO;
-For the raw data, ``size`` field must be set properly. This specifies
+For raw data, ``size`` field must be set properly. This specifies
the maximum size of the proc file access.
The read/write callbacks of raw mode are more direct than the text mode.
You need to use a low-level I/O functions such as
-:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
-
-::
+:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the
+data::
static ssize_t my_file_io_read(struct snd_info_entry *entry,
void *file_private_data,
@@ -3938,12 +3726,11 @@ Power Management
If the chip is supposed to work with suspend/resume functions, you need
to add power-management code to the driver. The additional code for
power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
-with __maybe_unused attribute; otherwise the compiler will complain
-you.
+with __maybe_unused attribute; otherwise the compiler will complain.
If the driver *fully* supports suspend/resume that is, the device can be
properly resumed to its state when suspend was called, you can set the
-``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
+``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is
possible when the registers of the chip can be safely saved and restored
to RAM. If this is set, the trigger callback is called with
``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
@@ -3953,7 +3740,7 @@ is still possible, it's still worthy to implement suspend/resume
callbacks. In such a case, applications would reset the status by
calling :c:func:`snd_pcm_prepare()` and restart the stream
appropriately. Hence, you can define suspend/resume callbacks below but
-don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
+don't set the ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
Note that the trigger with SUSPEND can always be called when
:c:func:`snd_pcm_suspend_all()` is called, regardless of the
@@ -3963,12 +3750,9 @@ behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
to keep it for compatibility reasons.)
-In the earlier version of ALSA drivers, a common power-management layer
-was provided, but it has been removed. The driver needs to define the
+The driver needs to define the
suspend/resume hooks according to the bus the device is connected to. In
-the case of PCI drivers, the callbacks look like below:
-
-::
+the case of PCI drivers, the callbacks look like below::
static int __maybe_unused snd_my_suspend(struct device *dev)
{
@@ -3981,7 +3765,7 @@ the case of PCI drivers, the callbacks look like below:
return 0;
}
-The scheme of the real suspend job is as follows.
+The scheme of the real suspend job is as follows:
1. Retrieve the card and the chip data.
@@ -3995,9 +3779,7 @@ The scheme of the real suspend job is as follows.
5. Stop the hardware if necessary.
-A typical code would be like:
-
-::
+Typical code would look like::
static int __maybe_unused mychip_suspend(struct device *dev)
{
@@ -4016,7 +3798,7 @@ A typical code would be like:
}
-The scheme of the real resume job is as follows.
+The scheme of the real resume job is as follows:
1. Retrieve the card and the chip data.
@@ -4024,16 +3806,14 @@ The scheme of the real resume job is as follows.
3. Restore the saved registers if necessary.
-4. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
+4. Resume the mixer, e.g. by calling :c:func:`snd_ac97_resume()`.
5. Restart the hardware (if any).
6. Call :c:func:`snd_power_change_state()` with
``SNDRV_CTL_POWER_D0`` to notify the processes.
-A typical code would be like:
-
-::
+Typical code would look like::
static int __maybe_unused mychip_resume(struct pci_dev *pci)
{
@@ -4060,9 +3840,7 @@ been already suspended via its own PM ops calling
OK, we have all callbacks now. Let's set them up. In the initialization
of the card, make sure that you can get the chip data from the card
instance, typically via ``private_data`` field, in case you created the
-chip data individually.
-
-::
+chip data individually::
static int snd_mychip_probe(struct pci_dev *pci,
const struct pci_device_id *pci_id)
@@ -4082,9 +3860,7 @@ chip data individually.
}
When you created the chip data with :c:func:`snd_card_new()`, it's
-anyway accessible via ``private_data`` field.
-
-::
+anyway accessible via ``private_data`` field::
static int snd_mychip_probe(struct pci_dev *pci,
const struct pci_device_id *pci_id)
@@ -4101,14 +3877,12 @@ anyway accessible via ``private_data`` field.
....
}
-If you need a space to save the registers, allocate the buffer for it
+If you need space to save the registers, allocate the buffer for it
here, too, since it would be fatal if you cannot allocate a memory in
the suspend phase. The allocated buffer should be released in the
corresponding destructor.
-And next, set suspend/resume callbacks to the pci_driver.
-
-::
+And next, set suspend/resume callbacks to the pci_driver::
static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
@@ -4128,9 +3902,7 @@ have the ``index``, ``id`` and ``enable`` options.
If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
cards), they should be arrays. The default initial values are defined
-already as constants for easier programming:
-
-::
+already as constants for easier programming::
static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
@@ -4144,9 +3916,7 @@ The module parameters must be declared with the standard
``module_param()``, ``module_param_array()`` and
:c:func:`MODULE_PARM_DESC()` macros.
-The typical coding would be like below:
-
-::
+Typical code would look as below::
#define CARD_NAME "My Chip"
@@ -4159,9 +3929,7 @@ The typical coding would be like below:
Also, don't forget to define the module description and the license.
Especially, the recent modprobe requires to define the
-module license as GPL, etc., otherwise the system is shown as “tainted”.
-
-::
+module license as GPL, etc., otherwise the system is shown as “tainted”::
MODULE_DESCRIPTION("Sound driver for My Chip");
MODULE_LICENSE("GPL");
@@ -4224,32 +3992,36 @@ Driver with A Single Source File
1. Modify sound/pci/Makefile
- Suppose you have a file xyz.c. Add the following two lines
-
-::
+ Suppose you have a file xyz.c. Add the following two lines::
snd-xyz-objs := xyz.o
obj-$(CONFIG_SND_XYZ) += snd-xyz.o
2. Create the Kconfig entry
- Add the new entry of Kconfig for your xyz driver. config SND_XYZ
- tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
- to include support for Foobar XYZ soundcard. To compile this driver
- as a module, choose M here: the module will be called snd-xyz. the
- line, select SND_PCM, specifies that the driver xyz supports PCM. In
- addition to SND_PCM, the following components are supported for
- select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
- SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
- SND_AC97_CODEC. Add the select command for each supported
- component.
+ Add the new entry of Kconfig for your xyz driver::
+
+ config SND_XYZ
+ tristate "Foobar XYZ"
+ depends on SND
+ select SND_PCM
+ help
+ Say Y here to include support for Foobar XYZ soundcard.
+ To compile this driver as a module, choose M here:
+ the module will be called snd-xyz.
+
+The line ``select SND_PCM`` specifies that the driver xyz supports PCM.
+In addition to SND_PCM, the following components are supported for
+select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
+SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
+Add the select command for each supported component.
- Note that some selections imply the lowlevel selections. For example,
- PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
- includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
- the lowlevel selections again.
+Note that some selections imply the lowlevel selections. For example,
+PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
+includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
+the lowlevel selections again.
- For the details of Kconfig script, refer to the kbuild documentation.
+For the details of Kconfig script, refer to the kbuild documentation.
Drivers with Several Source Files
---------------------------------
@@ -4258,16 +4030,12 @@ Suppose that the driver snd-xyz have several source files. They are
located in the new subdirectory, sound/pci/xyz.
1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
- as below
-
-::
+ as below::
obj-$(CONFIG_SND) += sound/pci/xyz/
-2. Under the directory ``sound/pci/xyz``, create a Makefile
-
-::
+2. Under the directory ``sound/pci/xyz``, create a Makefile::
snd-xyz-objs := xyz.o abc.o def.o
obj-$(CONFIG_SND_XYZ) += snd-xyz.o