runtime: improve comment about non-preemption during GC work

Currently, gcDrainN is documented saying that it must be run on the
system stack. In fact, the problem and solution here are somewhat
subtler. First, it doesn't have to happen on the system stack, it just
has to be non-stoppable (that is, non-preemptible). Second, this isn't
specific to gcDrainN (though gcDrainN is perhaps the most surprising
instance); it's general to anything that uses the gcWork structure.

Move the comment to gcWork and generalize it.

Change-Id: I5277b5abb070e47f8d783bc15a310b379c6adc22
Reviewed-on: https://go-review.googlesource.com/8247
Reviewed-by: Rick Hudson <rlh@golang.org>

src/runtime/mgcmark.go

@@ -366,9 +366,6 @@ func gcDrain(gcw *gcWork) {
 }
 
 // gcDrainN scans n objects, blackening grey objects.
-//
-// This MUST be run on the system stack to prevent a stop-the-world
-// while this locally holds GC work buffers.
 //go:nowritebarrier
 func gcDrainN(gcw *gcWork, n int) {
 	checknocurrentwbuf()

src/runtime/mgcwork.go

@@ -41,8 +41,15 @@ func (wp wbufptr) ptr() *workbuf {
 // The usual pattern for using gcWork is:
 //
 //     var gcw gcWork
+//     disable preemption
 //     .. call gcw.put() to produce and gcw.get() to consume ..
 //     gcw.dispose()
+//     enable preemption
+//
+// It's important that any use of gcWork during the mark phase prevent
+// the garbage collector from transitioning to mark termination since
+// gcWork may locally hold GC work buffers. This can be done by
+// disabling preemption (systemstack or acquirem).
 type gcWork struct {
 	// Invariant: wbuf is never full or empty
 	wbuf wbufptr