[PATCH] Documentation/devicetree: document OCTEON USB bindings

[PATCH] Documentation/devicetree: document OCTEON USB bindings

[Aaro Koskinen]

Document device-tree bindings for the USB controller on older
OCTEON SOCs (OCTEON, OCTEON+).

Signed-off-by: Aaro Koskinen <aaro.koskinen-X3B1VOXEql0@public.gmane.org>
---
 .../devicetree/bindings/usb/octeon-usb.txt         | 58 ++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/usb/octeon-usb.txt

diff --git a/Documentation/devicetree/bindings/usb/octeon-usb.txt b/Documentation/devicetree/bindings/usb/octeon-usb.txt
new file mode 100644
index 0000000..fd121c4
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/octeon-usb.txt
@@ -0,0 +1,58 @@
+OCTEON/OCTEON+ USB BLOCK
+
+1) Main node
+
+   Required properties:
+
+   - compatible: must be "cavium,octeon-5750-usbn"
+
+   - reg: specifies the physical base address of the USBN block and
+     the length of the memory mapped region.
+
+   - #address-cells: specifies the number of cells needed to encode an
+     address. The value must be 2.
+
+   - #size-cells: specifies the number of cells used to represent the size
+     of an address. The value must be 2.
+
+   - ranges: specifies the translation between child address space and parent
+     address space.
+
+   - refclk-frequency: speed of the USB reference clock. Allowed values are
+     12000000, 24000000 or 48000000.
+
+   - refclk-type: type of the USB reference clock. Allowed values are
+     "crystal" or "external".
+
+2) Child node
+
+   The main node must have one child node which describes the built-in
+   USB controller.
+
+   Required properties:
+
+   - compatible: must be "cavium,octeon-5750-usbc"
+
+   - reg: specifies the physical base address of the USBC block and
+     the length of the memory mapped region.
+
+   - interrupts: specifies the interrupt number for the USB controller.
+
+3) Example:
+
+	usbn: usbn@1180068000000 {
+		compatible = "cavium,octeon-5750-usbn";
+		reg = <0x11800 0x68000000 0x0 0x1000>;
+		ranges; /* Direct mapping */
+		#address-cells = <2>;
+		#size-cells = <2>;
+		refclk-frequency = <12000000>;
+		refclk-type = "crystal";
+
+		usbc@16f0010000000 {
+			compatible = "cavium,octeon-5750-usbc";
+			reg = <0x16f00 0x10000000 0x0 0x80000>;
+			interrupts = <0 56>;
+		};
+	};
+
-- 
2.3.3

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/devicetree: document OCTEON USB bindings

[Rob Herring]

On Thu, Apr 30, 2015 at 2:44 PM, Aaro Koskinen <aaro.koskinen-X3B1VOXEql0@public.gmane.org> wrote:
> Document device-tree bindings for the USB controller on older
> OCTEON SOCs (OCTEON, OCTEON+).
>
> Signed-off-by: Aaro Koskinen <aaro.koskinen-X3B1VOXEql0@public.gmane.org>
> ---
>  .../devicetree/bindings/usb/octeon-usb.txt         | 58 ++++++++++++++++++++++
>  1 file changed, 58 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/usb/octeon-usb.txt
>
> diff --git a/Documentation/devicetree/bindings/usb/octeon-usb.txt b/Documentation/devicetree/bindings/usb/octeon-usb.txt
> new file mode 100644
> index 0000000..fd121c4
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/octeon-usb.txt
> @@ -0,0 +1,58 @@
> +OCTEON/OCTEON+ USB BLOCK
> +
> +1) Main node
> +
> +   Required properties:
> +
> +   - compatible: must be "cavium,octeon-5750-usbn"
> +
> +   - reg: specifies the physical base address of the USBN block and
> +     the length of the memory mapped region.
> +
> +   - #address-cells: specifies the number of cells needed to encode an
> +     address. The value must be 2.
> +
> +   - #size-cells: specifies the number of cells used to represent the size
> +     of an address. The value must be 2.
> +
> +   - ranges: specifies the translation between child address space and parent
> +     address space.
> +
> +   - refclk-frequency: speed of the USB reference clock. Allowed values are
> +     12000000, 24000000 or 48000000.

We already have a standard property for this if you only have 1 clock:
clock-frequency.

> +   - refclk-type: type of the USB reference clock. Allowed values are
> +     "crystal" or "external".

Should be prefixed with "cavium,".

> +
> +2) Child node
> +
> +   The main node must have one child node which describes the built-in
> +   USB controller.
> +
> +   Required properties:
> +
> +   - compatible: must be "cavium,octeon-5750-usbc"
> +
> +   - reg: specifies the physical base address of the USBC block and
> +     the length of the memory mapped region.
> +
> +   - interrupts: specifies the interrupt number for the USB controller.
> +
> +3) Example:
> +
> +       usbn: usbn@1180068000000 {
> +               compatible = "cavium,octeon-5750-usbn";
> +               reg = <0x11800 0x68000000 0x0 0x1000>;
> +               ranges; /* Direct mapping */
> +               #address-cells = <2>;
> +               #size-cells = <2>;
> +               refclk-frequency = <12000000>;
> +               refclk-type = "crystal";
> +
> +               usbc@16f0010000000 {
> +                       compatible = "cavium,octeon-5750-usbc";
> +                       reg = <0x16f00 0x10000000 0x0 0x80000>;
> +                       interrupts = <0 56>;
> +               };
> +       };
> +
> --
> 2.3.3
>
> --
> To unsubscribe from this list: send the line "unsubscribe devicetree" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/devicetree: document OCTEON USB bindings

[Aaro Koskinen]

Hi,

On Fri, May 01, 2015 at 09:39:19AM -0500, Rob Herring wrote:
> > +   - refclk-frequency: speed of the USB reference clock. Allowed values are
> > +     12000000, 24000000 or 48000000.
> 
> We already have a standard property for this if you only have 1 clock:
> clock-frequency.
> 
> > +   - refclk-type: type of the USB reference clock. Allowed values are
> > +     "crystal" or "external".
> 
> Should be prefixed with "cavium,".

Both of these are already used in
Documentation/devicetree/bindings/mips/cavium/uctl.txt (the USB
controller for newer OCTEONs). These bindings are unfortunately
just "reverse-engineered" from products that are already shipping
and likely not perfect, but shouldn't we still try to be compatible
for the sake of users?

A.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/devicetree: document OCTEON USB bindings

[Rob Herring]

On Fri, May 1, 2015 at 11:15 AM, Aaro Koskinen <aaro.koskinen-X3B1VOXEql0@public.gmane.org> wrote:
> Hi,
>
> On Fri, May 01, 2015 at 09:39:19AM -0500, Rob Herring wrote:
>> > +   - refclk-frequency: speed of the USB reference clock. Allowed values are
>> > +     12000000, 24000000 or 48000000.
>>
>> We already have a standard property for this if you only have 1 clock:
>> clock-frequency.
>>
>> > +   - refclk-type: type of the USB reference clock. Allowed values are
>> > +     "crystal" or "external".
>>
>> Should be prefixed with "cavium,".
>
> Both of these are already used in
> Documentation/devicetree/bindings/mips/cavium/uctl.txt (the USB
> controller for newer OCTEONs). These bindings are unfortunately
> just "reverse-engineered" from products that are already shipping
> and likely not perfect, but shouldn't we still try to be compatible
> for the sake of users?

Well, generally we don't just accept whatever crap people came up with
behind closed doors. But for this case, I'm not going to bikeshed it.

Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/devicetree: document OCTEON USB bindings

[Arnd Bergmann]

On Thursday 30 April 2015 22:44:00 Aaro Koskinen wrote:
> +1) Main node
> +
> +   Required properties:
> +
> +   - compatible: must be "cavium,octeon-5750-usbn"
> +
> +   - reg: specifies the physical base address of the USBN block and
> +     the length of the memory mapped region.
> +
> +   - #address-cells: specifies the number of cells needed to encode an
> +     address. The value must be 2.
> +
> +   - #size-cells: specifies the number of cells used to represent the size
> +     of an address. The value must be 2.
> +
> +   - ranges: specifies the translation between child address space and parent
> +     address space.
> +
> +   - refclk-frequency: speed of the USB reference clock. Allowed values are
> +     12000000, 24000000 or 48000000.
> +
> +   - refclk-type: type of the USB reference clock. Allowed values are
> +     "crystal" or "external".
> +
> +2) Child node
> +
> +   The main node must have one child node which describes the built-in
> +   USB controller.
> +
> +   Required properties:
> +
> +   - compatible: must be "cavium,octeon-5750-usbc"
> +
> +   - reg: specifies the physical base address of the USBC block and
> +     the length of the memory mapped region.
> +
> +   - interrupts: specifies the interrupt number for the USB controller.
> +
> 

What does that main node actually do?

The common setup is that you have regular ehci/ohci/uhci host bridges
connected to an mmio bus, plus with shared PHY driver that would nowadays
sit in drivers/phy/ and handle the setup of the physical USB interface.

Is Octeon different from everything else here?

	Arnd
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/devicetree: document OCTEON USB bindings

[Aaro Koskinen]

Hi,

On Tue, May 05, 2015 at 12:02:04PM +0200, Arnd Bergmann wrote:
> What does that main node actually do?
> 
> The common setup is that you have regular ehci/ohci/uhci host bridges
> connected to an mmio bus, plus with shared PHY driver that would nowadays
> sit in drivers/phy/ and handle the setup of the physical USB interface.

The main node is not just PHY and clock control, there is also DMA
registers at least. Also the controller part is not generic ?hci.

> Is Octeon different from everything else here?

Certainly it's not like any generic COTS PC HW...

A.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/devicetree: document OCTEON USB bindings

[Arnd Bergmann]

On Tuesday 05 May 2015 20:57:52 Aaro Koskinen wrote:
> 
> On Tue, May 05, 2015 at 12:02:04PM +0200, Arnd Bergmann wrote:
> > What does that main node actually do?
> > 
> > The common setup is that you have regular ehci/ohci/uhci host bridges
> > connected to an mmio bus, plus with shared PHY driver that would nowadays
> > sit in drivers/phy/ and handle the setup of the physical USB interface.
> 
> The main node is not just PHY and clock control, there is also DMA
> registers at least. Also the controller part is not generic ?hci.

Are you sure it's not one of the other common host implementations
(synopsys dwc2, mentor musb, chipidea, ...) then? Maybe there is
already a binding.

If not, would it make sense to put the two nodes into one that is
just handled by a single driver?

> > Is Octeon different from everything else here?
> 
> Certainly it's not like any generic COTS PC HW...

I was asking about SoC implementations like the octeon-6335, 
which seems to be more regular.

	Arnd
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/devicetree: document OCTEON USB bindings

[Aaro Koskinen]

Hi,

On Tue, May 05, 2015 at 10:42:36PM +0200, Arnd Bergmann wrote:
> On Tuesday 05 May 2015 20:57:52 Aaro Koskinen wrote:
> > 
> > On Tue, May 05, 2015 at 12:02:04PM +0200, Arnd Bergmann wrote:
> > > What does that main node actually do?
> > > 
> > > The common setup is that you have regular ehci/ohci/uhci host bridges
> > > connected to an mmio bus, plus with shared PHY driver that would nowadays
> > > sit in drivers/phy/ and handle the setup of the physical USB interface.
> > 
> > The main node is not just PHY and clock control, there is also DMA
> > registers at least. Also the controller part is not generic ?hci.
> 
> Are you sure it's not one of the other common host implementations
> (synopsys dwc2, mentor musb, chipidea, ...) then? Maybe there is
> already a binding.

The usbn block is Cavium proprietary. The usbc part is apparantely
based on dwc2, but even still the current dwc2 driver does not work
with the cavium variant as it's coupled with usbn (and perhaps due
to some other undocumented differences).

> If not, would it make sense to put the two nodes into one that is
> just handled by a single driver?

It's already handled by single driver (staging/octeon-usb). The reason
for this specific binding is to allow compatibility with flashed firmware
providing the cavium DTB. But for my boards, I'm using in-tree DTB
so probably I could change it if that's strictly required.

A.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html