init: Split LK_INIT_FLAG_CPU_SUSPEND/RESUME

Split LK_INIT_FLAG_CPU_SUSPEND and LK_INIT_FLAG_CPU_RESUME into
LK_INIT_FLAG_CPU_ENTER_IDLE/LK_INIT_FLAG_CPU_OFF and
LK_INIT_FLAG_CPU_EXIT_IDLE/LK_INIT_FLAG_CPU_ON.

Change-Id: I894ea945c31a17f0ab4b62c44a27203067b2f700

top/include/lk/init.h

@@ -36,12 +36,73 @@ enum lk_init_level {
     LK_INIT_LEVEL_LAST = UINT16_MAX,
 };
 
+/**
+ * enum lk_init_flags - Flags specifying init hook type.
+ *
+ * Flags passed to LK_INIT_HOOK_FLAGS to specify when the hook should be called.
+ */
 enum lk_init_flags {
+    /**
+     * @LK_INIT_FLAG_PRIMARY_CPU: Call init hook when booting primary CPU.
+     */
     LK_INIT_FLAG_PRIMARY_CPU     = 0x1,
+
+    /**
+     * @LK_INIT_FLAG_SECONDARY_CPUS: Call init hook when booting secondary CPUs.
+     */
     LK_INIT_FLAG_SECONDARY_CPUS  = 0x2,
+
+    /**
+     * @LK_INIT_FLAG_ALL_CPUS: Call init hook when booting any CPU.
+     */
     LK_INIT_FLAG_ALL_CPUS        = LK_INIT_FLAG_PRIMARY_CPU | LK_INIT_FLAG_SECONDARY_CPUS,
-    LK_INIT_FLAG_CPU_SUSPEND     = 0x4,
-    LK_INIT_FLAG_CPU_RESUME      = 0x8,
+
+    /**
+     * @LK_INIT_FLAG_CPU_ENTER_IDLE: Call init hook before a CPU enters idle.
+     *
+     * The CPU may lose state after this, but it should respond to interrupts.
+     */
+    LK_INIT_FLAG_CPU_ENTER_IDLE  = 0x4,
+
+    /**
+     * @LK_INIT_FLAG_CPU_OFF: Call init hook before a CPU goes offline.
+     *
+     * The CPU may lose state after this, and it should not respond to
+     * interrupts.
+     */
+    LK_INIT_FLAG_CPU_OFF         = 0x8,
+
+    /**
+     * @LK_INIT_FLAG_CPU_SUSPEND: Call init hook before a CPU loses state.
+     *
+     * Alias to call hook for both LK_INIT_FLAG_CPU_ENTER_IDLE and
+     * LK_INIT_FLAG_CPU_OFF events.
+     */
+    LK_INIT_FLAG_CPU_SUSPEND     = LK_INIT_FLAG_CPU_ENTER_IDLE | LK_INIT_FLAG_CPU_OFF,
+
+    /**
+     * @LK_INIT_FLAG_CPU_EXIT_IDLE: Call init hook after a CPU exits idle.
+     *
+     * LK_INIT_FLAG_CPU_ENTER_IDLE should have been called before this.
+     */
+    LK_INIT_FLAG_CPU_EXIT_IDLE   = 0x10,
+
+    /**
+     * @LK_INIT_FLAG_CPU_ON: Call init hook after a CPU turns on.
+     *
+     * LK_INIT_FLAG_CPU_OFF should have been called before this. The first time
+     * a CPU turns on LK_INIT_FLAG_PRIMARY_CPU or LK_INIT_FLAG_SECONDARY_CPUS
+     * is called instead of this.
+     */
+    LK_INIT_FLAG_CPU_ON          = 0x20,
+
+    /**
+     * @LK_INIT_FLAG_CPU_RESUME: Call init hook after a CPU exits idle.
+     *
+     * Alias to call hook for both LK_INIT_FLAG_CPU_EXIT_IDLE and
+     * LK_INIT_FLAG_CPU_ON events.
+     */
+    LK_INIT_FLAG_CPU_RESUME      = LK_INIT_FLAG_CPU_EXIT_IDLE | LK_INIT_FLAG_CPU_ON,
 };
 
 // Run init hooks between start_level (inclusive) and stop_level (exclusive) that match the required_flags.