[03/11] Documentation: mmc: sdhci-of-arasan: Add soc-ctl-syscon for corecfg regs
diff mbox

Message ID 1465339484-969-4-git-send-email-dianders@chromium.org
State New
Headers show

Commit Message

Douglas Anderson June 7, 2016, 10:44 p.m. UTC
As can be seen in Arasan's datasheet [1] there are several "corecfg"
settings in their SDHCI IP Block that are supposed to be controlled by
software.  Although the datasheet referenced is a bit vague about how to
access corecfg, in Figure 5 you can see that for Arasan's PHY (a
separate component than their SDHCI component) they describe the
"phyctrl" registers as being "FROM SOC CTL REG", implying that it's up
to the licensee of the Arasan IP block to implement these registers.  It
seems sane to assume that the "corecfg" registers in their SDHCI IP
block works in a similar way for all licensees of the IP Block.

Device tree has a model that allows a device to get a reference to
random registers located elsewhere in the SoC: sysctl.  Let's leverage
this model and allow adding a sysctl reference to access the control
registers for the Arasan SDHCI PHYs.

Having a reference to the control registers doesn't do much for us on
its own since the Arasan spec doesn't specify how these corecfg values
are laid out in memory.  In the SDHCI driver we'll need a map detailing
where each corecfg can be found in each implementation.  This map can be
found using the primary compatible string of the SDHCI device.  In that
spirit, document that existing rk3399 device trees already have a
specific compatible string, though up to now they've always been relying
on the driver supporting the generic.

Note that since existing devices seem to work fairly well as-is, we'll
list the syscon reference as "optional", but it's likely that we'll run
into much fewer problems if we can actually set the proper values in the
syscon, so it is strongly suggested that any SoCs where we have a map to
set the corecfg also include a reference to the syscon.

[1]: https://arasan.com/wp-content/media/eMMC-5-1-Total-Solution_Rev-1-3.pdf

Signed-off-by: Douglas Anderson <dianders@chromium.org>
---
 .../devicetree/bindings/mmc/arasan,sdhci.txt       | 27 ++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

Comments

Rob Herring June 8, 2016, 8:17 p.m. UTC | #1
On Tue, Jun 07, 2016 at 03:44:36PM -0700, Douglas Anderson wrote:
> As can be seen in Arasan's datasheet [1] there are several "corecfg"
> settings in their SDHCI IP Block that are supposed to be controlled by
> software.  Although the datasheet referenced is a bit vague about how to
> access corecfg, in Figure 5 you can see that for Arasan's PHY (a
> separate component than their SDHCI component) they describe the
> "phyctrl" registers as being "FROM SOC CTL REG", implying that it's up
> to the licensee of the Arasan IP block to implement these registers.  It
> seems sane to assume that the "corecfg" registers in their SDHCI IP
> block works in a similar way for all licensees of the IP Block.
> 
> Device tree has a model that allows a device to get a reference to
> random registers located elsewhere in the SoC: sysctl.  Let's leverage
> this model and allow adding a sysctl reference to access the control
> registers for the Arasan SDHCI PHYs.
> 
> Having a reference to the control registers doesn't do much for us on
> its own since the Arasan spec doesn't specify how these corecfg values
> are laid out in memory.  In the SDHCI driver we'll need a map detailing
> where each corecfg can be found in each implementation.  This map can be
> found using the primary compatible string of the SDHCI device.  In that
> spirit, document that existing rk3399 device trees already have a
> specific compatible string, though up to now they've always been relying
> on the driver supporting the generic.
> 
> Note that since existing devices seem to work fairly well as-is, we'll
> list the syscon reference as "optional", but it's likely that we'll run
> into much fewer problems if we can actually set the proper values in the
> syscon, so it is strongly suggested that any SoCs where we have a map to
> set the corecfg also include a reference to the syscon.
> 
> [1]: https://arasan.com/wp-content/media/eMMC-5-1-Total-Solution_Rev-1-3.pdf
> 
> Signed-off-by: Douglas Anderson <dianders@chromium.org>
> ---
>  .../devicetree/bindings/mmc/arasan,sdhci.txt       | 27 ++++++++++++++++++++--
>  1 file changed, 25 insertions(+), 2 deletions(-)

Acked-by: Rob Herring <robh@kernel.org>
Shawn Lin June 13, 2016, 8:18 a.m. UTC | #2
On 2016/6/8 6:44, Douglas Anderson wrote:
> As can be seen in Arasan's datasheet [1] there are several "corecfg"
> settings in their SDHCI IP Block that are supposed to be controlled by
> software.  Although the datasheet referenced is a bit vague about how to
> access corecfg, in Figure 5 you can see that for Arasan's PHY (a
> separate component than their SDHCI component) they describe the
> "phyctrl" registers as being "FROM SOC CTL REG", implying that it's up
> to the licensee of the Arasan IP block to implement these registers.  It
> seems sane to assume that the "corecfg" registers in their SDHCI IP
> block works in a similar way for all licensees of the IP Block.
>
> Device tree has a model that allows a device to get a reference to
> random registers located elsewhere in the SoC: sysctl.  Let's leverage
> this model and allow adding a sysctl reference to access the control
> registers for the Arasan SDHCI PHYs.
>
> Having a reference to the control registers doesn't do much for us on
> its own since the Arasan spec doesn't specify how these corecfg values
> are laid out in memory.  In the SDHCI driver we'll need a map detailing
> where each corecfg can be found in each implementation.  This map can be
> found using the primary compatible string of the SDHCI device.  In that
> spirit, document that existing rk3399 device trees already have a
> specific compatible string, though up to now they've always been relying
> on the driver supporting the generic.
>
> Note that since existing devices seem to work fairly well as-is, we'll
> list the syscon reference as "optional", but it's likely that we'll run
> into much fewer problems if we can actually set the proper values in the
> syscon, so it is strongly suggested that any SoCs where we have a map to
> set the corecfg also include a reference to the syscon.

yes, the interaction of phy and controller should be more explicitly
now. Why not make it mandatory for arasan,sdhci-5.1.

>
> [1]: https://arasan.com/wp-content/media/eMMC-5-1-Total-Solution_Rev-1-3.pdf
>
> Signed-off-by: Douglas Anderson <dianders@chromium.org>
> ---
>  .../devicetree/bindings/mmc/arasan,sdhci.txt       | 27 ++++++++++++++++++++--
>  1 file changed, 25 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
> index 31b35c3a5e47..b67e623ca1ff 100644
> --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
> +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
> @@ -9,8 +9,12 @@ Device Tree Bindings for the Arasan SDHCI Controller
>    [4] Documentation/devicetree/bindings/phy/phy-bindings.txt
>
>  Required Properties:
> -  - compatible: Compatibility string. Must be 'arasan,sdhci-8.9a' or
> -                'arasan,sdhci-4.9a' or 'arasan,sdhci-5.1'
> +  - compatible: Compatibility string.  One of:
> +    - "arasan,sdhci-8.9a"
> +    - "arasan,sdhci-4.9a"
> +    - "arasan,sdhci-5.1"
> +    - "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1": The PHY in rk3399.

The PHY in rk3399?

> +      For this device it is strongly suggested to include arasan,soc-ctl-syscon.
>    - reg: From mmc bindings: Register location and length.
>    - clocks: From clock bindings: Handles to clock inputs.
>    - clock-names: From clock bindings: Tuple including "clk_xin" and "clk_ahb"
> @@ -22,6 +26,11 @@ Required Properties for "arasan,sdhci-5.1":
>    - phys: From PHY bindings: Phandle for the Generic PHY for arasan.
>    - phy-names:  MUST be "phy_arasan".
>
> +Optional Properties:
> +  - arasan,soc-ctl-syscon: A phandle to a syscon device (see ../mfd/syscon.txt)
> +    used to access core corecfg registers.  Offsets of registers in this
> +    syscon are determined based on the main compatible string for the device.
> +
>  Example:
>  	sdhci@e0100000 {
>  		compatible = "arasan,sdhci-8.9a";
> @@ -42,3 +51,17 @@ Example:
>  		phys = <&emmc_phy>;
>  		phy-names = "phy_arasan";
>  	} ;
> +
> +	sdhci: sdhci@fe330000 {
> +		compatible = "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1";
> +		reg = <0x0 0xfe330000 0x0 0x10000>;
> +		interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
> +		clocks = <&cru SCLK_EMMC>, <&cru ACLK_EMMC>;
> +		clock-names = "clk_xin", "clk_ahb";
> +		arasan,soc-ctl-syscon = <&grf>;
> +		assigned-clocks = <&cru SCLK_EMMC>;
> +		assigned-clock-rates = <200000000>;
> +		phys = <&emmc_phy>;
> +		phy-names = "phy_arasan";
> +		status = "disabled";
> +	};
>
Heiko Stuebner June 13, 2016, 9:32 a.m. UTC | #3
Am Montag, 13. Juni 2016, 16:18:24 schrieb Shawn Lin:
> On 2016/6/8 6:44, Douglas Anderson wrote:
> > As can be seen in Arasan's datasheet [1] there are several "corecfg"
> > settings in their SDHCI IP Block that are supposed to be controlled by
> > software.  Although the datasheet referenced is a bit vague about how to
> > access corecfg, in Figure 5 you can see that for Arasan's PHY (a
> > separate component than their SDHCI component) they describe the
> > "phyctrl" registers as being "FROM SOC CTL REG", implying that it's up
> > to the licensee of the Arasan IP block to implement these registers.  It
> > seems sane to assume that the "corecfg" registers in their SDHCI IP
> > block works in a similar way for all licensees of the IP Block.
> > 
> > Device tree has a model that allows a device to get a reference to
> > random registers located elsewhere in the SoC: sysctl.  Let's leverage
> > this model and allow adding a sysctl reference to access the control
> > registers for the Arasan SDHCI PHYs.
> > 
> > Having a reference to the control registers doesn't do much for us on
> > its own since the Arasan spec doesn't specify how these corecfg values
> > are laid out in memory.  In the SDHCI driver we'll need a map detailing
> > where each corecfg can be found in each implementation.  This map can be
> > found using the primary compatible string of the SDHCI device.  In that
> > spirit, document that existing rk3399 device trees already have a
> > specific compatible string, though up to now they've always been relying
> > on the driver supporting the generic.
> > 
> > Note that since existing devices seem to work fairly well as-is, we'll
> > list the syscon reference as "optional", but it's likely that we'll run
> > into much fewer problems if we can actually set the proper values in the
> > syscon, so it is strongly suggested that any SoCs where we have a map to
> > set the corecfg also include a reference to the syscon.
> 
> yes, the interaction of phy and controller should be more explicitly
> now. Why not make it mandatory for arasan,sdhci-5.1.

The omnipresent backwards-compatiblity :-) .

The binding did not require any of this in the past, so the driver should 
always also work with devicetrees created according to this old binding.

And obviously it was working without that before as well, as Doug stated.


Heiko
Douglas Anderson June 13, 2016, 11:07 p.m. UTC | #4
Hi,

On Mon, Jun 13, 2016 at 1:18 AM, Shawn Lin <shawn.lin@rock-chips.com> wrote:
> On 2016/6/8 6:44, Douglas Anderson wrote:
>>
>> As can be seen in Arasan's datasheet [1] there are several "corecfg"
>> settings in their SDHCI IP Block that are supposed to be controlled by
>> software.  Although the datasheet referenced is a bit vague about how to
>> access corecfg, in Figure 5 you can see that for Arasan's PHY (a
>> separate component than their SDHCI component) they describe the
>> "phyctrl" registers as being "FROM SOC CTL REG", implying that it's up
>> to the licensee of the Arasan IP block to implement these registers.  It
>> seems sane to assume that the "corecfg" registers in their SDHCI IP
>> block works in a similar way for all licensees of the IP Block.
>>
>> Device tree has a model that allows a device to get a reference to
>> random registers located elsewhere in the SoC: sysctl.  Let's leverage
>> this model and allow adding a sysctl reference to access the control
>> registers for the Arasan SDHCI PHYs.
>>
>> Having a reference to the control registers doesn't do much for us on
>> its own since the Arasan spec doesn't specify how these corecfg values
>> are laid out in memory.  In the SDHCI driver we'll need a map detailing
>> where each corecfg can be found in each implementation.  This map can be
>> found using the primary compatible string of the SDHCI device.  In that
>> spirit, document that existing rk3399 device trees already have a
>> specific compatible string, though up to now they've always been relying
>> on the driver supporting the generic.
>>
>> Note that since existing devices seem to work fairly well as-is, we'll
>> list the syscon reference as "optional", but it's likely that we'll run
>> into much fewer problems if we can actually set the proper values in the
>> syscon, so it is strongly suggested that any SoCs where we have a map to
>> set the corecfg also include a reference to the syscon.
>
>
> yes, the interaction of phy and controller should be more explicitly
> now. Why not make it mandatory for arasan,sdhci-5.1.
>
>>
>> [1]:
>> https://arasan.com/wp-content/media/eMMC-5-1-Total-Solution_Rev-1-3.pdf
>>
>> Signed-off-by: Douglas Anderson <dianders@chromium.org>
>> ---
>>  .../devicetree/bindings/mmc/arasan,sdhci.txt       | 27
>> ++++++++++++++++++++--
>>  1 file changed, 25 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
>> b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
>> index 31b35c3a5e47..b67e623ca1ff 100644
>> --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
>> +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
>> @@ -9,8 +9,12 @@ Device Tree Bindings for the Arasan SDHCI Controller
>>    [4] Documentation/devicetree/bindings/phy/phy-bindings.txt
>>
>>  Required Properties:
>> -  - compatible: Compatibility string. Must be 'arasan,sdhci-8.9a' or
>> -                'arasan,sdhci-4.9a' or 'arasan,sdhci-5.1'
>> +  - compatible: Compatibility string.  One of:
>> +    - "arasan,sdhci-8.9a"
>> +    - "arasan,sdhci-4.9a"
>> +    - "arasan,sdhci-5.1"
>> +    - "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1": The PHY in rk3399.
>
>
> The PHY in rk3399?

I presume that you found the above confusing?  I changed it to:

  - compatible: Compatibility string.  One of:
    - "arasan,sdhci-8.9a": generic Arasan SDHCI 8.9a PHY
    - "arasan,sdhci-4.9a": generic Arasan SDHCI 4.9a PHY
    - "arasan,sdhci-5.1": generic Arasan SDHCI 5.1 PHY
    - "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1": rk3399 eMMC PHY
      For this device it is strongly suggested to include arasan,soc-ctl-syscon.

I kept Rob's Ack since those changes didn't seem too major.  I will
remove it if requested.

-Doug

Patch
diff mbox

diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
index 31b35c3a5e47..b67e623ca1ff 100644
--- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
+++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt
@@ -9,8 +9,12 @@  Device Tree Bindings for the Arasan SDHCI Controller
   [4] Documentation/devicetree/bindings/phy/phy-bindings.txt
 
 Required Properties:
-  - compatible: Compatibility string. Must be 'arasan,sdhci-8.9a' or
-                'arasan,sdhci-4.9a' or 'arasan,sdhci-5.1'
+  - compatible: Compatibility string.  One of:
+    - "arasan,sdhci-8.9a"
+    - "arasan,sdhci-4.9a"
+    - "arasan,sdhci-5.1"
+    - "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1": The PHY in rk3399.
+      For this device it is strongly suggested to include arasan,soc-ctl-syscon.
   - reg: From mmc bindings: Register location and length.
   - clocks: From clock bindings: Handles to clock inputs.
   - clock-names: From clock bindings: Tuple including "clk_xin" and "clk_ahb"
@@ -22,6 +26,11 @@  Required Properties for "arasan,sdhci-5.1":
   - phys: From PHY bindings: Phandle for the Generic PHY for arasan.
   - phy-names:  MUST be "phy_arasan".
 
+Optional Properties:
+  - arasan,soc-ctl-syscon: A phandle to a syscon device (see ../mfd/syscon.txt)
+    used to access core corecfg registers.  Offsets of registers in this
+    syscon are determined based on the main compatible string for the device.
+
 Example:
 	sdhci@e0100000 {
 		compatible = "arasan,sdhci-8.9a";
@@ -42,3 +51,17 @@  Example:
 		phys = <&emmc_phy>;
 		phy-names = "phy_arasan";
 	} ;
+
+	sdhci: sdhci@fe330000 {
+		compatible = "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1";
+		reg = <0x0 0xfe330000 0x0 0x10000>;
+		interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
+		clocks = <&cru SCLK_EMMC>, <&cru ACLK_EMMC>;
+		clock-names = "clk_xin", "clk_ahb";
+		arasan,soc-ctl-syscon = <&grf>;
+		assigned-clocks = <&cru SCLK_EMMC>;
+		assigned-clock-rates = <200000000>;
+		phys = <&emmc_phy>;
+		phy-names = "phy_arasan";
+		status = "disabled";
+	};