A nexus node is some kind of parent device abstracting the outer
connections. They are particularly useful for describing connectors-like
interfaces but not only. Certain IP blocks will typically include inner
blocks and distribute resources to them.
In the case of clocks, there is already the concept of clock controller,
but this usually indicates some kind of control over the said clock,
ie. gate or rate control. When there is none of this, an existing
approach is to reference the upper clock, which is wrong from a hardware
point of view.
Nexus nodes are already part of the device-tree specification and clocks
are already mentioned:
https://github.com/devicetree-org/devicetree-specification/blob/v0.4/source/chapter2-devicetree-basics.rst#nexus-nodes-and-specifier-mapping
Following the introductions of nexus nodes support for interrupts, gpios
and pwms, here is the same logic applied again to the clk subsystem,
just by transitioning from of_parse_phandle_with_args() to
of_parse_phandle_with_args_map():
* Nexus OF support:
commit bd6f2fd5a1d5 ("of: Support parsing phandle argument lists through a nexus node")
* GPIO adoption:
commit c11e6f0f04db ("gpio: Support gpio nexus dt bindings")
* PWM adoption:
commit e71e46a6f19c ("pwm: Add support for pwm nexus dt bindings")
Expected Nexus properties supported:
- clock-map: maps inner clocks to inlet clocks,
- clock-map-mask: specifier cell(s) which will be remapped,
- clock-map-pass-thru: specifier cell(s) not used for remapping,
forwarded as-is.
In my own usage I had to deal with controllers where clock-map-mask and
clock-map-pass-thru were not relevant, but here is a made up example
showing how all these properties could go together:
Example:
soc_clk: clock-controller {
#clock-cells = <2>;
};
container: container {
#clock-cells = <2>;
clock-map = <0 0 &soc_clk 2 0>,
<1 0 &soc_clk 6 0>;
clock-map-mask = <0xffffffff 0x0>;
clock-map-pass-thru = <0x0 0xffffffff>;
child-device {
clocks = <&container 1 0>;
/* This is equivalent to <&soc_clk 6 0> */
};
};
The child device does not need to know about the outer implementation,
and only knows about what the nexus provides. The nexus acts as a
pass-through, with no extra control.
Signed-off-by: Miquel Raynal (Schneider Electric) <miquel.raynal@bootlin.com>
Reviewed-by: Herve Codina <herve.codina@bootlin.com>
---
drivers/clk/clk.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
index 93e33ff30f3a..196ba727e84b 100644
--- a/drivers/clk/clk.c
+++ b/drivers/clk/clk.c
@@ -5218,8 +5218,8 @@ static int of_parse_clkspec(const struct device_node *np, int index,
*/
if (name)
index = of_property_match_string(np, "clock-names", name);
- ret = of_parse_phandle_with_args(np, "clocks", "#clock-cells",
- index, out_args);
+ ret = of_parse_phandle_with_args_map(np, "clocks", "clock",
+ index, out_args);
if (!ret)
break;
if (name && index >= 0)
--
2.51.1On Fri, Mar 27, 2026 at 09:09:32PM +0100, Miquel Raynal (Schneider Electric) wrote:
> A nexus node is some kind of parent device abstracting the outer
> connections. They are particularly useful for describing connectors-like
> interfaces but not only. Certain IP blocks will typically include inner
> blocks and distribute resources to them.
>
> In the case of clocks, there is already the concept of clock controller,
> but this usually indicates some kind of control over the said clock,
> ie. gate or rate control. When there is none of this, an existing
> approach is to reference the upper clock, which is wrong from a hardware
> point of view.
>
> Nexus nodes are already part of the device-tree specification and clocks
> are already mentioned:
> https://github.com/devicetree-org/devicetree-specification/blob/v0.4/source/chapter2-devicetree-basics.rst#nexus-nodes-and-specifier-mapping
>
> Following the introductions of nexus nodes support for interrupts, gpios
> and pwms, here is the same logic applied again to the clk subsystem,
> just by transitioning from of_parse_phandle_with_args() to
> of_parse_phandle_with_args_map():
>
> * Nexus OF support:
> commit bd6f2fd5a1d5 ("of: Support parsing phandle argument lists through a nexus node")
> * GPIO adoption:
> commit c11e6f0f04db ("gpio: Support gpio nexus dt bindings")
> * PWM adoption:
> commit e71e46a6f19c ("pwm: Add support for pwm nexus dt bindings")
>
> Expected Nexus properties supported:
> - clock-map: maps inner clocks to inlet clocks,
> - clock-map-mask: specifier cell(s) which will be remapped,
> - clock-map-pass-thru: specifier cell(s) not used for remapping,
> forwarded as-is.
>
> In my own usage I had to deal with controllers where clock-map-mask and
> clock-map-pass-thru were not relevant, but here is a made up example
> showing how all these properties could go together:
>
> Example:
> soc_clk: clock-controller {
> #clock-cells = <2>;
> };
>
> container: container {
> #clock-cells = <2>;
> clock-map = <0 0 &soc_clk 2 0>,
> <1 0 &soc_clk 6 0>;
> clock-map-mask = <0xffffffff 0x0>;
> clock-map-pass-thru = <0x0 0xffffffff>;
>
> child-device {
> clocks = <&container 1 0>;
> /* This is equivalent to <&soc_clk 6 0> */
> };
> };
>
> The child device does not need to know about the outer implementation,
> and only knows about what the nexus provides. The nexus acts as a
> pass-through, with no extra control.
>
> Signed-off-by: Miquel Raynal (Schneider Electric) <miquel.raynal@bootlin.com>
> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
> ---
> drivers/clk/clk.c | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
> index 93e33ff30f3a..196ba727e84b 100644
> --- a/drivers/clk/clk.c
> +++ b/drivers/clk/clk.c
> @@ -5218,8 +5218,8 @@ static int of_parse_clkspec(const struct device_node *np, int index,
> */
> if (name)
> index = of_property_match_string(np, "clock-names", name);
> - ret = of_parse_phandle_with_args(np, "clocks", "#clock-cells",
> - index, out_args);
> + ret = of_parse_phandle_with_args_map(np, "clocks", "clock",
> + index, out_args);
Before I left my Reviewed-by, I should have double checked Sashiko. It
has several questions about this patch. The first is:
Are there other places in the clock framework that need to transition to the
new map API to ensure assigned clocks work?
For instance, assigned-clocks and assigned-clock-parents are parsed in
drivers/clk/clk-conf.c using of_parse_phandle_with_args(). If a device
specifies an assigned clock that routes through a nexus node, will it fail
to configure because the map is not traversed?
https://sashiko.dev/#/patchset/20260327-schneider-v7-0-rc1-crypto-v1-0-5e6ff7853994%40bootlin.com?patch=12563
Brian
Hello Brian, First, thanks for the whole review. On 30/03/2026 at 11:16:44 -04, Brian Masney <bmasney@redhat.com> wrote: >> - ret = of_parse_phandle_with_args(np, "clocks", "#clock-cells", >> - index, out_args); >> + ret = of_parse_phandle_with_args_map(np, "clocks", "clock", >> + index, out_args); > > Before I left my Reviewed-by, I should have double checked Sashiko. It > has several questions about this patch. The first is: > > Are there other places in the clock framework that need to transition to the > new map API to ensure assigned clocks work? > > For instance, assigned-clocks and assigned-clock-parents are parsed in > drivers/clk/clk-conf.c using of_parse_phandle_with_args(). If a device > specifies an assigned clock that routes through a nexus node, will it fail > to configure because the map is not traversed? The goal of the nexus node is to isolate what is behind. Are assigned-clocks et al. supposed to traverse a nexus node? I am tempted to say "no", but I'm open to discussing this ofc. > https://sashiko.dev/#/patchset/20260327-schneider-v7-0-rc1-crypto-v1-0-5e6ff7853994%40bootlin.com?patch=12563 I have mixed feelings concerning Sashiko's feedback. I will go through that page nevertheless, there are interesting comments in there. Thanks, Miquèl
Hi Miquel, On Wed, Apr 01, 2026 at 10:47:51AM +0200, Miquel Raynal wrote: > First, thanks for the whole review. > > On 30/03/2026 at 11:16:44 -04, Brian Masney <bmasney@redhat.com> wrote: > >> - ret = of_parse_phandle_with_args(np, "clocks", "#clock-cells", > >> - index, out_args); > >> + ret = of_parse_phandle_with_args_map(np, "clocks", "clock", > >> + index, out_args); > > > > Before I left my Reviewed-by, I should have double checked Sashiko. It > > has several questions about this patch. The first is: > > > > Are there other places in the clock framework that need to transition to the > > new map API to ensure assigned clocks work? > > > > For instance, assigned-clocks and assigned-clock-parents are parsed in > > drivers/clk/clk-conf.c using of_parse_phandle_with_args(). If a device > > specifies an assigned clock that routes through a nexus node, will it fail > > to configure because the map is not traversed? > > The goal of the nexus node is to isolate what is behind. Are > assigned-clocks et al. supposed to traverse a nexus node? I am tempted > to say "no", but I'm open to discussing this ofc. I agree that it's not needed as well, however I want to defer to Stephen's expertise here. I mainly brought this up trying to help him with reviews. > > https://sashiko.dev/#/patchset/20260327-schneider-v7-0-rc1-crypto-v1-0-5e6ff7853994%40bootlin.com?patch=12563 > > I have mixed feelings concerning Sashiko's feedback. I will go through > that page nevertheless, there are interesting comments in there. I have mixed feelings as well about the feedback from Sashiko. It finds issues, however not all of the feedback has been helpful. On the whole, I'm glad that it's available. Brian
On Fri, Mar 27, 2026 at 09:09:32PM +0100, Miquel Raynal (Schneider Electric) wrote:
> A nexus node is some kind of parent device abstracting the outer
> connections. They are particularly useful for describing connectors-like
> interfaces but not only. Certain IP blocks will typically include inner
> blocks and distribute resources to them.
>
> In the case of clocks, there is already the concept of clock controller,
> but this usually indicates some kind of control over the said clock,
> ie. gate or rate control. When there is none of this, an existing
> approach is to reference the upper clock, which is wrong from a hardware
> point of view.
>
> Nexus nodes are already part of the device-tree specification and clocks
> are already mentioned:
> https://github.com/devicetree-org/devicetree-specification/blob/v0.4/source/chapter2-devicetree-basics.rst#nexus-nodes-and-specifier-mapping
>
> Following the introductions of nexus nodes support for interrupts, gpios
> and pwms, here is the same logic applied again to the clk subsystem,
> just by transitioning from of_parse_phandle_with_args() to
> of_parse_phandle_with_args_map():
>
> * Nexus OF support:
> commit bd6f2fd5a1d5 ("of: Support parsing phandle argument lists through a nexus node")
> * GPIO adoption:
> commit c11e6f0f04db ("gpio: Support gpio nexus dt bindings")
> * PWM adoption:
> commit e71e46a6f19c ("pwm: Add support for pwm nexus dt bindings")
>
> Expected Nexus properties supported:
> - clock-map: maps inner clocks to inlet clocks,
> - clock-map-mask: specifier cell(s) which will be remapped,
> - clock-map-pass-thru: specifier cell(s) not used for remapping,
> forwarded as-is.
>
> In my own usage I had to deal with controllers where clock-map-mask and
> clock-map-pass-thru were not relevant, but here is a made up example
> showing how all these properties could go together:
>
> Example:
> soc_clk: clock-controller {
> #clock-cells = <2>;
> };
>
> container: container {
> #clock-cells = <2>;
> clock-map = <0 0 &soc_clk 2 0>,
> <1 0 &soc_clk 6 0>;
> clock-map-mask = <0xffffffff 0x0>;
> clock-map-pass-thru = <0x0 0xffffffff>;
>
> child-device {
> clocks = <&container 1 0>;
> /* This is equivalent to <&soc_clk 6 0> */
> };
> };
>
> The child device does not need to know about the outer implementation,
> and only knows about what the nexus provides. The nexus acts as a
> pass-through, with no extra control.
>
> Signed-off-by: Miquel Raynal (Schneider Electric) <miquel.raynal@bootlin.com>
> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
Reviewed-by: Brian Masney <bmasney@redhat.com>
© 2016 - 2026 Red Hat, Inc.