Mps awldiag: (comments only) clarify arenaaccess, accessset, and awlsegalloc

Copied from Perforce
 Change: 163342
 ServerID: perforce.ravenbrook.com

mps/code/global.c

@@ -531,9 +531,17 @@ MutatorFaultContext mps_exception_info = NULL;
 
 /* ArenaAccess -- deal with an access fault
  *
- * This is called when a protected address is accessed.  The mode
- * corresponds to which mode flags need to be cleared in order for the
- * access to continue.  */
+ * Our signal handler calls this when a protected address is accessed.
+ *
+ * "mode" states which attempted operations (AccessREAD, WRITE) were
+ * caught by the signal handler.  Note: this may be a conservative
+ * exaggeration, because the handler cannot always precisely determine
+ * what operation was being attempted (see for example
+ * protsgix.c#1:.sigh.mode).
+ *
+ * MPS must lift prohibition of the "mode" operations, in order for the
+ * access to continue.
+ */
 
 Bool ArenaAccess(Addr addr, AccessSet mode, MutatorFaultContext context)
 {

mps/code/mpmtypes.h

@@ -270,10 +270,20 @@ typedef Res (*RootScanRegMethod)(ScanState ss, Thread thread, void *p, size_t s)
 #define SigInvalid      ((Sig)0x51915BAD)
 
 #define SizeMAX         ((Size)-1)
+
+/* AccessSet -- operations that access memory
+ *
+ * Note: in most MPS source code, these operation codes are used in the
+ * non-permissive sense, ie: "intercept/trap/prohibit this operation".
+ * For example, when a segment is added to the greylist, mutator read 
+ * access is _prohibited_, by calling:
+ *   ShieldRaise(arena, seg, AccessREAD);
+ */
 #define AccessSetEMPTY  ((AccessSet)0) /* <design/type/#access-set> */
 #define AccessREAD      ((AccessSet)(1<<0))
 #define AccessWRITE     ((AccessSet)(1<<1))
 #define AccessSetWIDTH  (2)
+
 #define RefSetEMPTY     BS_EMPTY(RefSet)
 #define RefSetUNIV      BS_UNIV(RefSet)
 #define ZoneSetEMPTY    BS_EMPTY(ZoneSet)

mps/code/poolawl.c

@@ -451,7 +451,10 @@ static Res AWLSegCreate(AWLSeg *awlsegReturn,
 }
 
 
-/* AWLSegAlloc -- allocate an object in a given segment */
+/* AWLSegAlloc -- find a space >= size in the segment (or fail)
+ *
+ * Note: despite the name, this function does not actually 'allocate'.
+ */
 
 static Bool AWLSegAlloc(Addr *baseReturn, Addr *limitReturn,
                         AWLSeg awlseg, AWL awl, Size size)