cpuidle: Add comments about noinstr/__cpuidle usage

Add a few words on noinstr / __cpuidle usage.

Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Link: https://lore.kernel.org/r/20230112195542.397238052@infradead.org

diff --git a/drivers/cpuidle/cpuidle.c b/drivers/cpuidle/cpuidle.c
index 73f7d8b763c6c7469638aa5f61da07441bf07c3d..500d1720421eaa5706dbd4fc5324ce1ca619e95b 100644 (file)
--- a/drivers/cpuidle/cpuidle.c
+++ b/drivers/cpuidle/cpuidle.c
@@ -252,6 +252,18 @@ noinstr int cpuidle_enter_state(struct cpuidle_device *dev,
                instrumentation_begin();
        }
 
+       /*
+        * NOTE!!
+        *
+        * For cpuidle_state::enter() methods that do *NOT* set
+        * CPUIDLE_FLAG_RCU_IDLE RCU will be disabled here and these functions
+        * must be marked either noinstr or __cpuidle.
+        *
+        * For cpuidle_state::enter() methods that *DO* set
+        * CPUIDLE_FLAG_RCU_IDLE this isn't required, but they must mark the
+        * function calling ct_cpuidle_enter() as noinstr/__cpuidle and all
+        * functions called within the RCU-idle region.
+        */
        entered_state = target_state->enter(dev, drv, index);
 
        if (WARN_ONCE(!irqs_disabled(), "%ps leaked IRQ state", target_state->enter))

diff --git a/include/linux/compiler_types.h b/include/linux/compiler_types.h
index d7858901f03550c3411fb57c452554ee900b17a6..dea5bf5bd09c4dcf650effe0c6e3d71d8a2b63a4 100644 (file)
--- a/include/linux/compiler_types.h
+++ b/include/linux/compiler_types.h
@@ -239,6 +239,16 @@ struct ftrace_likely_data {
 
 #define noinstr __noinstr_section(".noinstr.text")
 
+/*
+ * The __cpuidle section is used twofold:
+ *
+ *  1) the original use -- identifying if a CPU is 'stuck' in idle state based
+ *     on it's instruction pointer. See cpu_in_idle().
+ *
+ *  2) supressing instrumentation around where cpuidle disables RCU; where the
+ *     function isn't strictly required for #1, this is interchangeable with
+ *     noinstr.
+ */
 #define __cpuidle __noinstr_section(".cpuidle.text")
 
 #endif /* __KERNEL__ */