Skip to contentSkip to conversation

dt/bindings: update fsl-fec regarding compatible and clocks

PATCH New Shawn Guo 3 participants 8 messages Feb 10, 2014 – Feb 24, 2014

Subsystems (2)
lore
Share & tools
lore

Shawn Guo

author
#0 lore raw

PATCH 1/1 dt/bindings: update fsl-fec regarding compatible and clocks

Update fsl-fec to explicitly list the supported compatible strings and add missing 'clocks' and 'clock-names' properties. It does not change anything about how kernel drive works. Instead, it just reflects how kernel driver works today.

---
 Documentation/devicetree/bindings/net/fsl-fec.txt |   19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)
Documentation/devicetree/bindings/net/fsl-fec.txt +18 -1
index 845ff84..3ebd395 100644
@@ -1,9 +1,26 @@
 * Freescale Fast Ethernet Controller (FEC)
 
 Required properties:
-- compatible : Should be "fsl,<soc>-fec"
+- compatible : Should contain one of the following:
+		"fsl,imx25-fec"
+		"fsl,imx27-fec"
+		"fsl,imx28-fec"
+		"fsl,imx6q-fec"
+		"fsl,mvf600-fec"
 - reg : Address and length of the register set for the device
 - interrupts : Should contain fec interrupt
+- clocks: phandle to the clocks feeding the FEC controller and phy. The
+  following two are required:
+   - "ipg": the peripheral access clock
+   - "ahb": the bus clock for MAC
+  The following two are optional:
+   - "ptp": the sampling clock for PTP (IEEE 1588).  On SoC like i.MX6Q,
+     the clock could come from either the internal clock control module
+     or external oscillator via pad depending on board design.
+   - "enet_out": the phy reference clock provided by SoC via pad, which
+     is available on SoC like i.MX28.
+- clock-names: Must contain the clock names described just above
+
 - phy-mode : String, operation mode of the PHY interface.
   Supported values are: "mii", "gmii", "sgmii", "tbi", "rmii",
   "rgmii", "rgmii-id", "rgmii-rxid", "rgmii-txid", "rtbi", "smii".
Signature · 1 line
1.7.9.5
author
#1 lore raw

PATCH 1/1 dt/bindings: update fsl-fec regarding compatible and clocks

Hi Rob and DT folks,

Quoted 6 lines · Shawn Guo

Update fsl-fec to explicitly list the supported compatible strings and add missing 'clocks' and 'clock-names' properties. It does not change anything about how kernel drive works. Instead, it just reflects how kernel driver works today.

Any comments? Or can it be applied?

Shawn

Quoted 40 lines
---
 Documentation/devicetree/bindings/net/fsl-fec.txt |   19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)
Documentation/devicetree/bindings/net/fsl-fec.txt +18 -1
index 845ff84..3ebd395 100644
@@ -1,9 +1,26 @@
 * Freescale Fast Ethernet Controller (FEC)
 
 Required properties:
-- compatible : Should be "fsl,<soc>-fec"
+- compatible : Should contain one of the following:
+		"fsl,imx25-fec"
+		"fsl,imx27-fec"
+		"fsl,imx28-fec"
+		"fsl,imx6q-fec"
+		"fsl,mvf600-fec"
 - reg : Address and length of the register set for the device
 - interrupts : Should contain fec interrupt
+- clocks: phandle to the clocks feeding the FEC controller and phy. The
+  following two are required:
+   - "ipg": the peripheral access clock
+   - "ahb": the bus clock for MAC
+  The following two are optional:
+   - "ptp": the sampling clock for PTP (IEEE 1588).  On SoC like i.MX6Q,
+     the clock could come from either the internal clock control module
+     or external oscillator via pad depending on board design.
+   - "enet_out": the phy reference clock provided by SoC via pad, which
+     is available on SoC like i.MX28.
+- clock-names: Must contain the clock names described just above
+
 - phy-mode : String, operation mode of the PHY interface.
   Supported values are: "mii", "gmii", "sgmii", "tbi", "rmii",
   "rgmii", "rgmii-id", "rgmii-rxid", "rgmii-txid", "rtbi", "smii".
Signature · 1 line
1.7.9.5
#2 lore raw

PATCH 1/1 dt/bindings: update fsl-fec regarding compatible and clocks

In reply to Shawn Guo
Quoted 16 lines · Shawn Guo

Update fsl-fec to explicitly list the supported compatible strings and add missing 'clocks' and 'clock-names' properties. It does not change anything about how kernel drive works. Instead, it just reflects how kernel driver works today.

---
 Documentation/devicetree/bindings/net/fsl-fec.txt |   19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)
Documentation/devicetree/bindings/net/fsl-fec.txt +0 -0
index 845ff84..3ebd395 100644

Documentation/devicetree/bindings/net/fsl-fec.txt line 9

Quoted 10 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +6 -1
@@ -1,9 +1,26 @@
 * Freescale Fast Ethernet Controller (FEC)
 
 Required properties:
-- compatible : Should be "fsl,<soc>-fec"
+- compatible : Should contain one of the following:
+		"fsl,imx25-fec"
+		"fsl,imx27-fec"
+		"fsl,imx28-fec"
+		"fsl,imx6q-fec"
+		"fsl,mvf600-fec"

This appears to miss all the PowerPC based SoCs. See
git grep 'fsl,.*-fec' arch/*/boot/dts

Quoted 4 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +2 -0
 - reg : Address and length of the register set for the device
 - interrupts : Should contain fec interrupt
+- clocks: phandle to the clocks feeding the FEC controller and phy. The
+  following two are required:

Documentation/devicetree/bindings/net/fsl-fec.txt line 23

Quoted 10 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +10 -0
+   - "ipg": the peripheral access clock
+   - "ahb": the bus clock for MAC
+  The following two are optional:
+   - "ptp": the sampling clock for PTP (IEEE 1588).  On SoC like i.MX6Q,
+     the clock could come from either the internal clock control module
+     or external oscillator via pad depending on board design.
+   - "enet_out": the phy reference clock provided by SoC via pad, which
+     is available on SoC like i.MX28.
+- clock-names: Must contain the clock names described just above
+

Listing 'clocks' under the "required properties" all of a sudden invalidates existing device trees, if they don't carry the property which before the change was not required, not even documented.

The PowerPC based chips probably have differing sets of clocks. I'm aware of the MPC512x, where one "per" clock is sufficient, and even this spec is optional. Other machines may not have yet been converted to CCF.

Your description needs to get rephrased, it triggers Mark Rutland's regular "clocks are not just phandles" reply. See how he suggested quite a few times a better wording.

virtually yours
Gerhard Sittig

Signature · 3 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr. 5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-0 Fax: +49-8142-66989-80  Email: office at denx.de
author
#3 lore raw

PATCH 1/1 dt/bindings: update fsl-fec regarding compatible and clocks

Quoted 19 lines · Gerhard Sittig
Quoted 18 lines · Shawn Guo

Update fsl-fec to explicitly list the supported compatible strings and add missing 'clocks' and 'clock-names' properties. It does not change anything about how kernel drive works. Instead, it just reflects how kernel driver works today.

---
 Documentation/devicetree/bindings/net/fsl-fec.txt |   19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)
Documentation/devicetree/bindings/net/fsl-fec.txt +0 -0
index 845ff84..3ebd395 100644
@@ -1,9 +1,26 @@
 * Freescale Fast Ethernet Controller (FEC)
 
Quoted 11 lines

Documentation/devicetree/bindings/net/fsl-fec.txt line 9

Quoted 8 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +6 -1
 Required properties:
-- compatible : Should be "fsl,<soc>-fec"
+- compatible : Should contain one of the following:
+		"fsl,imx25-fec"
+		"fsl,imx27-fec"
+		"fsl,imx28-fec"
+		"fsl,imx6q-fec"
+		"fsl,mvf600-fec"

This appears to miss all the PowerPC based SoCs. See
git grep 'fsl,.*-fec' arch/*/boot/dts

Hmm, this is a binding for IMX FEC/ENET, and the driver is drivers/net/ethernet/freescale/fec_main.c. I think I've listed all the compatibles that the driver supports.

Quoted 16 lines
Quoted 5 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +2 -0
 - reg : Address and length of the register set for the device
 - interrupts : Should contain fec interrupt
+- clocks: phandle to the clocks feeding the FEC controller and phy. The
+  following two are required:

Documentation/devicetree/bindings/net/fsl-fec.txt line 23

Quoted 10 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +10 -0
+   - "ipg": the peripheral access clock
+   - "ahb": the bus clock for MAC
+  The following two are optional:
+   - "ptp": the sampling clock for PTP (IEEE 1588).  On SoC like i.MX6Q,
+     the clock could come from either the internal clock control module
+     or external oscillator via pad depending on board design.
+   - "enet_out": the phy reference clock provided by SoC via pad, which
+     is available on SoC like i.MX28.
+- clock-names: Must contain the clock names described just above
+
Quoted 4 lines

Listing 'clocks' under the "required properties" all of a sudden invalidates existing device trees, if they don't carry the property which before the change was not required, not even documented.

Since the day we move to device tree clock lookup, the driver fec_main does not probe at all if the property is absent.

Quoted 5 lines

The PowerPC based chips probably have differing sets of clocks. I'm aware of the MPC512x, where one "per" clock is sufficient, and even this spec is optional. Other machines may not have yet been converted to CCF.

Again, the binding is created for IMX FEC/ENET controller and the driver fec_main, so I'm not sure you should look at this binding for PowerPC/MPC512x stuff at all.

Quoted 4 lines

Your description needs to get rephrased, it triggers Mark Rutland's regular "clocks are not just phandles" reply. See how he suggested quite a few times a better wording.

Can you give a pointer or good example? I worded it following an example [1] found on recent linux-next/spi tree.

Shawn

[1] https://git.kernel.org/cgit/linux/kernel/git/broonie/spi.git/commit/?h=topic/sunxi&id=3558fe900e8af6c3bfadeff24a12ffb19ac9b108

#4 lore raw

PATCH 1/1 dt/bindings: update fsl-fec regarding compatible and clocks

Quoted 33 lines · Shawn Guo
Quoted 19 lines · Gerhard Sittig
Quoted 18 lines · Shawn Guo

Update fsl-fec to explicitly list the supported compatible strings and add missing 'clocks' and 'clock-names' properties. It does not change anything about how kernel drive works. Instead, it just reflects how kernel driver works today.

---
 Documentation/devicetree/bindings/net/fsl-fec.txt |   19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)
Documentation/devicetree/bindings/net/fsl-fec.txt +0 -0
index 845ff84..3ebd395 100644
@@ -1,9 +1,26 @@
 * Freescale Fast Ethernet Controller (FEC)
 
Quoted 11 lines

Documentation/devicetree/bindings/net/fsl-fec.txt line 9

Quoted 8 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +6 -1
 Required properties:
-- compatible : Should be "fsl,<soc>-fec"
+- compatible : Should contain one of the following:
+		"fsl,imx25-fec"
+		"fsl,imx27-fec"
+		"fsl,imx28-fec"
+		"fsl,imx6q-fec"
+		"fsl,mvf600-fec"

This appears to miss all the PowerPC based SoCs. See
git grep 'fsl,.*-fec' arch/*/boot/dts

Quoted 2 lines

Hmm, this is a binding for IMX FEC/ENET, and the driver is drivers/net/ethernet/freescale/fec_main.c.

The binding text says otherwise. It claims to apply for "fsl,<soc>-fec" compatibles.

It's funny how the first line of the source you point to talks about being a FEC driver for MPC8xx. :) But that doesn't matter here, as it's just a comment in some code.

Quoted 2 lines

I think I've listed all the compatibles that the driver supports.

You got it backwards. The binding is not the after-the-fact documentation of a specific Linux driver. Instead the Linux driver is (supposed to be) an implementation of what the binding specifies. And in this case, there are several drivers, each managing a subset of the compatibles space, each supposed to follow the spec. See

git grep 'fsl,.*-fec' drivers/net/ethernet

Quoted 15 lines
Quoted 15 lines
Quoted 14 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +12 -0
 - reg : Address and length of the register set for the device
 - interrupts : Should contain fec interrupt
+- clocks: phandle to the clocks feeding the FEC controller and phy. The
+  following two are required:
+   - "ipg": the peripheral access clock
+   - "ahb": the bus clock for MAC
+  The following two are optional:
+   - "ptp": the sampling clock for PTP (IEEE 1588).  On SoC like i.MX6Q,
+     the clock could come from either the internal clock control module
+     or external oscillator via pad depending on board design.
+   - "enet_out": the phy reference clock provided by SoC via pad, which
+     is available on SoC like i.MX28.
+- clock-names: Must contain the clock names described just above
+
Quoted 7 lines
Quoted 4 lines

Listing 'clocks' under the "required properties" all of a sudden invalidates existing device trees, if they don't carry the property which before the change was not required, not even documented.

Since the day we move to device tree clock lookup, the driver fec_main does not probe at all if the property is absent.

That's an implementation detail. It's not what the spec says, and neither is what the spec is to blindly follow after the / a driver created the fact. Instead, a binding gets designed, and the software follows.

In reality, the doc may be behind as developers are more concerned about the code. But still when you "update" the binding, don't break compatibility! Even if you'd adjust all drivers you can spot, it's still only Linux and not all device tree users.

Quoted 8 lines
Quoted 4 lines

The PowerPC based chips probably have differing sets of clocks. I'm aware of the MPC512x, where one "per" clock is sufficient, and even this spec is optional. Other machines may not have yet been converted to CCF.

Again, the binding is created for IMX FEC/ENET controller and the driver fec_main, so I'm not sure you should look at this binding for PowerPC/MPC512x stuff at all.

See above, the binding is _not_ specific to i.MX, it's a FEC binding. Which happens to apply to several architectures, as the FEC is used in several SoCs. And keep in mind that the device tree binding is OS agnostic, Linux details just are not the reference.

virtually yours
Gerhard Sittig

Signature · 3 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr. 5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-0 Fax: +49-8142-66989-80  Email: office at denx.de
author
#5 lore raw

PATCH 1/1 dt/bindings: update fsl-fec regarding compatible and clocks

Quoted 15 lines · Gerhard Sittig
Quoted 15 lines
Quoted 14 lines

Documentation/devicetree/bindings/net/fsl-fec.txt line 9

Quoted 11 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +6 -1
@@ -1,9 +1,26 @@
 * Freescale Fast Ethernet Controller (FEC)
 
 Required properties:
-- compatible : Should be "fsl,<soc>-fec"
+- compatible : Should contain one of the following:
+		"fsl,imx25-fec"
+		"fsl,imx27-fec"
+		"fsl,imx28-fec"
+		"fsl,imx6q-fec"
+		"fsl,mvf600-fec"

This appears to miss all the PowerPC based SoCs. See
git grep 'fsl,.*-fec' arch/*/boot/dts

Quoted 5 lines
Quoted 2 lines

Hmm, this is a binding for IMX FEC/ENET, and the driver is drivers/net/ethernet/freescale/fec_main.c.

The binding text says otherwise. It claims to apply for "fsl,<soc>-fec" compatibles.

I should really list the compatibles specifically when I was creating the document at day one. But honestly, I did not intend to cover PowerPC chips with this document.

Quoted 5 lines

It's funny how the first line of the source you point to talks about being a FEC driver for MPC8xx. :) But that doesn't matter here, as it's just a comment in some code.

Quoted 7 lines
Quoted 2 lines

I think I've listed all the compatibles that the driver supports.

You got it backwards. The binding is not the after-the-fact documentation of a specific Linux driver. Instead the Linux driver is (supposed to be) an implementation of what the binding specifies.

Yes, theoretically. But practically, well ...

Quoted 6 lines

And in this case, there are several drivers, each managing a subset of the compatibles space, each supposed to follow the spec. See

git grep 'fsl,.*-fec' drivers/net/ethernet

The spec was created without considering those drivers other than fec_main. For example, the 'phy-mode' is documented as a required property in the spec. But I do not think that's the case for drivers fec_mpc52xx and fs_enet-main.

Quoted 28 lines
Quoted 15 lines
Quoted 15 lines
Quoted 14 lines
Documentation/devicetree/bindings/net/fsl-fec.txt +12 -0
 - reg : Address and length of the register set for the device
 - interrupts : Should contain fec interrupt
+- clocks: phandle to the clocks feeding the FEC controller and phy. The
+  following two are required:
+   - "ipg": the peripheral access clock
+   - "ahb": the bus clock for MAC
+  The following two are optional:
+   - "ptp": the sampling clock for PTP (IEEE 1588).  On SoC like i.MX6Q,
+     the clock could come from either the internal clock control module
+     or external oscillator via pad depending on board design.
+   - "enet_out": the phy reference clock provided by SoC via pad, which
+     is available on SoC like i.MX28.
+- clock-names: Must contain the clock names described just above
+
Quoted 7 lines
Quoted 4 lines

Listing 'clocks' under the "required properties" all of a sudden invalidates existing device trees, if they don't carry the property which before the change was not required, not even documented.

Since the day we move to device tree clock lookup, the driver fec_main does not probe at all if the property is absent.

That's an implementation detail. It's not what the spec says, and neither is what the spec is to blindly follow after the / a driver created the fact. Instead, a binding gets designed, and the software follows.

Quoted 5 lines

In reality, the doc may be behind as developers are more concerned about the code. But still when you "update" the binding, don't break compatibility! Even if you'd adjust all drivers you can spot, it's still only Linux and not all device tree users.

So what's your suggestion? Add the properties as the optional?

Shawn

#6 lore raw

PATCH 1/1 dt/bindings: update fsl-fec regarding compatible and clocks

Quoted 32 lines · Shawn Guo
Quoted 30 lines · Gerhard Sittig

[ ... ]

Quoted 15 lines
Quoted 15 lines
Quoted 14 lines

- reg : Address and length of the register set for the device
- interrupts : Should contain fec interrupt
+- clocks: phandle to the clocks feeding the FEC controller and phy. The

Documentation/devicetree/bindings/net/fsl-fec.txt +11 -0
+  following two are required:
+   - "ipg": the peripheral access clock
+   - "ahb": the bus clock for MAC
+  The following two are optional:
+   - "ptp": the sampling clock for PTP (IEEE 1588).  On SoC like i.MX6Q,
+     the clock could come from either the internal clock control module
+     or external oscillator via pad depending on board design.
+   - "enet_out": the phy reference clock provided by SoC via pad, which
+     is available on SoC like i.MX28.
+- clock-names: Must contain the clock names described just above
+
Quoted 7 lines
Quoted 4 lines

Listing 'clocks' under the "required properties" all of a sudden invalidates existing device trees, if they don't carry the property which before the change was not required, not even documented.

Since the day we move to device tree clock lookup, the driver fec_main does not probe at all if the property is absent.

That's an implementation detail. It's not what the spec says, and neither is what the spec is to blindly follow after the / a driver created the fact. Instead, a binding gets designed, and the software follows.

Quoted 7 lines
Quoted 5 lines

In reality, the doc may be behind as developers are more concerned about the code. But still when you "update" the binding, don't break compatibility! Even if you'd adjust all drivers you can spot, it's still only Linux and not all device tree users.

So what's your suggestion? Add the properties as the optional?

Have there been i.MX device trees in mainline releases which lack the clock specs? If so, making the clock specs mandatory breaks backwards compatibility for these existing device trees as well.

I assume that listing the clocks as optional keeps the binding most compatible. You might as well list them as recommended, if optional is "too weak" for you.

I guess that listing the clocks as recommended, and telling which clock names apply to which SoC variants, allows to keep using the binding for all current implementations which were written against this spec. This way you might focus on i.MX and say "the following SoCs require the following clock names", and still leave the PowerPC stuff or other FEC users for a followup patch.

virtually yours
Gerhard Sittig

Signature · 3 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr. 5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-0 Fax: +49-8142-66989-80  Email: office at denx.de
#7 lore raw

PATCH 1/1 dt/bindings: update fsl-fec regarding compatible and clocks

Quoted 41 lines · Gerhard Sittig
Quoted 32 lines · Shawn Guo
Quoted 30 lines · Gerhard Sittig

[ ... ]

Quoted 15 lines
Quoted 15 lines
Quoted 14 lines

- reg : Address and length of the register set for the device
- interrupts : Should contain fec interrupt
+- clocks: phandle to the clocks feeding the FEC controller and phy. The

Documentation/devicetree/bindings/net/fsl-fec.txt +11 -0
+  following two are required:
+   - "ipg": the peripheral access clock
+   - "ahb": the bus clock for MAC
+  The following two are optional:
+   - "ptp": the sampling clock for PTP (IEEE 1588).  On SoC like i.MX6Q,
+     the clock could come from either the internal clock control module
+     or external oscillator via pad depending on board design.
+   - "enet_out": the phy reference clock provided by SoC via pad, which
+     is available on SoC like i.MX28.
+- clock-names: Must contain the clock names described just above
+
Quoted 7 lines
Quoted 4 lines

Listing 'clocks' under the "required properties" all of a sudden invalidates existing device trees, if they don't carry the property which before the change was not required, not even documented.

Since the day we move to device tree clock lookup, the driver fec_main does not probe at all if the property is absent.

That's an implementation detail. It's not what the spec says, and neither is what the spec is to blindly follow after the / a driver created the fact. Instead, a binding gets designed, and the software follows.

Quoted 7 lines
Quoted 5 lines

In reality, the doc may be behind as developers are more concerned about the code. But still when you "update" the binding, don't break compatibility! Even if you'd adjust all drivers you can spot, it's still only Linux and not all device tree users.

So what's your suggestion? Add the properties as the optional?

Quoted 7 lines

Have there been i.MX device trees in mainline releases which lack the clock specs? If so, making the clock specs mandatory breaks backwards compatibility for these existing device trees as well.

I assume that listing the clocks as optional keeps the binding most compatible. You might as well list them as recommended, if optional is "too weak" for you.

Why should we keep the binding compatible when the driver requires the clocks? The clocks are not at all optional for the driver. We made the clocks mandatory at a time when the bindings didn't make any promises about stability, so Shawn only documents what the driver requires anyway.
If anything, we should doument that this binding is not valid for the PowerPC variants of the FEC.

Sascha

Signature · 4 lines
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |