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

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

[Can Guo]

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

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

Document vendor-neutral properties in ufs-common.yaml:
- txeq-preshoot-g[1-6]
- txeq-deemphasis-g[1-6]
- tx-precode-enable-g6

Values are per-lane Host/Device tuples (2 values for x1, 4 values for
x2). PreShoot/DeEmphasis range from 0..7, and Precode is 0/1.

These are board-specific signal-integrity tuning values. They depend on
channel SI/PHY characterization and validation (host PHY, device PHY,
package, and board routing), and are determined by HW/PHY designers.

Although UFSHCI v5.0 supports TX Equalization Training via UniPro v3.0,
which allows host software to determine optimal TX Equalization at
runtime, static board-specific TX Equalization settings in the Device
Tree are still necessary because:
- TX Equalization Training is not supported for HS-G3 and below
- TX Equalization Training is disabled on some platforms

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

diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
index ed97f5682509..145a6416e1df 100644
--- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
+++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
@@ -105,6 +105,61 @@ 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-matrix
+    oneOf:
+      - items:
+          - description: Host_Lane0 precode
+          - description: Device_Lane0 precode
+      - items:
+          - description: Host_Lane0 precode
+          - description: Device_Lane0 precode
+          - description: Host_Lane1 precode
+          - description: Device_Lane1 precode
+    items:
+      enum: [0, 1]
+    description:
+      Static TX Precode enable values for HS-G6 only.
+
+patternProperties:
+  "^txeq-preshoot-g[1-6]$":
+    $ref: /schemas/types.yaml#/definitions/uint32-matrix
+    oneOf:
+      - items:
+          - description: Host_Lane0 Preshoot value
+          - description: Device_Lane0 Preshoot value
+      - items:
+          - description: Host_Lane0 Preshoot value
+          - description: Device_Lane0 Preshoot value
+          - description: Host_Lane1 Preshoot value
+          - description: Device_Lane1 Preshoot value
+    items:
+      enum: [0, 1, 2, 3, 4, 5, 6, 7]
+    description: |
+      Static TX Equalization PreShoot settings for High Speed Gears. These
+      values are programmed to the corresponding UniPro PA layer attribute
+      PA_TxEQG[1-6]Setting. Each value selects a Pre-Shoot level as defined
+      by the MIPI M-PHY specification (TX_HS_PreShoot_Setting).
+
+  "^txeq-deemphasis-g[1-6]$":
+    $ref: /schemas/types.yaml#/definitions/uint32-matrix
+    oneOf:
+      - items:
+          - description: Host_Lane0 DeEmphasis value
+          - description: Device_Lane0 DeEmphasis value
+      - items:
+          - description: Host_Lane0 DeEmphasis value
+          - description: Device_Lane0 DeEmphasis value
+          - description: Host_Lane1 DeEmphasis value
+          - description: Device_Lane1 DeEmphasis value
+    items:
+      enum: [0, 1, 2, 3, 4, 5, 6, 7]
+    description: |
+      Static TX Equalization DeEmphasis settings for High Speed Gears. These
+      values are programmed to the corresponding UniPro PA layer attribute
+      PA_TxEQG[1-6]Setting. Each value selects a De-Emphasis level as defined
+      by the MIPI M-PHY specification (TX_HS_DeEmphasis_Setting).
+
 dependencies:
   freq-table-hz: [ clocks ]
   operating-points-v2: [ clocks, clock-names ]
-- 
2.34.1

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

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] The new TX Equalization properties incorrectly use `uint32-matrix` instead of `uint32-array`, causing `dt_binding_check` validation to fail unconditionally on all valid device trees.
--

commit 3028e214ba5cd87e73e5059697a94d86be2b33c8
Author: Can Guo <can.guo@oss.qualcomm.com>
Date:   Mon Jun 15 08:50:25 2026 +0000

dt-bindings: ufs: Document static TX Equalization settings properties

This commit documents vendor-neutral properties for UFS static TX
Equalization settings in UFS v5.0/UFSHCI v5.0. It defines properties
for tx-precode-enable-g6, txeq-preshoot-g[1-6], and txeq-deemphasis-g[1-6]
to compensate for channel loss and improve high-speed signal integrity.

> diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> index ed97f56825093..145a6416e1dff 100644
> --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> @@ -105,6 +105,61 @@ 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-matrix

[Severity: Medium]
Should this reference /schemas/types.yaml#/definitions/uint32-array instead
of uint32-matrix?

Because uint32-matrix evaluates as an array of inner arrays, applying flat
scalar constraints like the enum sequence below makes the constraints
structurally impossible to satisfy. Will this cause make dtbs_check
validation to fail unconditionally on any device tree implementing this
property?

> +    oneOf:
> +      - items:
> +          - description: Host_Lane0 precode
> +          - description: Device_Lane0 precode

[ ... ]

> +patternProperties:
> +  "^txeq-preshoot-g[1-6]$":
> +    $ref: /schemas/types.yaml#/definitions/uint32-matrix

[Severity: Medium]
Does this pattern property also require uint32-array instead of
uint32-matrix for the scalar enum constraints to apply correctly?

> +    oneOf:
> +      - items:
> +          - description: Host_Lane0 Preshoot value
> +          - description: Device_Lane0 Preshoot value

[ ... ]

> +  "^txeq-deemphasis-g[1-6]$":
> +    $ref: /schemas/types.yaml#/definitions/uint32-matrix

[Severity: Medium]
Would changing uint32-matrix to uint32-array here as well resolve the
schema validation failures for these flat arrays?

> +    oneOf:
> +      - items:
> +          - description: Host_Lane0 DeEmphasis value
> +          - description: Device_Lane0 DeEmphasis value

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260615085027.2102882-1-can.guo@oss.qualcomm.com?part=1

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

[Krzysztof Kozlowski]

On 15/06/2026 10:50, Can Guo wrote:
> UFS v5.0/UFSHCI v5.0 adds HS-G6 support (46.6 Gbps/lane) via UniPro
> v3.0 and M-PHY v6.0. These specs define TX Equalization for all
> High-Speed Gears (not only HS-G6) to compensate channel loss and
> improve signal integrity at high speed.
> 
> For HS-G6, M-PHY uses PAM4 1b1b line coding. Pre-Coding may also be
> required depending on channel characteristics.
> 
> Document vendor-neutral properties in ufs-common.yaml:
> - txeq-preshoot-g[1-6]
> - txeq-deemphasis-g[1-6]
> - tx-precode-enable-g6
> 
> Values are per-lane Host/Device tuples (2 values for x1, 4 values for
> x2). PreShoot/DeEmphasis range from 0..7, and Precode is 0/1.
> 
> These are board-specific signal-integrity tuning values. They depend on
> channel SI/PHY characterization and validation (host PHY, device PHY,
> package, and board routing), and are determined by HW/PHY designers.
> 
> Although UFSHCI v5.0 supports TX Equalization Training via UniPro v3.0,
> which allows host software to determine optimal TX Equalization at
> runtime, static board-specific TX Equalization settings in the Device
> Tree are still necessary because:
> - TX Equalization Training is not supported for HS-G3 and below
> - TX Equalization Training is disabled on some platforms
> 
> Signed-off-by: Can Guo <can.guo@oss.qualcomm.com>
> ---
>  .../devicetree/bindings/ufs/ufs-common.yaml   | 55 +++++++++++++++++++
>  1 file changed, 55 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> index ed97f5682509..145a6416e1df 100644
> --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
> @@ -105,6 +105,61 @@ 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-matrix
> +    oneOf:
> +      - items:
> +          - description: Host_Lane0 precode
> +          - description: Device_Lane0 precode
> +      - items:
> +          - description: Host_Lane0 precode
> +          - description: Device_Lane0 precode
> +          - description: Host_Lane1 precode
> +          - description: Device_Lane1 precode
> +    items:
> +      enum: [0, 1]
> +    description:
> +      Static TX Precode enable values for HS-G6 only.

My bad here, that was my mistake. I wanted matrix, but gave you array
syntax. Proper code would be:

  tx-precode-enable-g6:
    $ref: /schemas/types.yaml#/definitions/uint32-matrix
    minItems: 1
    items:
      - items:
          - description: Host_Lane0 precode
            enum: [0, 1]
          - description: Device_Lane0 precode
            enum: [0, 1]
      - items:
          - description: Host_Lane1 precode
            enum: [0, 1]
          - description: Device_Lane1 precode
            enum: [0, 1]
    description:
      Static TX Precode enable values for HS-G6 only.


I tested it with DTS and seems to work fine. Please use the same for
other properties, but enum will be 0-7.


Best regards,
Krzysztof

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

[Can Guo]

On 6/15/2026 7:26 PM, Krzysztof Kozlowski wrote:
> On 15/06/2026 10:50, Can Guo wrote:
>> UFS v5.0/UFSHCI v5.0 adds HS-G6 support (46.6 Gbps/lane) via UniPro
>> v3.0 and M-PHY v6.0. These specs define TX Equalization for all
>> High-Speed Gears (not only HS-G6) to compensate channel loss and
>> improve signal integrity at high speed.
>>
>> For HS-G6, M-PHY uses PAM4 1b1b line coding. Pre-Coding may also be
>> required depending on channel characteristics.
>>
>> Document vendor-neutral properties in ufs-common.yaml:
>> - txeq-preshoot-g[1-6]
>> - txeq-deemphasis-g[1-6]
>> - tx-precode-enable-g6
>>
>> Values are per-lane Host/Device tuples (2 values for x1, 4 values for
>> x2). PreShoot/DeEmphasis range from 0..7, and Precode is 0/1.
>>
>> These are board-specific signal-integrity tuning values. They depend on
>> channel SI/PHY characterization and validation (host PHY, device PHY,
>> package, and board routing), and are determined by HW/PHY designers.
>>
>> Although UFSHCI v5.0 supports TX Equalization Training via UniPro v3.0,
>> which allows host software to determine optimal TX Equalization at
>> runtime, static board-specific TX Equalization settings in the Device
>> Tree are still necessary because:
>> - TX Equalization Training is not supported for HS-G3 and below
>> - TX Equalization Training is disabled on some platforms
>>
>> Signed-off-by: Can Guo <can.guo@oss.qualcomm.com>
>> ---
>>   .../devicetree/bindings/ufs/ufs-common.yaml   | 55 +++++++++++++++++++
>>   1 file changed, 55 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
>> index ed97f5682509..145a6416e1df 100644
>> --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
>> +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
>> @@ -105,6 +105,61 @@ 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-matrix
>> +    oneOf:
>> +      - items:
>> +          - description: Host_Lane0 precode
>> +          - description: Device_Lane0 precode
>> +      - items:
>> +          - description: Host_Lane0 precode
>> +          - description: Device_Lane0 precode
>> +          - description: Host_Lane1 precode
>> +          - description: Device_Lane1 precode
>> +    items:
>> +      enum: [0, 1]
>> +    description:
>> +      Static TX Precode enable values for HS-G6 only.
> My bad here, that was my mistake. I wanted matrix, but gave you array
> syntax. Proper code would be:
>
>    tx-precode-enable-g6:
>      $ref: /schemas/types.yaml#/definitions/uint32-matrix
>      minItems: 1
>      items:
>        - items:
>            - description: Host_Lane0 precode
>              enum: [0, 1]
>            - description: Device_Lane0 precode
>              enum: [0, 1]
>        - items:
>            - description: Host_Lane1 precode
>              enum: [0, 1]
>            - description: Device_Lane1 precode
>              enum: [0, 1]
>      description:
>        Static TX Precode enable values for HS-G6 only.
>
>
> I tested it with DTS and seems to work fine. Please use the same for
> other properties, but enum will be 0-7.
Sure, I will correct it and validate the same for the next version.

Thank you for helping me out.

Best Regards,
Can Guo.
>
> Best regards,
> Krzysztof