[1/3] dt-bindings: net: dp83826: add ti,cfg-dac-minus binding

  Add property ti,cfg-dac-minus to allow for voltage tuning
of logical level -1 of the MLT-3 encoded data.

Signed-off-by: Catalin Popescu <catalin.popescu@leica-geosystems.com>
---
 Documentation/devicetree/bindings/net/ti,dp83822.yaml | 9 +++++++++
 1 file changed, 9 insertions(+)
  

On Thu, 11 Jan 2024 17:19:25 +0100, Catalin Popescu wrote:
> Add property ti,cfg-dac-minus to allow for voltage tuning
> of logical level -1 of the MLT-3 encoded data.
> 
> Signed-off-by: Catalin Popescu <catalin.popescu@leica-geosystems.com>
> ---
>  Documentation/devicetree/bindings/net/ti,dp83822.yaml | 9 +++++++++
>  1 file changed, 9 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:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/ti,dp83822.yaml: ti,cfg-dac-minus: missing type definition

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20240111161927.3689084-1-catalin.popescu@leica-geosystems.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 11.01.24 17:47, Andrew Lunn wrote:
> This email is not from Hexagon’s Office 365 instance. Please be careful while clicking links, opening attachments, or replying to this email.
>
>
>> These are not raw register values and these are not voltage values but
>> voltage ratios. I'm mapping the voltage ratios to enum values [0-16]
>> which are converted to register raw values by the driver. I don't see a
>> better way to do this.
> I assume 802.3 states what the actual voltage should be? So you can
> calculate what 50% of that is?
>
>            Andrew
The actual voltage depends on the mode (I know that for 100BASE-TX and 
MLT-3 it's +/-1V) : it makes no sense to try to code the actual voltage, 
we need to keep voltage ratio here.
  

On 11.01.24 18:20, Krzysztof Kozlowski wrote:
> [You don't often get email from krzysztof.kozlowski@linaro.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>
> This email is not from Hexagon’s Office 365 instance. Please be careful while clicking links, opening attachments, or replying to this email.
>
>
> On 11/01/2024 17:19, Catalin Popescu wrote:
>> Add property ti,cfg-dac-minus to allow for voltage tuning
>> of logical level -1 of the MLT-3 encoded data.
> A nit, subject: drop second/last, redundant "binding". 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
>> Signed-off-by: Catalin Popescu <catalin.popescu@leica-geosystems.com>
>> ---
>>   Documentation/devicetree/bindings/net/ti,dp83822.yaml | 9 +++++++++
>>   1 file changed, 9 insertions(+)
> Don't add properties one by one. Especially if they are related.
OK
>
>> diff --git a/Documentation/devicetree/bindings/net/ti,dp83822.yaml b/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>> index db74474207ed..2f010333be49 100644
>> --- a/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>> +++ b/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>> @@ -62,6 +62,15 @@ properties:
>>          for the PHY.  The internal delay for the PHY is fixed to 3.5ns relative
>>          to transmit data.
>>
>> +  ti,cfg-dac-minus:
>> +    description: |
>> +       DP83826 PHY only.
>> +       Sets the voltage ratio of the logical level -1 for the MLT-3 encoded data.
> ratio between what and what?
It's the ration b/w the actual output voltage of AOI and the spec
reference (the datasheet is not very clear).
>
>> +       0 = 50%, 1 = 56.25%, 2 = 62.50%, 3 = 68.75%, 4 = 75%, 5 = 81.25%, 6 = 87.50%,
>> +       7 = 93.75%, 8 = 100%, 9 = 106.25%, 10 = 112.50%, 11 = 118.75%, 12 = 125%,
>> +       13 = 131.25%, 14 = 137.50%, 15 = 143.75%, 16 = 150%.
>> +    enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
> Missing: "default:"
>
>
> Best regards,
> Krzysztof
>
  

On 11.01.24 18:21, Krzysztof Kozlowski wrote:
> [You don't often get email from krzysztof.kozlowski@linaro.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>
> This email is not from Hexagon’s Office 365 instance. Please be careful while clicking links, opening attachments, or replying to this email.
>
>
> On 11/01/2024 17:59, POPESCU Catalin wrote:
>> On 11.01.24 17:52, Russell King (Oracle) wrote:
>>> This email is not from Hexagon’s Office 365 instance. Please be careful while clicking links, opening attachments, or replying to this email.
>>>
>>>
>>> On Thu, Jan 11, 2024 at 04:45:26PM +0000, POPESCU Catalin wrote:
>>>> On 11.01.24 17:35, Andrew Lunn wrote:
>>>>> [You don't often get email from andrew@lunn.ch. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>>>>>
>>>>> This email is not from Hexagon’s Office 365 instance. Please be careful while clicking links, opening attachments, or replying to this email.
>>>>>
>>>>>
>>>>> On Thu, Jan 11, 2024 at 05:19:25PM +0100, Catalin Popescu wrote:
>>>>>> Add property ti,cfg-dac-minus to allow for voltage tuning
>>>>>> of logical level -1 of the MLT-3 encoded data.
>>>>>>
>>>>>> Signed-off-by: Catalin Popescu <catalin.popescu@leica-geosystems.com>
>>>>>> ---
>>>>>>     Documentation/devicetree/bindings/net/ti,dp83822.yaml | 9 +++++++++
>>>>>>     1 file changed, 9 insertions(+)
>>>>>>
>>>>>> diff --git a/Documentation/devicetree/bindings/net/ti,dp83822.yaml b/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>>>>>> index db74474207ed..2f010333be49 100644
>>>>>> --- a/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>>>>>> +++ b/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>>>>>> @@ -62,6 +62,15 @@ properties:
>>>>>>            for the PHY.  The internal delay for the PHY is fixed to 3.5ns relative
>>>>>>            to transmit data.
>>>>>>
>>>>>> +  ti,cfg-dac-minus:
>>>>>> +    description: |
>>>>>> +       DP83826 PHY only.
>>>>>> +       Sets the voltage ratio of the logical level -1 for the MLT-3 encoded data.
>>>>>> +       0 = 50%, 1 = 56.25%, 2 = 62.50%, 3 = 68.75%, 4 = 75%, 5 = 81.25%, 6 = 87.50%,
>>>>>> +       7 = 93.75%, 8 = 100%, 9 = 106.25%, 10 = 112.50%, 11 = 118.75%, 12 = 125%,
>>>>>> +       13 = 131.25%, 14 = 137.50%, 15 = 143.75%, 16 = 150%.
>>>>>> +    enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
>>>>> We try to avoid register values in DT. We use real units. This is a
>>>>> voltage you are configuring, so can you change the unit to millivolts?
>>>>> Have the driver do the conversion of volts to register value.
>>>>>
>>>>> Is it possible to configure any of the other logical levels?
>>>> Hi Andrew,
>>>> These are not raw register values and these are not voltage values but
>>>> voltage ratios. I'm mapping the voltage ratios to enum values [0-16]
>>>> which are converted to register raw values by the driver. I don't see a
>>>> better way to do this.
>>>           enum: [ 5000, 5625, 6250, 6875, 7500, 8125, 8750, 9375, 10000,
>>>                   10625, 11250, 11875, 12500 13125, 13750, 14375, 15000 ]
>>>
>>> ?
>> I'm okay with that approach if there's no better one. I would need to
>> remove the register raw values tables from the driver and use a switch
>> statement to map those values to raw values.
> You can also use -bp or -percent:
> https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml

   ti,cfg-dac-minus-percent:
     description: |
        DP83826 PHY only.
        Sets the voltage ratio of the logical level -1 relative to the
nominal level for the MLT-3 encoded TX data.
     enum: [50, 56, 62, 68, 75, 81, 87, 93, 100, 106, 112, 118, 125,
131, 137, 143, 150]
     default: 100


would this be acceptable ??

> Best regards,
> Krzysztof
>
  

On 12/01/2024 14:41, POPESCU Catalin wrote:
> On 11.01.24 18:21, Krzysztof Kozlowski wrote:
>> [You don't often get email from krzysztof.kozlowski@linaro.org. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>>
>> This email is not from Hexagon’s Office 365 instance. Please be careful while clicking links, opening attachments, or replying to this email.
>>
>>
>> On 11/01/2024 17:59, POPESCU Catalin wrote:
>>> On 11.01.24 17:52, Russell King (Oracle) wrote:
>>>> This email is not from Hexagon’s Office 365 instance. Please be careful while clicking links, opening attachments, or replying to this email.
>>>>
>>>>
>>>> On Thu, Jan 11, 2024 at 04:45:26PM +0000, POPESCU Catalin wrote:
>>>>> On 11.01.24 17:35, Andrew Lunn wrote:
>>>>>> [You don't often get email from andrew@lunn.ch. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>>>>>>
>>>>>> This email is not from Hexagon’s Office 365 instance. Please be careful while clicking links, opening attachments, or replying to this email.
>>>>>>
>>>>>>
>>>>>> On Thu, Jan 11, 2024 at 05:19:25PM +0100, Catalin Popescu wrote:
>>>>>>> Add property ti,cfg-dac-minus to allow for voltage tuning
>>>>>>> of logical level -1 of the MLT-3 encoded data.
>>>>>>>
>>>>>>> Signed-off-by: Catalin Popescu <catalin.popescu@leica-geosystems.com>
>>>>>>> ---
>>>>>>>     Documentation/devicetree/bindings/net/ti,dp83822.yaml | 9 +++++++++
>>>>>>>     1 file changed, 9 insertions(+)
>>>>>>>
>>>>>>> diff --git a/Documentation/devicetree/bindings/net/ti,dp83822.yaml b/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>>>>>>> index db74474207ed..2f010333be49 100644
>>>>>>> --- a/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>>>>>>> +++ b/Documentation/devicetree/bindings/net/ti,dp83822.yaml
>>>>>>> @@ -62,6 +62,15 @@ properties:
>>>>>>>            for the PHY.  The internal delay for the PHY is fixed to 3.5ns relative
>>>>>>>            to transmit data.
>>>>>>>
>>>>>>> +  ti,cfg-dac-minus:
>>>>>>> +    description: |
>>>>>>> +       DP83826 PHY only.
>>>>>>> +       Sets the voltage ratio of the logical level -1 for the MLT-3 encoded data.
>>>>>>> +       0 = 50%, 1 = 56.25%, 2 = 62.50%, 3 = 68.75%, 4 = 75%, 5 = 81.25%, 6 = 87.50%,
>>>>>>> +       7 = 93.75%, 8 = 100%, 9 = 106.25%, 10 = 112.50%, 11 = 118.75%, 12 = 125%,
>>>>>>> +       13 = 131.25%, 14 = 137.50%, 15 = 143.75%, 16 = 150%.
>>>>>>> +    enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
>>>>>> We try to avoid register values in DT. We use real units. This is a
>>>>>> voltage you are configuring, so can you change the unit to millivolts?
>>>>>> Have the driver do the conversion of volts to register value.
>>>>>>
>>>>>> Is it possible to configure any of the other logical levels?
>>>>> Hi Andrew,
>>>>> These are not raw register values and these are not voltage values but
>>>>> voltage ratios. I'm mapping the voltage ratios to enum values [0-16]
>>>>> which are converted to register raw values by the driver. I don't see a
>>>>> better way to do this.
>>>>           enum: [ 5000, 5625, 6250, 6875, 7500, 8125, 8750, 9375, 10000,
>>>>                   10625, 11250, 11875, 12500 13125, 13750, 14375, 15000 ]
>>>>
>>>> ?
>>> I'm okay with that approach if there's no better one. I would need to
>>> remove the register raw values tables from the driver and use a switch
>>> statement to map those values to raw values.
>> You can also use -bp or -percent:
>> https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
> 
>    ti,cfg-dac-minus-percent:
>      description: |
>         DP83826 PHY only.
>         Sets the voltage ratio of the logical level -1 relative to the
> nominal level for the MLT-3 encoded TX data.
>      enum: [50, 56, 62, 68, 75, 81, 87, 93, 100, 106, 112, 118, 125,
> 131, 137, 143, 150]
>      default: 100

Yes, which would also solve your problem of binding errors. But does not
remove the need of testing it before sending to the lists.

Best regards,
Krzysztof
  

Hi Catalin,

kernel test robot noticed the following build warnings:

[auto build test WARNING on robh/for-next]
[also build test WARNING on net-next/main net/main linus/master v6.7 next-20240112]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Catalin-Popescu/dt-bindings-net-dp83826-add-ti-cfg-dac-plus-binding/20240112-002701
base:   https://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git for-next
patch link:    https://lore.kernel.org/r/20240111161927.3689084-1-catalin.popescu%40leica-geosystems.com
patch subject: [PATCH 1/3] dt-bindings: net: dp83826: add ti,cfg-dac-minus binding
compiler: loongarch64-linux-gcc (GCC) 13.2.0
reproduce: (https://download.01.org/0day-ci/archive/20240113/202401131320.WhWHSzeD-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202401131320.WhWHSzeD-lkp@intel.com/

dtcheck warnings: (new ones prefixed by >>)
>> Documentation/devicetree/bindings/net/ti,dp83822.yaml: ti,cfg-dac-minus: missing type definition
   Documentation/devicetree/bindings/net/snps,dwmac.yaml: mac-mode: missing type definition