Re: [PATCH 1/1] dt-bindings: net: snps,dwmac: Document queue config subnodes

[Krzysztof Kozlowski]

On 21/10/2022 13:10, Sebastian Reichel wrote:
> The queue configuration is referenced by snps,mtl-rx-config and
> snps,mtl-tx-config. Most in-tree DTs put the referenced object
> as child node of the dwmac node.
> 
> This adds proper description for this setup, which has the
> advantage of properly making sure only known properties are
> used.
> 
> Signed-off-by: Sebastian Reichel <sebastian.reichel@xxxxxxxxxxxxx>
> ---
>  .../devicetree/bindings/net/snps,dwmac.yaml   | 154 ++++++++++++------
>  1 file changed, 108 insertions(+), 46 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml
> index 13b984076af5..0bf6112cec2f 100644
> --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml
> +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml
> @@ -167,56 +167,118 @@ properties:
>    snps,mtl-rx-config:
>      $ref: /schemas/types.yaml#/definitions/phandle
>      description:
> -      Multiple RX Queues parameters. Phandle to a node that can
> -      contain the following properties
> -        * snps,rx-queues-to-use, number of RX queues to be used in the
> -          driver
> -        * Choose one of these RX scheduling algorithms
> -          * snps,rx-sched-sp, Strict priority
> -          * snps,rx-sched-wsp, Weighted Strict priority
> -        * For each RX queue
> -          * Choose one of these modes
> -            * snps,dcb-algorithm, Queue to be enabled as DCB
> -            * snps,avb-algorithm, Queue to be enabled as AVB
> -          * snps,map-to-dma-channel, Channel to map
> -          * Specifiy specific packet routing
> -            * snps,route-avcp, AV Untagged Control packets
> -            * snps,route-ptp, PTP Packets
> -            * snps,route-dcbcp, DCB Control Packets
> -            * snps,route-up, Untagged Packets
> -            * snps,route-multi-broad, Multicast & Broadcast Packets
> -          * snps,priority, bitmask of the tagged frames priorities assigned to
> -            the queue
> +      Multiple RX Queues parameters. Phandle to a node that
> +      implements the 'rx-queues-config' object described in
> +      this binding.
> +
> +  rx-queues-config:

If this field is specific to this device, then you need vendor prefix:
snps,rq-queues-config

> +    type: object
> +    properties:
> +      snps,rx-queues-to-use:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: number of RX queues to be used in the driver
> +      snps,rx-sched-sp:
> +        type: boolean
> +        description: Strict priority
> +      snps,rx-sched-wsp:
> +        type: boolean
> +        description: Weighted Strict priority
> +    patternProperties:
> +      "^queue[0-9]$":
> +        description: Each subnode represents a queue.
> +        type: object
> +        properties:
> +          snps,dcb-algorithm:
> +            type: boolean
> +            description: Queue to be enabled as DCB
> +          snps,avb-algorithm:
> +            type: boolean
> +            description: Queue to be enabled as AVB
> +          snps,map-to-dma-channel:
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            description: DMA channel id to map
> +          snps,route-avcp:
> +            type: boolean
> +            description: AV Untagged Control packets
> +          snps,route-ptp:
> +            type: boolean
> +            description: PTP Packets
> +          snps,route-dcbcp:
> +            type: boolean
> +            description: DCB Control Packets
> +          snps,route-up:
> +            type: boolean
> +            description: Untagged Packets
> +          snps,route-multi-broad:
> +            type: boolean
> +            description: Multicast & Broadcast Packets
> +          snps,priority:
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            description: Bitmask of the tagged frames priorities assigned to the queue
> +    additionalProperties: false

Please update the DTS example with all this.

>  
>    snps,mtl-tx-config:
>      $ref: /schemas/types.yaml#/definitions/phandle
>      description:
> -      Multiple TX Queues parameters. Phandle to a node that can
> -      contain the following properties
> -        * snps,tx-queues-to-use, number of TX queues to be used in the
> -          driver
> -        * Choose one of these TX scheduling algorithms
> -          * snps,tx-sched-wrr, Weighted Round Robin
> -          * snps,tx-sched-wfq, Weighted Fair Queuing
> -          * snps,tx-sched-dwrr, Deficit Weighted Round Robin
> -          * snps,tx-sched-sp, Strict priority
> -        * For each TX queue
> -          * snps,weight, TX queue weight (if using a DCB weight
> -            algorithm)
> -          * Choose one of these modes
> -            * snps,dcb-algorithm, TX queue will be working in DCB
> -            * snps,avb-algorithm, TX queue will be working in AVB
> -              [Attention] Queue 0 is reserved for legacy traffic
> -                          and so no AVB is available in this queue.
> -          * Configure Credit Base Shaper (if AVB Mode selected)
> -            * snps,send_slope, enable Low Power Interface
> -            * snps,idle_slope, unlock on WoL
> -            * snps,high_credit, max write outstanding req. limit
> -            * snps,low_credit, max read outstanding req. limit
> -          * snps,priority, bitmask of the priorities assigned to the queue.
> -            When a PFC frame is received with priorities matching the bitmask,
> -            the queue is blocked from transmitting for the pause time specified
> -            in the PFC frame.
> +      Multiple TX Queues parameters. Phandle to a node that
> +      implements the 'tx-queues-config' object described in
> +      this binding.
> +
> +  tx-queues-config:
> +    type: object
> +    properties:
> +      snps,tx-queues-to-use:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description: number of TX queues to be used in the driver
> +      snps,tx-sched-wrr:
> +        type: boolean
> +        description: Weighted Round Robin
> +      snps,tx-sched-wfq:
> +        type: boolean
> +        description: Weighted Fair Queuing
> +      snps,tx-sched-dwrr:
> +        type: boolean
> +        description: Deficit Weighted Round Robin
> +      snps,tx-sched-sp:
> +        type: boolean
> +        description: Strict priority
> +    patternProperties:
> +      "^queue[0-9]$":
> +        description: Each subnode represents a queue.
> +        type: object
> +        properties:
> +          snps,weight:
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            description: TX queue weight (if using a DCB weight algorithm)
> +          snps,dcb-algorithm:
> +            type: boolean
> +            description: TX queue will be working in DCB
> +          snps,avb-algorithm:

Is DCB and AVB compatible with each other? If not, then this should be
rather enum (with a string for algorithm name).

This applies also to other fields which are mutually exclusive.

> +            type: boolean
> +            description:
> +              TX queue will be working in AVB.
> +              Queue 0 is reserved for legacy traffic and so no AVB is
> +              available in this queue.
> +          snps,send_slope:

Use hyphens, no underscores.
(This is already an incompatible change in bindings, so we can fix up
the naming)

> +            type: boolean
> +            description: enable Low Power Interface
> +          snps,idle_slope:
> +            type: boolean
> +            description: unlock on WoL
> +          snps,high_credit:
> +            type: boolean
> +            description: max write outstanding req. limit

Is it really a boolean?

> +          snps,low_credit:
> +            type: boolean
> +            description: max read outstanding req. limit

Same question

> +          snps,priority:
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            description:
> +              Bitmask of the tagged frames priorities assigned to the queue.
> +              When a PFC frame is received with priorities matching the bitmask,
> +              the queue is blocked from transmitting for the pause time specified
> +              in the PFC frame.
> +    additionalProperties: false
>  
>    snps,reset-gpio:
>      deprecated: true

Best regards,
Krzysztof