xref: /linux/Documentation/devicetree/bindings/net/pse-pd/realtek,pse-mcu-gen1.yaml (revision 91ec2035134982b98fab0609a9fd8480e8217dc1) 
1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/net/pse-pd/realtek,pse-mcu-gen1.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Realtek PSE MCU
8
9maintainers:
10  - Jonas Jelonek <jelonek.jonas@gmail.com>
11
12description: |
13  A microcontroller (MCU) that manages the PSE (Power Sourcing Equipment)
14  hardware on a range of managed PoE switches. The host CPU talks only to
15  this MCU - over I2C/SMBus or UART - using a small message-based protocol;
16  the PSE silicon it drives sits behind the MCU and is never accessed
17  directly. For example, on the Zyxel GS1900-10HP the SoC reaches the MCU
18  over UART, and the MCU manages the on-board PSE chip.
19
20  This binding describes the MCU together with its Realtek firmware: the
21  firmware and its host protocol, which are stable across boards. The
22  microcontroller silicon is a general-purpose part that varies, and the
23  PSE silicon behind the MCU (Realtek RTL823x/RTL8239* or Broadcom
24  BCM59xxx) is reported by the MCU and detected at runtime - neither is
25  named here.
26
27  Two protocol generations exist, both Realtek's:
28    gen1  older boards, where the MCU fronts Broadcom PSE silicon
29    gen2  the altered protocol used with Realtek's own PSE silicon
30
31  On an I2C attachment the framing the MCU firmware expects is part of the
32  compatible: '-smbus' (reads carry a leading command byte and a repeated
33  start) or '-i2c' (bare block writes and reads). A UART attachment carries
34  no framing suffix; the transport is given by the parent 'serial' node.
35
36  Each board additionally carries a device-specific compatible that falls
37  back to one of the protocol compatibles above. Drivers bind on the
38  protocol compatible; the device-specific string identifies the board and
39  reserves a place for a future per-board quirk without having to retrofit
40  device trees already in the field.
41
42properties:
43  compatible:
44    oneOf:
45      # UART
46      - items:
47          - enum:
48              - zyxel,gs1900-10hp-a1-pse
49          - const: realtek,pse-mcu-gen1
50
51      # I2C, SMBus framing
52      - items:
53          - enum:
54              - zyxel,gs1920-24hp-v2-pse
55          - const: realtek,pse-mcu-gen1-smbus
56
57      # UART
58      - items:
59          - enum:
60              - zyxel,gs1900-10hp-b1-pse
61              - zyxel,xmg1915-10ep-pse
62          - const: realtek,pse-mcu-gen2
63
64      # I2C, SMBus framing
65      - items:
66          - enum:
67              - zyxel,xs1930-12hp-pse
68          - const: realtek,pse-mcu-gen2-smbus
69
70      # I2C, raw framing
71      - items:
72          - enum:
73              - linksys,lgs328mpc-v2-pse
74          - const: realtek,pse-mcu-gen2-i2c
75
76  reg:
77    maxItems: 1
78
79  reset-gpios:
80    description: Reset line of the MCU.
81    maxItems: 1
82
83  disable-ports-gpios:
84    description:
85      Hardware gate that forces all ports into admin-disabled state while
86      asserted.
87    maxItems: 1
88
89required:
90  - compatible
91
92allOf:
93  - $ref: pse-controller.yaml#
94  # A '-smbus'/'-i2c' compatible is an I2C attachment: it has 'reg' and
95  # cannot carry serial bus properties. A bare gen compatible is a UART
96  # attachment: no 'reg', the transport comes from the parent serial node.
97  - if:
98      properties:
99        compatible:
100          contains:
101            enum:
102              - realtek,pse-mcu-gen1-smbus
103              - realtek,pse-mcu-gen2-smbus
104              - realtek,pse-mcu-gen2-i2c
105    then:
106      required:
107        - reg
108      properties:
109        current-speed: false
110        max-speed: false
111    else:
112      allOf:
113        - $ref: /schemas/serial/serial-peripheral-props.yaml#
114
115      properties:
116        reg: false
117
118unevaluatedProperties: false
119
120examples:
121  # SMBus-framed I2C attachment
122  - |
123    i2c {
124        #address-cells = <1>;
125        #size-cells = <0>;
126
127        ethernet-pse@20 {
128            compatible = "zyxel,xs1930-12hp-pse", "realtek,pse-mcu-gen2-smbus";
129            reg = <0x20>;
130
131            pse-pis {
132                #address-cells = <1>;
133                #size-cells = <0>;
134
135                pse-pi@0 {
136                    reg = <0>;
137                    #pse-cells = <0>;
138                };
139            };
140        };
141    };
142
143  # Raw-I2C-framed attachment
144  - |
145    i2c {
146        #address-cells = <1>;
147        #size-cells = <0>;
148
149        ethernet-pse@20 {
150            compatible = "linksys,lgs328mpc-v2-pse", "realtek,pse-mcu-gen2-i2c";
151            reg = <0x20>;
152
153            pse-pis {
154                #address-cells = <1>;
155                #size-cells = <0>;
156
157                pse-pi@0 {
158                    reg = <0>;
159                    #pse-cells = <0>;
160                };
161            };
162        };
163    };
164
165  # UART attachment
166  - |
167    serial {
168        ethernet-pse {
169            compatible = "zyxel,gs1900-10hp-a1-pse", "realtek,pse-mcu-gen1";
170            current-speed = <19200>;
171
172            pse-pis {
173                #address-cells = <1>;
174                #size-cells = <0>;
175
176                pse-pi@0 {
177                    reg = <0>;
178                    #pse-cells = <0>;
179                };
180            };
181        };
182    };
183