[RFC][PATCH 1/5] signal: Document signal locking rules

[Matt Fleming <matt@console-pimps.org>]

From: Matt Fleming <matt.fleming@intel.com>

The current locking rules for signal handling and job control are
complex and pretty much undocumented. Fix that by explaining which
data structures are involved. At the moment, all the necessary locking
is covered by the per-process sighand->siglock but patches later in
the series will change that.

Cc: Tejun Heo <tj@kernel.org>
Cc: Oleg Nesterov <oleg@redhat.com>
Cc: Peter Zijlstra <a.p.zijlstra@chello.nl>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Anirudh Badam <abadam@cs.princeton.edu>
Signed-off-by: Matt Fleming <matt.fleming@intel.com>
---
 kernel/signal.c |   27 +++++++++++++++++++++++++++
 1 files changed, 27 insertions(+), 0 deletions(-)

diff --git a/kernel/signal.c b/kernel/signal.c
index 3868e66..54fc552 100644
--- a/kernel/signal.c
+++ b/kernel/signal.c
@@ -38,6 +38,33 @@
 #include "audit.h"	/* audit_signal_info() */
 
 /*
+ * signal locking rules:
+ *
+ *   - sighand->siglock (spinlock) protects,
+ *
+ *        * the tsk->sighand pointer from being modified, see de_thread() and
+ *          __exit_signal(). If you need to dereference tsk->sighand (for
+ *          example when locking ->siglock) and tsk is not current, you must
+ *          call lock_task_sighand().
+ *
+ *        * most things under tsk->signal
+ *
+ *        * tsk->sighand->action[]
+ *
+ *        * tsk->last_siginfo
+ *        * tsk->group_stop
+ *        * tsk->pending
+ *        * tsk->jobctl
+ *
+ *        * the atomic operation of checking tsk->jobctl, tsk->pending and
+ *          tsk->signal->shared_pending and setting/clearing TIF_SIGPENDING,
+ *          see recalc_sigpending().
+ *
+ *        * tsk->cpu_timers
+ *
+ */
+
+/*
  * SLAB caches for signal bits.
  */
 
-- 
1.7.4.4