[PATCH v6 0/2] A proposal to add a gpio-locked clock driver.

[PATCH v6 0/2] A proposal to add a gpio-locked clock driver.

[Vyacheslav Yurkov via B4 Relay]

A gpio-locked clock represents an input clock, which state is determined
by a GPIO signal. It's similar to a gated-fixed-clock, but GPIO direction
is inverted. Consumers can use the output clock to wait until all input
clocks are locked and only then initialize / access dependent peripherals.

The usage example for such a driver is when peripherals depend on PLLs in
a FPGA, which can't be directly accessed by the CPU, but need a GPIO pin
to check whether clock is actually usable. E.g. some of the IPs might not
have a proper split between registers and IP core, which means that if an
external clock and/or PLL lock is missing and one tries to access the 
registers, the response never comes, thus the CPU stalls.

Signed-off-by: Vyacheslav Yurkov <uvv.mail@gmail.com>
Signed-off-by: Vyacheslav Yurkov <V.Yurkov.EXT@bruker.com>
---
Changes in v6:
- Debug messages dropped.
- The new driver is now an extension of exising clk-gpio drivers.
- The controller doesn't enable the parent clock, the consumer is
  supposed to do that instead.
- Link to v5: https://lore.kernel.org/r/20260915-feature-clock-guard-v5-0-42ab5dc3a6aa@bruker.com

Changes in v5:
- Use existing DT binding with an additional property instead of adding
  a new one
- The driver is simplified in a way that it represents the actual HW
  desgin without additional unrelated constructs
- Aggregation is removed, now it's one clock input, one clock output
- Link to v4: https://lore.kernel.org/r/20260726-feature-clock-guard-v4-0-e9c8b372b71c@bruker.com

Changes in v4:
- Removed driver specifics from DT binding
- Link to v3: https://lore.kernel.org/r/20260603-feature-clock-guard-v3-0-01cca0aa04a5@bruker.com

Changes in v3:
- Removed unnecessary dt bindings
- Improved HW description and commit messages
- Link to v2: https://lore.kernel.org/r/20260510-feature-clock-guard-v2-0-6c25458d5340@bruker.com

Changes in v2:
- Renamed to clk-gpio-locked to express intent.
- Provide enable() / is_enabled() operations so the clock behaves as
  expected
- Fixed DTS errors / warnings
- Link to v1: https://lore.kernel.org/r/20260318-feature-clock-guard-v1-0-6137cb4084b7@bruker.com

---
Vyacheslav Yurkov (2):
      dt-bindings: clock: gpio-gate-clock: Add a new compatible string
      clk: Add gpio-locked clock driver

 .../devicetree/bindings/clock/gpio-gate-clock.yaml | 32 +++++++++++++++-
 drivers/clk/clk-gpio.c                             | 44 ++++++++++++++++++++--
 2 files changed, 71 insertions(+), 5 deletions(-)
---
base-commit: fd179f8a05be3ccae366b9b96e176b51fbe54aab
change-id: 20260318-feature-clock-guard-f20a2c35b965

Best regards,
-- 
Vyacheslav Yurkov <V.Yurkov.EXT@bruker.com>

[PATCH v6 1/2] dt-bindings: clock: gpio-gate-clock: Add a new compatible string

[Vyacheslav Yurkov via B4 Relay]

From: Vyacheslav Yurkov <V.Yurkov.EXT@bruker.com>

Extend the binding to be used also for gpio-locked-fixed-clock.
A GPIO-locked fixed clock provider exposes a fixed-rate clock whose
availability depends on one or more GPIO lock-status signals.

Some hardware designs provide fixed-frequency clocks generated outside
software control, such as by FPGA-resident PLLs. While the clock rate is
fixed, a separate GPIO signal indicates whether the clock source is
locked and producing a valid output.

Signed-off-by: Vyacheslav Yurkov <V.Yurkov.EXT@bruker.com>
---
 .../devicetree/bindings/clock/gpio-gate-clock.yaml | 32 ++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml b/Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
index d09d0e3f0c6e..f44fdb17b627 100644
--- a/Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
+++ b/Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
@@ -11,7 +11,9 @@ maintainers:
 
 properties:
   compatible:
-    const: gpio-gate-clock
+    enum:
+      - gpio-gate-clock
+      - gpio-locked-clock
 
   clocks:
     maxItems: 1
@@ -23,10 +25,29 @@ properties:
     description: GPIO reference for enabling and disabling the clock.
     maxItems: 1
 
+  enabled-gpios:
+    description: GPIO that indicates whether the clock is enabled or disabled.
+    maxItems: 1
+
 required:
   - compatible
   - '#clock-cells'
-  - enable-gpios
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          const: gpio-gate-clock
+    then:
+      required:
+        - enable-gpios
+  - if:
+      properties:
+        compatible:
+          const: gpio-locked-fixed-clock
+    then:
+      required:
+        - enabled-gpios
 
 additionalProperties: false
 
@@ -40,3 +61,10 @@ examples:
         #clock-cells = <0>;
         enable-gpios = <&gpio 1 GPIO_ACTIVE_HIGH>;
     };
+
+    clk_gpio_locked {
+        compatible = "gpio-locked-fixed-clock";
+        #clock-cells = <0>;
+        clocks = <&pll>;
+        enabled-gpios = <&gpio0 4 GPIO_ACTIVE_HIGH>;
+    };

-- 
2.34.1

[PATCH v6 2/2] clk: Add gpio-locked clock driver

[Vyacheslav Yurkov via B4 Relay]

From: Vyacheslav Yurkov <V.Yurkov.EXT@bruker.com>

A gpio-locked clock exposes a clock, which status is determined by a
GPIO signal. The common use-case is a FPGA-assisted clocking design
where peripheral clocks are generated by FPGA PLLs that are outside
CPU control, with clock-valid/PLL-lock status exposed through GPIO signals.
Consumers can use the output clock to wait until the input clock is locked
and only then initialize dependent peripherals.

Signed-off-by: Vyacheslav Yurkov <V.Yurkov.EXT@bruker.com>
---
 drivers/clk/clk-gpio.c | 44 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/drivers/clk/clk-gpio.c b/drivers/clk/clk-gpio.c
index 9099c57e2715..a264ba21baf2 100644
--- a/drivers/clk/clk-gpio.c
+++ b/drivers/clk/clk-gpio.c
@@ -138,6 +138,19 @@ static const struct clk_ops clk_gpio_mux_ops = {
 	.determine_rate = __clk_mux_determine_rate,
 };
 
+/* We can't prepare the clock, but the Common Clock Framework calls only
+ * prepare() not is_prepared(), therefore we fallback on the actuall GPIO value.
+ */
+static int clk_gpio_locked_prepare(struct clk_hw *hw)
+{
+	return clk_sleeping_gpio_gate_is_prepared(hw);
+}
+
+static const struct clk_ops clk_gpio_locked_ops = {
+	.prepare =	clk_gpio_locked_prepare,
+	.is_prepared =	clk_sleeping_gpio_gate_is_prepared,
+};
+
 static struct clk_hw *clk_register_gpio(struct device *dev, u8 num_parents,
 					struct gpio_desc *gpiod,
 					const struct clk_ops *clk_gpio_ops)
@@ -146,6 +159,7 @@ static struct clk_hw *clk_register_gpio(struct device *dev, u8 num_parents,
 	struct clk_hw *hw;
 	struct clk_init_data init = {};
 	int err;
+	const char *clk_name;
 	const struct clk_parent_data gpio_parent_data[] = {
 		{ .index = 0 },
 		{ .index = 1 },
@@ -155,7 +169,11 @@ static struct clk_hw *clk_register_gpio(struct device *dev, u8 num_parents,
 	if (!clk_gpio)
 		return ERR_PTR(-ENOMEM);
 
-	init.name = dev->of_node->name;
+	err = device_property_read_string(dev, "clock-output-names", &clk_name);
+	if (err)
+		clk_name = fwnode_get_name(dev->fwnode);
+
+	init.name = clk_name;
 	init.ops = clk_gpio_ops;
 	init.parent_data = gpio_parent_data;
 	init.num_parents = num_parents;
@@ -192,6 +210,12 @@ static struct clk_hw *clk_hw_register_gpio_mux(struct device *dev,
 	return clk_register_gpio(dev, 2, gpiod, &clk_gpio_mux_ops);
 }
 
+static struct clk_hw *clk_hw_register_gpio_locked(struct device *dev,
+						  struct gpio_desc *gpiod)
+{
+	return clk_register_gpio(dev, 1, gpiod, &clk_gpio_locked_ops);
+}
+
 static int gpio_clk_driver_probe(struct platform_device *pdev)
 {
 	struct device *dev = &pdev->dev;
@@ -201,8 +225,11 @@ static int gpio_clk_driver_probe(struct platform_device *pdev)
 	struct gpio_desc *gpiod;
 	struct clk_hw *hw;
 	bool is_mux;
+	bool is_gpio_locked;
+	enum gpiod_flags gpio_flags;
 
 	is_mux = of_device_is_compatible(node, "gpio-mux-clock");
+	is_gpio_locked = of_device_is_compatible(node, "gpio-locked-clock");
 
 	num_parents = of_clk_get_parent_count(node);
 	if (is_mux && num_parents != 2) {
@@ -210,14 +237,24 @@ static int gpio_clk_driver_probe(struct platform_device *pdev)
 		return -EINVAL;
 	}
 
-	gpio_name = is_mux ? "select" : "enable";
-	gpiod = devm_gpiod_get(dev, gpio_name, GPIOD_OUT_LOW);
+	if (is_mux)
+		gpio_name = "select";
+	else if (is_gpio_locked)
+		gpio_name = "enabled";
+	else
+		gpio_name = "enable";
+
+	gpio_flags = is_gpio_locked ? GPIOD_IN : GPIOD_OUT_LOW;
+
+	gpiod = devm_gpiod_get(dev, gpio_name, gpio_flags);
 	if (IS_ERR(gpiod))
 		return dev_err_probe(dev, PTR_ERR(gpiod),
 				     "Can't get '%s' named GPIO property\n", gpio_name);
 
 	if (is_mux)
 		hw = clk_hw_register_gpio_mux(dev, gpiod);
+	else if (is_gpio_locked)
+		hw = clk_hw_register_gpio_locked(dev, gpiod);
 	else
 		hw = clk_hw_register_gpio_gate(dev, num_parents, gpiod);
 	if (IS_ERR(hw))
@@ -229,6 +266,7 @@ static int gpio_clk_driver_probe(struct platform_device *pdev)
 static const struct of_device_id gpio_clk_match_table[] = {
 	{ .compatible = "gpio-mux-clock" },
 	{ .compatible = "gpio-gate-clock" },
+	{ .compatible = "gpio-locked-clock" },
 	{ }
 };
 

-- 
2.34.1

Re: [PATCH v6 1/2] dt-bindings: clock: gpio-gate-clock: Add a new compatible string

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] dt-bindings: clock: gpio-gate-clock: compatible string mismatch breaks validation
--

commit 2b809675a6d656fd8b8fcf12572b9880f2905a0c
Author: Vyacheslav Yurkov <V.Yurkov.EXT@bruker.com>

dt-bindings: clock: gpio-gate-clock: Add a new compatible string

Extend the binding to be used also for gpio-locked-fixed-clock.
A GPIO-locked fixed clock provider exposes a fixed-rate clock whose
availability depends on one or more GPIO lock-status signals.

> diff --git a/Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml b/Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
> index d09d0e3f0c6ec..f44fdb17b627b 100644
> --- a/Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
> +++ b/Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml
> @@ -11,7 +11,9 @@ maintainers:
>  
>  properties:
>    compatible:
> -    const: gpio-gate-clock
> +    enum:
> +      - gpio-gate-clock
> +      - gpio-locked-clock

[Severity: Low]
Does this missing "-fixed" suffix introduce a regression in validation? The
commit message, conditional block, and example below all use
"gpio-locked-fixed-clock", which will fail schema validation against this
enum.

[ ... ]

> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          const: gpio-gate-clock
> +    then:
> +      required:
> +        - enable-gpios
> +  - if:
> +      properties:
> +        compatible:
> +          const: gpio-locked-fixed-clock

[Severity: Low]
Does this compatible string mismatch introduce a regression in schema checks?
If the hardware uses "gpio-locked-clock" from the enum above, this
conditional won't match and will allow invalid nodes to pass validation
silently by bypassing the required "enabled-gpios" check.

> +    then:
> +      required:
> +        - enabled-gpios
>  
>  additionalProperties: false

[ ... ]

> @@ -40,3 +61,10 @@ examples:
>          #clock-cells = <0>;
>          enable-gpios = <&gpio 1 GPIO_ACTIVE_HIGH>;
>      };
> +
> +    clk_gpio_locked {
> +        compatible = "gpio-locked-fixed-clock";

[Severity: Low]
Will this compatible string cause a regression during dt_binding_check? The
example uses a string that does not match the allowed enum values defined
above.

> +        #clock-cells = <0>;
> +        clocks = <&pll>;
> +        enabled-gpios = <&gpio0 4 GPIO_ACTIVE_HIGH>;
> +    };

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260927-feature-clock-guard-v6-0-007983b13ec2@bruker.com?part=1

Re: [PATCH v6 2/2] clk: Add gpio-locked clock driver

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [High] clk: gpio: locked-clock prepare callback violates API and inverts success
--

commit 6568d5231c6cc47d178121c89d700cd8a3a8cf08
Author: Vyacheslav Yurkov <V.Yurkov.EXT@bruker.com>

clk: Add gpio-locked clock driver

This commit introduces a gpio-locked clock driver where the clock's status
is determined by a GPIO signal. It is intended for FPGA-assisted clocking
designs where consumers can wait until the input clock is locked before
initializing dependent peripherals.

> diff --git a/drivers/clk/clk-gpio.c b/drivers/clk/clk-gpio.c
> index 9099c57e27156..a264ba21baf26 100644
> --- a/drivers/clk/clk-gpio.c
> +++ b/drivers/clk/clk-gpio.c

[ ... ]

> @@ -138,6 +138,19 @@ static const struct clk_ops clk_gpio_mux_ops = {
>  	.determine_rate = __clk_mux_determine_rate,
>  };
>  
> +/* We can't prepare the clock, but the Common Clock Framework calls only
> + * prepare() not is_prepared(), therefore we fallback on the actuall GPIO value.
> + */
> +static int clk_gpio_locked_prepare(struct clk_hw *hw)
> +{
> +	return clk_sleeping_gpio_gate_is_prepared(hw);
> +}

[Severity: High]
Does this callback violate the Common Clock Framework prepare semantics?

The Common Clock Framework expects the prepare callback to return 0 on
success and a negative error code on failure. However,
clk_sleeping_gpio_gate_is_prepared() returns the instantaneous boolean GPIO
state.

If the clock is successfully locked, this returns 1, which the framework
interprets as an error, aborting the preparation. If it is unlocked, it
returns 0, which the framework interprets as a success.

Additionally, the commit message states consumers can wait until the clock is
locked, but this implementation returns the state immediately without blocking
or polling for the lock. Will this cause dependent peripherals to initialize
prematurely or fail to initialize at all?

[ ... ]

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260927-feature-clock-guard-v6-0-007983b13ec2@bruker.com?part=2