[PATCH 0/8] ASoC: fsl: Refine DT binding documents for more readability

[Nicolin Chen]

This series of patches simply add indentations and blank lines to each DT
binding documents of Freescale ASoC drivers so as to make them more clear
and readable.

@Mark Brown
Not sure if they are okay to get applied through your tree.
Otherwise, I might need to change these subjects and send
them to DT maillist only. Thank you.

Nicolin Chen (8):
ASoC: fsl_esai: Add indentation for binding doc to increase
readability
ASoC: fsl_spdif: Add indentation for binding doc to increase
readability
ASoC: fsl_sai: Add indentation for binding doc to increase readability
ASoC: eukrea-tlv320: Add indentation for binding doc to increase
readability
ASoC: imx-audmux: Add indentation for binding doc to increase
readability
ASoC: imx-sgtl5000: Add indentation for binding doc to increase
readability
ASoC: imx-spdif: Add indentation for binding doc to increase
readability
ASoC: imx-wm8962: Add indentation for binding doc to increase
readability

.../devicetree/bindings/sound/eukrea-tlv320.txt | 15 +++--
.../devicetree/bindings/sound/fsl,esai.txt | 44 ++++++++-------
.../devicetree/bindings/sound/fsl,spdif.txt | 37 ++++++------
.../devicetree/bindings/sound/fsl-sai.txt | 66 ++++++++++++++--------
.../bindings/sound/imx-audio-sgtl5000.txt | 61 +++++++++++---------
.../devicetree/bindings/sound/imx-audio-spdif.txt | 22 ++++----
.../devicetree/bindings/sound/imx-audio-wm8962.txt | 45 ++++++++-------
.../devicetree/bindings/sound/imx-audmux.txt | 22 +++++---
8 files changed, 178 insertions(+), 134 deletions(-)

[Nicolin Chen]

This patch refines the DT binding doc for more readability by adding
extra blank lines and indentations.

Signed-off-by: Nicolin Chen <***@gmail.com>
---
Documentation/devicetree/bindings/sound/eukrea-tlv320.txt | 15 ++++++++++-----
1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt b/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt
index 0d7985c..6dfa88c 100644
--- a/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt
+++ b/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt
@@ -1,11 +1,16 @@
Audio complex for Eukrea boards with tlv320aic23 codec.

Required properties:
-- compatible : "eukrea,asoc-tlv320"
-- eukrea,model : The user-visible name of this sound complex.
-- ssi-controller : The phandle of the SSI controller.
-- fsl,mux-int-port : The internal port of the i.MX audio muxer (AUDMUX).
-- fsl,mux-ext-port : The external port of the i.MX audio muxer.
+
+ - compatible : "eukrea,asoc-tlv320"
+
+ - eukrea,model : The user-visible name of this sound complex.
+
+ - ssi-controller : The phandle of the SSI controller.
+
+ - fsl,mux-int-port : The internal port of the i.MX audio muxer (AUDMUX).
+
+ - fsl,mux-ext-port : The external port of the i.MX audio muxer.

Note: The AUDMUX port numbering should start at 1, which is consistent with
hardware manual.

[Nicolin Chen]

This patch simply adds indentations for DT binding doc to increase readability
without changing any contents.

Signed-off-by: Nicolin Chen <***@gmail.com>
---
.../devicetree/bindings/sound/imx-audio-spdif.txt | 22 ++++++++++++----------
1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt b/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt
index 7d13479..da84a44 100644
--- a/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt
+++ b/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt
@@ -2,23 +2,25 @@ Freescale i.MX audio complex with S/PDIF transceiver

Required properties:

- - compatible : "fsl,imx-audio-spdif"
+ - compatible : "fsl,imx-audio-spdif"

- - model : The user-visible name of this sound complex
+ - model : The user-visible name of this sound complex

- - spdif-controller : The phandle of the i.MX S/PDIF controller
+ - spdif-controller : The phandle of the i.MX S/PDIF controller


Optional properties:

- - spdif-out : This is a boolean property. If present, the transmitting
- function of S/PDIF will be enabled, indicating there's a physical
- S/PDIF out connector/jack on the board or it's connecting to some
- other IP block, such as an HDMI encoder/display-controller.
+ - spdif-out : This is a boolean property. If present, the
+ transmitting function of S/PDIF will be enabled,
+ indicating there's a physical S/PDIF out connector
+ or jack on the board or it's connecting to some
+ other IP block, such as an HDMI encoder or
+ display-controller.

- - spdif-in : This is a boolean property. If present, the receiving
- function of S/PDIF will be enabled, indicating there's a physical
- S/PDIF in connector/jack on the board.
+ - spdif-in : This is a boolean property. If present, the receiving
+ function of S/PDIF will be enabled, indicating there
+ is a physical S/PDIF in connector/jack on the board.

* Note: At least one of these two properties should be set in the DT binding.

[Nicolin Chen]

This patch simply adds indentations for DT binding doc to increase readability
without changing any contents.

Signed-off-by: Nicolin Chen <***@gmail.com>
---
.../devicetree/bindings/sound/fsl,esai.txt | 44 +++++++++++-----------
1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt
index 52f5b6b..d3b6b5f 100644
--- a/Documentation/devicetree/bindings/sound/fsl,esai.txt
+++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt
@@ -7,37 +7,39 @@ other DSPs. It has up to six transmitters and four receivers.

Required properties:

- - compatible : Compatible list, must contain "fsl,imx35-esai" or
- "fsl,vf610-esai"
+ - compatible : Compatible list, must contain "fsl,imx35-esai" or
+ "fsl,vf610-esai"

- - reg : Offset and length of the register set for the device.
+ - reg : Offset and length of the register set for the device.

- - interrupts : Contains the spdif interrupt.
+ - interrupts : Contains the spdif interrupt.

- - dmas : Generic dma devicetree binding as described in
- Documentation/devicetree/bindings/dma/dma.txt.
+ - dmas : Generic dma devicetree binding as described in
+ Documentation/devicetree/bindings/dma/dma.txt.

- - dma-names : Two dmas have to be defined, "tx" and "rx".
+ - dma-names : Two dmas have to be defined, "tx" and "rx".

- - clocks: Contains an entry for each entry in clock-names.
+ - clocks : Contains an entry for each entry in clock-names.

- - clock-names : Includes the following entries:
- "core" The core clock used to access registers
- "extal" The esai baud clock for esai controller used to derive
- HCK, SCK and FS.
- "fsys" The system clock derived from ahb clock used to derive
- HCK, SCK and FS.
+ - clock-names : Includes the following entries:
+ "core" The core clock used to access registers
+ "extal" The esai baud clock for esai controller used to
+ derive HCK, SCK and FS.
+ "fsys" The system clock derived from ahb clock used to
+ derive HCK, SCK and FS.

- - fsl,fifo-depth: The number of elements in the transmit and receive FIFOs.
- This number is the maximum allowed value for TFCR[TFWM] or RFCR[RFWM].
+ - fsl,fifo-depth : The number of elements in the transmit and receive
+ FIFOs. This number is the maximum allowed value for
+ TFCR[TFWM] or RFCR[RFWM].

- fsl,esai-synchronous: This is a boolean property. If present, indicating
- that ESAI would work in the synchronous mode, which means all the settings
- for Receiving would be duplicated from Transmition related registers.
+ that ESAI would work in the synchronous mode, which
+ means all the settings for Receiving would be
+ duplicated from Transmition related registers.

- - big-endian : If this property is absent, the native endian mode will
- be in use as default, or the big endian mode will be in use for all the
- device registers.
+ - big-endian : If this property is absent, the native endian mode
+ will be in use as default, or the big endian mode
+ will be in use for all the device registers.

Example:

[Nicolin Chen]

This patch simply adds indentations for DT binding doc to increase readability
without changing any contents.

Signed-off-by: Nicolin Chen <***@gmail.com>
---
.../devicetree/bindings/sound/imx-audio-wm8962.txt | 45 +++++++++++++---------
1 file changed, 26 insertions(+), 19 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt b/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt
index f49450a..acea71b 100644
--- a/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt
+++ b/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt
@@ -1,25 +1,32 @@
Freescale i.MX audio complex with WM8962 codec

Required properties:
-- compatible : "fsl,imx-audio-wm8962"
-- model : The user-visible name of this sound complex
-- ssi-controller : The phandle of the i.MX SSI controller
-- audio-codec : The phandle of the WM8962 audio codec
-- audio-routing : A list of the connections between audio components.
- Each entry is a pair of strings, the first being the connection's sink,
- the second being the connection's source. Valid names could be power
- supplies, WM8962 pins, and the jacks on the board:
-
- Power supplies:
- * Mic Bias
-
- Board connectors:
- * Mic Jack
- * Headphone Jack
- * Ext Spk
-
-- mux-int-port : The internal port of the i.MX audio muxer (AUDMUX)
-- mux-ext-port : The external port of the i.MX audio muxer
+
+ - compatible : "fsl,imx-audio-wm8962"
+
+ - model : The user-visible name of this sound complex
+
+ - ssi-controller : The phandle of the i.MX SSI controller
+
+ - audio-codec : The phandle of the WM8962 audio codec
+
+ - audio-routing : A list of the connections between audio components.
+ Each entry is a pair of strings, the first being the
+ connection's sink, the second being the connection's
+ source. Valid names could be power supplies, WM8962
+ pins, and the jacks on the board:
+
+ Power supplies:
+ * Mic Bias
+
+ Board connectors:
+ * Mic Jack
+ * Headphone Jack
+ * Ext Spk
+
+ - mux-int-port : The internal port of the i.MX audio muxer (AUDMUX)
+
+ - mux-ext-port : The external port of the i.MX audio muxer

Note: The AUDMUX port numbering should start at 1, which is consistent with
hardware manual.

[Nicolin Chen]

This patch simply adds indentations for DT binding doc to increase readability
without changing any contents.

Signed-off-by: Nicolin Chen <***@gmail.com>
---
.../devicetree/bindings/sound/fsl,spdif.txt | 37 +++++++++++-----------
1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/fsl,spdif.txt b/Documentation/devicetree/bindings/sound/fsl,spdif.txt
index 3e9e82c8..b5ee32e 100644
--- a/Documentation/devicetree/bindings/sound/fsl,spdif.txt
+++ b/Documentation/devicetree/bindings/sound/fsl,spdif.txt
@@ -6,32 +6,31 @@ a fibre cable.

Required properties:

- - compatible : Compatible list, must contain "fsl,imx35-spdif".
+ - compatible : Compatible list, must contain "fsl,imx35-spdif".

- - reg : Offset and length of the register set for the device.
+ - reg : Offset and length of the register set for the device.

- - interrupts : Contains the spdif interrupt.
+ - interrupts : Contains the spdif interrupt.

- - dmas : Generic dma devicetree binding as described in
- Documentation/devicetree/bindings/dma/dma.txt.
+ - dmas : Generic dma devicetree binding as described in
+ Documentation/devicetree/bindings/dma/dma.txt.

- - dma-names : Two dmas have to be defined, "tx" and "rx".
+ - dma-names : Two dmas have to be defined, "tx" and "rx".

- - clocks : Contains an entry for each entry in clock-names.
+ - clocks : Contains an entry for each entry in clock-names.

- - clock-names : Includes the following entries:
- "core" The core clock of spdif controller
- "rxtx<0-7>" Clock source list for tx and rx clock.
- This clock list should be identical to
- the source list connecting to the spdif
- clock mux in "SPDIF Transceiver Clock
- Diagram" of SoC reference manual. It
- can also be referred to TxClk_Source
- bit of register SPDIF_STC.
+ - clock-names : Includes the following entries:
+ "core" The core clock of spdif controller.
+ "rxtx<0-7>" Clock source list for tx and rx clock.
+ This clock list should be identical to the source
+ list connecting to the spdif clock mux in "SPDIF
+ Transceiver Clock Diagram" of SoC reference manual.
+ It can also be referred to TxClk_Source bit of
+ register SPDIF_STC.

- - big-endian : If this property is absent, the native endian mode will
- be in use as default, or the big endian mode will be in use for all the
- device registers.
+ - big-endian : If this property is absent, the native endian mode
+ will be in use as default, or the big endian mode
+ will be in use for all the device registers.

Example:

[Nicolin Chen]

This patch refines the DT binding doc for more readability by adding
extra blank lines and indentations.

Signed-off-by: Nicolin Chen <***@gmail.com>
---
.../bindings/sound/imx-audio-sgtl5000.txt | 61 ++++++++++++----------
1 file changed, 34 insertions(+), 27 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt b/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt
index e4acdd8..2f89db8 100644
--- a/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt
+++ b/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt
@@ -1,33 +1,40 @@
Freescale i.MX audio complex with SGTL5000 codec

Required properties:
-- compatible : "fsl,imx-audio-sgtl5000"
-- model : The user-visible name of this sound complex
-- ssi-controller : The phandle of the i.MX SSI controller
-- audio-codec : The phandle of the SGTL5000 audio codec
-- audio-routing : A list of the connections between audio components.
- Each entry is a pair of strings, the first being the connection's sink,
- the second being the connection's source. Valid names could be power
- supplies, SGTL5000 pins, and the jacks on the board:
-
- Power supplies:
- * Mic Bias
-
- SGTL5000 pins:
- * MIC_IN
- * LINE_IN
- * HP_OUT
- * LINE_OUT
-
- Board connectors:
- * Mic Jack
- * Line In Jack
- * Headphone Jack
- * Line Out Jack
- * Ext Spk
-
-- mux-int-port : The internal port of the i.MX audio muxer (AUDMUX)
-- mux-ext-port : The external port of the i.MX audio muxer
+
+ - compatible : "fsl,imx-audio-sgtl5000"
+
+ - model : The user-visible name of this sound complex
+
+ - ssi-controller : The phandle of the i.MX SSI controller
+
+ - audio-codec : The phandle of the SGTL5000 audio codec
+
+ - audio-routing : A list of the connections between audio components.
+ Each entry is a pair of strings, the first being the
+ connection's sink, the second being the connection's
+ source. Valid names could be power supplies, SGTL5000
+ pins, and the jacks on the board:
+
+ Power supplies:
+ * Mic Bias
+
+ SGTL5000 pins:
+ * MIC_IN
+ * LINE_IN
+ * HP_OUT
+ * LINE_OUT
+
+ Board connectors:
+ * Mic Jack
+ * Line In Jack
+ * Headphone Jack
+ * Line Out Jack
+ * Ext Spk
+
+ - mux-int-port : The internal port of the i.MX audio muxer (AUDMUX)
+
+ - mux-ext-port : The external port of the i.MX audio muxer

Note: The AUDMUX port numbering should start at 1, which is consistent with
hardware manual.

[Nicolin Chen]

This patch refines the DT binding doc for more readability by adding
extra blank lines and indentations.

Signed-off-by: Nicolin Chen <***@gmail.com>
---
.../devicetree/bindings/sound/imx-audmux.txt | 22 ++++++++++++++--------
1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/imx-audmux.txt b/Documentation/devicetree/bindings/sound/imx-audmux.txt
index f88a00e..b30a737 100644
--- a/Documentation/devicetree/bindings/sound/imx-audmux.txt
+++ b/Documentation/devicetree/bindings/sound/imx-audmux.txt
@@ -1,18 +1,24 @@
Freescale Digital Audio Mux (AUDMUX) device

Required properties:
-- compatible : "fsl,imx21-audmux" for AUDMUX version firstly used on i.MX21,
- or "fsl,imx31-audmux" for the version firstly used on i.MX31.
-- reg : Should contain AUDMUX registers location and length
+
+ - compatible : "fsl,imx21-audmux" for AUDMUX version firstly used
+ on i.MX21, or "fsl,imx31-audmux" for the version
+ firstly used on i.MX31.
+
+ - reg : Should contain AUDMUX registers location and length.

An initial configuration can be setup using child nodes.

Required properties of optional child nodes:
-- fsl,audmux-port : Integer of the audmux port that is configured by this
- child node.
-- fsl,port-config : List of configuration options for the specific port. For
- imx31-audmux and above, it is a list of tuples <ptcr pdcr>. For
- imx21-audmux it is a list of pcr values.
+
+ - fsl,audmux-port : Integer of the audmux port that is configured by this
+ child node.
+
+ - fsl,port-config : List of configuration options for the specific port.
+ For imx31-audmux and above, it is a list of tuples
+ <ptcr pdcr>. For imx21-audmux it is a list of pcr
+ values.

Example:

[Nicolin Chen]

This patch refines the DT binding doc for more readability by adding
extra blank lines and indentations.

Signed-off-by: Nicolin Chen <***@gmail.com>
---
.../devicetree/bindings/sound/fsl-sai.txt | 66 ++++++++++++++--------
1 file changed, 41 insertions(+), 25 deletions(-)

diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt
index 4956b14..044e5d7 100644
--- a/Documentation/devicetree/bindings/sound/fsl-sai.txt
+++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt
@@ -5,32 +5,48 @@ which provides a synchronous audio interface that supports fullduplex
serial interfaces with frame synchronization such as I2S, AC97, TDM, and
codec/DSP interfaces.

-
Required properties:
-- compatible: Compatible list, contains "fsl,vf610-sai" or "fsl,imx6sx-sai".
-- reg: Offset and length of the register set for the device.
-- clocks: Must contain an entry for each entry in clock-names.
-- clock-names : Must include the "bus" for register access and "mclk1" "mclk2"
- "mclk3" for bit clock and frame clock providing.
-- dmas : Generic dma devicetree binding as described in
- Documentation/devicetree/bindings/dma/dma.txt.
-- dma-names : Two dmas have to be defined, "tx" and "rx".
-- pinctrl-names: Must contain a "default" entry.
-- pinctrl-NNN: One property must exist for each entry in pinctrl-names.
- See ../pinctrl/pinctrl-bindings.txt for details of the property values.
-- big-endian: Boolean property, required if all the FTM_PWM registers
- are big-endian rather than little-endian.
-- lsb-first: Configures whether the LSB or the MSB is transmitted first for
- the fifo data. If this property is absent, the MSB is transmitted first as
- default, or the LSB is transmitted first.
-- fsl,sai-synchronous-rx: This is a boolean property. If present, indicating
- that SAI will work in the synchronous mode (sync Tx with Rx) which means
- both the transimitter and receiver will send and receive data by following
- receiver's bit clocks and frame sync clocks.
-- fsl,sai-asynchronous: This is a boolean property. If present, indicating
- that SAI will work in the asynchronous mode, which means both transimitter
- and receiver will send and receive data by following their own bit clocks
- and frame sync clocks separately.
+
+ - compatible : Compatible list, contains "fsl,vf610-sai" or
+ "fsl,imx6sx-sai".
+
+ - reg : Offset and length of the register set for the device.
+
+ - clocks : Must contain an entry for each entry in clock-names.
+
+ - clock-names : Must include the "bus" for register access and
+ "mclk1", "mclk2", "mclk3" for bit clock and frame
+ clock providing.
+ - dmas : Generic dma devicetree binding as described in
+ Documentation/devicetree/bindings/dma/dma.txt.
+
+ - dma-names : Two dmas have to be defined, "tx" and "rx".
+
+ - pinctrl-names : Must contain a "default" entry.
+
+ - pinctrl-NNN : One property must exist for each entry in
+ pinctrl-names. See ../pinctrl/pinctrl-bindings.txt
+ for details of the property values.
+
+ - big-endian : Boolean property, required if all the FTM_PWM
+ registers are big-endian rather than little-endian.
+
+ - lsb-first : Configures whether the LSB or the MSB is transmitted
+ first for the fifo data. If this property is absent,
+ the MSB is transmitted first as default, or the LSB
+ is transmitted first.
+
+ - fsl,sai-synchronous-rx: This is a boolean property. If present, indicating
+ that SAI will work in the synchronous mode (sync Tx
+ with Rx) which means both the transimitter and the
+ receiver will send and receive data by following
+ receiver's bit clocks and frame sync clocks.
+
+ - fsl,sai-asynchronous: This is a boolean property. If present, indicating
+ that SAI will work in the asynchronous mode, which
+ means both transimitter and receiver will send and
+ receive data by following their own bit clocks and
+ frame sync clocks separately.

Note:
- If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are absent, the

[Mark Brown]

Post by Nicolin Chen
This series of patches simply add indentations and blank lines to each DT
binding documents of Freescale ASoC drivers so as to make them more clear
and readable.

Applied all, thanks.