Received-SPF: pass (google.com: domain of linux-kernel+bounces-170478-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Received-SPF: Pass (protection.outlook.com: domain of nvidia.com designates
 216.228.118.233 as permitted sender) receiver=protection.outlook.com;
 client-ip=216.228.118.233; helo=mail.nvidia.com; pr=C
From: Krishna Yarlagadda <kyarlagadda@nvidia.com>
To: <linux-tegra@vger.kernel.org>, <devicetree@vger.kernel.org>,
	<linux-doc@vger.kernel.org>, <linux-i2c@vger.kernel.org>,
	<linux-mmc@vger.kernel.org>, <linux-kernel@vger.kernel.org>
CC: <thierry.reding@gmail.com>, <jonathanh@nvidia.com>, <robh@kernel.org>,
	<krzk+dt@kernel.org>, <conor+dt@kernel.org>, <corbet@lwn.net>,
	<andi.shyti@kernel.org>, <wsa+renesas@sang-engineering.com>,
	<ulf.hansson@linaro.org>, <adrian.hunter@intel.com>, <digetx@gmail.com>,
	<ldewangan@nvidia.com>, <kyarlagadda@nvidia.com>, <mkumard@nvidia.com>
Subject: [RFC PATCH 01/11] Documentation: Introduce config settings framework
Date: Tue, 7 May 2024 04:21:29 +0530
Message-ID: <20240506225139.57647-2-kyarlagadda@nvidia.com>
In-Reply-To: <20240506225139.57647-1-kyarlagadda@nvidia.com>
References: <20240506225139.57647-1-kyarlagadda@nvidia.com>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 06 May 2024 22:52:27.9777
 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: 3ae6fd2f-828b-4df2-ee2d-08dc6e1f345a
X-MS-Exchange-CrossTenant-Id: 43083d15-7273-40c1-b7db-39efd9ccc17a
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=43083d15-7273-40c1-b7db-39efd9ccc17a;Ip=[216.228.118.233];Helo=[mail.nvidia.com]
X-MS-Exchange-CrossTenant-AuthSource:
	SN1PEPF00036F3D.namprd05.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Anonymous
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: IA1PR12MB6580

Add documentation for config settings framework utilized by Tegra SOCs.
This framework is used to configure various device registers (I2C, SPI,
etc)  with the optimal/recommended settings for a given operating mode.
For each operating mode there may be various register fields that need
to be configured and so these settings are broken down by register field.

This framework uses device-tree for specifying various register settings
for each operating mode for a given device.

Signed-off-by: Krishna Yarlagadda <kyarlagadda@nvidia.com>
---
 Documentation/misc-devices/tegra-cfg.rst | 128 +++++++++++++++++++++++
 MAINTAINERS                              |   7 ++
 2 files changed, 135 insertions(+)
 create mode 100644 Documentation/misc-devices/tegra-cfg.rst

diff --git a/Documentation/misc-devices/tegra-cfg.rst b/Documentation/misc-devices/tegra-cfg.rst
new file mode 100644
index 000000000000..be3926ff9a3e
--- /dev/null
+++ b/Documentation/misc-devices/tegra-cfg.rst
@@ -0,0 +1,128 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+NVIDIA Tegra Configuration Settings
+===================================
+
+Introduction
+------------
+NVIDIA Tegra SoCs have various I/O controllers and these controllers require
+specific register configurations.
+
+They could be due to changes in:
+ - Functional mode (eg. speed)
+ - Interface properties (eg. signal timings)
+ - Manufacturing characteristics (eg. process/package)
+ - Thermal characteristics
+ - Board characteristics
+
+Some of the configurations can be provided by device specific standard DT
+properties like speed of interface in I2C, rising/falling timing etc. However,
+there are more device specific configurations required to tune the interface
+based on execution mode or other runtime parameters. All such configurations are
+defined as 'config' settings of the device. This configures a device to operate
+with the optimal settings for a particular mode to improve performance,
+stability or reduce power.
+
+These configurations are either static or dynamic:
+ - Static configuration which is set once during device boot and controller
+   reset
+ - Dynamic configuration is applied based on a particular condition like bus
+   speed, controller mode, peripheral connected to controller, SoC and platform
+   characterization
+
+Static configurations are provided as common config setting and dynamic
+configurations are provided as mode/condition specific.
+
+Background
+----------
+Slew rates, tap delay and other calibration parameters for an interface
+controller, are measured through characterization. These values are dynamic
+and requires different values for same property / field.
+
+Use case
+--------
+Tegra device drivers that use these config settings include:
+ - I2C uses config settings to configure setup & hold times, clock divider
+   values.
+ - SDMMC tuning iterations per speed and CQE values can be set with this method.
+
+Device tree
+-----------
+Config settings of a controller are added under a child node
+"config" of the controller's device tree node.
+Further subnodes are created under config for each conditional setting.
+::
+
+  controller@xyz {
+    config {
+      common {
+        reg-field-a = <val-a1>;
+        reg-field-b = <val-b1>;
+        reg-field-c = <val-c1>;
+      };
+      cfg1 {
+        reg-field-a = <val-a2>;
+        reg-field-b = <val-b2>;
+        reg-field-c = <val-c2>;
+      };
+      cfg2 {
+        reg-field-a = <val-a3>;
+        reg-field-b = <val-b3>;
+        reg-field-c = <val-c3>;
+      };
+    };
+  };
+
+:
+ - "config": subnode in device node to hold configuration settings.
+ - "common": static configuration that needs to be applied on controller reset.
+   Register fields under 'common' node are applied during initialization
+   irrespective of any condition.
+ - "cfg1": conditional configuration to be applied when controller is set in
+   specific functional mode. Conditional configs may override existing settings
+   in 'common' or contain settings unique to the config.
+ - Properties defined under config must correspond to a register field of
+   device controller.
+ - Properties are device specific and added to device node.
+
+Example
+-------
+Ex::
+
+  i2c@3160000 {
+    config {
+      common {
+        nvidia,i2c-hs-sclk-high-period = <0x03>;
+        nvidia,i2c-hs-sclk-low-period = <0x08>;
+      };
+      fast {
+        nvidia,i2c-clk-divisor-fs-mode = <0x3c>;
+        nvidia,i2c-sclk-high-period = <0x02>;
+        nvidia,i2c-sclk-low-period = <0x02>;
+        nvidia,i2c-bus-free-time = <0x02>;
+        nvidia,i2c-stop-setup-time = <0x02>;
+        nvidia,i2c-start-hold-time = <0x02>;
+        nvidia,i2c-start-setup-time = <0x02>;
+      };
+      fastplus {
+        nvidia,i2c-clk-divisor-fs-mode = <0x16>;
+        nvidia,i2c-sclk-high-period = <0x02>;
+        nvidia,i2c-sclk-low-period = <0x02>;
+        nvidia,i2c-bus-free-time = <0x02>;
+        nvidia,i2c-stop-setup-time = <0x02>;
+        nvidia,i2c-start-hold-time = <0x02>;
+        nvidia,i2c-start-setup-time = <0x02>;
+      };
+      standard {
+        nvidia,i2c-clk-divisor-fs-mode = <0x4f>;
+        nvidia,i2c-sclk-high-period = <0x07>;
+        nvidia,i2c-sclk-low-period = <0x08>;
+        nvidia,i2c-bus-free-time = <0x08>;
+        nvidia,i2c-stop-setup-time = <0x08>;
+        nvidia,i2c-start-hold-time = <0x08>;
+        nvidia,i2c-start-setup-time = <0x08>;
+      };
+    };
+  };
+
diff --git a/MAINTAINERS b/MAINTAINERS
index eea74166a2d9..c788ff0506c3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -21991,6 +21991,13 @@ S:	Maintained
 F:	Documentation/devicetree/bindings/mtd/nvidia-tegra20-nand.txt
 F:	drivers/mtd/nand/raw/tegra_nand.c
 
+TEGRA CONFIG SETTINGS DRIVER
+M:	Thierry Reding <thierry.reding@gmail.com>
+R:	Laxman Dewangan <ldewangan@nvidia.com>
+R:	Krishna Yarlagadda <kyarlagadda@nvidia.com>
+S:	Supported
+F:	Documentation/misc-devices/tegra-cfg.rst
+
 TEGRA PWM DRIVER
 M:	Thierry Reding <thierry.reding@gmail.com>
 S:	Supported
-- 
2.43.2