[PATCH 0/2] Add static TX Equalization settings support from DT

[PATCH 0/2] Add static TX Equalization settings support from DT

[Can Guo]

Hi,

This series adds support for board-specific static TX Equalization settings
provided through device tree.

This series is based on the earlier TX Equalization enablement work and
persistent storage/retrieval of optimal TX Equalization settings work:
https://lore.kernel.org/all/20260325152154.1604082-1-can.guo@oss.qualcomm.com
https://lore.kernel.org/all/20260424151420.111675-1-can.guo@oss.qualcomm.com

Background
==========

For some boards, HW design teams also provide pre-characterized static TX
Equalization values per gear/lane. This series adds a DT path for those
static values.

Relationship with Adaptive TX Equalization
==========================================

Adaptive TX Equalization remains the primary path when enabled.

Static TX Equalization settings from DT are board-specific baseline values,
but when adaptive TX Equalization is used, static settings are not final:
- If valid settings are retrieved from qTxEQGnSettings/wTxEQGnSettingsExt,
those retrieved settings override static DT settings.
- If retrieval is not available/valid, TX EQTR runs and trained settings
override static DT settings.

So static DT settings are a fallback and are intended for cases where
adaptive TX Equalization is not enabled/used.

No behavior changes for platforms that do not provide `txeq-settings-g*`
properties.

What this series adds
=====================

1. dt-bindings:
- Document `txeq-settings-g[1-6]` in `ufs-common.yaml`.
- Define tuple format as `(PreShoot, DeEmphasis, PreCodeEn)` in lane order:
Host Lane 0, [Host Lane 1], Device Lane 0, [Device Lane 1].

2. UFS core/platform integration:
- Parse and validate per-gear DT TX EQ settings during platform init.
- Store parsed values into per-gear TX EQ params and mark them as static.
- Integrate static-state handling in TX EQ flow so static entries are
  handled through the adaptive TX Equalization path and then converted to
  normal runtime params.


Can Guo (2):
  dt-bindings: ufs: Document static TX Equalization settings properties
  scsi: ufs: core: Add support for static TX Equalization settings

 .../devicetree/bindings/ufs/ufs-common.yaml   | 11 +++
 drivers/ufs/core/ufs-txeq.c                   |  4 +-
 drivers/ufs/host/ufshcd-pltfrm.c              | 82 +++++++++++++++++++
 include/ufs/ufshcd.h                          |  5 ++
 4 files changed, 101 insertions(+), 1 deletion(-)

-- 
2.34.1

[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 2/2] scsi: ufs: core: Add support for static TX Equalization settings

[Can Guo]

HW design team usually provide static TX Equalization settings based on
PCB board characteristics. The static TX Equalization settings may not be
optimal for all PCBs, but it is better than having nothing when adaptive
TX EQTR is not used. Since the static TX Equalization settings are PCB
board specific, pass the static TX Equalization settings from device tree.

Signed-off-by: Can Guo <can.guo@oss.qualcomm.com>
---
 drivers/ufs/core/ufs-txeq.c      |  4 +-
 drivers/ufs/host/ufshcd-pltfrm.c | 82 ++++++++++++++++++++++++++++++++
 include/ufs/ufshcd.h             |  5 ++
 3 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/drivers/ufs/core/ufs-txeq.c b/drivers/ufs/core/ufs-txeq.c
index 4b264adfdf49..634ec039e129 100644
--- a/drivers/ufs/core/ufs-txeq.c
+++ b/drivers/ufs/core/ufs-txeq.c
@@ -1297,7 +1297,7 @@ int ufshcd_config_tx_eq_settings(struct ufs_hba *hba,
 	}
 
 	params = &hba->tx_eq_params[gear - 1];
-	if (!params->is_valid || force_tx_eqtr) {
+	if (!params->is_valid || params->is_static || force_tx_eqtr) {
 		int ret;
 
 		ret = ufshcd_tx_eqtr(hba, params, pwr_mode);
@@ -1310,6 +1310,7 @@ int ufshcd_config_tx_eq_settings(struct ufs_hba *hba,
 		/* Mark TX Equalization settings as valid */
 		params->is_valid = true;
 		params->is_trained = true;
+		params->is_static = false;
 		params->is_applied = false;
 	}
 
@@ -1495,6 +1496,7 @@ static void ufshcd_extract_tx_eq_settings_attrs(struct ufs_hba *hba, u8 gear)
 	}
 
 	params->is_valid = true;
+	params->is_static = false;
 }
 
 void ufshcd_retrieve_tx_eq_settings(struct ufs_hba *hba)
diff --git a/drivers/ufs/host/ufshcd-pltfrm.c b/drivers/ufs/host/ufshcd-pltfrm.c
index c2dafb583cf5..de6302e8c067 100644
--- a/drivers/ufs/host/ufshcd-pltfrm.c
+++ b/drivers/ufs/host/ufshcd-pltfrm.c
@@ -210,6 +210,86 @@ static void ufshcd_init_lanes_per_dir(struct ufs_hba *hba)
 	}
 }
 
+static void ufshcd_parse_static_tx_eq_settings(struct ufs_hba *hba)
+{
+	size_t sz = hba->lanes_per_direction * 2 * TX_EQ_SETTINGS_TUPLE_SZ;
+	u32 settings[UFS_MAX_LANES * 2 * TX_EQ_SETTINGS_TUPLE_SZ];
+	u32 *host_settings, *device_settings;
+	u32 lpd = hba->lanes_per_direction;
+	struct ufshcd_tx_eq_params *params;
+	struct device *dev = hba->dev;
+	int i, err, count, gear, lane;
+	char prop_name[MAX_PROP_SIZE];
+
+	if (!lpd || lpd > UFS_MAX_LANES) {
+		dev_err(dev, "Invalid lanes-per-direction value (%u) provided\n", lpd);
+		return;
+	}
+
+	for (gear = UFS_HS_G1; gear <= UFS_HS_GEAR_MAX; gear++) {
+		snprintf(prop_name, MAX_PROP_SIZE, "txeq-settings-g%d", gear);
+		count = of_property_count_u32_elems(dev->of_node, prop_name);
+		if (count <= 0)
+			continue;
+
+		if (count != sz) {
+			dev_err(dev, "Property %s has invalid count (%d), expecting %zu \n",
+				prop_name, count, sz);
+			continue;
+		}
+
+		err = of_property_read_u32_array(dev->of_node, prop_name,
+						 settings, sz);
+		if (err) {
+			dev_err(dev, "Failed to read %s property, %d\n",
+				prop_name, err);
+			continue;
+		}
+
+		for (i = 0; i < count; i += TX_EQ_SETTINGS_TUPLE_SZ) {
+			if (settings[i] >= TX_HS_NUM_PRESHOOT) {
+				dev_err(dev, "An invalid TX EQ PreShoot (%d) provided in %s property\n",
+					settings[i], prop_name);
+				break;
+			}
+
+			if (settings[i + 1] >= TX_HS_NUM_DEEMPHASIS) {
+				dev_err(dev, "An invalid TX EQ DeEmphasis (%d) provided in %s property\n",
+					settings[i + 1], prop_name);
+				break;
+			}
+
+			if (settings[i + 2] > 1) {
+				dev_err(dev, "An invalid PrecodeEn (%d) provided in %s property\n",
+					settings[i + 2], prop_name);
+				break;
+			}
+		}
+
+		if (i != count)
+			continue;
+
+		params = &hba->tx_eq_params[gear - 1];
+		host_settings = settings;
+		device_settings = settings + lpd * TX_EQ_SETTINGS_TUPLE_SZ;
+
+		for (lane = 0; lane < lpd; lane++) {
+			params->host[lane].preshoot = host_settings[0];
+			params->host[lane].deemphasis =	host_settings[1];
+			params->host[lane].precode_en = host_settings[2];
+			host_settings += TX_EQ_SETTINGS_TUPLE_SZ;
+
+			params->device[lane].preshoot =	device_settings[0];
+			params->device[lane].deemphasis = device_settings[1];
+			params->device[lane].precode_en = device_settings[2];
+			device_settings += TX_EQ_SETTINGS_TUPLE_SZ;
+		}
+
+		params->is_valid = true;
+		params->is_static = true;
+	}
+}
+
 /**
  * ufshcd_parse_clock_min_max_freq  - Parse MIN and MAX clocks freq
  * @hba: per adapter instance
@@ -528,6 +608,8 @@ int ufshcd_pltfrm_init(struct platform_device *pdev,
 
 	ufshcd_init_lanes_per_dir(hba);
 
+	ufshcd_parse_static_tx_eq_settings(hba);
+
 	err = ufshcd_parse_operating_points(hba);
 	if (err) {
 		dev_err(dev, "%s: OPP parse failed %d\n", __func__, err);
diff --git a/include/ufs/ufshcd.h b/include/ufs/ufshcd.h
index f48d6416e299..2d385d42fcff 100644
--- a/include/ufs/ufshcd.h
+++ b/include/ufs/ufshcd.h
@@ -359,6 +359,7 @@ struct ufshcd_tx_eqtr_record {
  * @is_valid: True if parameter contains valid TX Equalization settings
  * @is_applied: True if settings have been applied to UniPro of both sides
  * @is_trained: True if parameters obtained from TX EQTR procedure
+ * @is_static: True if settings are static
  */
 struct ufshcd_tx_eq_params {
 	struct ufshcd_tx_eq_settings host[UFS_MAX_LANES];
@@ -367,8 +368,12 @@ struct ufshcd_tx_eq_params {
 	bool is_valid;
 	bool is_applied;
 	bool is_trained;
+	bool is_static;
 };
 
+/* TX EQ Settings Tuple has 3 elements - PreShoot, DeEmphasis and PrecodeEn. */
+#define TX_EQ_SETTINGS_TUPLE_SZ		3
+
 /**
  * struct ufs_hba_variant_ops - variant specific callbacks
  * @name: variant name
-- 
2.34.1