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

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

[Can Guo]

UFS v5.0/UFSHCI v5.0 add HS-G6 support (46.6 Gbps/lane) via UniPro v3.0
and M-PHY v6.0. In these specs, TX Equalization is defined for all High
Speed Gears (not only HS-G6) to compensate channel loss and improve signal
integrity at high speed operation.

For HS-G6, M-PHY uses PAM4 1b1b line coding, Pre-Coding may also be
required depending on channel characteristics.

Add vendor-neutral DT properties:

- patternProperties for txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6]
- fixed property tx-precode-enable-g6

Each property is a uint32 array of per-lane tuples:
<Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>]

Accept 2 or 4 values (x1/x2 lane configs). PreShoot and DeEmphasis values
are 0..7. Precode enable values are 0/1 and only applicable to HS-G6.

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

diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
index ed97f5682509..d90cf25adfa5 100644
--- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
+++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
@@ -105,6 +105,51 @@ properties:
       Restricts the UFS controller to rate-a or rate-b for both TX and
       RX directions.
 
+  tx-precode-enable-g6:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    oneOf:
+      - minItems: 2
+        maxItems: 2
+      - minItems: 4
+        maxItems: 4
+    items:
+      enum: [0, 1]
+    description: |
+      Static TX Precode enable values for HS-G6 only.
+      Values are specified as per-lane tuples:
+      <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>].
+
+patternProperties:
+  "^txeq-preshoot-g[1-6]$":
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    oneOf:
+      - minItems: 2
+        maxItems: 2
+      - minItems: 4
+        maxItems: 4
+    items:
+      minimum: 0
+      maximum: 7
+    description: |
+      Static TX Equalization PreShoot values for High Speed Gears.
+      Values are specified as per-lane tuples:
+      <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>].
+
+  "^txeq-deemphasis-g[1-6]$":
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    oneOf:
+      - minItems: 2
+        maxItems: 2
+      - minItems: 4
+        maxItems: 4
+    items:
+      minimum: 0
+      maximum: 7
+    description: |
+      Static TX Equalization DeEmphasis values for High Speed Gears.
+      Values are specified as per-lane tuples:
+      <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>].
+
 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

[Manivannan Sadhasivam]

On Wed, May 27, 2026 at 07:40:54AM -0700, Can Guo wrote:
> UFS v5.0/UFSHCI v5.0 add HS-G6 support (46.6 Gbps/lane) via UniPro v3.0
> and M-PHY v6.0. In these specs, TX Equalization is defined for all High
> Speed Gears (not only HS-G6) to compensate channel loss and improve signal
> integrity at high speed operation.
> 
> For HS-G6, M-PHY uses PAM4 1b1b line coding, Pre-Coding may also be
> required depending on channel characteristics.
> 
> Add vendor-neutral DT properties:
> 
> - patternProperties for txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6]
> - fixed property tx-precode-enable-g6
> 
> Each property is a uint32 array of per-lane tuples:
> <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>]
> 
> Accept 2 or 4 values (x1/x2 lane configs). PreShoot and DeEmphasis values
> are 0..7. Precode enable values are 0/1 and only applicable to HS-G6.
> 
> Signed-off-by: Can Guo <can.guo@oss.qualcomm.com>

Acked-by: Manivannan Sadhasivam <mani@kernel.org>

- Mani

> ---
>  .../devicetree/bindings/ufs/ufs-common.yaml   | 45 +++++++++++++++++++
>  1 file changed, 45 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> index ed97f5682509..d90cf25adfa5 100644
> --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> @@ -105,6 +105,51 @@ properties:
>        Restricts the UFS controller to rate-a or rate-b for both TX and
>        RX directions.
>  
> +  tx-precode-enable-g6:
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    oneOf:
> +      - minItems: 2
> +        maxItems: 2
> +      - minItems: 4
> +        maxItems: 4
> +    items:
> +      enum: [0, 1]
> +    description: |
> +      Static TX Precode enable values for HS-G6 only.
> +      Values are specified as per-lane tuples:
> +      <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>].
> +
> +patternProperties:
> +  "^txeq-preshoot-g[1-6]$":
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    oneOf:
> +      - minItems: 2
> +        maxItems: 2
> +      - minItems: 4
> +        maxItems: 4
> +    items:
> +      minimum: 0
> +      maximum: 7
> +    description: |
> +      Static TX Equalization PreShoot values for High Speed Gears.
> +      Values are specified as per-lane tuples:
> +      <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>].
> +
> +  "^txeq-deemphasis-g[1-6]$":
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    oneOf:
> +      - minItems: 2
> +        maxItems: 2
> +      - minItems: 4
> +        maxItems: 4
> +    items:
> +      minimum: 0
> +      maximum: 7
> +    description: |
> +      Static TX Equalization DeEmphasis values for High Speed Gears.
> +      Values are specified as per-lane tuples:
> +      <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>].
> +
>  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

[Krzysztof Kozlowski]

On Wed, May 27, 2026 at 07:40:54AM -0700, Can Guo wrote:
> UFS v5.0/UFSHCI v5.0 add HS-G6 support (46.6 Gbps/lane) via UniPro v3.0
> and M-PHY v6.0. In these specs, TX Equalization is defined for all High
> Speed Gears (not only HS-G6) to compensate channel loss and improve signal
> integrity at high speed operation.
> 
> For HS-G6, M-PHY uses PAM4 1b1b line coding, Pre-Coding may also be
> required depending on channel characteristics.
> 
> Add vendor-neutral DT properties:
> 
> - patternProperties for txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6]
> - fixed property tx-precode-enable-g6
> 
> Each property is a uint32 array of per-lane tuples:
> <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>]
> 
> Accept 2 or 4 values (x1/x2 lane configs). PreShoot and DeEmphasis values
> are 0..7. Precode enable values are 0/1 and only applicable to HS-G6.
> 

Why are they SIX versions within three days? I see this for the third
time in Patchwork already.


Best regards,
Krzysztof