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

[Can Guo]

On 5/31/2026 1:33 AM, Krzysztof Kozlowski wrote:
> On 30/05/2026 14:45, Can Guo wrote:
>>
>> On 5/30/2026 12:58 AM, Krzysztof Kozlowski wrote:
>>> On Fri, May 29, 2026 at 04:33:37AM -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.
>>>>
>>>> Acked-by: Manivannan Sadhasivam <mani at kernel.org>
>>>> Reviewed-by: Bean Huo <beanhuo at micron.com>
>>>> Reviewed-by: Peter Wang <peter.wang at mediatek.com>
>>>> Signed-off-by: Can Guo <can.guo at 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>].
>>> You need to include them in any of applicable examples, otherwise
>>> nothing here is validated.
>> Hi Krzysztof,
>>
>> Thanks for the review.
>>
>> Since no UFS5-capable SoC binding exists upstream yet (the target SoC is
> I would imagine cover letter or commit msg would briefly mention that.
Thanks for the clarification. Will do.
>
>> still pre-CS), there is no vendor-specific YAML to attach the example to.
>>
>> Is a synthetic example directly in ufs-common.yaml OK to you?
> Skip example in such case.
>
>>> Why values cannot be on or off? Or even better: why you cannot just list
>>> all the lanes which has it enabled, assuming disabled is by default?
>> Thanks for the suggestions.
>>
>> For the "just list enabled lanes" suggestion: precode must be configured
>> independently for the Host-side TX and Device-side TX transceivers within
>> the same physical lane. A lane index list alone cannot capture this
>> two-dimensional per-lane state. The tuple format <Host_LaneN Device_LaneN>
>> is the minimal encoding that covers both.
> Again, why do you need to encode '0'?
The tuple is still needed because Precoding is configured per 
transmitter-receiver pair,
so each lane has two independent states:
- Host_TX -> Device_RX
- Device_TX -> Host_RX
A lane-only enabled list cannot represent directional combinations like 
lane0 =
(on, off) vs (off, on).
>
>> For the "on/off" suggestion: the on/off string pattern is used with
>> single-value properties (e.g. LED default-state) read via
>> of_property_read_string(). I am not aware of precedent for on/off as a
>> string array for per-lane tuples.
> git grep string-array. Plenty of precedents.
I will keep the per-lane tuple model but switch tx-precode-enable-g6 
from 0/1 to
"on"/"off" (string array) in v7.

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