pm: device_runtime: Change API behavior s/_sync/_async

Most APIs have the default synchronous and an asynchronous version
with the sufix _async because that is the most common use.

All devices in tree right now are using the synchronous version, so
just change it to be consistent with the rest of the system.

Signed-off-by: Flavio Ceolin <[email protected]>

Author: Flavio Ceolin

doc/reference/power_management/index.rst

@@ -440,7 +440,7 @@ Resume Device asynchronously API
 
 .. code-block:: c
 
-   int pm_device_get(const struct device *dev);
+   int pm_device_get_async(const struct device *dev);
 
 Marks the device as being used. This API will asynchronously
 bring the device to resume state if it was suspended. If the device
@@ -455,7 +455,7 @@ Resume Device synchronously API
 
 .. code-block:: c
 
-   int pm_device_get_sync(const struct device *dev);
+   int pm_device_get(const struct device *dev);
 
 Marks the device as being used. It will bring up or resume
 the device if it is in suspended state based on the device
@@ -467,7 +467,7 @@ Suspend Device asynchronously API
 
 .. code-block:: c
 
-   int pm_device_put(const struct device *dev);
+   int pm_device_put_async(const struct device *dev);
 
 Releases a device. This API asynchronously puts the device to suspend
 state if not already in suspend state if the usage count of this device
@@ -481,7 +481,7 @@ Suspend Device synchronously API
 
 .. code-block:: c
 
-   int pm_device_put_sync(const struct device *dev);
+   int pm_device_put(const struct device *dev);
 
 Marks the device as being released. It will put the device to
 suspended state if is is in active state based on the device

drivers/gpio/gpio_stm32.c

@@ -467,7 +467,7 @@ static int gpio_stm32_config(const struct device *dev,
 #ifdef CONFIG_PM_DEVICE_RUNTIME
 	/* Enable device clock before configuration (requires bank writes) */
 	if (data->power_state != PM_DEVICE_STATE_ACTIVE) {
-		err = pm_device_get_sync(dev);
+		err = pm_device_get(dev);
 		if (err < 0) {
 			return err;
 		}
@@ -488,7 +488,7 @@ static int gpio_stm32_config(const struct device *dev,
 #ifdef CONFIG_PM_DEVICE_RUNTIME
 	/* Release clock only if configuration doesn't require bank writes */
 	if ((flags & GPIO_OUTPUT) == 0) {
-		err = pm_device_put(dev);
+		err = pm_device_put_async(dev);
 		if (err < 0) {
 			return err;
 		}

drivers/pinmux/stm32/pinmux_stm32.c

@@ -129,7 +129,7 @@ int stm32_dt_pinctrl_configure(const struct soc_gpio_pinctrl *pinctrl,
 		port_device = gpio_ports[STM32_PORT(pin)];
 
 #ifdef CONFIG_PM_DEVICE_RUNTIME
-		ret = pm_device_get_sync(port_device);
+		ret = pm_device_get(port_device);
 #else
 		ret = gpio_stm32_clock_request(port_device, true);
 		/* Note, we don't use pm_constraint_foo functions here */

include/pm/device_runtime.h

@@ -68,7 +68,7 @@ void pm_device_disable(const struct device *dev);
  * pm signal mechanism to know the completion of resume operation.
  * @retval Errno Negative errno code if failure.
  */
-int pm_device_get(const struct device *dev);
+int pm_device_get_async(const struct device *dev);
 
 /**
  * @brief Call device resume synchronously based on usage count
@@ -83,7 +83,7 @@ int pm_device_get(const struct device *dev);
  * @retval 0 If successful.
  * @retval Errno Negative errno code if failure.
  */
-int pm_device_get_sync(const struct device *dev);
+int pm_device_get(const struct device *dev);
 
 /**
  * @brief Call device suspend asynchronously based on usage count
@@ -101,7 +101,7 @@ int pm_device_get_sync(const struct device *dev);
  * signal mechanism to know the completion of suspend operation.
  * @retval Errno Negative errno code if failure.
  */
-int pm_device_put(const struct device *dev);
+int pm_device_put_async(const struct device *dev);
 
 /**
  * @brief Call device suspend synchronously based on usage count
@@ -116,14 +116,14 @@ int pm_device_put(const struct device *dev);
  * @retval 0 If successful.
  * @retval Errno Negative errno code if failure.
  */
-int pm_device_put_sync(const struct device *dev);
+int pm_device_put(const struct device *dev);
 
 /**
  * @brief Wait on a device to finish an operation.
  *
- * The calling thread blocks until the device finishes a @ref pm_device_put or
- * @ref pm_device_get operation. If there is no operation in progress
- * this function will return immediately.
+ * The calling thread blocks until the device finishes a
+ * @ref pm_device_put_async or @ref pm_device_get_async operation. If there is
+ * no operation in progress this function will return immediately.
  *
  * @param dev Pointer to device structure of the specific device driver
  * the caller is interested in.
@@ -138,9 +138,9 @@ int pm_device_wait(const struct device *dev, k_timeout_t timeout);
 static inline void pm_device_enable(const struct device *dev) { }
 static inline void pm_device_disable(const struct device *dev) { }
 static inline int pm_device_get(const struct device *dev) { return -ENOSYS; }
-static inline int pm_device_get_sync(const struct device *dev) { return -ENOSYS; }
+static inline int pm_device_get_async(const struct device *dev) { return -ENOSYS; }
 static inline int pm_device_put(const struct device *dev) { return -ENOSYS; }
-static inline int pm_device_put_sync(const struct device *dev) { return -ENOSYS; }
+static inline int pm_device_put_async(const struct device *dev) { return -ENOSYS; }
 static inline int pm_device_wait(const struct device *dev,
 		k_timeout_t timeout) { return -ENOSYS; }
 #endif

samples/subsys/pm/device_pm/src/dummy_driver.c

@@ -19,12 +19,12 @@ static int dummy_open(const struct device *dev)
 	printk("open()\n");
 
 	/* Make sure parent is resumed */
-	ret = pm_device_get_sync(parent);
+	ret = pm_device_get(parent);
 	if (ret < 0) {
 		return ret;
 	}
 
-	ret = pm_device_get(dev);
+	ret = pm_device_get_async(dev);
 	if (ret < 0) {
 		return ret;
 	}
@@ -72,14 +72,14 @@ static int dummy_close(const struct device *dev)
 	int ret;
 
 	printk("close()\n");
-	ret = pm_device_put_sync(dev);
+	ret = pm_device_put(dev);
 	if (ret == 1) {
 		printk("Async suspend request ququed\n");
 	}
 
 	/* Parent can be suspended */
 	if (parent) {
-		pm_device_put_sync(parent);
+		pm_device_put(parent);
 	}
 
 	return ret;

subsys/pm/device_runtime.c

@@ -178,24 +178,22 @@ static int pm_device_request(const struct device *dev,
 
 int pm_device_get(const struct device *dev)
 {
-	return pm_device_request(dev,
-			PM_DEVICE_STATE_ACTIVE, PM_DEVICE_ASYNC);
+	return pm_device_request(dev, PM_DEVICE_STATE_ACTIVE, 0);
 }
 
-int pm_device_get_sync(const struct device *dev)
+int pm_device_get_async(const struct device *dev)
 {
-	return pm_device_request(dev, PM_DEVICE_STATE_ACTIVE, 0);
+	return pm_device_request(dev, PM_DEVICE_STATE_ACTIVE, PM_DEVICE_ASYNC);
 }
 
 int pm_device_put(const struct device *dev)
 {
-	return pm_device_request(dev,
-			PM_DEVICE_STATE_SUSPEND, PM_DEVICE_ASYNC);
+	return pm_device_request(dev, PM_DEVICE_STATE_SUSPEND, 0);
 }
 
-int pm_device_put_sync(const struct device *dev)
+int pm_device_put_async(const struct device *dev)
 {
-	return pm_device_request(dev, PM_DEVICE_STATE_SUSPEND, 0);
+	return pm_device_request(dev, PM_DEVICE_STATE_SUSPEND, PM_DEVICE_ASYNC);
 }
 
 void pm_device_enable(const struct device *dev)

tests/subsys/pm/device_runtime/src/dummy_driver.c

@@ -18,22 +18,22 @@ static int dummy_wait(const struct device *dev)
 
 static int dummy_open(const struct device *dev)
 {
-	return pm_device_get(dev);
+	return pm_device_get_async(dev);
 }
 
 static int dummy_open_sync(const struct device *dev)
 {
-	return pm_device_get_sync(dev);
+	return pm_device_get(dev);
 }
 
 static int dummy_close(const struct device *dev)
 {
-	return pm_device_put(dev);
+	return pm_device_put_async(dev);
 }
 
 static int dummy_close_sync(const struct device *dev)
 {
-	return pm_device_put_sync(dev);
+	return pm_device_put(dev);
 }
 
 static uint32_t dummy_get_power_state(const struct device *dev)

tests/subsys/pm/device_runtime/src/main.c

@@ -94,7 +94,7 @@ void threadB_func(void *arg1, void *arg2, void *arg3)
  *    in favor of threadA. At this point the device should reflect these
  *    operations and be suspended.
  *
- * @see pm_device_get(), pm_device_put()
+ * @see pm_device_get_async(), pm_device_put_async()
  *
  * @ingroup power_tests
  */
@@ -144,7 +144,7 @@ void test_teardown(void)
  * @details
  *  - Just bring up and put down the device using the synchronous API.
  *
- * @see pm_device_get_sync(), pm_device_put_sync()
+ * @see pm_device_get_async(), pm_device_put()
  *
  * @ingroup power_tests
  */

tests/subsys/pm/power_mgmt/src/dummy_driver.c

@@ -13,12 +13,12 @@ static uint32_t device_power_state;
 
 static int dummy_open(const struct device *dev)
 {
-	return pm_device_get_sync(dev);
+	return pm_device_get(dev);
 }
 
 static int dummy_close(const struct device *dev)
 {
-	return pm_device_put_sync(dev);
+	return pm_device_put(dev);
 }
 
 static uint32_t dummy_get_power_state(const struct device *dev)

tests/subsys/pm/power_mgmt/src/main.c

@@ -165,12 +165,12 @@ void test_power_state_trans(void)
  * @brief notification between system and device
  *
  * @details
- *  - device driver notify its power state change by pm_device_get and
- *    pm_device_put
+ *  - device driver notify its power state change by pm_device_get_async and
+ *    pm_device_put_async
  *  - system inform device system power state change through device interface
  *    pm_control
  *
- * @see pm_device_get(), pm_device_put(), pm_device_state_set(),
+ * @see pm_device_get_async(), pm_device_put_async(), pm_device_state_set(),
  *      pm_device_state_get()
  *
  * @ingroup power_tests