pm: device: move pm_device_runtime_init_* funcs

Move the `pm_device_runtime_init_*` functions from <pm/device_runtime.h>
to <pm/device.h>. The initial device state should be settable
independently of whether `CONFIG_PM_DEVICE_RUNTIME` is enabled.

This also resolves a compilation error when attempting to use these
functions without also including <pm/device.h>.

Function documentation is also updated to be more general than only
referencing runtime PM, as this also applies to system PM and manually
run actions.

Signed-off-by: Jordan Yates <jordan.yates@data61.csiro.au>
This commit is contained in:
Jordan Yates 2022-03-12 22:00:27 +10:00 committed by Carles Cufí
commit 6d1a08b3a8
6 changed files with 55 additions and 48 deletions

View file

@ -145,7 +145,7 @@ To enable device runtime power management on a device, the driver needs to call
function will suspend the device if its state is
:c:enumerator:`PM_DEVICE_STATE_ACTIVE`. In case the device is physically
suspended, the init function should call
:c:func:`pm_device_runtime_init_suspended` before calling
:c:func:`pm_device_init_suspended` before calling
:c:func:`pm_device_runtime_enable`.
.. code-block:: c
@ -157,7 +157,7 @@ suspended, the init function should call
...
/* OPTIONAL: mark device as suspended if it is physically suspended */
pm_device_runtime_init_suspended(dev);
pm_device_init_suspended(dev);
/* enable device runtime power management */
ret = pm_device_runtime_enable(dev);

View file

@ -626,7 +626,7 @@ static int gpio_stm32_init(const struct device *dev)
return ret;
}
pm_device_runtime_init_suspended(dev);
pm_device_init_suspended(dev);
(void)pm_device_runtime_enable(dev);
return 0;

View file

@ -83,10 +83,10 @@ static int pd_gpio_init(const struct device *dev)
if (pm_device_on_power_domain(dev)) {
/* Device is unpowered */
pm_device_runtime_init_off(dev);
pm_device_init_off(dev);
rc = gpio_pin_configure_dt(&cfg->enable, GPIO_DISCONNECTED);
} else {
pm_device_runtime_init_suspended(dev);
pm_device_init_suspended(dev);
rc = gpio_pin_configure_dt(&cfg->enable, GPIO_OUTPUT_INACTIVE);
}

View file

@ -361,6 +361,44 @@ void pm_device_children_action_run(const struct device *dev,
pm_device_action_failed_cb_t failure_cb);
#if defined(CONFIG_PM_DEVICE) || defined(__DOXYGEN__)
/**
* @brief Initialize a device state to #PM_DEVICE_STATE_SUSPENDED.
*
* By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. However
* in order to save power some drivers may choose to only initialize the device
* to the suspended state, or actively put the device into the suspended state.
* This function can therefore be used to notify the PM subsystem that the
* device is in #PM_DEVICE_STATE_SUSPENDED instead of the default.
*
* @param dev Device instance.
*/
static inline void pm_device_init_suspended(const struct device *dev)
{
struct pm_device *pm = dev->pm;
pm->state = PM_DEVICE_STATE_SUSPENDED;
}
/**
* @brief Initialize a device state to #PM_DEVICE_STATE_OFF.
*
* By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. In
* general, this makes sense because the device initialization function will
* resume and configure a device, leaving it operational. However, when power
* domains are enabled, the device may be connected to a switchable power
* source, in which case it won't be powered at boot. This function can
* therefore be used to notify the PM subsystem that the device is in
* #PM_DEVICE_STATE_OFF instead of the default.
*
* @param dev Device instance.
*/
static inline void pm_device_init_off(const struct device *dev)
{
struct pm_device *pm = dev->pm;
pm->state = PM_DEVICE_STATE_OFF;
}
/**
* @brief Mark a device as busy.
*
@ -484,6 +522,14 @@ bool pm_device_state_is_locked(const struct device *dev);
bool pm_device_on_power_domain(const struct device *dev);
#else
static inline void pm_device_init_suspended(const struct device *dev)
{
ARG_UNUSED(dev);
}
static inline void pm_device_init_off(const struct device *dev)
{
ARG_UNUSED(dev);
}
static inline void pm_device_busy_set(const struct device *dev)
{
ARG_UNUSED(dev);

View file

@ -37,7 +37,7 @@ extern "C" {
* @retval -ENOSYS If the functionality is not available.
* @retval -errno Other negative errno, result of suspending the device.
*
* @see pm_device_runtime_init_suspended()
* @see pm_device_init_suspended()
*/
int pm_device_runtime_enable(const struct device *dev);
@ -137,43 +137,6 @@ int pm_device_runtime_put_async(const struct device *dev);
*/
bool pm_device_runtime_is_enabled(const struct device *dev);
/**
* @brief Initialize a device state to #PM_DEVICE_STATE_SUSPENDED.
*
* By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. In
* general, this makes sense because the device initialization function will
* resume and configure a device, leaving it operational. However, when device
* runtime PM is enabled, the device may not be resumed and the init function
* will just enable device runtime PM. If that is the case, this function can be
* used to set the initial device state to #PM_DEVICE_STATE_SUSPENDED.
*
* @param dev Device instance.
*/
static inline void pm_device_runtime_init_suspended(const struct device *dev)
{
struct pm_device *pm = dev->pm;
pm->state = PM_DEVICE_STATE_SUSPENDED;
}
/**
* @brief Initialize a device state to #PM_DEVICE_STATE_OFF.
*
* By default device state is initialized to #PM_DEVICE_STATE_ACTIVE. In
* general, this makes sense because the device initialization function will
* resume and configure a device, leaving it operational. However, when device
* runtime PM is enabled, the device may be connected to a power domain, at
* which case it won't be powered at boot.
*
* @param dev Device instance.
*/
static inline void pm_device_runtime_init_off(const struct device *dev)
{
struct pm_device *pm = dev->pm;
pm->state = PM_DEVICE_STATE_OFF;
}
#else
static inline int pm_device_runtime_enable(const struct device *dev) { return -ENOSYS; }
static inline int pm_device_runtime_disable(const struct device *dev) { return -ENOSYS; }
@ -181,8 +144,6 @@ static inline int pm_device_runtime_get(const struct device *dev) { return 0; }
static inline int pm_device_runtime_put(const struct device *dev) { return 0; }
static inline int pm_device_runtime_put_async(const struct device *dev) { return 0; }
static inline bool pm_device_runtime_is_enabled(const struct device *dev) { return false; }
static inline void pm_device_runtime_init_suspended(const struct device *dev) { }
static inline void pm_device_runtime_init_off(const struct device *dev) { }
#endif
/** @} */

View file

@ -123,9 +123,9 @@ static void test_power_domain_device_runtime(void)
deva = DEVICE_DT_GET(TEST_DEVA);
devb = DEVICE_DT_GET(TEST_DEVB);
pm_device_runtime_init_suspended(domain);
pm_device_runtime_init_suspended(deva);
pm_device_runtime_init_suspended(devb);
pm_device_init_suspended(domain);
pm_device_init_suspended(deva);
pm_device_init_suspended(devb);
pm_device_runtime_enable(domain);
pm_device_runtime_enable(deva);