[4/6] dt-bindings: net: add hisilicon-femac

  From: Yang Xiwen <forbidden405@outlook.com>

This binding gets rewritten. Compared to previous txt based binding doc,
the following changes are made:

- No "hisi-femac-v1/2" binding anymore
- Remove unused Hi3516 SoC, add Hi3798MV200
- add MDIO subnode
- add phy clock and reset

Signed-off-by: Yang Xiwen <forbidden405@outlook.com>
---
 .../devicetree/bindings/net/hisilicon-femac.yaml   | 125 +++++++++++++++++++++
 1 file changed, 125 insertions(+)
  

On Fri, 16 Feb 2024 07:48:56 +0800, Yang Xiwen wrote:
> This binding gets rewritten. Compared to previous txt based binding doc,
> the following changes are made:
> 
> - No "hisi-femac-v1/2" binding anymore
> - Remove unused Hi3516 SoC, add Hi3798MV200
> - add MDIO subnode
> - add phy clock and reset
> 
> Signed-off-by: Yang Xiwen <forbidden405@outlook.com>
> ---
>  .../devicetree/bindings/net/hisilicon-femac.yaml   | 125 +++++++++++++++++++++
>  1 file changed, 125 insertions(+)
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
Documentation/devicetree/bindings/net/hisilicon-femac.example.dtb: /example-0/ethernet@9c30000/mdio@1100: failed to match any schema with compatible: ['hisilicon,hisi-femac-mdio']

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20240216-net-v1-4-e0ad972cda99@outlook.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.
  

On 16/02/2024 07:30, Yang Xiwen wrote:
> On 2/16/2024 10:09 AM, Rob Herring wrote:
>> On Fri, 16 Feb 2024 07:48:56 +0800, Yang Xiwen wrote:
>>> This binding gets rewritten. Compared to previous txt based binding doc,
>>> the following changes are made:
>>>
>>> - No "hisi-femac-v1/2" binding anymore
>>> - Remove unused Hi3516 SoC, add Hi3798MV200
>>> - add MDIO subnode
>>> - add phy clock and reset
>>>
>>> Signed-off-by: Yang Xiwen <forbidden405@outlook.com>
>>> ---
>>>   .../devicetree/bindings/net/hisilicon-femac.yaml   | 125 +++++++++++++++++++++
>>>   1 file changed, 125 insertions(+)
>>>
>> My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
>> on your patch (DT_CHECKER_FLAGS is new in v5.13):
>>
>> yamllint warnings/errors:
>>
>> dtschema/dtc warnings/errors:
>> Documentation/devicetree/bindings/net/hisilicon-femac.example.dtb: /example-0/ethernet@9c30000/mdio@1100: failed to match any schema with compatible: ['hisilicon,hisi-femac-mdio']
> it's fine. This compatible is documented in a plain text file 
> `./hisi-femac-mdio.txt`.

No, it is not fine. This must be fixed.

Best regards,
Krzysztof
  

On 16/02/2024 00:48, Yang Xiwen via B4 Relay wrote:
> From: Yang Xiwen <forbidden405@outlook.com>
> 
> This binding gets rewritten. Compared to previous txt based binding doc,
> the following changes are made:
> 
> - No "hisi-femac-v1/2" binding anymore
> - Remove unused Hi3516 SoC, add Hi3798MV200
> - add MDIO subnode
> - add phy clock and reset

I don't understand why conversion you make in two commits. Please
perform proper conversion and then propose changes to the binding.

> 
> Signed-off-by: Yang Xiwen <forbidden405@outlook.com>
> ---
>  .../devicetree/bindings/net/hisilicon-femac.yaml   | 125 +++++++++++++++++++++
>  1 file changed, 125 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/net/hisilicon-femac.yaml b/Documentation/devicetree/bindings/net/hisilicon-femac.yaml
> new file mode 100644
> index 000000000000..008127e148aa
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/hisilicon-femac.yaml

Use compatible as filename.

> @@ -0,0 +1,125 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/hisilicon-femac.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Hisilicon Fast Ethernet MAC controller
> +
> +maintainers:
> +  - Yang Xiwen <forbidden405@foxmail.com>
> +
> +allOf:
> +  - $ref: ethernet-controller.yaml
> +
> +properties:
> +  compatible:
> +    enum:
> +      - hisilicon,hi3798mv200-femac
> +
> +  reg:
> +    minItems: 2
> +    maxItems: 2
> +    description: |
> +      The first region is the MAC core register base and size.
> +      The second region is the global MAC control register.

Just items: - description: instead of all this.

> +
> +  ranges:
> +    maxItems: 1
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    minItems: 3

Drop

> +    maxItems: 3
> +
> +  clock-names:
> +    items:
> +      - const: mac
> +      - const: macif
> +      - const: phy
> +
> +  resets:
> +    minItems: 2

Drop

> +    maxItems: 2
> +
> +  reset-names:
> +    items:
> +      - const: mac
> +      - const: phy
> +
> +  hisilicon,phy-reset-delays-us:
> +    minItems: 3
> +    maxItems: 3
> +    description: |
> +      The 1st cell is reset pre-delay in micro seconds.
> +      The 2nd cell is reset pulse in micro seconds.
> +      The 3rd cell is reset post-delay in micro seconds.

items:
 - description:

Anyway, isn't this property of the phy?


> +
> +patternProperties:
> +  '^mdio@[0-9a-f]+$':
> +    type: object
> +    description: See ./hisi-femac-mdio.txt

No, please first convert other file and then reference it here.

> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +  - resets
> +  - reset-names
> +  - phy-connection-type
> +  - phy-handle
> +  - hisilicon,phy-reset-delays-us
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +    #include <dt-bindings/clock/histb-clock.h>
> +
> +    #ifndef HISTB_ETH0_PHY_CLK
> +    #define HISTB_ETH0_PHY_CLK 0
> +    #endif

Drop these defines.

> +    femac: ethernet@9c30000 {

Drop label.

> +        compatible = "hisilicon,hi3798mv200-femac";
> +        reg = <0x9c30000 0x1000>, <0x9c31300 0x200>;
> +        ranges = <0x0 0x9c30000 0x10000>;
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +        interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>;
> +        clocks = <&crg HISTB_ETH0_MAC_CLK>,
> +                 <&crg HISTB_ETH0_MACIF_CLK>,
> +                 <&crg HISTB_ETH0_PHY_CLK>;
> +        clock-names = "mac", "macif", "phy";
> +        resets = <&crg 0xd0 3>, <&crg 0x388 4>;
> +        reset-names = "mac", "phy";
> +        phy-handle = <&fephy>;
> +        phy-connection-type = "mii";
> +        // To be filled by bootloader
> +        mac-address = [00 00 00 00 00 00];
> +        hisilicon,phy-reset-delays-us = <10000 10000 500000>;
> +        status = "okay";

Drop

> +
> +        mdio: mdio@1100 {

Drop label

> +            compatible = "hisilicon,hisi-femac-mdio";
> +            reg = <0x1100 0x20>;
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +            status = "okay";

Drop

> +
> +            fephy: ethernet-phy@1 {

Drop label


> +                reg = <1>;
> +                #phy-cells = <0>;
> +            };
> +        };
> +    };
> 

Best regards,
Krzysztof
  

On 16/02/2024 10:36, Yang Xiwen wrote:
>>
>>> +    maxItems: 2
>>> +
>>> +  reset-names:
>>> +    items:
>>> +      - const: mac
>>> +      - const: phy
>>> +
>>> +  hisilicon,phy-reset-delays-us:
>>> +    minItems: 3
>>> +    maxItems: 3
>>> +    description: |
>>> +      The 1st cell is reset pre-delay in micro seconds.
>>> +      The 2nd cell is reset pulse in micro seconds.
>>> +      The 3rd cell is reset post-delay in micro seconds.
>> items:
>>   - description:
>>
>> Anyway, isn't this property of the phy?
> It ought to be. But it seems a bit hard to implement it like this.

Why? You have phy node, so phy should know what to do.



Best regards,
Krzysztof
  

> I've tried accessing MDIO address space and MAC controller address space in
> u-boot with `md` and `mw` [1]. From the result, i guess the CLK_BUS is the
> System Bus clock (AHB Bus clock), and the CLK_MAC is the clock shared by
> both MDIO bus and MAC. The MAC has a internal clock divider to divide the
> input clock(54MHz in common) to a configurable variable rate.

In general, sharing a clock is not a problem. The clock API does
reference counting. So if two consumers enable the clock, it will not
be disabled until two consumes disable the clock. So it should not be
an issue for both the MAC and the MDIO driver to consume the clock.

However, the funny PHY reset code is going to be key here. We need to
understand that in more detail.

Talking about details, you commit messages need improving. The commit
message is your chance to answer all the reviewers questions before
they even ask them. Removing a binding was always going to need
justification, so you needed to have that in the commit message.  In
order to review a DT bindings, having an overview of what the hardware
actually looks like is needed. So that is something which you can add
to the commit messages.

Please take a look at your patches from the perspective of a reviewer,
somebody how knows nothing about this device. What information is
needed to understand the patches?

       Andrew