pm: add type for device PM control callback

Add a type and documentation for the device PM control callback. This
way possible return codes and its meaning are documented.

Signed-off-by: Gerard Marull-Paretas <[email protected]>

Author: gmarull

include/device.h

@@ -384,8 +384,7 @@ struct device {
 	const device_handle_t *const handles;
 #ifdef CONFIG_PM_DEVICE
 	/** Power Management function */
-	int (*pm_control)(const struct device *dev,
-			  enum pm_device_state state);
+	pm_device_control_callback_t pm_control;
 	/** Pointer to device instance power management data */
 	struct pm_device * const pm;
 #endif

include/pm/device.h

@@ -93,6 +93,19 @@ struct pm_device {
 	struct k_condvar condvar;
 };
 
+/**
+ * @brief Device power management control function callback.
+ *
+ * @param dev Device instance.
+ * @param state Requested state.
+ *
+ * @retval 0 If successful.
+ * @retval -ENOTSUP If the requested state is not supported.
+ * @retval Errno Other negative errno on failure.
+ */
+typedef int (*pm_device_control_callback_t)(const struct device *dev,
+					    enum pm_device_state state);
+
 /**
  * @brief Get name of device PM state
  *