From 673662ef9455e8e538b3dfb8315866d9a6851f56 Mon Sep 17 00:00:00 2001
From: yamt <yamt@NetBSD.org>
Date: Wed, 18 Apr 2012 13:42:11 +0000
Subject: [PATCH] comment

---
 sys/kern/kern_synch.c |  8 ++++++--
 sys/kern/subr_pcu.c   | 31 +++++++++++++++++++++++++------
 sys/sys/pcu.h         | 16 +++++++++++++++-
 3 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/sys/kern/kern_synch.c b/sys/kern/kern_synch.c
index e50d17cd679d..cb0915c366de 100644
--- a/sys/kern/kern_synch.c
+++ b/sys/kern/kern_synch.c
@@ -1,4 +1,4 @@
-/*	$NetBSD: kern_synch.c,v 1.299 2012/03/03 00:22:24 matt Exp $	*/
+/*	$NetBSD: kern_synch.c,v 1.300 2012/04/18 13:44:19 yamt Exp $	*/
 
 /*-
  * Copyright (c) 1999, 2000, 2004, 2006, 2007, 2008, 2009
@@ -69,7 +69,7 @@
  */
 
 #include <sys/cdefs.h>
-__KERNEL_RCSID(0, "$NetBSD: kern_synch.c,v 1.299 2012/03/03 00:22:24 matt Exp $");
+__KERNEL_RCSID(0, "$NetBSD: kern_synch.c,v 1.300 2012/04/18 13:44:19 yamt Exp $");
 
 #include "opt_kstack.h"
 #include "opt_perfctrs.h"
@@ -755,6 +755,10 @@ mi_switch(lwp_t *l)
 
 		KASSERT(l->l_cpu == ci);
 		splx(oldspl);
+		/*
+		 * note that, unless the caller disabled preemption,
+		 * we can be preempted at any time after the above splx() call.
+		 */
 		retval = 1;
 	} else {
 		/* Nothing to do - just unlock and return. */
diff --git a/sys/kern/subr_pcu.c b/sys/kern/subr_pcu.c
index 9a8f62a53701..2431c5eab4bb 100644
--- a/sys/kern/subr_pcu.c
+++ b/sys/kern/subr_pcu.c
@@ -1,4 +1,4 @@
-/*	$NetBSD: subr_pcu.c,v 1.10 2011/09/27 01:02:39 jym Exp $	*/
+/*	$NetBSD: subr_pcu.c,v 1.11 2012/04/18 13:43:13 yamt Exp $	*/
 
 /*-
  * Copyright (c) 2011 The NetBSD Foundation, Inc.
@@ -57,7 +57,7 @@
  */
 
 #include <sys/cdefs.h>
-__KERNEL_RCSID(0, "$NetBSD: subr_pcu.c,v 1.10 2011/09/27 01:02:39 jym Exp $");
+__KERNEL_RCSID(0, "$NetBSD: subr_pcu.c,v 1.11 2012/04/18 13:43:13 yamt Exp $");
 
 #include <sys/param.h>
 #include <sys/cpu.h>
@@ -75,6 +75,13 @@ static void pcu_lwp_op(const pcu_ops_t *, lwp_t *, int);
 /* XXX */
 extern const pcu_ops_t * const	pcu_ops_md_defs[];
 
+/*
+ * pcu_switchpoint: release PCU state if the LWP is being run on another CPU.
+ *
+ * On each context switches, called by mi_switch() with IPL_SCHED.
+ * 'l' is an LWP which is just we switched to.  (the new curlwp)
+ */
+
 void
 pcu_switchpoint(lwp_t *l)
 {
@@ -88,6 +95,7 @@ pcu_switchpoint(lwp_t *l)
 		/* PCUs are not in use. */
 		return;
 	}
+	/* commented out as we know we are already at IPL_SCHED */
 	/* s = splsoftclock(); */
 	for (id = 0; id < PCU_UNIT_COUNT; id++) {
 		if ((pcu_inuse & (1 << id)) == 0) {
@@ -103,6 +111,12 @@ pcu_switchpoint(lwp_t *l)
 	/* splx(s); */
 }
 
+/*
+ * pcu_discard_all: discard PCU state of the given LWP.
+ *
+ * Used by exec and LWP exit.
+ */
+
 void
 pcu_discard_all(lwp_t *l)
 {
@@ -133,10 +147,19 @@ pcu_discard_all(lwp_t *l)
 	splx(s);
 }
 
+/*
+ * pcu_save_all: save PCU state of the given LWP so that eg. coredump can
+ * examine it.
+ */
+
 void
 pcu_save_all(lwp_t *l)
 {
 	const uint32_t pcu_inuse = l->l_pcu_used;
+	/*
+	 * Unless LW_WCORE, we aren't releasing since this LWP isn't giving
+	 * up PCU, just saving it.
+	 */
 	const int flags = PCU_SAVE | (l->l_flag & LW_WCORE ? PCU_RELEASE : 0);
 
 	/*
@@ -162,10 +185,6 @@ pcu_save_all(lwp_t *l)
 			continue;
 		}
 		const pcu_ops_t * const pcu = pcu_ops_md_defs[id];
-		/*
-		 * We aren't releasing since this LWP isn't giving up PCU,
-		 * just saving it.
-		 */
 		pcu_lwp_op(pcu, l, flags);
 	}
 	splx(s);
diff --git a/sys/sys/pcu.h b/sys/sys/pcu.h
index fbe6f9979e94..29710978da40 100644
--- a/sys/sys/pcu.h
+++ b/sys/sys/pcu.h
@@ -1,4 +1,4 @@
-/*	$NetBSD: pcu.h,v 1.8 2011/06/06 22:04:34 matt Exp $	*/
+/*	$NetBSD: pcu.h,v 1.9 2012/04/18 13:42:11 yamt Exp $	*/
 
 /*-
  * Copyright (c) 2011 The NetBSD Foundation, Inc.
@@ -49,6 +49,20 @@
 
 #if PCU_UNIT_COUNT > 0
 
+/*
+ * pcu_state_save(lwp)
+ *	save the current CPU's state into the given LWP's MD storage.
+ *
+ * pcu_state_load(lwp, used)
+ *	load PCU state from the given LWP's MD storage to the current CPU.
+ *	the 'used' argument is true if it isn't the first time the LWP uses
+ *	the PCU.
+ *
+ * pcu_state_release(lwp)
+ *	tell MD code detect the next use of the PCU on the LWP, and call
+ *	pcu_load().
+ */
+
 typedef struct {
 	u_int	pcu_id;
 	void	(*pcu_state_save)(lwp_t *);