[PATCH v2 1/2] usb: samsung: Update Exynos EHCI/OHCI bindings documentation

[PATCH v2 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>
---
Changes since v1:
* Updated review comments from Stephen Warren regarding the wording
and some styling.
---
 .../devicetree/bindings/usb/exynos-usb.txt         |   29 ++++++++++----------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt
index d967ba1..56468f7 100644
--- a/Documentation/devicetree/bindings/usb/exynos-usb.txt
+++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt
@@ -5,13 +5,14 @@ The device node has following properties.
 
 EHCI
 Required properties:
- - compatible: should be "samsung,exynos4210-ehci" for USB 2.0
-   EHCI controller in host mode.
+ - compatible: should be one of the following for USB 2.0 EHCI controller:
+	(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: shall be "usbhost".
 
 Optional properties:
  - samsung,vbus-gpio:  if present, specifies the GPIO that
@@ -23,7 +24,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 +32,14 @@ Example:
 
 OHCI
 Required properties:
- - compatible: should be "samsung,exynos4210-ohci" for USB 2.0
-   OHCI companion controller in host mode.
+ - compatible: should be one of the following for USB 2.0 OHCI controller:
+	(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: shall be "usbhost".
 
 Example:
 	usb@12120000 {
@@ -53,12 +55,11 @@ DWC3
 Required properties:
  - 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.
+ - #address-cells, #size-cells: should be '1'.
  - 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
+ - clock-names: shall be "usbdrd30".
 
 Sub-nodes:
 The dwc3 core should be added as subnode to Exynos dwc3 glue.
-- 
1.7.9.5

[PATCH v2 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     |   53 ++++++++------------
 1 file changed, 22 insertions(+), 31 deletions(-)

diff --git a/Documentation/devicetree/bindings/usb/samsung-usbphy.txt b/Documentation/devicetree/bindings/usb/samsung-usbphy.txt
index 33fd354..a088a30 100644
--- a/Documentation/devicetree/bindings/usb/samsung-usbphy.txt
+++ b/Documentation/devicetree/bindings/usb/samsung-usbphy.txt
@@ -1,40 +1,35 @@
 SAMSUNG USB-PHY controllers
 
-** Samsung's usb 2.0 phy transceiver
+** Samsung 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 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
+- 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 clock correseponding IDs clock property as requested
-	       by the controller driver.
-
-Exynos5250:
-- compatible : should be "samsung,exynos5250-usb2phy"
-- reg : base physical address of the phy registers and length of memory mapped
-	region.
+- clock-names: shall be "usbhost" for Exynos5250 and "otg" for others.
 
 Optional properties:
-- #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'
-	       property.
+- #address-cells: should be '1'.
+- #size-cells: should be '1'.
 - 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
   interface for usb-phy. It should provide the following information required by
   usb-phy controller to control phy.
-  - reg : base physical address of PHY_CONTROL registers.
+  - reg: base physical address of PHY_CONTROL registers.
 	  The size of this register is the total sum of size of all PHY_CONTROL
 	  registers that the SoC has. For example, the size will be
 	  '0x4' in case we have only one PHY_CONTROL register (e.g.
@@ -62,28 +57,24 @@ Example:
 		};
 	};
 
+** Samsung 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 SoCs 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:
 
 Exynos5250:
-- compatible : should be "samsung,exynos5250-usb3phy"
-- reg : base physical address of the phy registers and length of memory mapped
+- 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
-	       as requested by the controller driver.
+- clock-names: shall be "usbdrd30".
 
 Optional properties:
-- #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'
-	       property.
+- #address-cells: should be '1'.
+- #size-cells: should be '1'.
 - ranges: allows valid translation between child's address space and parent's
 	  address space.
 
-- 
1.7.9.5

Re: [PATCH v2 1/2] usb: samsung: Update Exynos EHCI/OHCI bindings documentation

[Mark Rutland]

Hi,

On Thu, Aug 29, 2013 at 12:33:25PM +0100, Sachin Kamat wrote:
> 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>
> ---
> Changes since v1:
> * Updated review comments from Stephen Warren regarding the wording
> and some styling.
> ---
>  .../devicetree/bindings/usb/exynos-usb.txt         |   29 ++++++++++----------
>  1 file changed, 15 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt
> index d967ba1..56468f7 100644
> --- a/Documentation/devicetree/bindings/usb/exynos-usb.txt
> +++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt
> @@ -5,13 +5,14 @@ The device node has following properties.
>  
>  EHCI
>  Required properties:
> - - compatible: should be "samsung,exynos4210-ehci" for USB 2.0
> -   EHCI controller in host mode.
> + - compatible: should be one of the following for USB 2.0 EHCI controller:
> +	(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.

If this is going to be reorganised, can we fix the terminology?
Interrupts are defined by interrupt-specifiers:

 - interrupts: a single interrupt-specifier for the sole interrupt
               generated by the device.

> + - clocks: from common clock binding: handle to USB clock.
> + - clock-names: shall be "usbhost".

Similarly:

 - clocks: phandle amd clock-specifier pair for the clocks listed in
   clock-names.
 - clock-names: shall contain "usbhost" for the USB clock.

>  
>  Optional properties:
>   - samsung,vbus-gpio:  if present, specifies the GPIO that
> @@ -23,7 +24,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>;

Why does the gpio in the example need to be changed in this way?

>  
>  		clocks = <&clock 285>;
>  		clock-names = "usbhost";
> @@ -31,13 +32,14 @@ Example:
>  
>  OHCI
>  Required properties:
> - - compatible: should be "samsung,exynos4210-ohci" for USB 2.0
> -   OHCI companion controller in host mode.
> + - compatible: should be one of the following for USB 2.0 OHCI controller:
> +	(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: shall be "usbhost".

Similarly it would be nice to fix up the terminology here.

>  
>  Example:
>  	usb@12120000 {
> @@ -53,12 +55,11 @@ DWC3
>  Required properties:
>   - 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.
> + - #address-cells, #size-cells: should be '1'.
>   - ranges: allows valid 1:1 translation between child's address space and
>  	   parent's address space

Huh? What if I'm on an LPAE system. I can't necessarily have both an
empty ranges property (for 1:1 translation) and #address-cells = <1>,
#size-cells = <1>. That's just broken.

Is the driver relying on this, or does it just require some valid
ranges, #address-cells, and #size-cells that the Linux infrastructure
can already handle?

As far as I an see, this should be something like:

- #address-cells: as required to describe any child nodes.

- #size-cells: as required to describe any child nodes.

- ranges: as required to map any child nodes to the parent address space.

>   - clocks: Clock IDs array as required by the controller.
> - - clock-names: names of clocks correseponding to IDs in the clock property
> + - clock-names: shall be "usbdrd30".

It would be nice to fix up the terminology here too.

Thanks,
Mark.