lib/lock: Clarify comments

diff --git a/open-vm-tools/lib/lock/ul.c b/open-vm-tools/lib/lock/ul.c
index 78b200fe34ba67b6dbd1a7f054698e0bb2a600f5..6dbf39479fd21e8f816d39c66cd9905dbf3b459d 100644 (file)
--- a/open-vm-tools/lib/lock/ul.c
+++ b/open-vm-tools/lib/lock/ul.c
@@ -148,12 +148,15 @@ MXUserInternalSingleton(Atomic_Ptr *storage)  // IN:
  *      detection of locks created with one copy of the MXUser library and
  *      passed to another copy of the MXUser library.
  *
- *      The syndrome bits are important as they prevent incompatible versions
- *      of the MXUser library from trashing each other.
+ *      The syndrome bits provide a detection mechanism for locks created and
+ *      maintained by one copy of the lock library being used by another copy
+ *      of the lock library. Undetected, strange crashes can occur due to locks
+ *      that are aliased or are incompatible with the lock library that is
+ *      manipulating them.
  *
- *      The bits are generated by using a source of bits that is external to
- *      a program and its libraries. This way no code or data based scheme
- *      can be spoofed or aliased.
+ *      The syndrome bits are generated by using a source of bits that is
+ *      external to a program and its libraries. This way no code or data
+ *      based scheme can be spoofed or aliased.
  *
  * Results:
  *      As above
@@ -228,10 +231,11 @@ MXUserGetSignature(MXUserObjectType objectType)  // IN:
           (objectType != MXUSER_TYPE_NEVER_USE));
 
    /*
-    * Use a random syndrome combined with a unique bit pattern mapping
-    * of objectType to bits in a nibble. The random portion of the signature
-    * can be used to catch multiple copies of lib/lock that are "leaking"
-    * locks between them (which may be incompatible due to internal changes).
+    * Create a unique signature by combining the unique syndrome of this
+    * instance of lib/lock with a mapping of objectType. The unique syndome
+    * within the signature is used to catch multiple copies of lib/lock that
+    * are "leaking" locks between them (e.g. locks may be aliased (which means
+    * no protection) or internal implementation details may have changed).
     */
 
    signature = (MXUserSyndrome() & 0x0FFFFFFF) | (objectType << 28);