Re: [PATCH 2/2] dt-bindings: net: Convert fsl-fman to yaml

[Frank Li <Frank.li@nxp.com>]

On Mon, Jun 17, 2024 at 09:14:05AM +0200, Krzysztof Kozlowski wrote:
> On 14/06/2024 22:33, Frank Li wrote:
> > Convert fsl-fman from txt to yaml format and split it fsl,fman.yam,
> > fsl,fman-port.yaml, fsl-muram.yaml, fsl-mdio.yaml.
> 
> 
> > +  clocks:
> > +    items:
> > +      - description: A reference to the input clock of the controller
> > +          from which the MDC frequency is derived.
> > +
> > +  clock-frequency:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description: |
> > +      Specifies the external MDC frequency, in Hertz, to
> > +      be used. Requires that the input clock is specified in the
> > +      "clocks" property. See also: mdio.yaml.
> 
> Drop entire property. Comes from mdio.yaml.
> 
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  fsl,fman-internal-mdio:
> > +    $ref: /schemas/types.yaml#/definitions/flag
> > +    description:
> > +      Fman has internal MDIO for internal PCS(Physical
> > +      Coding Sublayer) PHYs and external MDIO for external PHYs.
> > +      The settings and programming routines for internal/external
> > +      MDIO are different. Must be included for internal MDIO.
> > +
> 
> ...
> 
> > +  - Frank Li <Frank.Li@nxp.com>
> > +
> > +description: |
> > +  FMan Internal memory - shared between all the FMan modules.
> > +  It contains data structures that are common and written to or read by
> > +  the modules.
> > +
> > +  FMan internal memory is split into the following parts:
> > +    Packet buffering (Tx/Rx FIFOs)
> > +    Frames internal context
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - fsl,fman-muram
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  ranges: true
> 
> That's odd. Why do you need ranges without children?

It think it is legacy method in driver.

	muram_node = of_find_matching_node(fm_node, fman_muram_match);                              
        if (!muram_node) {                                                                          
                err = -EINVAL;                                                                      
                dev_err(&of_dev->dev, "%s: could not find MURAM node\n",                            
                        __func__);                                                                  
                goto fman_free;                                                                     
        }                                                                                           
                                                                                                    
        err = of_address_to_resource(muram_node, 0,                                                 
                                     &fman->dts_params.muram_res);                                  
        if (err) {                                                                                  
                of_node_put(muram_node);                                                            
                dev_err(&of_dev->dev, "%s: of_address_to_resource() = %d\n",                        
                        __func__, err);                                                             
                goto fman_free;                                                                     
        }  

> 
> > +
> > +required:
> > +  - compatible
> > +  - ranges
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    muram@0 {
> > +        compatible = "fsl,fman-muram";
> > +        ranges = <0 0x000000 0x0 0x28000>;
> > +    };
> 
> 
> > diff --git a/Documentation/devicetree/bindings/net/fsl,fman-port.yaml b/Documentation/devicetree/bindings/net/fsl,fman-port.yaml
> > new file mode 100644
> > index 0000000000000..7e69cf02bd024
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/net/fsl,fman-port.yaml
> > @@ -0,0 +1,86 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/net/fsl,fman-port.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Freescale Frame Manager Port Device
> > +
> > +maintainers:
> > +  - Frank Li <Frank.Li@nxp.com>
> > +
> > +description: |
> > +  The Frame Manager (FMan) supports several types of hardware ports:
> > +    Ethernet receiver (RX)
> > +    Ethernet transmitter (TX)
> > +    Offline/Host command (O/H)
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - fsl,fman-v2-port-oh
> > +      - fsl,fman-v2-port-rx
> > +      - fsl,fman-v2-port-tx
> > +      - fsl,fman-v3-port-oh
> > +      - fsl,fman-v3-port-rx
> > +      - fsl,fman-v3-port-tx
> > +
> > +  cell-index:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description:
> > +      Specifies the hardware port id.
> > +      Each hardware port on the FMan has its own hardware PortID.
> > +      Super set of all hardware Port IDs available at FMan Reference
> > +      Manual under "FMan Hardware Ports in Freescale Devices" table.
> > +
> > +      Each hardware port is assigned a 4KB, port-specific page in
> > +      the FMan hardware port memory region (which is part of the
> > +      FMan memory map). The first 4 KB in the FMan hardware ports
> > +      memory region is used for what are called common registers.
> > +      The subsequent 63 4KB pages are allocated to the hardware
> > +      ports.
> > +      The page of a specific port is determined by the cell-index.
> > +
> > +  reg:
> > +    items:
> > +      - description: There is one reg region describing the port
> > +          configuration registers.
> > +
> > +  fsl,fman-10g-port:
> > +    $ref: /schemas/types.yaml#/definitions/flag
> > +    description: The default port rate is 1G.
> > +      If this property exists, the port is s 10G port.
> > +
> > +  fsl,fman-best-effort-port:
> > +    $ref: /schemas/types.yaml#/definitions/flag
> > +    description: The default port rate is 1G.
> > +      Can be defined only if 10G-support is set.
> > +      This property marks a best-effort 10G port (10G port that
> > +      may not be capable of line rate).
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - cell-index
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    port@a8000 {
> > +        compatible = "fsl,fman-v2-port-tx";
> > +        reg = <0xa8000 0x1000>;
> > +        cell-index = <0x28>;
> > +    };
> 
> Just keep one example.
> 
> > +
> > +    port@88000 {
> > +        cell-index = <0x8>;
> > +        compatible = "fsl,fman-v2-port-rx";
> > +        reg = <0x88000 0x1000>;
> > +    };
> > +
> > +    port@81000 {
> > +        cell-index = <0x1>;
> > +        compatible = "fsl,fman-v2-port-oh";
> > +        reg = <0x81000 0x1000>;
> > +    };
> > diff --git a/Documentation/devicetree/bindings/net/fsl,fman.yaml b/Documentation/devicetree/bindings/net/fsl,fman.yaml
> > new file mode 100644
> > index 0000000000000..dfd403f9a7c9d
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/net/fsl,fman.yaml
> > @@ -0,0 +1,335 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/net/fsl,fman.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Freescale Frame Manager Device
> > +
> > +maintainers:
> > +  - Frank Li <Frank.Li@nxp.com>
> > +
> > +description:
> > +  Due to the fact that the FMan is an aggregation of sub-engines (ports, MACs,
> > +  etc.) the FMan node will have child nodes for each of them.
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - fsl,fman
> > +    description:
> > +      FMan version can be determined via FM_IP_REV_1 register in the
> > +      FMan block. The offset is 0xc4 from the beginning of the
> > +      Frame Processing Manager memory map (0xc3000 from the
> > +      beginning of the FMan node).
> > +
> > +  cell-index:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description: |
> > +      Specifies the index of the FMan unit.
> > +
> > +      The cell-index value may be used by the SoC, to identify the
> > +      FMan unit in the SoC memory map. In the table below,
> > +      there's a description of the cell-index use in each SoC:
> > +
> > +      - P1023:
> > +      register[bit]      FMan unit  cell-index
> > +      ============================================================
> > +      DEVDISR[1]      1    0
> > +
> > +      - P2041, P3041, P4080 P5020, P5040:
> > +      register[bit]      FMan unit  cell-index
> > +      ============================================================
> > +      DCFG_DEVDISR2[6]    1    0
> > +      DCFG_DEVDISR2[14]    2    1
> > +        (Second FM available only in P4080 and P5040)
> > +
> > +      - B4860, T1040, T2080, T4240:
> > +      register[bit]      FMan unit  cell-index
> > +      ============================================================
> > +      DCFG_CCSR_DEVDISR2[24]    1    0
> > +      DCFG_CCSR_DEVDISR2[25]    2    1
> > +        (Second FM available only in T4240)
> > +
> > +      DEVDISR, DCFG_DEVDISR2 and DCFG_CCSR_DEVDISR2 are located in
> > +      the specific SoC "Device Configuration/Pin Control" Memory
> > +      Map.
> > +
> > +  reg:
> > +    items:
> > +      - description: BMI configuration registers.
> > +      - description: QMI configuration registers.
> > +      - description: DMA configuration registers.
> > +      - description: FPM configuration registers.
> > +      - description: FMan controller configuration registers.
> > +    minItems: 1
> > +
> > +  ranges: true
> > +
> > +  clocks:
> > +    maxItems: 1
> > +
> > +  clock-names:
> > +    items:
> > +      - const: fmanclk
> > +
> > +  interrupts:
> > +    items:
> > +      - description: The first element is associated with the event interrupts.
> > +      - description: the second element is associated with the error interrupts.
> > +
> > +  fsl,qman-channel-range:
> > +    $ref: /schemas/types.yaml#/definitions/uint32-array
> > +    description:
> > +      Specifies the range of the available dedicated
> > +      channels in the FMan. The first cell specifies the beginning
> > +      of the range and the second cell specifies the number of
> > +      channels
> > +    items:
> > +      - description: The first cell specifies the beginning of the range.
> > +      - description: |
> > +          The second cell specifies the number of channels.
> > +          Further information available at:
> > +          "Work Queue (WQ) Channel Assignments in the QMan" section
> > +          in DPAA Reference Manual.
> > +
> > +  fsl,qman:
> > +    $ref: /schemas/types.yaml#/definitions/phandle
> > +    description: See soc/fsl/qman.txt
> > +
> > +  fsl,bman:
> > +    $ref: /schemas/types.yaml#/definitions/phandle
> > +    description: See soc/fsl/bman.txt
> > +
> > +  fsl,erratum-a050385:
> > +    $ref: /schemas/types.yaml#/definitions/flag
> > +    description: A boolean property. Indicates the presence of the
> > +      erratum A050385 which indicates that DMA transactions that are
> > +      split can result in a FMan lock.
> > +
> > +  "#address-cells": true
> > +
> > +  "#size-cells": true
> 
> Make both const.
> 
> > +
> > +patternProperties:
> > +  '^muram@[a-f0-9]+$':
> > +    $ref: fsl,fman-muram.yaml
> > +
> > +  '^port@[a-f0-9]+$':
> > +    $ref: fsl,fman-port.yaml
> > +
> > +  '^ethernet@[a-f0-9]+$':
> > +    $ref: fsl,fman-dtsec.yaml
> > +
> > +  '^mdio@[a-f0-9]+$':
> > +    $ref: fsl,fman-mdio.yaml
> > +
> > +  '^ptp\-timer@[a-f0-9]+$':
> > +    $ref: /schemas/ptp/ptp-qoriq.yaml
> > +
> > +required:
> > +  - compatible
> > +  - cell-index
> > +  - reg
> > +  - ranges
> > +  - clocks
> > +  - clock-names
> > +  - interrupts
> > +  - fsl,qman-channel-range
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    fman@400000 {
> > +        #address-cells = <1>;
> > +        #size-cells = <1>;
> > +        cell-index = <1>;
> > +        compatible = "fsl,fman";
> 
> Compatible is always the first property. reg follows, third ranges.
> 
> > +        ranges = <0 0x400000 0x100000>;
> > +        reg = <0x400000 0x100000>;
> > +        clocks = <&fman_clk>;
> > +        clock-names = "fmanclk";
> > +        interrupts = <96 2>,
> > +                     <16 2>;
> 
> Use proper defines for flags.
> 
> 
> 
> Best regards,
> Krzysztof
>