[PATCH Resend 1/2] usb: samsung: Update Exynos ehci/ohci bindings documentation

[PATCH Resend 1/2] usb: samsung: Update Exynos ehci/ohci bindings documentation

[Sachin Kamat]

Updated the document as per the latest implementation.
While at it also fixed some trivial typos.

Signed-off-by: Sachin Kamat <sachin.kamat@linaro.org>
---
 .../devicetree/bindings/usb/exynos-usb.txt         |   38 +++++++++++---------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt
index d967ba1..16a2c0f 100644
--- a/Documentation/devicetree/bindings/usb/exynos-usb.txt
+++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt
@@ -5,13 +5,15 @@ The device node has following properties.
 
 EHCI
 Required properties:
- - compatible: should be "samsung,exynos4210-ehci" for USB 2.0
-   EHCI controller in host mode.
- - reg: physical base address of the controller and length of memory mapped
+ - compatible : should be one of the following for USB 2.0 EHCI controller
+		in host mode:
+	(a) "samsung,exynos5440-ehci" for Exynos5440 SoC
+	(b) "samsung,exynos4210-ehci" for all other Exynos4 and 5 SoCs
+ - reg : physical base address of the controller and length of memory mapped
    region.
- - interrupts: interrupt number to the cpu.
- - clocks: from common clock binding: handle to usb clock.
- - clock-names: from common clock binding: Shall be "usbhost".
+ - interrupts : interrupt number to the CPU.
+ - clocks : from common clock binding: handle to USB clock.
+ - clock-names : from common clock binding: Shall be "usbhost".
 
 Optional properties:
  - samsung,vbus-gpio:  if present, specifies the GPIO that
@@ -23,7 +25,7 @@ Example:
 		compatible = "samsung,exynos4210-ehci";
 		reg = <0x12110000 0x100>;
 		interrupts = <0 71 0>;
-		samsung,vbus-gpio = <&gpx2 6 1 3 3>;
+		samsung,vbus-gpio = <&gpx2 6 0>;
 
 		clocks = <&clock 285>;
 		clock-names = "usbhost";
@@ -31,13 +33,15 @@ Example:
 
 OHCI
 Required properties:
- - compatible: should be "samsung,exynos4210-ohci" for USB 2.0
-   OHCI companion controller in host mode.
- - reg: physical base address of the controller and length of memory mapped
+ - compatible : should be one of the following for USB 2.0 OHCI companion
+		controller in host mode:
+	(a) "samsung,exynos5440-ohci" for Exynos5440 SoC
+	(b) "samsung,exynos4210-ohci" for all other Exynos4 and 5 SoCs
+ - reg : physical base address of the controller and length of memory mapped
    region.
- - interrupts: interrupt number to the cpu.
- - clocks: from common clock binding: handle to usb clock.
- - clock-names: from common clock binding: Shall be "usbhost".
+ - interrupts : interrupt number to the CPU.
+ - clocks : from common clock binding: handle to USB clock.
+ - clock-names : from common clock binding: Shall be "usbhost".
 
 Example:
 	usb@12120000 {
@@ -51,14 +55,14 @@ Example:
 
 DWC3
 Required properties:
- - compatible: should be "samsung,exynos5250-dwusb3" for USB 3.0 DWC3
+ - compatible : should be "samsung,exynos5250-dwusb3" for USB 3.0 DWC3
 	       controller.
  - #address-cells, #size-cells : should be '1' if the device has sub-nodes
 				 with 'reg' property.
- - ranges: allows valid 1:1 translation between child's address space and
+ - ranges : allows valid 1:1 translation between child's address space and
 	   parent's address space
- - clocks: Clock IDs array as required by the controller.
- - clock-names: names of clocks correseponding to IDs in the clock property
+ - clocks : Clock IDs array as required by the controller.
+ - clock-names : names of clocks corresponding to IDs in the clock property
 
 Sub-nodes:
 The dwc3 core should be added as subnode to Exynos dwc3 glue.
-- 
1.7.9.5

[PATCH Resend 2/2] usb: phy: samsung: Update usbphy documentation

[Sachin Kamat]

Updated the documentation as per the latest driver implementation.
While at it also fixed some trivial typos.

Signed-off-by: Sachin Kamat <sachin.kamat@linaro.org>
Acked-by: Felipe Balbi <balbi@ti.com>
---
 .../devicetree/bindings/usb/samsung-usbphy.txt     |   48 ++++++++++----------
 1 file changed, 23 insertions(+), 25 deletions(-)

diff --git a/Documentation/devicetree/bindings/usb/samsung-usbphy.txt b/Documentation/devicetree/bindings/usb/samsung-usbphy.txt
index 33fd354..62e6f17 100644
--- a/Documentation/devicetree/bindings/usb/samsung-usbphy.txt
+++ b/Documentation/devicetree/bindings/usb/samsung-usbphy.txt
@@ -1,34 +1,32 @@
 SAMSUNG USB-PHY controllers
 
-** Samsung's usb 2.0 phy transceiver
+** Samsung's USB 2.0 phy transceiver
 
-The Samsung's usb 2.0 phy transceiver is used for controlling
-usb 2.0 phy for s3c-hsotg as well as ehci-s5p and ohci-exynos
-usb controllers across Samsung SOCs.
+The Samsung's USB 2.0 phy transceiver is used for controlling
+USB 2.0 phy for s3c-hsotg as well as ehci-s5p and ohci-exynos
+USB controllers across Samsung SOCs.
 TODO: Adding the PHY binding with controller(s) according to the under
 development generic PHY driver.
 
 Required properties:
 
-Exynos4210:
-- compatible : should be "samsung,exynos4210-usb2phy"
-- reg : base physical address of the phy registers and length of memory mapped
-	region.
-- clocks: Clock IDs array as required by the controller.
-- clock-names: names of clock correseponding IDs clock property as requested
-	       by the controller driver.
-
-Exynos5250:
-- compatible : should be "samsung,exynos5250-usb2phy"
+- compatible : value should be one among the following:
+	(a) "samsung,s3c64xx-usb2phy" for S3C64xx SoCs
+	(b) "samsung,exynos4210-usb2phy" for Exynos4210 SoC
+	(c) "samsung,exynos4x12-usb2phy" for Exynos4x12 SoCs
+	(d) "samsung,exynos5250-usb2phy" for Exynos5250 SoC
 - reg : base physical address of the phy registers and length of memory mapped
 	region.
+- clocks : Clock IDs array as required by the controller.
+- clock-names : names of clocks listed in clocks property in the same order
+	       as requested by the controller driver.
 
 Optional properties:
-- #address-cells: should be '1' when usbphy node has a child node with 'reg'
+- #address-cellsi : should be '1' when usbphy node has a child node with 'reg'
 		  property.
-- #size-cells: should be '1' when usbphy node has a child node with 'reg'
+- #size-cells : should be '1' when usbphy node has a child node with 'reg'
 	       property.
-- ranges: allows valid translation between child's address space and parent's
+- ranges : allows valid translation between child's address space and parent's
 	  address space.
 
 - The child node 'usbphy-sys' to the node 'usbphy' is for the system controller
@@ -63,10 +61,10 @@ Example:
 	};
 
 
-** Samsung's usb 3.0 phy transceiver
+** Samsung's USB 3.0 phy transceiver
 
-Starting exynso5250, Samsung's SoC have usb 3.0 phy transceiver
-which is used for controlling usb 3.0 phy for dwc3-exynos usb 3.0
+Starting Exynos5250, Samsung's SoC have USB 3.0 phy transceiver
+which is used for controlling USB 3.0 phy for dwc3-exynos USB 3.0
 controllers across Samsung SOCs.
 
 Required properties:
@@ -75,16 +73,16 @@ Exynos5250:
 - compatible : should be "samsung,exynos5250-usb3phy"
 - reg : base physical address of the phy registers and length of memory mapped
 	region.
-- clocks: Clock IDs array as required by the controller.
-- clock-names: names of clocks correseponding to IDs in the clock property
+- clocks : Clock IDs array as required by the controller.
+- clock-names : names of clocks correseponding to IDs in the clock property
 	       as requested by the controller driver.
 
 Optional properties:
-- #address-cells: should be '1' when usbphy node has a child node with 'reg'
+- #address-cells : should be '1' when usbphy node has a child node with 'reg'
 		  property.
-- #size-cells: should be '1' when usbphy node has a child node with 'reg'
+- #size-cells : should be '1' when usbphy node has a child node with 'reg'
 	       property.
-- ranges: allows valid translation between child's address space and parent's
+- ranges : allows valid translation between child's address space and parent's
 	  address space.
 
 - The child node 'usbphy-sys' to the node 'usbphy' is for the system controller
-- 
1.7.9.5

Re: [PATCH Resend 1/2] usb: samsung: Update Exynos ehci/ohci bindings documentation

[Stephen Warren]

On 08/14/2013 05:22 AM, Sachin Kamat wrote:
> Updated the document as per the latest implementation.
> While at it also fixed some trivial typos.

> diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt

>  EHCI
>  Required properties:
> - - compatible: should be "samsung,exynos4210-ehci" for USB 2.0
> -   EHCI controller in host mode.
> - - reg: physical base address of the controller and length of memory mapped
> + - compatible : should be one of the following for USB 2.0 EHCI controller
> +		in host mode:
> +	(a) "samsung,exynos5440-ehci" for Exynos5440 SoC
> +	(b) "samsung,exynos4210-ehci" for all other Exynos4 and 5 SoCs

I'm not sure the text "in host mode" belongs there. The DT should
describe the presence of the EHCI controller HW module. Whether the
module is programmed for host mode or device mode is surely a run-time
decision, not something that would need different DT bindings?

Re: [PATCH Resend 2/2] usb: phy: samsung: Update usbphy documentation

[Stephen Warren]

On 08/14/2013 05:22 AM, Sachin Kamat wrote:
> Updated the documentation as per the latest driver implementation.
> While at it also fixed some trivial typos.

> diff --git a/Documentation/devicetree/bindings/usb/samsung-usbphy.txt b/Documentation/devicetree/bindings/usb/samsung-usbphy.txt

> +- clocks : Clock IDs array as required by the controller.
> +- clock-names : names of clocks listed in clocks property in the same order
> +	       as requested by the controller driver.

This is wrong. The DT binding must specify the set of required
clock-names, not the driver; bindings must be self-contained. Also, the
order shouldn't matter, since everything should be looked up by name;
all that matters is the entries in clocks/clock-names match.

>  Optional properties:
> -- #address-cells: should be '1' when usbphy node has a child node with 'reg'
> +- #address-cellsi : should be '1' when usbphy node has a child node with 'reg'
>  		  property.

Type "cellsi".

What should the value be if there is no child node? In other words, I
think just delete the text "when usbphy node has a child node with 'reg'
property.". Same for size-cells.

> -- #size-cells: should be '1' when usbphy node has a child node with 'reg'
> +- #size-cells : should be '1' when usbphy node has a child node with 'reg'
>  	       property.

I don't think it's worth changing the binding doc just to add a space
before the colon... It looks better the first way, although
unfortunately many DT binding docs have the extra space.

> +- clocks : Clock IDs array as required by the controller.
> +- clock-names : names of clocks correseponding to IDs in the clock property
>  	       as requested by the controller driver.

May as well s/correseponding/corresponding/.

Re: [PATCH Resend 1/2] usb: samsung: Update Exynos ehci/ohci bindings documentation

[Sachin Kamat]

On 15 August 2013 03:44, Stephen Warren <swarren@wwwdotorg.org> wrote:
> On 08/14/2013 05:22 AM, Sachin Kamat wrote:
>> Updated the document as per the latest implementation.
>> While at it also fixed some trivial typos.
>
>> diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt
>
>>  EHCI
>>  Required properties:
>> - - compatible: should be "samsung,exynos4210-ehci" for USB 2.0
>> -   EHCI controller in host mode.
>> - - reg: physical base address of the controller and length of memory mapped
>> + - compatible : should be one of the following for USB 2.0 EHCI controller
>> +             in host mode:
>> +     (a) "samsung,exynos5440-ehci" for Exynos5440 SoC
>> +     (b) "samsung,exynos4210-ehci" for all other Exynos4 and 5 SoCs
>
> I'm not sure the text "in host mode" belongs there. The DT should
> describe the presence of the EHCI controller HW module. Whether the
> module is programmed for host mode or device mode is surely a run-time
> decision, not something that would need different DT bindings?

Yes, you are right. Probably since our boards mostly have only the
host connector, the original author was tempted to mention it that way
which I carried forward. I will remove it and re-send. Thanks for the
review.



-- 
With warm regards,
Sachin

Re: [PATCH Resend 2/2] usb: phy: samsung: Update usbphy documentation

[Sachin Kamat]

On 15 August 2013 03:48, Stephen Warren <swarren@wwwdotorg.org> wrote:
> On 08/14/2013 05:22 AM, Sachin Kamat wrote:
>> Updated the documentation as per the latest driver implementation.
>> While at it also fixed some trivial typos.
>
>> diff --git a/Documentation/devicetree/bindings/usb/samsung-usbphy.txt b/Documentation/devicetree/bindings/usb/samsung-usbphy.txt
>
>> +- clocks : Clock IDs array as required by the controller.
>> +- clock-names : names of clocks listed in clocks property in the same order
>> +            as requested by the controller driver.
>
> This is wrong. The DT binding must specify the set of required
> clock-names, not the driver; bindings must be self-contained.
OK.

Also, the
> order shouldn't matter, since everything should be looked up by name;
> all that matters is the entries in clocks/clock-names match.

It was supposed to mean the order of clocks to clock-names (relative).
I will re-phrase it.

>
>>  Optional properties:
>> -- #address-cells: should be '1' when usbphy node has a child node with 'reg'
>> +- #address-cellsi : should be '1' when usbphy node has a child node with 'reg'
>>                 property.
>
> Type "cellsi".

right.
>
> What should the value be if there is no child node? In other words, I
> think just delete the text "when usbphy node has a child node with 'reg'
> property.". Same for size-cells.

OK

>
>> -- #size-cells: should be '1' when usbphy node has a child node with 'reg'
>> +- #size-cells : should be '1' when usbphy node has a child node with 'reg'
>>              property.
>
> I don't think it's worth changing the binding doc just to add a space
> before the colon... It looks better the first way, although
> unfortunately many DT binding docs have the extra space.

I too prefer without the extra space. However most of the Samsung
bindings do have them and hence
thought of keeping this one consistent.

>
>> +- clocks : Clock IDs array as required by the controller.
>> +- clock-names : names of clocks correseponding to IDs in the clock property
>>              as requested by the controller driver.
>
> May as well s/correseponding/corresponding/.

Right.

Thanks for your review.


 --
With warm regards,
Sachin