runtime: clarify comment for m->locked

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/11671043

1 files changed, 7 insertions, 3 deletions

diff --git a/src/pkg/runtime/runtime.h b/src/pkg/runtime/runtime.h
index 36aff04ad3..f8d45ba819 100644
--- a/src/pkg/runtime/runtime.h
+++ b/src/pkg/runtime/runtime.h
@@ -359,9 +359,13 @@ struct P
 	byte	pad[64];
 };
 
-// The m->locked word holds a single bit saying whether
-// external calls to LockOSThread are in effect, and then a counter
-// of the internal nesting depth of lockOSThread / unlockOSThread.
+// The m->locked word holds two pieces of state counting active calls to LockOSThread/lockOSThread.
+// The low bit (LockExternal) is a boolean reporting whether any LockOSThread call is active.
+// External locks are not recursive; a second lock is silently ignored.
+// The upper bits of m->lockedcount record the nesting depth of calls to lockOSThread
+// (counting up by LockInternal), popped by unlockOSThread (counting down by LockInternal).
+// Internal locks can be recursive. For instance, a lock for cgo can occur while the main
+// goroutine is holding the lock during the initialization phase.
 enum
 {
 	LockExternal = 1,