[PATCH v2 1/1] pwm: Add support for pwm nexus dt bindings

[PATCH v2 1/1] pwm: Add support for pwm nexus dt bindings

[Herve Codina]

Platforms can have a standardized connector/expansion slot that exposes
signals like PWMs to expansion boards in an SoC agnostic way.

The support for nexus node [1] has been added to handle those cases in
commit bd6f2fd5a1d5 ("of: Support parsing phandle argument lists through
a nexus node"). This commit introduced of_parse_phandle_with_args_map()
to handle nexus nodes in a generic way and the gpio subsystem adopted
the support in commit c11e6f0f04db ("gpio: Support gpio nexus dt
bindings").

A nexus node allows to remap a phandle list in a consumer node through a
connector node in a generic way. With this remapping supported, the
consumer node needs to knwow only about the nexus node. Resources behind
the nexus node are decoupled by the nexus node itself.

This is particularly useful when this consumer is described in a
device-tree overlay. Indeed, to have the exact same overlay reused with
several base systems the overlay needs to known only about the connector
is going to be applied to without any knowledge of the SoC (or the
component providing the resource) available in the system.

As an example, suppose 3 PWMs connected to a connector. The connector
PWM 0 and 2 comes from the PWM 1 and 3 of the pwm-controller1. The
connector PWM 1 comes from the PWM 4 of the pwm-controller2. An
expansion device is connected to the connector and uses the connector
PMW 1.

Nexus node support in PWM allows the following description:
	soc {
		soc_pwm1: pwm-controller1 {
			#pwm-cells = <3>;
		};

		soc_pwm2: pwm-controller2 {
			#pwm-cells = <3>;
		};
	};

	connector: connector {
		#pwm-cells = <3>;
		pwm-map = <0 0 0 &soc_pwm1 1 0 0>,
			  <1 0 0 &soc_pwm2 4 0 0>,
			  <2 0 0 &soc_pwm1 3 0 0>,
		pwm-map-mask = <0xffffffff 0x0 0x0>;
		pwm-map-pass-thru = <0x0 0xffffffff 0xffffffff>
	};

	expansion_device {
		pwms = <&connector 1 57000 0>;
	};

From the expansion device point of view, the PWM requested is the PWM 1
available at the connector regardless of the exact PWM wired to this
connector PWM 1. Thanks to nexus node remapping described at connector
node, this PWM is the PWM 4 of the pwm-controller2.

The nexus node remapping handling consists in handling #*-cells, *-map,
*-map-mask and *-map-pass-thru properties. This is already supported
by of_parse_phandle_with_args_map().

Add support for nexus node device-tree binding and the related remapping
in the PWM subsystem by simply using of_parse_phandle_with_args_map()
instead of of_parse_phandle_with_args().

[1] https://github.com/devicetree-org/devicetree-specification/blob/v0.4/source/chapter2-devicetree-basics.rst#nexus-nodes-and-specifier-mapping

Signed-off-by: Herve Codina <herve.codina@bootlin.com>
---
Changes v1 -> v2
  - Rework commit log

 drivers/pwm/core.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/drivers/pwm/core.c b/drivers/pwm/core.c
index 9c733877e98e..4a7454841cef 100644
--- a/drivers/pwm/core.c
+++ b/drivers/pwm/core.c
@@ -1707,8 +1707,7 @@ static struct pwm_device *of_pwm_get(struct device *dev, struct device_node *np,
 			return ERR_PTR(index);
 	}
 
-	err = of_parse_phandle_with_args(np, "pwms", "#pwm-cells", index,
-					 &args);
+	err = of_parse_phandle_with_args_map(np, "pwms", "pwm", index, &args);
 	if (err) {
 		pr_err("%s(): can't parse \"pwms\" property\n", __func__);
 		return ERR_PTR(err);
-- 
2.47.1

Re: [PATCH v2 1/1] pwm: Add support for pwm nexus dt bindings

[Herve Codina]

Hi All,

I haven't receive any feedback on this patch neither the v1 nor this v2.

Maybe an issue with the mail. Add u.kleine-koenig@baylibre.com and hope to
have a feedback on this patch.

Best regards,
Hervé

On Wed,  8 Jan 2025 17:18:53 +0100
Herve Codina <herve.codina@bootlin.com> wrote:

> Platforms can have a standardized connector/expansion slot that exposes
> signals like PWMs to expansion boards in an SoC agnostic way.
> 
> The support for nexus node [1] has been added to handle those cases in
> commit bd6f2fd5a1d5 ("of: Support parsing phandle argument lists through
> a nexus node"). This commit introduced of_parse_phandle_with_args_map()
> to handle nexus nodes in a generic way and the gpio subsystem adopted
> the support in commit c11e6f0f04db ("gpio: Support gpio nexus dt
> bindings").
> 
> A nexus node allows to remap a phandle list in a consumer node through a
> connector node in a generic way. With this remapping supported, the
> consumer node needs to knwow only about the nexus node. Resources behind
> the nexus node are decoupled by the nexus node itself.
> 
> This is particularly useful when this consumer is described in a
> device-tree overlay. Indeed, to have the exact same overlay reused with
> several base systems the overlay needs to known only about the connector
> is going to be applied to without any knowledge of the SoC (or the
> component providing the resource) available in the system.
> 
> As an example, suppose 3 PWMs connected to a connector. The connector
> PWM 0 and 2 comes from the PWM 1 and 3 of the pwm-controller1. The
> connector PWM 1 comes from the PWM 4 of the pwm-controller2. An
> expansion device is connected to the connector and uses the connector
> PMW 1.
> 
> Nexus node support in PWM allows the following description:
> 	soc {
> 		soc_pwm1: pwm-controller1 {
> 			#pwm-cells = <3>;
> 		};
> 
> 		soc_pwm2: pwm-controller2 {
> 			#pwm-cells = <3>;
> 		};
> 	};
> 
> 	connector: connector {
> 		#pwm-cells = <3>;
> 		pwm-map = <0 0 0 &soc_pwm1 1 0 0>,
> 			  <1 0 0 &soc_pwm2 4 0 0>,
> 			  <2 0 0 &soc_pwm1 3 0 0>,
> 		pwm-map-mask = <0xffffffff 0x0 0x0>;
> 		pwm-map-pass-thru = <0x0 0xffffffff 0xffffffff>
> 	};
> 
> 	expansion_device {
> 		pwms = <&connector 1 57000 0>;
> 	};
> 
> From the expansion device point of view, the PWM requested is the PWM 1
> available at the connector regardless of the exact PWM wired to this
> connector PWM 1. Thanks to nexus node remapping described at connector
> node, this PWM is the PWM 4 of the pwm-controller2.
> 
> The nexus node remapping handling consists in handling #*-cells, *-map,
> *-map-mask and *-map-pass-thru properties. This is already supported
> by of_parse_phandle_with_args_map().
> 
> Add support for nexus node device-tree binding and the related remapping
> in the PWM subsystem by simply using of_parse_phandle_with_args_map()
> instead of of_parse_phandle_with_args().
> 
> [1] https://github.com/devicetree-org/devicetree-specification/blob/v0.4/source/chapter2-devicetree-basics.rst#nexus-nodes-and-specifier-mapping
> 
> Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> ---
> Changes v1 -> v2
>   - Rework commit log
> 
>  drivers/pwm/core.c | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/drivers/pwm/core.c b/drivers/pwm/core.c
> index 9c733877e98e..4a7454841cef 100644
> --- a/drivers/pwm/core.c
> +++ b/drivers/pwm/core.c
> @@ -1707,8 +1707,7 @@ static struct pwm_device *of_pwm_get(struct device *dev, struct device_node *np,
>  			return ERR_PTR(index);
>  	}
>  
> -	err = of_parse_phandle_with_args(np, "pwms", "#pwm-cells", index,
> -					 &args);
> +	err = of_parse_phandle_with_args_map(np, "pwms", "pwm", index, &args);
>  	if (err) {
>  		pr_err("%s(): can't parse \"pwms\" property\n", __func__);
>  		return ERR_PTR(err);

Re: [PATCH v2 1/1] pwm: Add support for pwm nexus dt bindings

[Uwe Kleine-König]

[-- Attachment #1: Type: text/plain, Size: 517 bytes --]

Hello Herve,

On Fri, Jan 17, 2025 at 09:27:04AM +0100, Herve Codina wrote:
> I haven't receive any feedback on this patch neither the v1 nor this v2.
> 
> Maybe an issue with the mail. Add u.kleine-koenig@baylibre.com and hope to
> have a feedback on this patch.

It's more a problem with the length of my review queue and the time I
have to spare for it. :-\

As long as your patch appears on
https://patchwork.ozlabs.org/project/linux-pwm/list/ I have it on my
radar eventually.

Best regards
Uwe

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v2 1/1] pwm: Add support for pwm nexus dt bindings

[Rob Herring]

On Wed, Jan 08, 2025 at 05:18:53PM +0100, Herve Codina wrote:
> Platforms can have a standardized connector/expansion slot that exposes
> signals like PWMs to expansion boards in an SoC agnostic way.
> 
> The support for nexus node [1] has been added to handle those cases in
> commit bd6f2fd5a1d5 ("of: Support parsing phandle argument lists through
> a nexus node"). This commit introduced of_parse_phandle_with_args_map()
> to handle nexus nodes in a generic way and the gpio subsystem adopted
> the support in commit c11e6f0f04db ("gpio: Support gpio nexus dt
> bindings").
> 
> A nexus node allows to remap a phandle list in a consumer node through a
> connector node in a generic way. With this remapping supported, the
> consumer node needs to knwow only about the nexus node. Resources behind
> the nexus node are decoupled by the nexus node itself.
> 
> This is particularly useful when this consumer is described in a
> device-tree overlay. Indeed, to have the exact same overlay reused with
> several base systems the overlay needs to known only about the connector
> is going to be applied to without any knowledge of the SoC (or the
> component providing the resource) available in the system.
> 
> As an example, suppose 3 PWMs connected to a connector. The connector
> PWM 0 and 2 comes from the PWM 1 and 3 of the pwm-controller1. The
> connector PWM 1 comes from the PWM 4 of the pwm-controller2. An
> expansion device is connected to the connector and uses the connector
> PMW 1.
> 
> Nexus node support in PWM allows the following description:
> 	soc {
> 		soc_pwm1: pwm-controller1 {
> 			#pwm-cells = <3>;
> 		};
> 
> 		soc_pwm2: pwm-controller2 {
> 			#pwm-cells = <3>;
> 		};
> 	};
> 
> 	connector: connector {
> 		#pwm-cells = <3>;
> 		pwm-map = <0 0 0 &soc_pwm1 1 0 0>,
> 			  <1 0 0 &soc_pwm2 4 0 0>,
> 			  <2 0 0 &soc_pwm1 3 0 0>,
> 		pwm-map-mask = <0xffffffff 0x0 0x0>;
> 		pwm-map-pass-thru = <0x0 0xffffffff 0xffffffff>
> 	};
> 
> 	expansion_device {
> 		pwms = <&connector 1 57000 0>;
> 	};
> 
> From the expansion device point of view, the PWM requested is the PWM 1
> available at the connector regardless of the exact PWM wired to this
> connector PWM 1. Thanks to nexus node remapping described at connector
> node, this PWM is the PWM 4 of the pwm-controller2.
> 
> The nexus node remapping handling consists in handling #*-cells, *-map,
> *-map-mask and *-map-pass-thru properties. This is already supported
> by of_parse_phandle_with_args_map().

You need a schema for all these properties (pwm-map, etc.). A wildcard 
doesn't work because '-map$' is not unique:

$ dt-extract-props Documentation/devicetree/bindings/ | grep '\-map'
 'adi,pdm-clk-map': ['uint32-array'],
 'arm,v2m-memory-map': ['string'],
 'brcm,ccode-map': ['string-array'],
 'brcm,ccode-map-trivial': ['flag'],
 'brcm,int-map-mask': ['uint32-array'],
 'charge-current-limit-mapping': ['uint32-matrix'],
 'dai-tdm-slot-width-map': ['uint32-matrix'],
 'data-mapping': ['string-array'],
 'fsl,asrc-clk-map': ['uint32'],
 'gpio-fan,speed-map': ['uint32-matrix'],
 'gpio-map': ['uint32-matrix'],
 'gpio-map-mask': ['uint32-array'],
 'gpio-map-pass-thru': ['uint32-array'],
 'intel,vm-map': ['uint8-array'],
 'interrupt-map': ['uint32-matrix'],
 'interrupt-map-mask': ['uint32-array'],
 'iommu-map': ['uint32-matrix'],
 'iommu-map-mask': ['uint32'],
 'linux,rc-map-name': ['string'],
 'msi-map': ['uint32-matrix'],
 'msi-map-mask': ['uint32'],
 'mstar,irqs-map-range': ['uint32-matrix'],
 'no-map': ['flag'],
 'port-mapping-mode': ['flag'],
 'qcom,mpm-pin-map': ['uint32-matrix'],
 'qcom,port-mapping': ['uint32-array'],
 'qcom,rx-port-mapping': ['uint32-array'],
 'qcom,tx-port-mapping': ['uint32-array'],
 'rockchip,path-map': ['uint32-array'],
 'ti,linear-mapping-mode': ['flag'],

Rob