[PATCH v4 01/16] spi: dt-bindings: add spi-max-post-config-frequency property

[Santhosh Kumar K]

Hello Krzysztof, Miquel and Conor,

Apologies for the delayed response.

On 29/06/26 21:11, Miquel Raynal wrote:
> On 22/06/2026 at 11:14:32 +02, Krzysztof Kozlowski <krzk at kernel.org> wrote:
> 
>> On Thu, Jun 18, 2026 at 01:07:10PM +0530, Santhosh Kumar K wrote:
>>> Add spi-max-post-config-frequency, a generic uint32 property for SPI
>>> peripherals that support two distinct clock rates: a conservative rate
>>> always reachable without controller configuration, and a higher rate
>>> reachable only after controller-side configuration such as PHY tuning.
>>>
>>> When both properties are present, spi-max-frequency gives the
>>> conservative pre-configuration rate and spi-max-post-config-frequency
>>> gives the higher post-configuration target.
>>>
>>> Signed-off-by: Santhosh Kumar K <s-k6 at ti.com>
>>> ---
>>>   .../devicetree/bindings/spi/spi-peripheral-props.yaml       | 6 ++++++
>>>   1 file changed, 6 insertions(+)
>>>
>>> diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml
>>> index 880a9f624566..ece86f65930f 100644
>>> --- a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml
>>> +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml
>>> @@ -45,6 +45,12 @@ properties:
>>>       description:
>>>         Maximum SPI clocking speed of the device in Hz.
>>>   
>>> +  spi-max-post-config-frequency:
>>
>> -hz
>> https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
>>
>> and you need maxItems: 1.
>>
>> Now, please take time and think if this should not be an array instead
>> (maxItems: ...) to cover other possible cases, e.g. different tuning
>> levels? IOW, having single spi-max-frequency turned out to be
>> insufficient. You address that insufficiency with one more frequency,
>> but what if this is going to be insufficient next month as well?
> 
> It is actually a very good remark. I do not have existing needs in mind
> at the momet, but that does not mean there is none.
> 
> In SPI NAND we have per-operation maximum frequencies being defined in
> manufacturer drivers (you can check drivers/mtd/nand/spi/winbond.c)
> because when the speed increases, the number of dummy cycles shall be
> adapted accordingly. So we kind of handle the various frequency possibilities already
> (the property added by Santhosh setting an absolute maximum that cannot
> be crossed).
> 
> However, I do not think SPI NORs have something similar, and also one
> day we might have different tuning levels requiring different "maximum
> frequencies": we could imagine a first mode where tuning is very fast to
> configure and speed gains good, in competition with another mode where
> tuning makes transfers extremely fast but with an extra configuration
> penalty (this is pure sci-fi in my head at the moment).
> 
> It is hard to tell whether this wet finger guessing will realize any
> time soon. Maybe the safest approach is to go for an array, though. In
> that case, could we add a mandatory name to ease (future) parsing?
> Typically here, we might want to call it phy-delay-tuning or something
> like that (name to be discussed, because there is the risk to make to
> too controller specific).

I would prefer to keep it as a scalar for now, though we can revisit
this if a real use case comes up.

The property represents a single state. The device is either optimized
and runs at one post-config frequency, or it is not. Even if the tuning
procedure tries multiple operation variants, it always ends up selecting
a single operating frequency. I don't think there is any hardware today
that needs more than one value here.

If such hardware appears in future, we can extend this. That would
likely also require driver changes to parse multiple values, so I think
we can defer that until there is a concrete requirement.

For v5, I'll add the -hz suffix and maxItems: 1 as suggested.

Thanks,
Santhosh.

> 
> Thanks,
> Miquèl