[v5,7/7] dt-bindings: usb: add documentation for aspeed usb-vhub
diff mbox series

Message ID 20200227230507.8682-8-rentao.bupt@gmail.com
State New
Headers show
Series
  • aspeed-g6: enable usb support
Related show

Commit Message

Tao Ren Feb. 27, 2020, 11:05 p.m. UTC
From: Tao Ren <rentao.bupt@gmail.com>

Add device tree binding documentation for the Aspeed USB 2.0 Virtual HUb
Controller.

Signed-off-by: Tao Ren <rentao.bupt@gmail.com>
Reviewed-by: Joel Stanley <joel@jms.id.au>
---
 Changes in v5:
   - updated maintainer to Ben.
   - refined patch description per Joel's suggestion.
 No change in v2/v3/v4:
   - the patch is added to the patch series since v4.

 .../bindings/usb/aspeed,usb-vhub.yaml         | 71 +++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml

Comments

Benjamin Herrenschmidt Feb. 27, 2020, 11:30 p.m. UTC | #1
On Thu, 2020-02-27 at 15:05 -0800, rentao.bupt@gmail.com wrote:

 .../...

You haven't fixed the problem spotted by Rob which is that the example
is now out of sync, it's missing the required properties.

Also long run I think best is going to have a child node per downstream
port, so we create a matching linux struct device. This will make it
easier to deal with the other device-controller in the ast2600 which is
basically one of these without a vhub above it.

> +required:
> +  - compatible
> +  - reg
> +  - clocks
> +  - interrupts
> +  - aspeed,vhub-downstream-ports
> +  - aspeed,vhub-generic-endpoints
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/aspeed-clock.h>
> +    vhub: usb-vhub@1e6a0000 {
> +            compatible = "aspeed,ast2500-usb-vhub";
> +            reg = <0x1e6a0000 0x300>;
> +            interrupts = <5>;
> +            clocks = <&syscon ASPEED_CLK_GATE_USBPORT1CLK>;
> +            pinctrl-names = "default";
> +            pinctrl-0 = <&pinctrl_usb2ad_default>;
> +    };
> --
Tao Ren Feb. 28, 2020, 1:05 a.m. UTC | #2
On Fri, Feb 28, 2020 at 10:30:02AM +1100, Benjamin Herrenschmidt wrote:
> On Thu, 2020-02-27 at 15:05 -0800, rentao.bupt@gmail.com wrote:
> 
>  .../...
> 
> You haven't fixed the problem spotted by Rob which is that the example
> is now out of sync, it's missing the required properties.

Ahhh, now I know where my problem is..
Let me see why I cannot reproduce the error on my side; otherwise I may
create more noise in my next patch set (customize device IDs/strings)..

> Also long run I think best is going to have a child node per downstream
> port, so we create a matching linux struct device. This will make it
> easier to deal with the other device-controller in the ast2600 which is
> basically one of these without a vhub above it.

Maybe a dumb question: what would be the proper place to parse the child
node/properties when they are added? For example, in some usb_gadget_ops
callback?


Cheers,

Tao
Benjamin Herrenschmidt Feb. 28, 2020, 3:02 a.m. UTC | #3
On Thu, 2020-02-27 at 17:05 -0800, Tao Ren wrote:
> > Also long run I think best is going to have a child node per downstream
> > port, so we create a matching linux struct device. This will make it
> > easier to deal with the other device-controller in the ast2600 which is
> > basically one of these without a vhub above it.
> 
> Maybe a dumb question: what would be the proper place to parse the child
> node/properties when they are added? For example, in some usb_gadget_ops
> callback?

No. What the vhub would do is when it probes, it creates a platform
device for each "port" child node that's linked to the DT node.

The driver for the device then attaches to it via standard DT matching
and checks if it has a vhub parent or not, and based on that, operates
as a vhub child device or a standalone one.

(For example, it might have different functions for EP selection since
standalone devices have private EPs rather than a shared pool)

They can both be in the same module or they can be separate modules
with cross dependencies.

Cheers,
Ben.
Tao Ren Feb. 28, 2020, 8:13 a.m. UTC | #4
On Fri, Feb 28, 2020 at 02:02:28PM +1100, Benjamin Herrenschmidt wrote:
> On Thu, 2020-02-27 at 17:05 -0800, Tao Ren wrote:
> > > Also long run I think best is going to have a child node per downstream
> > > port, so we create a matching linux struct device. This will make it
> > > easier to deal with the other device-controller in the ast2600 which is
> > > basically one of these without a vhub above it.
> > 
> > Maybe a dumb question: what would be the proper place to parse the child
> > node/properties when they are added? For example, in some usb_gadget_ops
> > callback?
> 
> No. What the vhub would do is when it probes, it creates a platform
> device for each "port" child node that's linked to the DT node.
> 
> The driver for the device then attaches to it via standard DT matching
> and checks if it has a vhub parent or not, and based on that, operates
> as a vhub child device or a standalone one.
> 
> (For example, it might have different functions for EP selection since
> standalone devices have private EPs rather than a shared pool)
> 
> They can both be in the same module or they can be separate modules
> with cross dependencies.
> 
> Cheers,
> Ben.

I see. It's to describe these downstream devices (such as configurations
and according functions) in device tree, which is similar to defining a
composite device and linking functions/interfaces via configfs. Thanks for
the clarify.


Cheers,

Tao
Benjamin Herrenschmidt March 2, 2020, 4:49 a.m. UTC | #5
On Fri, 2020-02-28 at 00:13 -0800, Tao Ren wrote:
> On Fri, Feb 28, 2020 at 02:02:28PM +1100, Benjamin Herrenschmidt wrote:
> > On Thu, 2020-02-27 at 17:05 -0800, Tao Ren wrote:
> > > > Also long run I think best is going to have a child node per downstream
> > > > port, so we create a matching linux struct device. This will make it
> > > > easier to deal with the other device-controller in the ast2600 which is
> > > > basically one of these without a vhub above it.
> > > 
> > > Maybe a dumb question: what would be the proper place to parse the child
> > > node/properties when they are added? For example, in some usb_gadget_ops
> > > callback?
> > 
> > No. What the vhub would do is when it probes, it creates a platform
> > device for each "port" child node that's linked to the DT node.
> > 
> > The driver for the device then attaches to it via standard DT matching
> > and checks if it has a vhub parent or not, and based on that, operates
> > as a vhub child device or a standalone one.
> > 
> > (For example, it might have different functions for EP selection since
> > standalone devices have private EPs rather than a shared pool)
> > 
> > They can both be in the same module or they can be separate modules
> > with cross dependencies.
> > 
> > Cheers,
> > Ben.
> 
> I see. It's to describe these downstream devices (such as configurations
> and according functions) in device tree, which is similar to defining a
> composite device and linking functions/interfaces via configfs. Thanks for
> the clarify.

It's also to make it easier long run to support both the standalone
variant and the vhub variant from the same code base.

Cheers,
Ben.

Patch
diff mbox series

diff --git a/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml b/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml
new file mode 100644
index 000000000000..b8b1700c2423
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml
@@ -0,0 +1,71 @@ 
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (c) 2020 Facebook Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/aspeed,usb-vhub.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED USB 2.0 Virtual Hub Controller
+
+maintainers:
+  - Benjamin Herrenschmidt <benh@kernel.crashing.org>
+
+description: |+
+  The ASPEED USB 2.0 Virtual Hub Controller implements 1 set of USB Hub
+  register and several sets of Device and Endpoint registers to support
+  the Virtual Hub's downstream USB devices.
+
+  Supported number of devices and endpoints vary depending on hardware
+  revisions. AST2400 and AST2500 Virtual Hub supports 5 downstream devices
+  and 15 generic endpoints, while AST2600 Virtual Hub supports 7 downstream
+  devices and 21 generic endpoints.
+
+properties:
+  compatible:
+    enum:
+      - aspeed,ast2400-usb-vhub
+      - aspeed,ast2500-usb-vhub
+      - aspeed,ast2600-usb-vhub
+
+  reg:
+    maxItems: 1
+    description: Common configuration registers
+
+  clocks:
+    maxItems: 1
+    description: The Virtual Hub Controller clock gate
+
+  interrupts:
+    maxItems: 1
+
+  aspeed,vhub-downstream-ports:
+    description: Number of downstream ports supported by the Virtual Hub
+    allOf:
+      - $ref: /schemas/types.yaml#/definitions/uint32
+
+  aspeed,vhub-generic-endpoints:
+    description: Number of generic endpoints supported by the Virtual Hub
+    allOf:
+      - $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - interrupts
+  - aspeed,vhub-downstream-ports
+  - aspeed,vhub-generic-endpoints
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/aspeed-clock.h>
+    vhub: usb-vhub@1e6a0000 {
+            compatible = "aspeed,ast2500-usb-vhub";
+            reg = <0x1e6a0000 0x300>;
+            interrupts = <5>;
+            clocks = <&syscon ASPEED_CLK_GATE_USBPORT1CLK>;
+            pinctrl-names = "default";
+            pinctrl-0 = <&pinctrl_usb2ad_default>;
+    };