Re: [PATCH net-next 02/20] dt-bindings: net: qcom,ppe: Add bindings yaml file

[Krzysztof Kozlowski]

On 10/01/2024 12:40, Luo Jie wrote:
> Qualcomm PPE(packet process engine) is supported on
> IPQ SOC platform.
> 

A nit, subject: drop second/last, redundant "bindings". The
"dt-bindings" prefix is already stating that these are bindings.
See also:
https://elixir.bootlin.com/linux/v6.7-rc8/source/Documentation/devicetree/bindings/submitting-patches.rst#L18

Basically your subject has only prefix and nothing else useful.

Limited review follows, I am not wasting my time much on this.

> Signed-off-by: Luo Jie <quic_luoj@xxxxxxxxxxx>
> ---
>  .../devicetree/bindings/net/qcom,ppe.yaml     | 1330 +++++++++++++++++
>  1 file changed, 1330 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/qcom,ppe.yaml
> 
> diff --git a/Documentation/devicetree/bindings/net/qcom,ppe.yaml b/Documentation/devicetree/bindings/net/qcom,ppe.yaml
> new file mode 100644
> index 000000000000..6afb2ad62707
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/qcom,ppe.yaml
> @@ -0,0 +1,1330 @@
> +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/qcom,ppe.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Qualcomm Packet Process Engine Ethernet controller

Where is the ref to ethernet controllers schema?

> +
> +maintainers:
> +  - Luo Jie <quic_luoj@xxxxxxxxxxx>
> +
> +description:
> +  The PPE(packet process engine) is comprised of three componets, Ethernet
> +  DMA, Switch core and Port wrapper, Ethernet DMA is used to transmit and
> +  receive packets between Ethernet subsytem and host. The Switch core has
> +  maximum 8 ports(maximum 6 front panel ports and two FIFO interfaces),
> +  among which there are GMAC/XGMACs used as external interfaces and FIFO
> +  interfaces connected the EDMA/EIP, The port wrapper provides connections
> +  from the GMAC/XGMACS to SGMII/QSGMII/PSGMII/USXGMII/10G-BASER etc, there
> +  are maximu 3 UNIPHY(PCS) instances supported by PPE.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - qcom,ipq5332-ppe
> +      - qcom,ipq9574-ppe
> +
> +  reg:
> +    maxItems: 1
> +
> +  "#address-cells":
> +    const: 1
> +
> +  "#size-cells":
> +    const: 1
> +
> +  ranges: true
> +
> +  clocks: true

These cannot be true, we expect here widest constraints.

> +
> +  clock-names: true
> +
> +  resets: true
> +
> +  reset-names: true
> +
> +  tdm-config:
> +    type: object
> +    additionalProperties: false
> +    description: |
> +      PPE TDM(time-division multiplexing) config includes buffer management
> +      and port scheduler.
> +
> +    properties:
> +      qcom,tdm-bm-config:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          The TDM buffer scheduler configs of PPE, there are multiple
> +          entries supported, each entry includes valid, direction
> +          (ingress or egress), port, second port valid, second port.
> +
> +      qcom,tdm-port-scheduler-config:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          The TDM port scheduler management configs of PPE, there
> +          are multiple entries supported each entry includes ingress
> +          scheduler port bitmap, ingress scheduler port, egress
> +          scheduler port, second egress scheduler port valid and
> +          second egress scheduler port.
> +
> +    required:
> +      - qcom,tdm-bm-config
> +      - qcom,tdm-port-scheduler-config
> +
> +  buffer-management-config:
> +    type: object
> +    additionalProperties: false
> +    description: |
> +      PPE buffer management config, which supports configuring group
> +      buffer and per port buffer, which decides the threshold of the
> +      flow control frame generated.
> +

I don't understand this sentence. Rephrase it to proper sentence and
proper hardware, not driver, description.

> +    properties:
> +      qcom,group-config:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          The PPE buffer support 4 groups, the entry includes
> +          the group ID and group buffer numbers, each buffer
> +          has 256 bytes.

Missing constraints, like min/max and number of items.

> +
> +      qcom,port-config:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          The PPE buffer number is also assigned per BM port ID,
> +          there are 10 BM ports supported on ipq5332, and 15 BM
> +          ports supported on ipq9574. Each entry includs group
> +          ID, BM port ID, dedicated buffer, the buffer numbers
> +          for receiving packet after pause frame sent, the
> +          threshold for pause frame, weight, restore ceil and
> +          dynamic buffer or static buffer management.
> +
> +    required:
> +      - qcom,group-config
> +      - qcom,port-config
> +
> +  queue-management-config:
> +    type: object
> +    additionalProperties: false
> +    description: |
> +      PPE queue management config, which supports configuring group
> +      and per queue buffer limitation, which decides the threshold
> +      to drop the packet on the egress port.
> +
> +    properties:
> +      qcom,group-config:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          The PPE queue management support 4 groups, the entry
> +          includes the group ID, group buffer number, dedicated
> +          buffer number, threshold to drop packet and restore
> +          ceil.
> +
> +      qcom,queue-config:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          PPE has 256 unicast queues and 44 multicast queues, the
> +          entry includes queue base, queue number, group ID,
> +          dedicated buffer, the threshold to drop packet, weight,
> +          restore ceil and dynamic or static queue management.
> +
> +    required:
> +      - qcom,group-config
> +      - qcom,queue-config
> +
> +  port-scheduler-resource:
> +    type: object
> +    additionalProperties: false
> +    description: The scheduler resource available in PPE.
> +    patternProperties:
> +      "^port[0-7]$":

port-

> +        description: Each subnode represents the scheduler resource per port.
> +        type: object
> +        properties:
> +          port-id:
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            description: |

Do not need '|' unless you need to preserve formatting. This applies
everywhere.

> +              The PPE port ID, there are maximum 6 physical port,
> +              EIP port and CPU port.

Your node  name suffix says 8 ports. Anyway, missing min/max.

All these nodes (before, here and further) looks like dump of vendor code.

I expect some good explanation why we should accept this. Commit msg you
wrote is meaningless. It literally brings zero information about hardware.

You have been asked to provide accurate hardware description yet you
keep ignoring people's feedback.
..

> +
> +patternProperties:


phy@

Node names should be generic. See also an explanation and list of
examples (not exhaustive) in DT specification:
https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation


> +  "^qcom-uniphy@[0-9a-f]+$":
> +    type: object
> +    additionalProperties: false
> +    description: uniphy configuration and clock provider
> +    properties:
> +      reg:
> +        minItems: 2
> +        items:
> +          - description: The first uniphy register range
> +          - description: The second uniphy register range
> +          - description: The third uniphy register range

first, second and third are really useless descriptions. We expect
something useful.

> +
> +      "#clock-cells":
> +        const: 1
> +
> +      clock-output-names:
> +        minItems: 4
> +        maxItems: 6
> +
> +    required:
> +      - reg
> +      - "#clock-cells"
> +      - clock-output-names
> +
> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: qcom,ipq5332-ppe
> +    then:
> +      properties:
> +        clocks:
> +          items:
> +            - description: Display common AHB clock from gcc
> +            - description: Display common system clock from gcc
> +            - description: Display uniphy0 AHB clock from gcc
> +            - description: Display uniphy1 AHB clock from gcc
> +            - description: Display uniphy0 system clock from gcc
> +            - description: Display uniphy1 system clock from gcc
> +            - description: Display nss clock from gcc
> +            - description: Display nss noc snoc clock from gcc
> +            - description: Display nss noc snoc_1 clock from gcc
> +            - description: Display sleep clock from gcc
> +            - description: Display PPE clock from nsscc
> +            - description: Display PPE config clock from nsscc
> +            - description: Display NSSNOC PPE clock from nsscc
> +            - description: Display NSSNOC PPE config clock from nsscc
> +            - description: Display EDMA clock from nsscc
> +            - description: Display EDMA config clock from nsscc
> +            - description: Display PPE IPE clock from nsscc
> +            - description: Display PPE BTQ clock from nsscc
> +            - description: Display port1 MAC clock from nsscc
> +            - description: Display port2 MAC clock from nsscc
> +            - description: Display port1 RX clock from nsscc
> +            - description: Display port1 TX clock from nsscc
> +            - description: Display port2 RX clock from nsscc
> +            - description: Display port2 TX clock from nsscc
> +            - description: Display UNIPHY port1 RX clock from nsscc
> +            - description: Display UNIPHY port1 TX clock from nsscc
> +            - description: Display UNIPHY port2 RX clock from nsscc
> +            - description: Display UNIPHY port2 TX clock from nsscc
> +        clock-names:
> +          items:
> +            - const: cmn_ahb
> +            - const: cmn_sys
> +            - const: uniphy0_ahb
> +            - const: uniphy1_ahb
> +            - const: uniphy0_sys
> +            - const: uniphy1_sys
> +            - const: gcc_nsscc
> +            - const: gcc_nssnoc_snoc
> +            - const: gcc_nssnoc_snoc_1
> +            - const: gcc_im_sleep
> +            - const: nss_ppe
> +            - const: nss_ppe_cfg
> +            - const: nssnoc_ppe
> +            - const: nssnoc_ppe_cfg
> +            - const: nss_edma
> +            - const: nss_edma_cfg
> +            - const: nss_ppe_ipe
> +            - const: nss_ppe_btq
> +            - const: port1_mac
> +            - const: port2_mac
> +            - const: nss_port1_rx
> +            - const: nss_port1_tx
> +            - const: nss_port2_rx
> +            - const: nss_port2_tx
> +            - const: uniphy_port1_rx
> +            - const: uniphy_port1_tx
> +            - const: uniphy_port2_rx
> +            - const: uniphy_port2_tx
> +
> +        resets:
> +          items:
> +            - description: Reset PPE
> +            - description: Reset uniphy0 software config
> +            - description: Reset uniphy1 software config
> +            - description: Reset uniphy0 AHB
> +            - description: Reset uniphy1 AHB
> +            - description: Reset uniphy0 system
> +            - description: Reset uniphy1 system
> +            - description: Reset uniphy0 XPCS
> +            - description: Reset uniphy1 SPCS
> +            - description: Reset uniphy port1 RX
> +            - description: Reset uniphy port1 TX
> +            - description: Reset uniphy port2 RX
> +            - description: Reset uniphy port2 TX
> +            - description: Reset PPE port1 RX
> +            - description: Reset PPE port1 TX
> +            - description: Reset PPE port2 RX
> +            - description: Reset PPE port2 TX
> +            - description: Reset PPE port1 MAC
> +            - description: Reset PPE port2 MAC
> +
> +        reset-names:
> +          items:
> +            - const: ppe
> +            - const: uniphy0_soft
> +            - const: uniphy1_soft
> +            - const: uniphy0_ahb
> +            - const: uniphy1_ahb
> +            - const: uniphy0_sys
> +            - const: uniphy1_sys
> +            - const: uniphy0_xpcs
> +            - const: uniphy1_xpcs
> +            - const: uniphy_port1_rx
> +            - const: uniphy_port1_tx
> +            - const: uniphy_port2_rx
> +            - const: uniphy_port2_tx
> +            - const: nss_port1_rx
> +            - const: nss_port1_tx
> +            - const: nss_port2_rx
> +            - const: nss_port2_tx
> +            - const: nss_port1_mac
> +            - const: nss_port2_mac
> +
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: qcom,ipq9574-ppe
> +    then:
> +      properties:
> +        clocks:
> +          items:
> +            - description: Display common AHB clock from gcc
> +            - description: Display common system clock from gcc
> +            - description: Display uniphy0 AHB clock from gcc
> +            - description: Display uniphy1 AHB clock from gcc
> +            - description: Display uniphy2 AHB clock from gcc
> +            - description: Display uniphy0 system clock from gcc
> +            - description: Display uniphy1 system clock from gcc
> +            - description: Display uniphy2 system clock from gcc
> +            - description: Display nss clock from gcc
> +            - description: Display nss noc clock from gcc
> +            - description: Display nss noc snoc clock from gcc
> +            - description: Display nss noc snoc_1 clock from gcc
> +            - description: Display PPE clock from nsscc
> +            - description: Display PPE config clock from nsscc
> +            - description: Display NSSNOC PPE clock from nsscc
> +            - description: Display NSSNOC PPE config clock from nsscc
> +            - description: Display EDMA clock from nsscc
> +            - description: Display EDMA config clock from nsscc
> +            - description: Display PPE IPE clock from nsscc
> +            - description: Display PPE BTQ clock from nsscc
> +            - description: Display port1 MAC clock from nsscc
> +            - description: Display port2 MAC clock from nsscc
> +            - description: Display port3 MAC clock from nsscc
> +            - description: Display port4 MAC clock from nsscc
> +            - description: Display port5 MAC clock from nsscc
> +            - description: Display port6 MAC clock from nsscc
> +            - description: Display port1 RX clock from nsscc
> +            - description: Display port1 TX clock from nsscc
> +            - description: Display port2 RX clock from nsscc
> +            - description: Display port2 TX clock from nsscc
> +            - description: Display port3 RX clock from nsscc
> +            - description: Display port3 TX clock from nsscc
> +            - description: Display port4 RX clock from nsscc
> +            - description: Display port4 TX clock from nsscc
> +            - description: Display port5 RX clock from nsscc
> +            - description: Display port5 TX clock from nsscc
> +            - description: Display port6 RX clock from nsscc
> +            - description: Display port6 TX clock from nsscc
> +            - description: Display UNIPHY port1 RX clock from nsscc
> +            - description: Display UNIPHY port1 TX clock from nsscc
> +            - description: Display UNIPHY port2 RX clock from nsscc
> +            - description: Display UNIPHY port2 TX clock from nsscc
> +            - description: Display UNIPHY port3 RX clock from nsscc
> +            - description: Display UNIPHY port3 TX clock from nsscc
> +            - description: Display UNIPHY port4 RX clock from nsscc
> +            - description: Display UNIPHY port4 TX clock from nsscc
> +            - description: Display UNIPHY port5 RX clock from nsscc
> +            - description: Display UNIPHY port5 TX clock from nsscc
> +            - description: Display UNIPHY port6 RX clock from nsscc
> +            - description: Display UNIPHY port6 TX clock from nsscc
> +            - description: Display port5 RX clock source from nsscc
> +            - description: Display port5 TX clock source from nsscc
> +        clock-names:
> +          items:
> +            - const: cmn_ahb
> +            - const: cmn_sys
> +            - const: uniphy0_ahb
> +            - const: uniphy1_ahb
> +            - const: uniphy2_ahb
> +            - const: uniphy0_sys
> +            - const: uniphy1_sys
> +            - const: uniphy2_sys
> +            - const: gcc_nsscc
> +            - const: gcc_nssnoc_nsscc
> +            - const: gcc_nssnoc_snoc
> +            - const: gcc_nssnoc_snoc_1
> +            - const: nss_ppe
> +            - const: nss_ppe_cfg
> +            - const: nssnoc_ppe
> +            - const: nssnoc_ppe_cfg
> +            - const: nss_edma
> +            - const: nss_edma_cfg
> +            - const: nss_ppe_ipe
> +            - const: nss_ppe_btq
> +            - const: port1_mac
> +            - const: port2_mac
> +            - const: port3_mac
> +            - const: port4_mac
> +            - const: port5_mac
> +            - const: port6_mac
> +            - const: nss_port1_rx
> +            - const: nss_port1_tx
> +            - const: nss_port2_rx
> +            - const: nss_port2_tx
> +            - const: nss_port3_rx
> +            - const: nss_port3_tx
> +            - const: nss_port4_rx
> +            - const: nss_port4_tx
> +            - const: nss_port5_rx
> +            - const: nss_port5_tx
> +            - const: nss_port6_rx
> +            - const: nss_port6_tx
> +            - const: uniphy_port1_rx
> +            - const: uniphy_port1_tx
> +            - const: uniphy_port2_rx
> +            - const: uniphy_port2_tx
> +            - const: uniphy_port3_rx
> +            - const: uniphy_port3_tx
> +            - const: uniphy_port4_rx
> +            - const: uniphy_port4_tx
> +            - const: uniphy_port5_rx
> +            - const: uniphy_port5_tx
> +            - const: uniphy_port6_rx
> +            - const: uniphy_port6_tx
> +            - const: nss_port5_rx_clk_src
> +            - const: nss_port5_tx_clk_src
> +
> +        resets:
> +          items:
> +            - description: Reset PPE
> +            - description: Reset uniphy0 software config
> +            - description: Reset uniphy1 software config
> +            - description: Reset uniphy2 software config
> +            - description: Reset uniphy0 AHB
> +            - description: Reset uniphy1 AHB
> +            - description: Reset uniphy2 AHB
> +            - description: Reset uniphy0 system
> +            - description: Reset uniphy1 system
> +            - description: Reset uniphy2 system
> +            - description: Reset uniphy0 XPCS
> +            - description: Reset uniphy1 XPCS
> +            - description: Reset uniphy2 XPCS
> +            - description: Assert uniphy port1
> +            - description: Assert uniphy port2
> +            - description: Assert uniphy port3
> +            - description: Assert uniphy port4
> +            - description: Reset PPE port1
> +            - description: Reset PPE port2
> +            - description: Reset PPE port3
> +            - description: Reset PPE port4
> +            - description: Reset PPE port5
> +            - description: Reset PPE port6
> +            - description: Reset PPE port1 MAC
> +            - description: Reset PPE port2 MAC
> +            - description: Reset PPE port3 MAC
> +            - description: Reset PPE port4 MAC
> +            - description: Reset PPE port5 MAC
> +            - description: Reset PPE port6 MAC
> +
> +        reset-names:
> +          items:
> +            - const: ppe
> +            - const: uniphy0_soft
> +            - const: uniphy1_soft
> +            - const: uniphy2_soft
> +            - const: uniphy0_ahb
> +            - const: uniphy1_ahb
> +            - const: uniphy2_ahb
> +            - const: uniphy0_sys
> +            - const: uniphy1_sys
> +            - const: uniphy2_sys
> +            - const: uniphy0_xpcs
> +            - const: uniphy1_xpcs
> +            - const: uniphy2_xpcs
> +            - const: uniphy0_port1_dis
> +            - const: uniphy0_port2_dis
> +            - const: uniphy0_port3_dis
> +            - const: uniphy0_port4_dis
> +            - const: nss_port1
> +            - const: nss_port2
> +            - const: nss_port3
> +            - const: nss_port4
> +            - const: nss_port5
> +            - const: nss_port6
> +            - const: nss_port1_mac
> +            - const: nss_port2_mac
> +            - const: nss_port3_mac
> +            - const: nss_port4_mac
> +            - const: nss_port5_mac
> +            - const: nss_port6_mac
> +
> +required:

allOf: goes after required:

> +  - compatible
> +  - reg
> +  - "#address-cells"
> +  - "#size-cells"
> +  - ranges
> +  - clocks
> +  - clock-names
> +  - resets
> +  - reset-names
> +  - tdm-config
> +  - buffer-management-config
> +  - queue-management-config
> +  - port-scheduler-resource
> +  - port-scheduler-config
> +
> +additionalProperties: false


> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/qcom,ipq9574-gcc.h>
> +    #include <dt-bindings/reset/qcom,ipq9574-gcc.h>
> +    #include <dt-bindings/clock/qcom,ipq9574-nsscc.h>
> +    #include <dt-bindings/reset/qcom,ipq9574-nsscc.h>
> +
> +    soc {
> +      #address-cells = <1>;
> +      #size-cells = <1>;
> +      qcom_ppe: qcom-ppe@3a000000 {

Drop label, Generic node names.

> +              compatible = "qcom,ipq9574-ppe";

Entire indentation of example is broken. Use one described in the
bindings coding style.

Best regards,
Krzysztof