Adding consistency checks of the event definitions.

Tidying up comments and declaration order.

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

3 files changed, 77 insertions, 38 deletions

diff --git a/mps/code/event.c b/mps/code/event.c
index c16ac133bbe..ca50a4ea32f 100644
--- a/mps/code/event.c
+++ b/mps/code/event.c
@@ -80,6 +80,41 @@ Res EventInit(void)
 {
   Res res;
 
+  /* Make local enums for all event params in order to check that the indexes
+     in the parameter definition macros are in order, and that parameter
+     idents are unique. */
+
+#define EVENT_CHECK_ENUM_PARAM(name, index, sort, ident) \
+  Event##name##Param##ident,
+
+#define EVENT_CHECK_ENUM(X, name, code, always, kind) \
+  enum Event##name##ParamEnum { \
+    EVENT_##name##_PARAMS(EVENT_CHECK_ENUM_PARAM, name) \
+    Event##name##ParamLIMIT \
+  };
+
+  EVENT_LIST(EVENT_CHECK_ENUM, X)
+
+  /* Check consistency of the event definitions.  These are all compile-time
+     checks and should get optimised away. */
+
+#define EVENT_PARAM_CHECK(name, index, sort, ident) \
+  AVER(index == Event##name##Param##ident); \
+  AVER(sizeof(EventF##sort) >= 0); /* check existence of type */
+
+#define EVENT_CHECK(X, name, code, always, kind) \
+  AVER(size_tAlignUp(sizeof(Event##name##Struct), MPS_PF_ALIGN) \
+       <= EventSizeMAX); \
+  AVER(Event##name##Code == code); \
+  AVER(0 <= code && code <= EventCodeMAX); \
+  AVER(sizeof(#name) - 1 <= EventNameMAX); \
+  AVER(Event##name##Always == always); \
+  AVERT(Bool, always); \
+  AVER(0 <= Event##name##Kind && Event##name##Kind < EventKindLIMIT); \
+  EVENT_##name##_PARAMS(EVENT_PARAM_CHECK, name)
+
+  EVENT_LIST(EVENT_CHECK, X)
+
   /* Ensure that no event can be larger than the maximum event size. */
   AVER(EventBufferSIZE <= EventSizeMAX);
 
diff --git a/mps/code/eventcom.h b/mps/code/eventcom.h
index c42dbeb4c61..d5e3959d72c 100644
--- a/mps/code/eventcom.h
+++ b/mps/code/eventcom.h
@@ -88,31 +88,10 @@ typedef Word EventClock;
 #endif
 
 
-/* Types for event fields */
-
-typedef unsigned short EventCode;
-typedef unsigned EventKind;
-typedef unsigned short EventSize;
-#define EventSizeMAX USHRT_MAX
-
-typedef Byte EventStringLen;
-
-typedef struct {
-  EventStringLen len;
-  char str[EventStringLengthMAX];
-} EventStringStruct;
-
-typedef EventStringStruct *EventString;
-
-
-#define EventNameMAX ((size_t)19)
-#define EventCodeMAX ((EventCode)0x0069)
-
-
 /* Event Kinds --- see <design/telemetry/>
  *
  * All events are classified as being of one event type.
- * They are small enough to be able to be used as shifts within a word.
+ * They are small enough to be able to be used as members of a bit set.
  */
 
 enum {
@@ -129,7 +108,8 @@ enum {
 
 /* Event type definitions
  *
- * Define various constants for each event type to describe them.
+ * Various constants for each event type to describe them, so that they
+ * can easily be looked up from macros by name.
  */
 
 /* Note that enum values can be up to fifteen bits long portably. */
@@ -149,7 +129,29 @@ EVENT_LIST(EVENT_ENUM, X)
  * buffers and on the binary telemetry output stream.
  */
 
-/* Event field types -- similar to WriteF* */
+/* Types for common event fields */
+typedef unsigned short EventCode;
+typedef unsigned EventKind;
+typedef unsigned short EventSize;
+#define EventSizeMAX USHRT_MAX
+
+/* FIXME: Is the length byte really necessary? Why not use the overall event
+   size and NUL terminate? */
+typedef Byte EventStringLen;
+typedef struct EventStringStruct {
+  EventStringLen len;
+  char str[EventStringLengthMAX];
+} EventStringStruct, *EventString;
+
+/* Common prefix for all event structures.  The size field allows an event
+   reader to skip over events whose codes it does not recognise. */
+typedef struct EventAnyStruct {
+  EventCode code;       /* encoding of the event type */
+  EventSize size;       /* allows reader to skip events of unknown code */
+  EventClock clock;     /* when the event occurred */
+} EventAnyStruct;
+
+/* Event field types, for indexing by macro on the event parameter sort */
 typedef void *EventFP;                  /* pointer to C object */
 typedef Addr EventFA;                   /* address on the heap */
 typedef Word EventFW;                   /* word */
@@ -158,6 +160,7 @@ typedef EventStringStruct EventFS;      /* string */
 typedef double EventFD;                 /* double */
 typedef int EventFB;                    /* boolean */
 
+/* Event packing bitfield specifiers */
 #define EventFP_BITFIELD
 #define EventFA_BITFIELD
 #define EventFW_BITFIELD
@@ -166,22 +169,14 @@ typedef int EventFB;                    /* boolean */
 #define EventFD_BITFIELD
 #define EventFB_BITFIELD : 1
 
-/* Common prefix for all event structures.  The size field allows an event
-   reader to skip over events whose codes it does not recognise. */
-typedef struct EventAnyStruct {
-  EventCode code;
-  EventSize size;
-  EventClock clock;
-} EventAnyStruct;
-
 #define EVENT_STRUCT_FIELD(X, index, sort, ident) \
   EventF##sort f##index EventF##sort##_BITFIELD;
 
 #define EVENT_STRUCT(X, name, _code, always, kind) \
   typedef struct Event##name##Struct { \
-    EventCode code; \
-    EventSize size; \
-    EventClock clock; \
+    EventCode code;     /* Must match EventAnyStruct */ \
+    EventSize size;     /* ditto */ \
+    EventClock clock;   /* ditto */ \
     EVENT_##name##_PARAMS(EVENT_STRUCT_FIELD, X) \
   } Event##name##Struct;
 
diff --git a/mps/code/eventdef.h b/mps/code/eventdef.h
index a0569bb4a16..77a1269369b 100644
--- a/mps/code/eventdef.h
+++ b/mps/code/eventdef.h
@@ -47,9 +47,14 @@
  *   - Kind: Category into which this event falls, without the
  *     leading "EventKind";
  *
+ * TODO: Add a doc string to each event type.
+ *
  * See also EVENT_*_PARAMS for definition of event parameters.
  */
  
+#define EventNameMAX ((size_t)19)
+#define EventCodeMAX ((EventCode)0x0069)
+
 /* FIXME: Work out why not-in-use events were not in use and restore or delete them. */
 
 #define EVENT_LIST(EVENT, X) \
@@ -152,17 +157,21 @@
   EVENT(X, SegMerge           , 0x0068,  TRUE, Seg) \
   EVENT(X, SegSplit           , 0x0069,  TRUE, Seg)
 
-/* Remember to update EventNameMAX and EventCodeMAX in eventcom.h! */
+/* Remember to update EventNameMAX and EventCodeMAX in eventcom.h! 
+   (These are checked in EventInit.) */
 
 
 /* EVENT_*_PARAMS -- definition of event parameters
  *
  * For each event type in EVENT_LIST, these macros list the parameters of
  * the event.  THe columns are:
- *   - the positional index of the parameter in the list
+ *   - the positional index of the parameter in the list, used to define
+ *     numeric field names using the C preprocessor
  *   - the parameter sort, similar to writef (Pointer, Addr, Word, Unsigned,
  *     String, Double)
- *   - a parameter name for display
+ *   - a parameter identifier for display or use in code
+ *
+ * TODO: Add a doc string to each parameter.
  */
 
 #define EVENT_AMCGenCreate_PARAMS(PARAM, X) \