[PATCH v2 3/4] dt-bindings: Add post-init-supplier property

Saravana Kannan
2024-02-12T21:32:01Z

The post-init-supplier property can be used to break a dependency cycle by
marking some supplier(s) as a post device initialization supplier(s). This
allows an OS to do a better job at ordering initialization and
suspend/resume of the devices in a dependency cycle.

Signed-off-by: Saravana Kannan <saravanak@google.com>
---
.../bindings/post-init-supplier.yaml | 101 ++++++++++++++++++
MAINTAINERS | 13 +--
2 files changed, 108 insertions(+), 6 deletions(-)
create mode 100644 Documentation/devicetree/bindings/post-init-supplier.yaml

diff --git a/Documentation/devicetree/bindings/post-init-supplier.yaml b/Documentation/devicetree/bindings/post-init-supplier.yaml
new file mode 100644
index 000000000000..aab75b667259
--- /dev/null
+++ b/Documentation/devicetree/bindings/post-init-supplier.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (c) 2020, Google LLC. All rights reserved.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/post-init-supplier.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Post device initialization supplier
+
+maintainers:
+ - Saravana Kannan <saravanak@google.com>
+
+description: |
+ This property is used to indicate that the device(s) pointed to by the
+ property are not needed for the initialization of the device that lists this
+ property. This property is meaningful only when pointing to direct suppliers
+ of a device that are pointed to by other properties in the device.
+
+ A device can list its suppliers in devicetree using one or more of the
+ standard devicetree bindings. By default, it would be safe to assume the
+ supplier device can be initialized before the consumer device is initialized.
+
+ However, that assumption cannot be made when there are cyclic dependencies
+ between devices. Since each device is a supplier (directly or indirectly) of
+ the others in the cycle, there is no guaranteed safe order for initializing
+ the devices in a cycle. We can try to initialize them in an arbitrary order
+ and eventually successfully initialize all of them, but that doesn't always
+ work well.
+
+ For example, say,
+ * The device tree has the following cyclic dependency X -> Y -> Z -> X (where
+ -> denotes "depends on").
+ * But X is not needed to fully initialize Z (X might be needed only when a
+ specific functionality is requested post initialization).
+
+ If all the other -> are mandatory initialization dependencies, then trying to
+ initialize the devices in a loop (or arbitrarily) will always eventually end
+ up with the devices being initialized in the order Z, Y and X.
+
+ However, if Y is an optional supplier for X (where X provides limited
+ functionality when Y is not initialized and providing its services), then
+ trying to initialize the devices in a loop (or arbitrarily) could end up with
+ the devices being initialized in the following order:
+
+ * Z, Y and X - All devices provide full functionality
+ * Z, X and Y - X provides partial functionality
+ * X, Z and Y - X provides partial functionality
+
+ However, we always want to initialize the devices in the order Z, Y and X
+ since that provides the full functionality without interruptions.
+
+ One alternate option that might be suggested is to have the driver for X
+ notice that Y became available at a later point and adjust the functionality
+ it provides. However, other userspace applications could have started using X
+ with the limited functionality before Y was available and it might not be
+ possible to transparently transition X or the users of X to full
+ functionality while X is in use.
+
+ Similarly, when it comes to suspend (resume) ordering, it's unclear which
+ device in a dependency cycle needs to be suspended/resumed first and trying
+ arbitrary orders can result in system crashes or instability.
+
+ Explicitly calling out which link in a cycle needs to be broken when
+ determining the order, simplifies things a lot, improves efficiency, makes
+ the behavior more deterministic and maximizes the functionality that can be
+ provided without interruption.
+
+ This property is used to provide this additional information between devices
+ in a cycle by telling which supplier(s) is not needed for initializing the
+ device that lists this property.
+
+ In the example above, Z would list X as a post-init-supplier and the
+ initialization dependency would become X -> Y -> Z -/-> X. So the best order
+ to initialize them become clear: Z, Y and then X.
+
+select: true
+properties:
+ post-init-supplier:
+ # One or more suppliers can be marked as post initialization supplier
+ description:
+ List of phandles to suppliers that are not needed for initializing or
+ resuming this device.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ maxItems: 1
+
+examples:
+ - |
+ gcc: clock-controller@1000 {
+ compatible = "vendor,soc4-gcc", "vendor,soc1-gcc";
+ reg = <0x1000 0x80>;
+ clocks = <&dispcc 0x1>
+ #clock-cells = <1>;
+ post-init-supplier = <&dispcc>;
+ };
+ dispcc: clock-controller@2000 {
+ compatible = "vendor,soc4-dispcc", "vendor,soc1-dispcc";
+ reg = <0x2000 0x80>;
+ clocks = <&gcc 0xdd>
+ #clock-cells = <1>;
+ };
diff --git a/MAINTAINERS b/MAINTAINERS
index 3dfe7ea25320..79719af714be 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6055,12 +6055,6 @@ S: Maintained
F: drivers/base/devcoredump.c
F: include/linux/devcoredump.h

-DEVICE DEPENDENCY HELPER SCRIPT
-M: Saravana Kannan <saravanak@google.com>
-L: linux-kernel@vger.kernel.org
-S: Maintained
-F: scripts/dev-needs.sh
-
DEVICE DIRECT ACCESS (DAX)
M: Dan Williams <dan.j.williams@intel.com>
M: Vishal Verma <vishal.l.verma@intel.com>
@@ -8295,6 +8289,13 @@ F: include/linux/firewire.h
F: include/uapi/linux/firewire*.h
F: tools/firewire/

+FIRMWARE DEVICE LINK (fw_devlink)
+M: Saravana Kannan <saravanak@google.com>
+L: linux-kernel@vger.kernel.org
+S: Maintained
+F: Documentation/devicetree/bindings/post-init-supplier.yaml
+F: scripts/dev-needs.sh
+
FIRMWARE FRAMEWORK FOR ARMV8-A
M: Sudeep Holla <sudeep.holla@arm.com>
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
--
2.43.0.687.g38aa6559b0-goog