[PATCH v1 0/2] Add pinctrl_pm_select_init_state helper function

[PATCH v1 0/2] Add pinctrl_pm_select_init_state helper function

[Christian Bruel]

Some platforms need to set the pinctrl to an initial state during
pm_resume, just like during probe. To achieve this, the missing function
pinctrl_pm_select_init_state() is added to the list of already existing
pinctrl PM helper functions.

This allows a driver to use the pinctrl init and default states in the
pm_runtime platform resume handlers, just as in probe.

Additionally the missing documentation describing these pinctrl standard
states used during probe has been added.

This fixes a build issue for the STM32MP25 PCIe staged in the pcie tree,
id 5a972a01e24b
 
Changes in v1:
   - Add missing information about PM helper functions.

Christian Bruel (2):
  Documentation: pinctrl: Describe PM helper functions for standard
    states.
  pinctrl: Add pinctrl_pm_select_init_state helper function

 Documentation/driver-api/pin-control.rst | 58 ++++++++++++++++++++++--
 drivers/pinctrl/core.c                   | 13 ++++++
 include/linux/pinctrl/consumer.h         | 10 ++++
 3 files changed, 78 insertions(+), 3 deletions(-)

-- 
2.34.1

[PATCH v1 1/2] Documentation: pinctrl: Describe PM helper functions for standard states.

[Christian Bruel]

Clarify documentation for predefined standard state names 'default',
'init', 'sleep', 'idle' and their associated PM API.

Signed-off-by: Christian Bruel <christian.bruel@foss.st.com>
---
 Documentation/driver-api/pin-control.rst | 57 +++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst
index 27ea1236307e..204cc3e162e2 100644
--- a/Documentation/driver-api/pin-control.rst
+++ b/Documentation/driver-api/pin-control.rst
@@ -1162,8 +1162,55 @@ pinmux core.
 Pin control requests from drivers
 =================================
 
-When a device driver is about to probe the device core will automatically
-attempt to issue ``pinctrl_get_select_default()`` on these devices.
+When a device driver is about to probe, the device core attaches the
+standard states if they are defined in the device tree by calling
+``pinctrl_bind_pins()`` on these devices.
+Possible standard state names are: "default", "init", "sleep" and "idle".
+
+- if ``default`` is defined in the device tree, it is selected before
+  device probe.
+
+- if ``init`` and ``default`` are defined in the device tree, the "init"
+  state is selected before the driver probe and the "default" state is
+  selected after the driver probe.
+
+- the ``sleep`` and ``idle`` states are for power management and can only
+  be selected with the PM API bellow.
+
+PM interfaces
+=================
+PM runtime suspend/resume might need to execute the same init sequence as
+during probe. Since the predefined states are already attached to the
+device, the driver can activate these states explicitly with the
+following helper functions:
+
+- ``pinctrl_pm_select_default_state()``
+- ``pinctrl_pm_select_init_state()``
+- ``pinctrl_pm_select_sleep_state()``
+- ``pinctrl_pm_select_idle_state()``
+
+For example, if resuming the device depend on certain pinmux states
+
+.. code-block:: c
+
+	foo_suspend()
+	{
+		/* suspend device */
+		...
+
+		pinctrl_pm_select_sleep_state(dev);
+	}
+
+	foo_resume()
+	{
+		pinctrl_pm_select_init_state(dev);
+
+		/* resuming device */
+		...
+
+		pinctrl_pm_select_default_state(dev);
+	}
+
 This way driver writers do not need to add any of the boilerplate code
 of the type found below. However when doing fine-grained state selection
 and not using the "default" state, you may have to do some device driver
@@ -1185,6 +1232,12 @@ operation and going to sleep, moving from the ``PINCTRL_STATE_DEFAULT`` to
 ``PINCTRL_STATE_SLEEP`` at runtime, re-biasing or even re-muxing pins to save
 current in sleep mode.
 
+Another case is when the pinctrl needs to switch to a certain mode during
+probe and then revert to the default state at the end of probe. For example
+a PINMUX may need to be configured as a GPIO during probe. In this case, use
+``PINCTRL_STATE_INIT`` to switch state before probe, then move to
+``PINCTRL_STATE_DEFAULT`` at the end of probe for normal operation.
+
 A driver may request a certain control state to be activated, usually just the
 default state like this:
 
-- 
2.34.1

[PATCH v1 2/2] pinctrl: Add pinctrl_pm_select_init_state helper function

[Christian Bruel]

If a platformm requires an initial pinctrl state during probing, this
helper function provides the client with access to the same initial
state.

eg:
 xxx_suspend_noirq
    ...
    pinctrl_pm_select_sleep_state

 xxx resume_noirq
    pinctrl_pm_select_init_state
    ...
    pinctrl_pm_select_default_state

Signed-off-by: Christian Bruel <christian.bruel@foss.st.com>
---
 drivers/pinctrl/core.c           | 13 +++++++++++++
 include/linux/pinctrl/consumer.h | 10 ++++++++++
 2 files changed, 23 insertions(+)

diff --git a/drivers/pinctrl/core.c b/drivers/pinctrl/core.c
index 73b78d6eac67..c5dbf4e9db84 100644
--- a/drivers/pinctrl/core.c
+++ b/drivers/pinctrl/core.c
@@ -1655,6 +1655,19 @@ int pinctrl_pm_select_default_state(struct device *dev)
 }
 EXPORT_SYMBOL_GPL(pinctrl_pm_select_default_state);
 
+/**
+ * pinctrl_pm_select_init_state() - select init pinctrl state for PM
+ * @dev: device to select init state for
+ */
+int pinctrl_pm_select_init_state(struct device *dev)
+{
+	if (!dev->pins)
+		return 0;
+
+	return pinctrl_select_bound_state(dev, dev->pins->init_state);
+}
+EXPORT_SYMBOL_GPL(pinctrl_pm_select_init_state);
+
 /**
  * pinctrl_pm_select_sleep_state() - select sleep pinctrl state for PM
  * @dev: device to select sleep state for
diff --git a/include/linux/pinctrl/consumer.h b/include/linux/pinctrl/consumer.h
index 73de70362b98..63ce16191eb9 100644
--- a/include/linux/pinctrl/consumer.h
+++ b/include/linux/pinctrl/consumer.h
@@ -48,6 +48,7 @@ int pinctrl_select_default_state(struct device *dev);
 
 #ifdef CONFIG_PM
 int pinctrl_pm_select_default_state(struct device *dev);
+int pinctrl_pm_select_init_state(struct device *dev);
 int pinctrl_pm_select_sleep_state(struct device *dev);
 int pinctrl_pm_select_idle_state(struct device *dev);
 #else
@@ -55,6 +56,10 @@ static inline int pinctrl_pm_select_default_state(struct device *dev)
 {
 	return 0;
 }
+static inline int pinctrl_pm_select_init_state(struct device *dev)
+{
+	return 0;
+}
 static inline int pinctrl_pm_select_sleep_state(struct device *dev)
 {
 	return 0;
@@ -143,6 +148,11 @@ static inline int pinctrl_pm_select_default_state(struct device *dev)
 	return 0;
 }
 
+static inline int pinctrl_pm_select_init_state(struct device *dev)
+{
+	return 0;
+}
+
 static inline int pinctrl_pm_select_sleep_state(struct device *dev)
 {
 	return 0;
-- 
2.34.1

Re: [PATCH v1 2/2] pinctrl: Add pinctrl_pm_select_init_state helper function

[Linus Walleij]

On Wed, Aug 13, 2025 at 10:13 AM Christian Bruel
<christian.bruel@foss.st.com> wrote:

> If a platformm requires an initial pinctrl state during probing, this
> helper function provides the client with access to the same initial
> state.
>
> eg:
>  xxx_suspend_noirq
>     ...
>     pinctrl_pm_select_sleep_state
>
>  xxx resume_noirq
>     pinctrl_pm_select_init_state
>     ...
>     pinctrl_pm_select_default_state
>
> Signed-off-by: Christian Bruel <christian.bruel@foss.st.com>

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Björn, just apply this with the other patch so all works fine
in your tree, I don't think it will conflict anything.

Yours,
Linus Walleij

Re: [PATCH v1 1/2] Documentation: pinctrl: Describe PM helper functions for standard states.

[Linus Walleij]

On Wed, Aug 13, 2025 at 10:13 AM Christian Bruel
<christian.bruel@foss.st.com> wrote:

> Clarify documentation for predefined standard state names 'default',
> 'init', 'sleep', 'idle' and their associated PM API.
>
> Signed-off-by: Christian Bruel <christian.bruel@foss.st.com>

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij

Re: [PATCH v1 0/2] Add pinctrl_pm_select_init_state helper function

[Linus Walleij]

On Wed, Aug 13, 2025 at 10:13 AM Christian Bruel
<christian.bruel@foss.st.com> wrote:

> Some platforms need to set the pinctrl to an initial state during
> pm_resume, just like during probe. To achieve this, the missing function
> pinctrl_pm_select_init_state() is added to the list of already existing
> pinctrl PM helper functions.
>
> This allows a driver to use the pinctrl init and default states in the
> pm_runtime platform resume handlers, just as in probe.
>
> Additionally the missing documentation describing these pinctrl standard
> states used during probe has been added.
>
> This fixes a build issue for the STM32MP25 PCIe staged in the pcie tree,
> id 5a972a01e24b

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Björn: Just apply this to the PCI tree.

Yours,
Linus Walleij

Re: [PATCH v1 0/2] Add pinctrl_pm_select_init_state helper function

[Bjorn Helgaas]

On Mon, Aug 18, 2025 at 05:32:14PM +0200, Linus Walleij wrote:
> On Wed, Aug 13, 2025 at 10:13 AM Christian Bruel
> <christian.bruel@foss.st.com> wrote:
> 
> > Some platforms need to set the pinctrl to an initial state during
> > pm_resume, just like during probe. To achieve this, the missing function
> > pinctrl_pm_select_init_state() is added to the list of already existing
> > pinctrl PM helper functions.
> >
> > This allows a driver to use the pinctrl init and default states in the
> > pm_runtime platform resume handlers, just as in probe.
> >
> > Additionally the missing documentation describing these pinctrl standard
> > states used during probe has been added.
> >
> > This fixes a build issue for the STM32MP25 PCIe staged in the pcie tree,
> > id 5a972a01e24b
> 
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
> 
> Björn: Just apply this to the PCI tree.

Thanks, Linus, will do!

Bjorn