[1/2] Documentation: bindings: add DT documentation for Rockchip USB2PHY
diff mbox

Message ID 1464676811-7418-2-git-send-email-frank.wang@rock-chips.com
State New
Headers show

Commit Message

Frank Wang May 31, 2016, 6:40 a.m. UTC
Signed-off-by: Frank Wang <frank.wang@rock-chips.com>
---
 .../bindings/phy/phy-rockchip-inno-usb2.txt        |   48 ++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt

Comments

Heiko Stübner May 31, 2016, 9:02 a.m. UTC | #1
Hi Frank,

Am Dienstag, 31. Mai 2016, 14:40:10 schrieb Frank Wang:
> Signed-off-by: Frank Wang <frank.wang@rock-chips.com>
> ---
>  .../bindings/phy/phy-rockchip-inno-usb2.txt        |   48
> ++++++++++++++++++++ 1 file changed, 48 insertions(+)
>  create mode 100644
> Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
> 
> diff --git
> a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
> b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt new file
> mode 100644
> index 0000000..4e537b2
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
> @@ -0,0 +1,48 @@
> +ROCKCHIP USB2.0 PHY WITH INNO IP BLOCK
> +
> +Required properties (phy (parent) node):
> + - compatible: should contain:
> +	* "rockchip,rk3366-usb2phy"
> + - #clock-cells: should be 0.
> + - clock-names: specify the 480m output clk name.
> +
> +Optional properties:
> + - vbus_host-gpio: pull gpio high/low to control the host vbus power.

sorry for not catching that in our earlier talks, but I believe this should be 
a regulator instead. See for example vcc5_host1, vcc5v_otg in rk3288-veyron-
chromebook.dtsi .


> +Required nodes: a sub-node is required for each port the phy provides.
> +		The sub-node name is used to identify host or otg port.
> +
> +Required properties (port (child) node):
> + - #phy-cells: must be 0. See ./phy-bindings.txt for details.
> + - interrupts: irq number for host/otg port.

make that something like:
Specify an interrupt for each entry in interrupt-names.

> + - interrupt-names: interrupt name, in line with irq number.

make that something like:
Shall be "linestate" for the linestate interrupt.
---

You might want to add the bvalid and id interrupts for the otg phys as well 
already - would make handling legacy devicetree files easier. [= if they get 
specified later, the driver would always need to also handle devicetrees where 
they aren't specified].


Heiko
Frank Wang June 1, 2016, 8:09 a.m. UTC | #2
Hi Heiko,

On 05/31/2016 05:02 PM, Heiko Stübner wrote:
> Hi Frank,
>
> Am Dienstag, 31. Mai 2016, 14:40:10 schrieb Frank Wang:
>> Signed-off-by: Frank Wang <frank.wang@rock-chips.com>
>> ---
>>   .../bindings/phy/phy-rockchip-inno-usb2.txt        |   48
>> ++++++++++++++++++++ 1 file changed, 48 insertions(+)
>>   create mode 100644
>> Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
>>
>> diff --git
>> a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
>> b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt new file
>> mode 100644
>> index 0000000..4e537b2
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
>> @@ -0,0 +1,48 @@
>> +ROCKCHIP USB2.0 PHY WITH INNO IP BLOCK
>> +
>> +Required properties (phy (parent) node):
>> + - compatible: should contain:
>> +	* "rockchip,rk3366-usb2phy"
>> + - #clock-cells: should be 0.
>> + - clock-names: specify the 480m output clk name.
>> +
>> +Optional properties:
>> + - vbus_host-gpio: pull gpio high/low to control the host vbus power.
>
> sorry for not catching that in our earlier talks, but I believe this should be
> a regulator instead. See for example vcc5_host1, vcc5v_otg in rk3288-veyron-
> chromebook.dtsi .
>

That is OK, I will correct it in the next version.

>
>> +Required nodes: a sub-node is required for each port the phy provides.
>> +		The sub-node name is used to identify host or otg port.
>> +
>> +Required properties (port (child) node):
>> + - #phy-cells: must be 0. See ./phy-bindings.txt for details.
>> + - interrupts: irq number for host/otg port.
>
> make that something like:
> Specify an interrupt for each entry in interrupt-names.
>
>> + - interrupt-names: interrupt name, in line with irq number.
>
> make that something like:
> Shall be "linestate" for the linestate interrupt.

Yeah, Got it.

> ---
>
> You might want to add the bvalid and id interrupts for the otg phys as well
> already - would make handling legacy devicetree files easier. [= if they get
> specified later, the driver would always need to also handle devicetrees where
> they aren't specified].
>

Hmmm! you mean that I can specify these properties into documentation, 
even if the driver have not handled (implemented) them in current?

BR.
Frank
Rob Herring June 1, 2016, 10:02 p.m. UTC | #3
On Tue, May 31, 2016 at 1:40 AM, Frank Wang <frank.wang@rock-chips.com> wrote:
> Signed-off-by: Frank Wang <frank.wang@rock-chips.com>

Please resend to DT list.

> ---
>  .../bindings/phy/phy-rockchip-inno-usb2.txt        |   48 ++++++++++++++++++++
>  1 file changed, 48 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
>
> diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
> new file mode 100644
> index 0000000..4e537b2
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
> @@ -0,0 +1,48 @@
> +ROCKCHIP USB2.0 PHY WITH INNO IP BLOCK
> +
> +Required properties (phy (parent) node):
> + - compatible: should contain:
> +       * "rockchip,rk3366-usb2phy"
> + - #clock-cells: should be 0.
> + - clock-names: specify the 480m output clk name.
> +
> +Optional properties:
> + - vbus_host-gpio: pull gpio high/low to control the host vbus power.
> +
> +Required nodes: a sub-node is required for each port the phy provides.
> +               The sub-node name is used to identify host or otg port.
> +
> +Required properties (port (child) node):
> + - #phy-cells: must be 0. See ./phy-bindings.txt for details.
> + - interrupts: irq number for host/otg port.
> + - interrupt-names: interrupt name, in line with irq number.
> +
> +Example:
> +
> +grf: syscon@ff770000 {
> +       compatible = "rockchip,rk3366-grf", "syscon", "simple-mfd";
> +       #address-cells = <1>;
> +       #size-cells = <1>;
> +
> +...
> +
> +       u2phy: usb2-phy {
> +               compatible = "rockchip,rk3366-usb2phy";
> +               #clock-cells = <0>;
> +               clock-output-names = "sclk_otgphy0_480m";
> +
> +               u2phy_otg: otg-port {
> +                       #phy-cells = <0>;
> +                       interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>;
> +                       interrupt-names = "linestate";
> +                       status = "okay";
> +               };
> +
> +               u2phy_host: host-port {
> +                       #phy-cells = <0>;
> +                       interrupts = <GIC_SPI 96 IRQ_TYPE_LEVEL_HIGH>;
> +                       interrupt-names = "linestate";
> +                       status = "okay";
> +               };
> +       };
> +};
> --
> 1.7.9.5
>
>
Heiko Stübner June 1, 2016, 10:17 p.m. UTC | #4
Hi Frank,

Am Mittwoch, 1. Juni 2016, 16:09:41 schrieb Frank Wang:
> > You might want to add the bvalid and id interrupts for the otg phys as
> > well
> > already - would make handling legacy devicetree files easier. [= if they
> > get specified later, the driver would always need to also handle
> > devicetrees where they aren't specified].
> 
> Hmmm! you mean that I can specify these properties into documentation,
> even if the driver have not handled (implemented) them in current?

The devicetree bindings are supposed to be a generic hardware-description.
And a driver then simply implements that binding. So if the interrupt is part 
of the hardware it can be part of the binding, independent of the driver.

I guess it really comes down to, will you need those interrupts later in the 
driver, then they should definitly be specified now, as later on you cannot 
require them anymore and always need to also support devicetrees not having 
them.


Heiko
Frank Wang June 2, 2016, 2:53 a.m. UTC | #5
Hi Heiko,

On 06/02/2016 06:17 AM, Heiko Stübner wrote:
> Hi Frank,
>
> Am Mittwoch, 1. Juni 2016, 16:09:41 schrieb Frank Wang:
>>> You might want to add the bvalid and id interrupts for the otg phys as
>>> well
>>> already - would make handling legacy devicetree files easier. [= if they
>>> get specified later, the driver would always need to also handle
>>> devicetrees where they aren't specified].
>>
>> Hmmm! you mean that I can specify these properties into documentation,
>> even if the driver have not handled (implemented) them in current?
>
> The devicetree bindings are supposed to be a generic hardware-description.
> And a driver then simply implements that binding. So if the interrupt is part
> of the hardware it can be part of the binding, independent of the driver.
>
> I guess it really comes down to, will you need those interrupts later in the
> driver, then they should definitly be specified now, as later on you cannot
> require them anymore and always need to also support devicetrees not having
> them.
>

Got it, I have already added them in the new patches which I will hand 
out later.

BR.
Frank

Patch
diff mbox

diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
new file mode 100644
index 0000000..4e537b2
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt
@@ -0,0 +1,48 @@ 
+ROCKCHIP USB2.0 PHY WITH INNO IP BLOCK
+
+Required properties (phy (parent) node):
+ - compatible: should contain:
+	* "rockchip,rk3366-usb2phy"
+ - #clock-cells: should be 0.
+ - clock-names: specify the 480m output clk name.
+
+Optional properties:
+ - vbus_host-gpio: pull gpio high/low to control the host vbus power.
+
+Required nodes: a sub-node is required for each port the phy provides.
+		The sub-node name is used to identify host or otg port.
+
+Required properties (port (child) node):
+ - #phy-cells: must be 0. See ./phy-bindings.txt for details.
+ - interrupts: irq number for host/otg port.
+ - interrupt-names: interrupt name, in line with irq number.
+
+Example:
+
+grf: syscon@ff770000 {
+	compatible = "rockchip,rk3366-grf", "syscon", "simple-mfd";
+	#address-cells = <1>;
+	#size-cells = <1>;
+
+...
+
+	u2phy: usb2-phy {
+		compatible = "rockchip,rk3366-usb2phy";
+		#clock-cells = <0>;
+		clock-output-names = "sclk_otgphy0_480m";
+
+		u2phy_otg: otg-port {
+			#phy-cells = <0>;
+			interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>;
+			interrupt-names = "linestate";
+			status = "okay";
+		};
+
+		u2phy_host: host-port {
+			#phy-cells = <0>;
+			interrupts = <GIC_SPI 96 IRQ_TYPE_LEVEL_HIGH>;
+			interrupt-names = "linestate";
+			status = "okay";
+		};
+	};
+};