[src/trunk]: src/sys/netipsec Update the locking notes

[ozaki-r <ozaki-r%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/05c95b2faa0a
branches:  trunk
changeset: 825929:05c95b2faa0a
user:      ozaki-r <ozaki-r%NetBSD.org@localhost>
date:      Mon Aug 07 03:28:31 2017 +0000

description:
Update the locking notes

- Add locking order
- Add locking notes for misc lists such as reglist
- Mention pserialize, key_sp_ref and key_sp_unref on SP operations

Requested by riastradh@

diffstat:

 sys/netipsec/key.c |  26 +++++++++++++++++++-------
 1 files changed, 19 insertions(+), 7 deletions(-)

diffs (66 lines):

diff -r b365501879c0 -r 05c95b2faa0a sys/netipsec/key.c
--- a/sys/netipsec/key.c        Mon Aug 07 03:22:33 2017 +0000
+++ b/sys/netipsec/key.c        Mon Aug 07 03:28:31 2017 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: key.c,v 1.209 2017/08/07 03:22:33 ozaki-r Exp $        */
+/*     $NetBSD: key.c,v 1.210 2017/08/07 03:28:31 ozaki-r Exp $        */
 /*     $FreeBSD: src/sys/netipsec/key.c,v 1.3.2.3 2004/02/14 22:23:23 bms Exp $        */
 /*     $KAME: key.c,v 1.191 2001/06/27 10:46:49 sakane Exp $   */
 
@@ -32,7 +32,7 @@
  */
 
 #include <sys/cdefs.h>
-__KERNEL_RCSID(0, "$NetBSD: key.c,v 1.209 2017/08/07 03:22:33 ozaki-r Exp $");
+__KERNEL_RCSID(0, "$NetBSD: key.c,v 1.210 2017/08/07 03:28:31 ozaki-r Exp $");
 
 /*
  * This code is referd to RFC 2367
@@ -149,23 +149,30 @@
 static u_int32_t acq_seq = 0;
 
 /*
+ * Locking order: there is no order for now; it means that any locks aren't
+ * overlapped.
+ */
+/*
  * Locking notes on SPD:
  * - Modifications to the key_spd.splist must be done with holding key_spd.lock
  *   which is a adaptive mutex
- * - Read accesses to the key_spd.splist must be in critical sections of pserialize(9)
+ * - Read accesses to the key_spd.splist must be in critical sections of
+ *   pserialize(9)
  * - SP's lifetime is managed by localcount(9)
- * - An SP that has been inserted to the key_spd.splist is initially referenced by none,
- *   i.e., a reference from the key_spd.splist isn't counted
+ * - An SP that has been inserted to the key_spd.splist is initially referenced
+ *   by none, i.e., a reference from the key_spd.splist isn't counted
  * - When an SP is being destroyed, we change its state as DEAD, wait for
  *   references to the SP to be released, and then deallocate the SP
  *   (see key_unlink_sp)
  * - Getting an SP
- *   - Normally we get an SP from the key_spd.splist by incrementing the reference count
- *     of the SP
+ *   - Normally we get an SP from the key_spd.splist (see key_lookup_sp_byspidx)
+ *     - Must iterate the list and increment the reference count of a found SP
+ *       (by key_sp_ref) in a pserialize critical section
  *   - We can gain another reference from a held SP only if we check its state
  *     and take its reference in a critical section of pserialize
  *     (see esp_output for example)
  *   - We may get an SP from an SP cache. See below
+ *   - A gotten SP must be released after use by KEY_SP_UNREF (key_sp_unref)
  * - Updating member variables of an SP
  *   - Most member variables of an SP are immutable
  *   - Only sp->state and sp->lastused can be changed
@@ -191,6 +198,11 @@
  *     it directly instead we just mark it DEAD and delay the destruction
  *     until GC by the timer
  */
+/*
+ * Locking notes on misc data:
+ * - All lists of key_misc are protected by key_misc.lock
+ *   - key_misc.lock must be held even for read accesses
+ */
 
 static pserialize_t key_psz;