[PATCH 1/3] sched: document that show_stack() should not be passed a NULL task

[Mark Rutland]

As noted in commit:

  81539169f283329f ("x86/dumpstack: Remove NULL task pointer convention")

... having a NULL task parameter imply current leads to subtle bugs in stack
walking code (so far seen on both 86 and arm64), makes callsites harder to
read, and is unnecessary as all callers have access to current.

As a step towards removing the problematic NULL-implies-current idiom entirely,
document that new code should pass current explicitly.

Signed-off-by: Mark Rutland <mark.rutland@xxxxxxx>
Cc: Ingo Molnar <mingo@xxxxxxxxxx>
Cc: Josh Poimboeuf <jpoimboe@xxxxxxxxxx>
Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx>
Cc: linux-kernel@xxxxxxxxxxxxxxx
---
 include/linux/sched.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/linux/sched.h b/include/linux/sched.h
index abb795a..4bc5571 100644
--- a/include/linux/sched.h
+++ b/include/linux/sched.h
@@ -367,6 +367,9 @@ extern void show_regs(struct pt_regs *);
  * TASK is a pointer to the task whose backtrace we want to see (or NULL for current
  * task), SP is the stack pointer of the first frame that should be shown in the back
  * trace (or NULL if the entire call-chain of the task should be shown).
+ *
+ * Note: passing a NULL task is deprecated, and new code should pass current
+ * explicitly.
  */
 extern void show_stack(struct task_struct *task, unsigned long *sp);
 
-- 
2.7.4