* [PATCH v2] schemas: Add schema for post-init-providers
@ 2024-03-08 6:56 Saravana Kannan
2024-03-08 6:58 ` Saravana Kannan
0 siblings, 1 reply; 2+ messages in thread
From: Saravana Kannan @ 2024-03-08 6:56 UTC (permalink / raw)
To: Rob Herring; +Cc: Saravana Kannan, devicetree-spec, kernel-team
The post-init-providers property can be used to break a dependency cycle by
marking some provider(s) as a post-device-initialization provider(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>
---
dtschema/schemas/post-init-providers.yaml | 105 ++++++++++++++++++++++
1 file changed, 105 insertions(+)
create mode 100644 dtschema/schemas/post-init-providers.yaml
diff --git a/dtschema/schemas/post-init-providers.yaml b/dtschema/schemas/post-init-providers.yaml
new file mode 100644
index 0000000..a329776
--- /dev/null
+++ b/dtschema/schemas/post-init-providers.yaml
@@ -0,0 +1,105 @@
+# 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-providers.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Post-device-initialization providers
+
+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 does not make a device (that's previously not a
+ provider) into a provider. It simply downgrades an existing provider to a
+ post-device-initialization provider.
+
+ A device can list its providers in devicetree using one or more of the
+ standard devicetree bindings. By default, it is assumed that the provider
+ 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 provider (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 after initialization of Z).
+
+ 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 provider 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 provider(s) is not needed for initializing the
+ device that lists this property.
+
+ In the example above, Z would list X as a post-init-providers and the
+ initialization dependency would become X -> Y -> Z -/-> X. So the best order
+ to initialize them becomes clear: Z, Y and then X.
+
+select: true
+
+properties:
+ post-init-providers:
+ # One or more providers can be marked as post initialization provider
+ description:
+ List of phandles to providers that are not needed for initializing or
+ resuming this device.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ maxItems: 1
+
+additionalProperties: true
+
+examples:
+ - |
+ gcc: clock-controller@1000 {
+ compatible = "vendor,soc4-gcc", "vendor,soc1-gcc";
+ reg = <0x1000 0x80>;
+ clocks = <&dispcc 0x1>;
+ #clock-cells = <1>;
+ post-init-providers = <&dispcc>;
+ };
+ dispcc: clock-controller@2000 {
+ compatible = "vendor,soc4-dispcc", "vendor,soc1-dispcc";
+ reg = <0x2000 0x80>;
+ clocks = <&gcc 0xdd>;
+ #clock-cells = <1>;
+ };
--
2.44.0.278.ge034bb2e1d-goog
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH v2] schemas: Add schema for post-init-providers
2024-03-08 6:56 [PATCH v2] schemas: Add schema for post-init-providers Saravana Kannan
@ 2024-03-08 6:58 ` Saravana Kannan
0 siblings, 0 replies; 2+ messages in thread
From: Saravana Kannan @ 2024-03-08 6:58 UTC (permalink / raw)
To: Rob Herring; +Cc: devicetree-spec, kernel-team
On Thu, Mar 7, 2024 at 10:56 PM Saravana Kannan <saravanak@google.com> wrote:
>
> The post-init-providers property can be used to break a dependency cycle by
> marking some provider(s) as a post-device-initialization provider(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>
> ---
> dtschema/schemas/post-init-providers.yaml | 105 ++++++++++++++++++++++
> 1 file changed, 105 insertions(+)
> create mode 100644 dtschema/schemas/post-init-providers.yaml
>
> diff --git a/dtschema/schemas/post-init-providers.yaml b/dtschema/schemas/post-init-providers.yaml
> new file mode 100644
> index 0000000..a329776
> --- /dev/null
> +++ b/dtschema/schemas/post-init-providers.yaml
> @@ -0,0 +1,105 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +# Copyright (c) 2020, Google LLC. All rights reserved.
Sigh. Forgot to update this.
Rob, can you please just change this to 2024 on your end?
Thanks,
Saravana
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/post-init-providers.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Post-device-initialization providers
> +
> +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 does not make a device (that's previously not a
> + provider) into a provider. It simply downgrades an existing provider to a
> + post-device-initialization provider.
> +
> + A device can list its providers in devicetree using one or more of the
> + standard devicetree bindings. By default, it is assumed that the provider
> + 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 provider (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 after initialization of Z).
> +
> + 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 provider 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 provider(s) is not needed for initializing the
> + device that lists this property.
> +
> + In the example above, Z would list X as a post-init-providers and the
> + initialization dependency would become X -> Y -> Z -/-> X. So the best order
> + to initialize them becomes clear: Z, Y and then X.
> +
> +select: true
> +
> +properties:
> + post-init-providers:
> + # One or more providers can be marked as post initialization provider
> + description:
> + List of phandles to providers that are not needed for initializing or
> + resuming this device.
> + $ref: /schemas/types.yaml#/definitions/phandle-array
> + items:
> + maxItems: 1
> +
> +additionalProperties: true
> +
> +examples:
> + - |
> + gcc: clock-controller@1000 {
> + compatible = "vendor,soc4-gcc", "vendor,soc1-gcc";
> + reg = <0x1000 0x80>;
> + clocks = <&dispcc 0x1>;
> + #clock-cells = <1>;
> + post-init-providers = <&dispcc>;
> + };
> + dispcc: clock-controller@2000 {
> + compatible = "vendor,soc4-dispcc", "vendor,soc1-dispcc";
> + reg = <0x2000 0x80>;
> + clocks = <&gcc 0xdd>;
> + #clock-cells = <1>;
> + };
> --
> 2.44.0.278.ge034bb2e1d-goog
>
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2024-03-08 6:59 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-03-08 6:56 [PATCH v2] schemas: Add schema for post-init-providers Saravana Kannan
2024-03-08 6:58 ` Saravana Kannan
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).