1.1 --- a/VMS.h	Thu Mar 15 20:47:54 2012 -0700
     1.2 +++ b/VMS.h	Fri Mar 16 09:39:53 2012 -0700
     1.3 @@ -29,12 +29,7 @@
     1.4  
     1.5  //================================ Typedefs =================================
     1.6  //
     1.7 -typedef unsigned long long TSCount;
     1.8 -typedef union
     1.9 - { uint32 lowHigh[2];
    1.10 -   uint64 longVal;
    1.11 - }
    1.12 -TSCountLowHigh;
    1.13 +typedef unsigned long long    TSCount;
    1.14  
    1.15  typedef struct _SchedSlot     SchedSlot;
    1.16  typedef struct _VMSReqst      VMSReqst;
    1.17 @@ -54,9 +49,6 @@
    1.18  #include "Hardware_Dependent/VMS__HW_measurement.h"
    1.19  #include "Hardware_Dependent/VMS__primitives.h"
    1.20  
    1.21 -//============================= Statistics ==================================
    1.22 -
    1.23 -inline TSCount getTSCount();
    1.24  
    1.25  //============= Request Related ===========
    1.26  //
    1.27 @@ -113,26 +105,29 @@
    1.28   };
    1.29  //SchedSlot
    1.30  
    1.31 -/*WARNING: re-arranging this data structure could cause Slv switching
    1.32 - *         assembly code to fail -- hard-codes offsets of fields
    1.33 +/*This structure embodies the state of a slaveVP.  It is reused for masterVP
    1.34 + * and shutdownVPs.
    1.35   */
    1.36  struct _SlaveVP
    1.37 - { int         slaveID;  //each slave given a unique ID
    1.38 -   int         coreAnimatedBy;
    1.39 -   void       *startOfStack;
    1.40 -   void       *stackPtr;
    1.41 -   void       *framePtr;
    1.42 -   void       *resumeInstrPtr;
    1.43 -   
    1.44 -   void       *coreCtlrStartPt;  //allows proto-runtime to be linked later
    1.45 + {    //The offsets of these fields are hard-coded into assembly
    1.46 +   void       *stackPtr;         //save the core's stack ptr when suspend
    1.47 +   void       *framePtr;         //save core's frame ptr when suspend
    1.48 +   void       *resumeInstrPtr;   //save core's program-counter when suspend
    1.49     void       *coreCtlrFramePtr; //restore before jmp back to core controller
    1.50     void       *coreCtlrStackPtr; //restore before jmp back to core controller
    1.51 +   
    1.52 +      //============ below this, no fields are used in asm =============
    1.53 +   int         slaveID;          //each slave given a globally unique ID
    1.54 +   int         coreAnimatedBy;
    1.55 +   void       *startOfStack;  //used to free, and to point slave to Fn
    1.56 +   
    1.57 +      //for comm -- between master and coreCtlr & btwn wrapper lib and plugin
    1.58 +   SchedSlot  *schedSlotAssignedTo;
    1.59 +   VMSReqst   *requests;      //wrapper lib puts in requests, plugin takes out
    1.60 +   void       *dataRetFromReq;//Return vals from plugin to Wrapper Lib
    1.61  
    1.62 -   SchedSlot  *schedSlot;
    1.63 -   VMSReqst   *requests;
    1.64 -
    1.65 -   void       *semanticData; //this is live for the life of Slv
    1.66 -   void       *dataRetFromReq;//Used to return vals from plugin to Wrapper Lib
    1.67 +      //Slave used as carrier for data
    1.68 +   void       *semanticData;  //Lang saves lang-specific things in slave here
    1.69  
    1.70        //=========== MEASUREMENT STUFF ==========
    1.71         MEAS__Insert_Meas_Fields_into_Slave;
    1.72 @@ -142,14 +137,15 @@
    1.73   };
    1.74  //SlaveVP
    1.75  
    1.76 -/*The one and only global variable, holds many odds and ends
    1.77 + 
    1.78 +/* The one and only global variable, holds many odds and ends
    1.79   */
    1.80  typedef struct
    1.81   {    //The offsets of these fields are hard-coded into assembly
    1.82     void            *coreCtlrReturnPt;    //offset of field used in asm
    1.83     int32            masterLock __align_to_cacheline__;   //used in asm
    1.84     
    1.85 -      //============ below this, no asm uses the field offsets =============
    1.86 +      //============ below this, no fields are used in asm =============
    1.87  
    1.88        //Basic VMS infrastructure
    1.89     SlaveVP        **masterVPs;
    1.90 @@ -214,6 +210,7 @@
    1.91  
    1.92  volatile MasterEnv      *_VMSMasterEnv __align_to_cacheline__;
    1.93  
    1.94 +   //these are global, but only used for startup and shutdown
    1.95  pthread_t       coreCtlrThdHandles[ NUM_CORES ]; //pthread's virt-procr state
    1.96  ThdParams      *coreCtlrThdParams [ NUM_CORES ];
    1.97  
    1.98 @@ -221,16 +218,28 @@
    1.99  pthread_cond_t  suspendCond;
   1.100  
   1.101  //=========================  Function Prototypes  ===========================
   1.102 -
   1.103 -/* MEANING OF   WL  PI  SS  int
   1.104 +/* MEANING OF   WL  PI  SS  int VMSOS
   1.105   * These indicate which places the function is safe to use.  They stand for:
   1.106 - * WL: Wrapper Library
   1.107 - * PI: Plugin 
   1.108 - * SS: Startup and Shutdown
   1.109 - * int: internal to the VMS implementation
   1.110 + * 
   1.111 + * WL   Wrapper Library -- wrapper lib code should only use these
   1.112 + * PI   Plugin          -- plugin code should only use these
   1.113 + * SS   Startup and Shutdown -- designates these relate to startup & shutdown
   1.114 + * int  internal to VMS -- should not be used in wrapper lib or plugin
   1.115 + * VMSOS means "OS functions for applications to use"
   1.116 + * 
   1.117 + * VMS_int__ functions touch internal VMS data structs and are only safe
   1.118 + *  to be used inside the master lock.  However, occasionally, they appear
   1.119 + * in wrapper-lib or plugin code.  In those cases, very careful analysis
   1.120 + * has been done to be sure no concurrency issues could arise.
   1.121 + * 
   1.122 + * VMS_WL__ functions are all safe for use outside the master lock.
   1.123 + * 
   1.124 + * VMSOS are only safe for applications to use -- they're like a second
   1.125 + * language mixed in -- but they can't be used inside plugin code, and
   1.126 + * aren't meant for use in wrapper libraries, because they are themselves
   1.127 + * wrapper-library calls!
   1.128   */
   1.129 -
   1.130 -//========== Setup and shutdown ==========
   1.131 +//========== Startup and shutdown ==========
   1.132  void
   1.133  VMS_SS__init();
   1.134