document/pm: update document for pm_idle smp case

Signed-off-by: buxiasen <buxiasen@xiaomi.com>

Documentation/components/drivers/special/power/pm/index.rst

@@ -229,24 +229,61 @@ All PM interfaces are declared in the file ``include/nuttx/power/pm.h``.
 
   :param handler: The execution after PM_IDLE_DOMAIN state changed
 
+.. c:function:: void pm_idle_unlock(void)
+
+  This function provide assist of smp pm idle work progress, for pm sequence
+  other cores will not release before the core hold cpus lock.
+  Call this function to release SMP idle cpus lock.
+
+.. c:function:: bool pm_idle_lock(int cpu)
+
+  This function provide assist of smp pm idle work progress, for pm sequence
+  other cores will not release before the core hold cpus lock.
+  Call this function to ensure other core will not run until released.
+
+  :param cpu: The current CPU, used to update cpu_set_t
+
   :return:
-     None
+    true, Current CPU is the first one woken from sleep, should handle system domain restore process also.
+    false, Current CPU is not the first one woken from sleep, should only handle cpu domain restore process.
+
+  **Assumptions:** Restore operation pm_changestate(, PM_RESTORE) will done
+  inside pm_idle. Handler don't have to care about it.
 
 Callbacks
 =========
 
-.. c:typedef::pm_idle_handler_t
+.. c:type:: pm_idle_handler_t
 
   This type declare is provide for pm_idle interface.
-  Handle the pm low power action and execution for not SMP case.
+  Handle the pm low power action and execution.
   Possible execution for long time because of WFI inside.
 
+  - for not SMP case.
+
   .. code-block:: c
 
-    typedef void (*pm_idle_handler_t)(enum pm_state_e);
+    typedef void (*pm_idle_handler_t)(enum pm_state_e systemstate);
 
-    :param pm_state_e:
-       Indicate the new system power state.
+  :param systemstate:
+      Indicate the new system power state.
+
+  - for SMP case.
+
+  .. code-block:: c
+
+    typedef bool (*pm_idle_handler_t)(int cpu,
+                                      enum pm_state_e cpustate,
+                                      enum pm_state_e systemstate);
+
+  :param cpu:
+      Indicate the current working cpu.
+  :param cpustate:
+      Indicate the current cpu power state.
+  :param systemstate:
+      Indicate the new system power state. If not the lastcore enter idle,
+      systemstate always PM_RESTORE. If not PM_RESTORE, handler should
+      cover system pm operations.
 
 .. c:struct:: pm_callback_s