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

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

[Can Guo]

UFS v5.0/UFSHCI v5.0 add HS-G6 support via UniPro v3.0 and M-PHY v6.0.
These specs define TX Equalization for all High Speed Gears, and HS-G6 may
also require TX precode depending on channel characteristics.

Document vendor-neutral DT properties in ufs-common.yaml:

- patternProperties for txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6]
- tx-precode-g6-host-lanes
- tx-precode-g6-device-lanes

txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6] accept per-lane tuples:
<Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>]

PreShoot and DeEmphasis values are 0..7 and accept 2 or 4 values for x1/x2
lane configurations.

tx-precode-g6-host-lanes and tx-precode-g6-device-lanes list lane indices
where precode is enabled on host and device sides.

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

diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
index ed97f5682509..2d53bbbe5865 100644
--- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml
+++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml
@@ -105,6 +105,67 @@ properties:
       Restricts the UFS controller to rate-a or rate-b for both TX and
       RX directions.
 
+  tx-precode-g6-host-lanes:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 1
+    maxItems: 2
+    uniqueItems: true
+    items:
+      minimum: 0
+      maximum: 1
+    description: |
+      Lane indices for static Host-side TX precode enable settings for HS-G6
+      only. Listed lanes have precode enabled; unlisted lanes are disabled.
+
+  tx-precode-g6-device-lanes:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 1
+    maxItems: 2
+    uniqueItems: true
+    items:
+      minimum: 0
+      maximum: 1
+    description: |
+      Lane indices for static Device-side TX precode enable settings for HS-G6
+      only. Listed lanes have precode enabled; unlisted lanes are disabled.
+
+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 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).
+      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 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).
+      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 v7 1/2] dt-bindings: ufs: Document static TX Equalization settings properties

[Krzysztof Kozlowski]

On 10/06/2026 09:15, Can Guo wrote:
> UFS v5.0/UFSHCI v5.0 add HS-G6 support via UniPro v3.0 and M-PHY v6.0.
> These specs define TX Equalization for all High Speed Gears, and HS-G6 may
> also require TX precode depending on channel characteristics.
> 
> Document vendor-neutral DT properties in ufs-common.yaml:
> 
> - patternProperties for txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6]
> - tx-precode-g6-host-lanes
> - tx-precode-g6-device-lanes
> 
> txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6] accept per-lane tuples:
> <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>]

Instead of repeating the diff, you should explain why these properties
are needed. Insufficient explanation was also pointed out at v1.

Why this cannot be deduced from the IP compatible? Does it depend on the
device memory? Who determines the values here and what do they depend
on? Also here you explain lack of auto tuning for example.

> 
> PreShoot and DeEmphasis values are 0..7 and accept 2 or 4 values for x1/x2
> lane configurations.
> 

...


> +      Lane indices for static Host-side TX precode enable settings for HS-G6
> +      only. Listed lanes have precode enabled; unlisted lanes are disabled.
> +
> +  tx-precode-g6-device-lanes:
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    minItems: 1
> +    maxItems: 2
> +    uniqueItems: true
> +    items:
> +      minimum: 0
> +      maximum: 1
> +    description: |
> +      Lane indices for static Device-side TX precode enable settings for HS-G6
> +      only. Listed lanes have precode enabled; unlisted lanes are disabled.


I need to reverse my opinion and let's go to v6 implementation. These
properties look more consistent in v6 with respect to preshoot and
deepmhasis properties.

You want actually matrix, so:

  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.

And similar style with items also for preshoot and deepmhasis.


Best regards,
Krzysztof

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

[Can Guo]

On 6/11/2026 9:32 PM, Krzysztof Kozlowski wrote:
> On 10/06/2026 09:15, Can Guo wrote:
>> UFS v5.0/UFSHCI v5.0 add HS-G6 support via UniPro v3.0 and M-PHY v6.0.
>> These specs define TX Equalization for all High Speed Gears, and HS-G6 may
>> also require TX precode depending on channel characteristics.
>>
>> Document vendor-neutral DT properties in ufs-common.yaml:
>>
>> - patternProperties for txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6]
>> - tx-precode-g6-host-lanes
>> - tx-precode-g6-device-lanes
>>
>> txeq-preshoot-g[1-6] and txeq-deemphasis-g[1-6] accept per-lane tuples:
>> <Host_Lane0 Device_Lane0>, [<Host_Lane1 Device_Lane1>]
> Instead of repeating the diff, you should explain why these properties
> are needed. Insufficient explanation was also pointed out at v1.
>
> Why this cannot be deduced from the IP compatible? Does it depend on the
> device memory? Who determines the values here and what do they depend
> on? Also here you explain lack of auto tuning for example.
I will give more explanations in next version.
>
>> PreShoot and DeEmphasis values are 0..7 and accept 2 or 4 values for x1/x2
>> lane configurations.
>>
> ...
>
>
>> +      Lane indices for static Host-side TX precode enable settings for HS-G6
>> +      only. Listed lanes have precode enabled; unlisted lanes are disabled.
>> +
>> +  tx-precode-g6-device-lanes:
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    minItems: 1
>> +    maxItems: 2
>> +    uniqueItems: true
>> +    items:
>> +      minimum: 0
>> +      maximum: 1
>> +    description: |
>> +      Lane indices for static Device-side TX precode enable settings for HS-G6
>> +      only. Listed lanes have precode enabled; unlisted lanes are disabled.
>
> I need to reverse my opinion and let's go to v6 implementation. These
> properties look more consistent in v6 with respect to preshoot and
> deepmhasis properties.
>
> You want actually matrix, so:
>
>    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.
>
> And similar style with items also for preshoot and deepmhasis.
Thanks for the suggestions. Will update in next version and come back.

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