Ocelot switches have the abilitiy to be used internally via
memory-mapped IO or externally via SPI or PCIe. This brings up issues
for documentation, where the same chip might be accessed internally in a
switchdev manner, or externally in a DSA configuration. This patch set
is perparation to bring DSA functionality to the VSC7512, utilizing as
much as possible with an almost identical VSC7514 chip.
During the most recent RFC for internal ethernet switch functionality to
the VSC7512, there were 10 steps laid out to adequately prepare
documentation:
https://lore.kernel.org/all/20221010174856.nd3n4soxk7zbmcm7@skbuf/
The full context is quoted below. This patch set represents steps 1-7 of
the 10 steps, with the remaining steps to likely be part of what was the
original RFC.
The first two patches are specifically rewording and fixing of the MFD
bindings. I kept them in this patch set since they might cause conflicts
with future documentation changes that will be part of the net-next
tree. I can separate them if desired.
Context:
```
To end the discussion on a constructive note, I think if I were Colin,
I would do the following, in the following order, according to what was
expressed as a constraint:
1. Reword the "driver" word out of mscc,vsc7514-switch.yaml and express
the description in terms of what the switch can do, not what the
driver can do.
2. Make qca8k.yaml have "$ref: dsa.yaml#". Remove "$ref: dsa-port.yaml#"
from the same schema.
3. Remove "- $ref: dsa-port.yaml#" from mediatek,mt7530.yaml. It doesn't
seem to be needed, since dsa.yaml also has this. We need this because
we want to make sure no one except dsa.yaml references dsa-port.yaml.
4. Move the DSA-unspecific portion from dsa.yaml into a new
ethernet-switch.yaml. What remains in dsa.yaml is "dsa,member".
The dsa.yaml schema will have "$ref: ethernet-switch.yaml#" for the
"(ethernet-)switch" node, plus its custom additions.
5. Move the DSA-unspecific portion from dsa-port.yaml into a new
ethernet-switch-port.yaml. What remains in dsa-port.yaml is:
* ethernet phandle
* link phandle
* label property
* dsa-tag-protocol property
* the constraint that CPU and DSA ports must have phylink bindings
6. The ethernet-switch.yaml will have "$ref: ethernet-switch-port.yaml#"
and "$ref: dsa-port.yaml". The dsa-port.yaml schema will *not* have
"$ref: ethernet-switch-port.yaml#", just its custom additions.
I'm not 100% on this, but I think there will be a problem if:
- dsa.yaml references ethernet-switch.yaml
- ethernet-switch.yaml references ethernet-switch-port.yaml
- dsa.yaml also references dsa-port.yaml
- dsa-port.yaml references ethernet-switch-port.yaml
because ethernet-switch-port.yaml will be referenced twice. Again,
not sure if this is a problem. If it isn't, things can be simpler,
just make dsa-port.yaml reference ethernet-switch-port.yaml, and skip
steps 2 and 3 since dsa-port.yaml containing just the DSA specifics
is no longer problematic.
7. Make mscc,vsc7514-switch.yaml have "$ref: ethernet-switch.yaml#" for
the "mscc,vsc7514-switch.yaml" compatible string. This will eliminate
its own definitions for the generic properties: $nodename and
ethernet-ports (~45 lines of code if I'm not mistaken).
8. Introduce the "mscc,vsc7512-switch" compatible string as part of
mscc,vsc7514-switch.yaml, but this will have "$ref: dsa.yaml#" (this
will have to be referenced by full path because they are in different
folders) instead of "ethernet-switch.yaml". Doing this will include
the common bindings for a switch, plus the DSA specifics.
9. Optional: rework ti,cpsw-switch.yaml, microchip,lan966x-switch.yaml,
microchip,sparx5-switch.yaml to have "$ref: ethernet-switch.yaml#"
which should reduce some duplication in existing schemas.
10. Question for future support of VSC7514 in DSA mode: how do we decide
whether to $ref: ethernet-switch.yaml or dsa.yaml? If the parent MFD
node has a compatible string similar to "mscc,vsc7512", then use DSA,
otherwise use generic ethernet-switch?
```
Colin Foster (7):
dt-bindings: mfd: ocelot: remove spi-max-frequency from required
properties
dt-bindings: mfd: ocelot: remove unnecessary driver wording
dt-bindings: net: dsa: qca8k: utilize shared dsa.yaml
dt-bindings: net: dsa: mediatek,mt7530: remove unnecessary dsa-port
reference
dt-bindings: net: add generic ethernet-switch
dt-bindings: net: add generic ethernet-switch-port binding
dt-bindings: net: mscc,vsc7514-switch: utilize generic
ethernet-switch.yaml
.../devicetree/bindings/mfd/mscc,ocelot.yaml | 4 +-
.../devicetree/bindings/net/dsa/dsa-port.yaml | 26 +---------
.../devicetree/bindings/net/dsa/dsa.yaml | 26 +---------
.../bindings/net/dsa/mediatek,mt7530.yaml | 3 --
.../devicetree/bindings/net/dsa/qca8k.yaml | 14 ++---
.../bindings/net/ethernet-switch-port.yaml | 44 ++++++++++++++++
.../bindings/net/ethernet-switch.yaml | 51 +++++++++++++++++++
.../bindings/net/mscc,vsc7514-switch.yaml | 36 +------------
MAINTAINERS | 2 +
9 files changed, 107 insertions(+), 99 deletions(-)
create mode 100644 Documentation/devicetree/bindings/net/ethernet-switch-port.yaml
create mode 100644 Documentation/devicetree/bindings/net/ethernet-switch.yaml
--
2.25.1
The dsa.yaml bindings had references that can apply to non-dsa switches. To
prevent duplication of this information, keep the dsa-specific information
inside dsa.yaml and move the remaining generic information to the newly
created ethernet-switch.yaml.
Signed-off-by: Colin Foster <[email protected]>
Suggested-by: Vladimir Oltean <[email protected]>
---
.../devicetree/bindings/net/dsa/dsa.yaml | 26 +---------
.../bindings/net/ethernet-switch.yaml | 49 +++++++++++++++++++
MAINTAINERS | 1 +
3 files changed, 52 insertions(+), 24 deletions(-)
create mode 100644 Documentation/devicetree/bindings/net/ethernet-switch.yaml
diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml
index b9d48e357e77..2290a9d32b21 100644
--- a/Documentation/devicetree/bindings/net/dsa/dsa.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml
@@ -18,6 +18,8 @@ description:
select: false
+$ref: "/schemas/net/ethernet-switch.yaml#"
+
properties:
$nodename:
pattern: "^(ethernet-)?switch(@.*)?$"
@@ -32,30 +34,6 @@ properties:
(single device hanging off a CPU port) must not specify this property
$ref: /schemas/types.yaml#/definitions/uint32-array
-patternProperties:
- "^(ethernet-)?ports$":
- type: object
- properties:
- '#address-cells':
- const: 1
- '#size-cells':
- const: 0
-
- patternProperties:
- "^(ethernet-)?port@[0-9]+$":
- type: object
- description: Ethernet switch ports
-
- $ref: dsa-port.yaml#
-
- unevaluatedProperties: false
-
-oneOf:
- - required:
- - ports
- - required:
- - ethernet-ports
-
additionalProperties: true
...
diff --git a/Documentation/devicetree/bindings/net/ethernet-switch.yaml b/Documentation/devicetree/bindings/net/ethernet-switch.yaml
new file mode 100644
index 000000000000..fbaac536673d
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/ethernet-switch.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/ethernet-switch.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ethernet Switch Device Tree Bindings
+
+maintainers:
+ - Andrew Lunn <[email protected]>
+ - Florian Fainelli <[email protected]>
+ - Vivien Didelot <[email protected]>
+
+description:
+ This binding represents Ethernet Switches which have a dedicated CPU
+ port. That port is usually connected to an Ethernet Controller of the
+ SoC. Such setups are typical for embedded devices.
+
+select: false
+
+properties:
+ $nodename:
+ pattern: "^(ethernet-)?switch(@.*)?$"
+
+patternProperties:
+ "^(ethernet-)?ports$":
+ type: object
+ properties:
+ '#address-cells':
+ const: 1
+ '#size-cells':
+ const: 0
+
+ patternProperties:
+ "^(ethernet-)?port@[0-9]+$":
+ type: object
+ description: Ethernet switch ports
+
+ $ref: /schemas/net/dsa/dsa-port.yaml#
+
+oneOf:
+ - required:
+ - ports
+ - required:
+ - ethernet-ports
+
+additionalProperties: true
+
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index 3106a9f0567a..3b6c3989c419 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14326,6 +14326,7 @@ M: Florian Fainelli <[email protected]>
M: Vladimir Oltean <[email protected]>
S: Maintained
F: Documentation/devicetree/bindings/net/dsa/
+F: Documentation/devicetree/bindings/net/ethernet-switch.yaml
F: drivers/net/dsa/
F: include/linux/dsa/
F: include/linux/platform_data/dsa.h
--
2.25.1
dsa.yaml contains a reference to dsa-port.yaml, so a duplicate reference to
the binding isn't necessary. Remove this unnecessary reference.
Signed-off-by: Colin Foster <[email protected]>
Suggested-by: Vladimir Oltean <[email protected]>
---
Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml | 3 ---
1 file changed, 3 deletions(-)
diff --git a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml
index f2e9ff3f580b..81f291105660 100644
--- a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml
@@ -159,8 +159,6 @@ patternProperties:
type: object
description: Ethernet switch ports
- unevaluatedProperties: false
-
properties:
reg:
description:
@@ -168,7 +166,6 @@ patternProperties:
for user ports.
allOf:
- - $ref: dsa-port.yaml#
- if:
required: [ ethernet ]
then:
--
2.25.1
The property spi-max-frequency was initially documented as a required
property. It is not actually required, and will break bindings validation
if other control mediums (e.g. PCIe) are used.
Remove this property from the required arguments.
Signed-off-by: Colin Foster <[email protected]>
Acked-by: Krzysztof Kozlowski <[email protected]>
---
Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml | 1 -
1 file changed, 1 deletion(-)
diff --git a/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml b/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml
index 8bf45a5673a4..c6da91211a18 100644
--- a/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml
+++ b/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml
@@ -61,7 +61,6 @@ required:
- reg
- '#address-cells'
- '#size-cells'
- - spi-max-frequency
additionalProperties: false
--
2.25.1
On 25.10.2022 08:03, Colin Foster wrote:
> dsa.yaml contains a reference to dsa-port.yaml, so a duplicate reference to
> the binding isn't necessary. Remove this unnecessary reference.
>
> Signed-off-by: Colin Foster <[email protected]>
> Suggested-by: Vladimir Oltean <[email protected]>
Reviewed-by: Arınç ÜNAL <[email protected]>
Thanks.
Arınç
On Mon, 24 Oct 2022, Colin Foster wrote:
> The property spi-max-frequency was initially documented as a required
> property. It is not actually required, and will break bindings validation
> if other control mediums (e.g. PCIe) are used.
>
> Remove this property from the required arguments.
>
> Signed-off-by: Colin Foster <[email protected]>
> Acked-by: Krzysztof Kozlowski <[email protected]>
> ---
> Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml | 1 -
> 1 file changed, 1 deletion(-)
Applied, thanks.
--
Lee Jones [李琼斯]
On Sun, Oct 30, 2022 at 08:42:32PM +0300, Arınç ÜNAL wrote:
> On 25.10.2022 08:03, Colin Foster wrote:
> > dsa.yaml contains a reference to dsa-port.yaml, so a duplicate reference to
> > the binding isn't necessary. Remove this unnecessary reference.
> >
> > Signed-off-by: Colin Foster <[email protected]>
> > Suggested-by: Vladimir Oltean <[email protected]>
>
> Reviewed-by: Arınç ÜNAL <[email protected]>
Thanks!
>
> Thanks.
> Arınç
On Mon, Oct 31, 2022 at 03:36:14PM +0000, Lee Jones wrote:
> On Mon, 24 Oct 2022, Colin Foster wrote:
>
> > The property spi-max-frequency was initially documented as a required
> > property. It is not actually required, and will break bindings validation
> > if other control mediums (e.g. PCIe) are used.
> >
> > Remove this property from the required arguments.
> >
> > Signed-off-by: Colin Foster <[email protected]>
> > Acked-by: Krzysztof Kozlowski <[email protected]>
> > ---
> > Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml | 1 -
> > 1 file changed, 1 deletion(-)
>
> Applied, thanks.
Thanks Lee
>
> --
> Lee Jones [李琼斯]