[PATCH 1/2] dt-bindings: ufs: Document static TX Equalization settings properties

[PATCH 1/2] dt-bindings: ufs: Document static TX Equalization settings properties

[Can Guo]

HW design team usually provides static TX Equalization settings based on
PCB board characteristics. These settings can be passed from the device
tree to configure the TX Equalization parameters (PreShoot, DeEmphasis,
and PreCodeEn) for Host and Device across different HS gears.

Add patternProperties for txeq-settings-g[1-6] to support specifying
static TX Equalization settings.

Signed-off-by: Can Guo <can.guo@oss.qualcomm.com>
---
 Documentation/devicetree/bindings/ufs/ufs-common.yaml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
index ed97f5682509..bc83948fc168 100644
--- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
+++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
@@ -105,6 +105,17 @@ properties:
       Restricts the UFS controller to rate-a or rate-b for both TX and
       RX directions.
 
+patternProperties:
+  "^txeq-settings-g[1-6]$":
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 6
+    maxItems: 12
+    description: |
+      Static TX Equalization settings for High Speed (HS) gears.
+      The settings are specified as an array of tuples (PreShoot, DeEmphasis, PrecodeEn).
+      The array must contain these tuples in the following order:
+      Host Lane 0, [Host Lane 1], Device Lane 0, [Device Lane 1].
+
 dependencies:
   freq-table-hz: [ clocks ]
   operating-points-v2: [ clocks, clock-names ]
-- 
2.34.1

Re: [PATCH 1/2] dt-bindings: ufs: Document static TX Equalization settings properties

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 1950 bytes --]

On Fri, May 01, 2026 at 06:44:17AM -0700, Can Guo wrote:
> HW design team usually provides static TX Equalization settings based on
> PCB board characteristics. These settings can be passed from the device
> tree to configure the TX Equalization parameters (PreShoot, DeEmphasis,
> and PreCodeEn) for Host and Device across different HS gears.

I'm not familiar enough with ufs stuff to tell, but this commit message
sounds very qcom specific, but this is being added to a common file.
I'd like to see a lot more detail in the commit message, detailing why
this is truly applicable across IP vendors.

> 
> Add patternProperties for txeq-settings-g[1-6] to support specifying
> static TX Equalization settings.
> 
> Signed-off-by: Can Guo <can.guo@oss.qualcomm.com>
> ---
>  Documentation/devicetree/bindings/ufs/ufs-common.yaml | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> index ed97f5682509..bc83948fc168 100644
> --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> @@ -105,6 +105,17 @@ properties:
>        Restricts the UFS controller to rate-a or rate-b for both TX and
>        RX directions.
>  
> +patternProperties:
> +  "^txeq-settings-g[1-6]$":
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    minItems: 6
> +    maxItems: 12
> +    description: |
> +      Static TX Equalization settings for High Speed (HS) gears.
> +      The settings are specified as an array of tuples (PreShoot, DeEmphasis, PrecodeEn).
> +      The array must contain these tuples in the following order:
> +      Host Lane 0, [Host Lane 1], Device Lane 0, [Device Lane 1].
> +
>  dependencies:
>    freq-table-hz: [ clocks ]
>    operating-points-v2: [ clocks, clock-names ]
> -- 
> 2.34.1
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 1/2] dt-bindings: ufs: Document static TX Equalization settings properties

[Can Guo]

Hi Conor,

On 5/2/2026 1:02 AM, Conor Dooley wrote:
> On Fri, May 01, 2026 at 06:44:17AM -0700, Can Guo wrote:
>> HW design team usually provides static TX Equalization settings based on
>> PCB board characteristics. These settings can be passed from the device
>> tree to configure the TX Equalization parameters (PreShoot, DeEmphasis,
>> and PreCodeEn) for Host and Device across different HS gears.
> I'm not familiar enough with ufs stuff to tell, but this commit message
> sounds very qcom specific, but this is being added to a common file.
> I'd like to see a lot more detail in the commit message, detailing why
> this is truly applicable across IP vendors.
Thanks for raising this point. I agree the current commit message is too 
narrow and I will
fix it in the next version.

This binding is intended to be vendor-neutral. The DT properties 
describe board-level
SI characterization data (per-gear/per-lane TX EQ values), not 
Qualcomm-specific controller
internals.

The tuple (PreShoot, DeEmphasis, PreCodeEn) is defined by the UFS link 
specs (MIPI UniPro
ver 3.0 & M-PHY ver 6.0), so the representation is generic and 
applicable to any UFS host
that supports TX EQ.

This is also consistent with existing kernel practice in PCIe, where 
board-provided Equalization
data is parsed from DT (see `of_pci_get_equalization_presets()` in 
`drivers/pci/of.c`).

I will update the commit message to explicitly describe this 
cross-vendor scope and to
clarify precedence: when adaptive TX EQ is enabled, DT static settings 
are fallback values
and can be overridden by retrieved/trained TX EQ settings.

Thanks,
Can Guo.
>
>> Add patternProperties for txeq-settings-g[1-6] to support specifying
>> static TX Equalization settings.
>>
>> Signed-off-by: Can Guo <can.guo@oss.qualcomm.com>
>> ---
>>   Documentation/devicetree/bindings/ufs/ufs-common.yaml | 11 +++++++++++
>>   1 file changed, 11 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
>> index ed97f5682509..bc83948fc168 100644
>> --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
>> +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
>> @@ -105,6 +105,17 @@ properties:
>>         Restricts the UFS controller to rate-a or rate-b for both TX and
>>         RX directions.
>>   
>> +patternProperties:
>> +  "^txeq-settings-g[1-6]$":
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    minItems: 6
>> +    maxItems: 12
>> +    description: |
>> +      Static TX Equalization settings for High Speed (HS) gears.
>> +      The settings are specified as an array of tuples (PreShoot, DeEmphasis, PrecodeEn).
>> +      The array must contain these tuples in the following order:
>> +      Host Lane 0, [Host Lane 1], Device Lane 0, [Device Lane 1].
>> +
>>   dependencies:
>>     freq-table-hz: [ clocks ]
>>     operating-points-v2: [ clocks, clock-names ]
>> -- 
>> 2.34.1
>>