document ErtsExternalDist flags and CON_ID mask

In the ErtsExternalDist structure, the flags field holds a combination of flags
(tagged into the high bits) and the connection ID (in the low bits).  This
wasn't clearing indicated anywhere.  This patch adds a comment before the flags
and mask that indicates their use and relation to each other.  This will help
guide people through the code and reduce the likelihood that someone will add a
flag without adjusting the mask.

1 files changed, 13 insertions, 4 deletions

diff --git a/erts/emulator/beam/external.h b/erts/emulator/beam/external.h
index aa124f5197..727333d539 100644
--- a/erts/emulator/beam/external.h
+++ b/erts/emulator/beam/external.h
@@ -98,10 +98,19 @@ typedef struct {
     Eterm atom[ERTS_ATOM_CACHE_SIZE];
 } ErtsAtomTranslationTable;
 
-#define ERTS_DIST_EXT_DFLAG_HDR (((Uint32) 1) << 31)
-#define ERTS_DIST_EXT_ATOM_TRANS_TAB (((Uint32) 1) << 30)
-#define ERTS_DIST_EXT_BTT_SAFE (((Uint32) 1) << 29)
-#define ERTS_DIST_EXT_CON_ID_MASK ((Uint32) 0x1fffffff)
+/*
+ * These flags are tagged onto the high bits of a connection ID and stored in
+ * the ErtsDistExternal structure's flags field.  They are used to indicate
+ * various bits of state necessary to decode binaries in a variety of
+ * scenarios. The mask ERTS_DIST_EXT_CON_ID_MASK is used later to separate the
+ * connection ID from the flags. Be careful to ensure that the mask does not
+ * overlap any of the bits used for flags, or ERTS will leak flags bits into
+ * connection IDs and leak connection ID bits into the flags.
+ */
+#define ERTS_DIST_EXT_DFLAG_HDR      ((Uint32) 0x80000000)
+#define ERTS_DIST_EXT_ATOM_TRANS_TAB ((Uint32) 0x40000000)
+#define ERTS_DIST_EXT_BTT_SAFE       ((Uint32) 0x20000000)
+#define ERTS_DIST_EXT_CON_ID_MASK    ((Uint32) 0x1fffffff)
 
 #define ERTS_DIST_EXT_CON_ID(DIST_EXTP) \
   ((DIST_EXTP)->flags & ERTS_DIST_EXT_CON_ID_MASK)