device_pm: Update control function name and doc to indicate PM specific

PM control function is used only by the PM subsystem. Update
documentations to make it clear and name the relevant structures and
functions with _pm_ in the name.

Jira: ZEP-1044
Change-Id: I29e5b7690db34a228ed30a24a2e912e1360a0090
Signed-off-by: Ramesh Thomas <ramesh.thomas@intel.com>

3 files changed, 31 insertions, 18 deletions

diff --git a/include/device.h b/include/device.h
index ff0abd915..1870b820a 100644
--- a/include/device.h
+++ b/include/device.h
@@ -126,7 +126,7 @@ extern "C" {
 	DEVICE_AND_API_INIT(dev_name, drv_name, init_fn, data, cfg_info, \
 			    level, prio, api)
 
-#define DEVICE_DEFINE(dev_name, drv_name, init_fn, control_fn, \
+#define DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_control_fn, \
 		      data, cfg_info, level, prio, api) \
 	DEVICE_AND_API_INIT(dev_name, drv_name, init_fn, data, cfg_info, \
 			    level, prio, api)
@@ -180,21 +180,20 @@ extern "C" {
 * @def DEVICE_DEFINE
 *
 * @brief Create device object and set it up for boot time initialization,
-* with the option to device_control.
+* with the option to device_pm_control.
 *
 * @copydetails DEVICE_AND_API_INIT
-* @param control_fn Provides an initial pointer to the API function
-* used by App to send control command to the driver.
-* Can be empty function (device_control_nop) for not implementing.
+* @param pm_control_fn Pointer to device_pm_control function.
+* Can be empty function (device_pm_control_nop) if not implemented.
 */
 extern struct device_pm_ops device_pm_ops_nop;
-#define DEVICE_DEFINE(dev_name, drv_name, init_fn, control_fn, \
+#define DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_control_fn, \
 		      data, cfg_info, level, prio, api) \
 	\
 	static struct device_config _CONCAT(__config_, dev_name) __used \
 	__attribute__((__section__(".devconfig.init"))) = { \
 		.name = drv_name, .init = (init_fn), \
-		.device_control = (control_fn), \
+		.device_pm_control = (pm_control_fn), \
 		.dev_pm_ops = (&device_pm_ops_nop), \
 		.config_info = (cfg_info) \
 	}; \
@@ -206,14 +205,14 @@ extern struct device_pm_ops device_pm_ops_nop;
 		 .driver_data = data \
 	}
 /*
- * Use the default device_control for devices that do not call the
+ * Use the default device_pm_control for devices that do not call the
  * DEVICE_DEFINE macro so that caller of hook functions
- * need not check device_control != NULL.
+ * need not check device_pm_control != NULL.
  */
 #define DEVICE_AND_API_INIT(dev_name, drv_name, init_fn, data, cfg_info, \
 			    level, prio, api) \
 	DEVICE_DEFINE(dev_name, drv_name, init_fn, \
-		      device_control_nop, data, cfg_info, level, \
+		      device_pm_control_nop, data, cfg_info, level, \
 		      prio, api)
 #endif
 
@@ -386,7 +385,7 @@ struct device_config {
 	int (*init)(struct device *device);
 #ifdef CONFIG_DEVICE_POWER_MANAGEMENT
 	struct device_pm_ops *dev_pm_ops; /* deprecated */
-	int (*device_control)(struct device *device, uint32_t command,
+	int (*device_pm_control)(struct device *device, uint32_t command,
 			      void *context);
 #endif
 	const void *config_info;
@@ -516,7 +515,7 @@ static inline int __deprecated device_resume(struct device *device,
  * @brief No-op function to initialize unimplemented hook
  *
  * This function should be used to initialize device hook
- * for which a device has no operation.
+ * for which a device has no PM operations.
  *
  * @param unused_device Unused
  * @param unused_ctrl_command Unused
@@ -524,7 +523,7 @@ static inline int __deprecated device_resume(struct device *device,
  *
  * @retval 0 Always returns 0
  */
-int device_control_nop(struct device *unused_device,
+int device_pm_control_nop(struct device *unused_device,
 		       uint32_t unused_ctrl_command, void *unused_context);
 /**
  * @brief Call the set power state function of a device
@@ -541,7 +540,7 @@ int device_control_nop(struct device *unused_device,
 static inline int device_set_power_state(struct device *device,
 					 uint32_t device_power_state)
 {
-	return device->config->device_control(device,
+	return device->config->device_pm_control(device,
 			DEVICE_PM_SET_POWER_STATE, &device_power_state);
 }
 
@@ -561,7 +560,7 @@ static inline int device_set_power_state(struct device *device,
 static inline int device_get_power_state(struct device *device,
 					 uint32_t *device_power_state)
 {
-	return device->config->device_control(device,
+	return device->config->device_pm_control(device,
 				DEVICE_PM_GET_POWER_STATE, device_power_state);
 }
 
diff --git a/include/drivers/system_timer.h b/include/drivers/system_timer.h
index b63bf7478..279a505be 100644
--- a/include/drivers/system_timer.h
+++ b/include/drivers/system_timer.h
@@ -70,7 +70,7 @@ extern int sys_clock_device_ctrl(struct device *device,
  * the app enables CONFIG_DEVICE_POWER_MANAGEMENT.
  */
 #ifndef CONFIG_LOAPIC_TIMER
-#define sys_clock_device_ctrl device_control_nop
+#define sys_clock_device_ctrl device_pm_control_nop
 #endif
 
 extern int32_t _sys_idle_elapsed_ticks;
diff --git a/include/init.h b/include/init.h
index 1274e4378..405bb1a46 100644
--- a/include/init.h
+++ b/include/init.h
@@ -63,6 +63,9 @@ extern "C" {
 /**
  * @def SYS_INIT_PM
  *
+ * @warning This macro is deprecated and will be removed in
+ *        a future version, superseded by SYS_DEVICE_DEFINE.
+ *
  * @brief Run an initialization function at boot at specified priority,
  * and define functions to run at suspend/resume.
  *
@@ -80,8 +83,19 @@ extern "C" {
 	DEVICE_INIT(_SYS_NAME(init_fn), "", init_fn, NULL, NULL, level, prio)
 #endif
 
-#define SYS_DEVICE_DEFINE(drv_name, init_fn, control_fn, level, prio) \
-	DEVICE_DEFINE(_SYS_NAME(init_fn), drv_name, init_fn, control_fn, \
+/**
+ * @def SYS_DEVICE_DEFINE
+ *
+ * @brief Run an initialization function at boot at specified priority,
+ * and define device PM control function.
+ *
+ * @copydetails SYS_INIT
+ * @param pm_control_fn Pointer to device_pm_control function.
+ * Can be empty function (device_pm_control_nop) if not implemented.
+ * @param drv_name Name of this system device
+ */
+#define SYS_DEVICE_DEFINE(drv_name, init_fn, pm_control_fn, level, prio) \
+	DEVICE_DEFINE(_SYS_NAME(init_fn), drv_name, init_fn, pm_control_fn, \
 		      NULL, NULL, level, prio, NULL)
 
 #ifdef __cplusplus