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

[Krzysztof Kozlowski <krzk@kernel.org>]

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?

> +
> +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