annotate PR.h @ 260:999f2966a3e5

new branch -- Dev_ML -- for making VMS take langlets whose constructs can be mixed
author Sean Halle <seanhalle@yahoo.com>
date Wed, 19 Sep 2012 23:12:44 -0700
parents
children dafae55597ce
rev   line source
seanhalle@260 1 /*
seanhalle@260 2 * Copyright 2009 OpenSourceStewardshipFoundation.org
seanhalle@260 3 * Licensed under GNU General Public License version 2
seanhalle@260 4 *
seanhalle@260 5 * Author: seanhalle@yahoo.com
seanhalle@260 6 *
seanhalle@260 7 */
seanhalle@260 8
seanhalle@260 9 #ifndef _PR_H
seanhalle@260 10 #define _PR_H
seanhalle@260 11 #define _GNU_SOURCE
seanhalle@260 12
seanhalle@260 13 #include "DynArray/DynArray.h"
seanhalle@260 14 #include "Hash_impl/PrivateHash.h"
seanhalle@260 15 #include "Histogram/Histogram.h"
seanhalle@260 16 #include "Queue_impl/PrivateQueue.h"
seanhalle@260 17
seanhalle@260 18 #include "PR_primitive_data_types.h"
seanhalle@260 19 #include "Services_Offered_by_PR/Memory_Handling/vmalloc.h"
seanhalle@260 20
seanhalle@260 21 #include <pthread.h>
seanhalle@260 22 #include <sys/time.h>
seanhalle@260 23
seanhalle@260 24 //================= Defines: included from separate files =================
seanhalle@260 25 //
seanhalle@260 26 // Note: ALL defines are in other files, none are in here
seanhalle@260 27 //
seanhalle@260 28 #include "Defines/PR_defs.h"
seanhalle@260 29
seanhalle@260 30
seanhalle@260 31 //================================ Typedefs =================================
seanhalle@260 32 //
seanhalle@260 33 typedef unsigned long long TSCount;
seanhalle@260 34
seanhalle@260 35 typedef struct _AnimSlot AnimSlot;
seanhalle@260 36 typedef struct _PRReqst PRReqst;
seanhalle@260 37 typedef struct _SlaveVP SlaveVP;
seanhalle@260 38 typedef struct _MasterVP MasterVP;
seanhalle@260 39 typedef struct _IntervalProbe IntervalProbe;
seanhalle@260 40
seanhalle@260 41
seanhalle@260 42 typedef SlaveVP *(*SlaveAssigner) ( void *, AnimSlot*); //semEnv, slot for HW info
seanhalle@260 43 typedef void (*RequestHandler) ( SlaveVP *, void * ); //prWReqst, semEnv
seanhalle@260 44 typedef void (*TopLevelFnPtr) ( void *, SlaveVP * ); //initData, animSlv
seanhalle@260 45 typedef void TopLevelFn ( void *, SlaveVP * ); //initData, animSlv
seanhalle@260 46 typedef void (*ResumeSlvFnPtr) ( SlaveVP *, void * );
seanhalle@260 47 //=========== MEASUREMENT STUFF ==========
seanhalle@260 48 MEAS__Insert_Counter_Handler
seanhalle@260 49 //========================================
seanhalle@260 50
seanhalle@260 51 //============================ HW Dependent Fns ================================
seanhalle@260 52
seanhalle@260 53 #include "HW_Dependent_Primitives/PR__HW_measurement.h"
seanhalle@260 54 #include "HW_Dependent_Primitives/PR__primitives.h"
seanhalle@260 55
seanhalle@260 56
seanhalle@260 57 //============= Request Related ===========
seanhalle@260 58 //
seanhalle@260 59
seanhalle@260 60 enum PRReqstType //avoid starting enums at 0, for debug reasons
seanhalle@260 61 {
seanhalle@260 62 semantic = 1,
seanhalle@260 63 createReq,
seanhalle@260 64 dissipate,
seanhalle@260 65 PRSemantic //goes with PRSemReqst below
seanhalle@260 66 };
seanhalle@260 67
seanhalle@260 68 struct _PRReqst
seanhalle@260 69 {
seanhalle@260 70 enum PRReqstType reqType;//used for dissipate and in future for IO requests
seanhalle@260 71 void *semReqData;
seanhalle@260 72
seanhalle@260 73 PRReqst *nextReqst;
seanhalle@260 74 };
seanhalle@260 75 //PRReqst
seanhalle@260 76
seanhalle@260 77 enum PRSemReqstType //These are equivalent to semantic requests, but for
seanhalle@260 78 { // PR's services available directly to app, like OS
seanhalle@260 79 make_probe = 1, // and probe services -- like a PR-wide built-in lang
seanhalle@260 80 throw_excp,
seanhalle@260 81 openFile,
seanhalle@260 82 otherIO
seanhalle@260 83 };
seanhalle@260 84
seanhalle@260 85 typedef struct
seanhalle@260 86 { enum PRSemReqstType reqType;
seanhalle@260 87 SlaveVP *requestingSlv;
seanhalle@260 88 char *nameStr; //for create probe
seanhalle@260 89 char *msgStr; //for exception
seanhalle@260 90 void *exceptionData;
seanhalle@260 91 }
seanhalle@260 92 PRSemReq;
seanhalle@260 93
seanhalle@260 94
seanhalle@260 95 //==================== Core data structures ===================
seanhalle@260 96
seanhalle@260 97 typedef struct
seanhalle@260 98 {
seanhalle@260 99 //for future expansion
seanhalle@260 100 }
seanhalle@260 101 SlotPerfInfo;
seanhalle@260 102
seanhalle@260 103 struct _AnimSlot
seanhalle@260 104 {
seanhalle@260 105 int workIsDone;
seanhalle@260 106 int needsSlaveAssigned;
seanhalle@260 107 SlaveVP *slaveAssignedToSlot;
seanhalle@260 108
seanhalle@260 109 int slotIdx; //needed by Holistic Model's data gathering
seanhalle@260 110 int coreSlotIsOn;
seanhalle@260 111 SlotPerfInfo *perfInfo; //used by assigner to pick best slave for core
seanhalle@260 112 };
seanhalle@260 113 //AnimSlot
seanhalle@260 114
seanhalle@260 115 enum VPtype
seanhalle@260 116 { TaskSlotSlv = 1,//Slave tied to an anim slot, only animates tasks
seanhalle@260 117 TaskExtraSlv, //When a suspended task ends, the slave becomes this
seanhalle@260 118 PersistentSlv, //the VP is explicitly seen in the app code, or task suspends
seanhalle@260 119 Slave, //to be removed
seanhalle@260 120 Master,
seanhalle@260 121 Shutdown,
seanhalle@260 122 Idle
seanhalle@260 123 };
seanhalle@260 124
seanhalle@260 125 /*This structure embodies the state of a slaveVP. It is reused for masterVP
seanhalle@260 126 * and shutdownVPs.
seanhalle@260 127 */
seanhalle@260 128 struct _SlaveVP
seanhalle@260 129 { //The offsets of these fields are hard-coded into assembly
seanhalle@260 130 void *stackPtr; //save the core's stack ptr when suspend
seanhalle@260 131 void *framePtr; //save core's frame ptr when suspend
seanhalle@260 132 void *resumeInstrPtr; //save core's program-counter when suspend
seanhalle@260 133 void *coreCtlrFramePtr; //restore before jmp back to core controller
seanhalle@260 134 void *coreCtlrStackPtr; //restore before jmp back to core controller
seanhalle@260 135
seanhalle@260 136 //============ below this, no fields are used in asm =============
seanhalle@260 137
seanhalle@260 138 int slaveID; //each slave given a globally unique ID
seanhalle@260 139 int coreAnimatedBy;
seanhalle@260 140 void *startOfStack; //used to free, and to point slave to Fn
seanhalle@260 141 enum VPtype typeOfVP; //Slave vs Master vs Shutdown..
seanhalle@260 142 int assignCount; //Each assign is for one work-unit, so IDs it
seanhalle@260 143 //note, a scheduling decision is uniquely identified by the triple:
seanhalle@260 144 // <slaveID, coreAnimatedBy, assignCount> -- used in record & replay
seanhalle@260 145
seanhalle@260 146 //for comm -- between master and coreCtlr & btwn wrapper lib and plugin
seanhalle@260 147 AnimSlot *animSlotAssignedTo;
seanhalle@260 148 PRReqst *request; //wrapper lib puts in requests, plugin takes out
seanhalle@260 149 void *dataRetFromReq;//Return vals from plugin to Wrapper Lib
seanhalle@260 150
seanhalle@260 151 //For using Slave as carrier for data
seanhalle@260 152 void *semanticData; //Lang saves lang-specific things in slave here
seanhalle@260 153
seanhalle@260 154 //=========== MEASUREMENT STUFF ==========
seanhalle@260 155 MEAS__Insert_Meas_Fields_into_Slave;
seanhalle@260 156 float64 createPtInSecs; //time VP created, in seconds
seanhalle@260 157 //========================================
seanhalle@260 158 };
seanhalle@260 159 //SlaveVP
seanhalle@260 160
seanhalle@260 161
seanhalle@260 162 /* The one and only global variable, holds many odds and ends
seanhalle@260 163 */
seanhalle@260 164 typedef struct
seanhalle@260 165 { //The offsets of these fields are hard-coded into assembly
seanhalle@260 166 void *coreCtlrReturnPt; //offset to this field used in asm
seanhalle@260 167 int8 falseSharePad1[256 - sizeof(void*)];
seanhalle@260 168 int32 masterLock; //offset to this field used in asm
seanhalle@260 169 int8 falseSharePad2[256 - sizeof(int32)];
seanhalle@260 170 //============ below this, no fields are used in asm =============
seanhalle@260 171
seanhalle@260 172 //Basic PR infrastructure
seanhalle@260 173 SlaveVP **masterVPs;
seanhalle@260 174 AnimSlot ***allAnimSlots;
seanhalle@260 175
seanhalle@260 176 //plugin related
seanhalle@260 177 PRSemEnv **langlets;
seanhalle@260 178
seanhalle@260 179 //Slave creation -- global count of slaves existing, across langs and processes
seanhalle@260 180 int32 numSlavesCreated; //used to give unique ID to processor
seanhalle@260 181 //no reasonable way to do fail-safe when have mult langlets and processes.. have to detect for each langlet separately
seanhalle@260 182 // int32 numSlavesAlive; //used to detect fail-safe shutdown
seanhalle@260 183
seanhalle@260 184 //Initialization related
seanhalle@260 185 int32 setupComplete; //use while starting up coreCtlr
seanhalle@260 186
seanhalle@260 187 //Memory management related
seanhalle@260 188 MallocArrays *freeLists;
seanhalle@260 189 int32 amtOfOutstandingMem;//total currently allocated
seanhalle@260 190
seanhalle@260 191 //Random number seeds -- random nums used in various places
seanhalle@260 192 uint32_t seed1;
seanhalle@260 193 uint32_t seed2;
seanhalle@260 194
seanhalle@260 195 //=========== MEASUREMENT STUFF =============
seanhalle@260 196 IntervalProbe **intervalProbes;
seanhalle@260 197 PtrToPrivDynArray *dynIntervalProbesInfo;
seanhalle@260 198 HashTable *probeNameHashTbl;
seanhalle@260 199 int32 masterCreateProbeID;
seanhalle@260 200 float64 createPtInSecs; //real-clock time PR initialized
seanhalle@260 201 Histogram **measHists;
seanhalle@260 202 PtrToPrivDynArray *measHistsInfo;
seanhalle@260 203 MEAS__Insert_Susp_Meas_Fields_into_MasterEnv;
seanhalle@260 204 MEAS__Insert_Master_Meas_Fields_into_MasterEnv;
seanhalle@260 205 MEAS__Insert_Master_Lock_Meas_Fields_into_MasterEnv;
seanhalle@260 206 MEAS__Insert_Malloc_Meas_Fields_into_MasterEnv;
seanhalle@260 207 MEAS__Insert_Plugin_Meas_Fields_into_MasterEnv;
seanhalle@260 208 MEAS__Insert_System_Meas_Fields_into_MasterEnv;
seanhalle@260 209 MEAS__Insert_Counter_Meas_Fields_into_MasterEnv;
seanhalle@260 210 //==========================================
seanhalle@260 211 }
seanhalle@260 212 MasterEnv;
seanhalle@260 213
seanhalle@260 214 //=====================
seanhalle@260 215 typedef struct
seanhalle@260 216 { int32 langletID; //acts as index into array of langlets in master env
seanhalle@260 217 void *langletSemEnv;
seanhalle@260 218 int32 langMagicNumber;
seanhalle@260 219 SlaveAssigner slaveAssigner;
seanhalle@260 220 RequestHandler requestHandler;
seanhalle@260 221 EndTaskHandler endTaskHandler;
seanhalle@260 222
seanhalle@260 223 //Tack slaves created, separately for each langlet (in each process)
seanhalle@260 224 int32 numSlavesCreated; //gives ordering to processor creation
seanhalle@260 225 int32 numSlavesAlive; //used to detect fail-safe shutdown
seanhalle@260 226
seanhalle@260 227 //when multi-lang, master polls sem env's to find one with work in it..
seanhalle@260 228 // in single-lang case, flag ignored, master always asks lang for work
seanhalle@260 229 int32 hasWork;
seanhalle@260 230 }
seanhalle@260 231 PRSemEnv;
seanhalle@260 232
seanhalle@260 233 //===================== Top Processor level Data Strucs ======================
seanhalle@260 234 typedef struct
seanhalle@260 235 {
seanhalle@260 236
seanhalle@260 237 }
seanhalle@260 238 PRProcess;
seanhalle@260 239 /*This structure holds all the information PR needs to manage a program. PR
seanhalle@260 240 * stores information about what percent of CPU time the program is getting,
seanhalle@260 241 *
seanhalle@260 242 */
seanhalle@260 243 typedef struct
seanhalle@260 244 { //void *semEnv;
seanhalle@260 245 //RequestHdlrFnPtr requestHandler;
seanhalle@260 246 //SlaveAssignerFnPtr slaveAssigner;
seanhalle@260 247 int32 numSlavesLive;
seanhalle@260 248 void *resultToReturn;
seanhalle@260 249
seanhalle@260 250 SlaveVP *seedSlv;
seanhalle@260 251
seanhalle@260 252 //These are used to coordinate within the main function..?
seanhalle@260 253 bool32 executionIsComplete;
seanhalle@260 254 pthread_mutex_t doneLock; //? not sure need these..?
seanhalle@260 255 pthread_cond_t doneCond;
seanhalle@260 256 }
seanhalle@260 257 PRProcess;
seanhalle@260 258
seanhalle@260 259
seanhalle@260 260 //========================= Extra Stuff Data Strucs =======================
seanhalle@260 261 typedef struct
seanhalle@260 262 {
seanhalle@260 263
seanhalle@260 264 }
seanhalle@260 265 PRExcp; //exception
seanhalle@260 266
seanhalle@260 267 //======================= OS Thread related ===============================
seanhalle@260 268
seanhalle@260 269 void * coreController( void *paramsIn ); //standard PThreads fn prototype
seanhalle@260 270 void * coreCtlr_Seq( void *paramsIn ); //standard PThreads fn prototype
seanhalle@260 271 void animationMaster( void *initData, SlaveVP *masterVP );
seanhalle@260 272
seanhalle@260 273
seanhalle@260 274 typedef struct
seanhalle@260 275 {
seanhalle@260 276 void *endThdPt;
seanhalle@260 277 unsigned int coreNum;
seanhalle@260 278 }
seanhalle@260 279 ThdParams;
seanhalle@260 280
seanhalle@260 281 //============================= Global Vars ================================
seanhalle@260 282
seanhalle@260 283 volatile MasterEnv *_PRMasterEnv __align_to_cacheline__;
seanhalle@260 284
seanhalle@260 285 //these are global, but only used for startup and shutdown
seanhalle@260 286 pthread_t coreCtlrThdHandles[ NUM_CORES ]; //pthread's virt-procr state
seanhalle@260 287 ThdParams *coreCtlrThdParams [ NUM_CORES ];
seanhalle@260 288
seanhalle@260 289 pthread_mutex_t suspendLock;
seanhalle@260 290 pthread_cond_t suspendCond;
seanhalle@260 291
seanhalle@260 292 //========================= Function Prototypes ===========================
seanhalle@260 293 /* MEANING OF WL PI SS int PROS
seanhalle@260 294 * These indicate which places the function is safe to use. They stand for:
seanhalle@260 295 *
seanhalle@260 296 * WL Wrapper Library -- wrapper lib code should only use these
seanhalle@260 297 * PI Plugin -- plugin code should only use these
seanhalle@260 298 * SS Startup and Shutdown -- designates these relate to startup & shutdown
seanhalle@260 299 * int internal to PR -- should not be used in wrapper lib or plugin
seanhalle@260 300 * PROS means "OS functions for applications to use"
seanhalle@260 301 *
seanhalle@260 302 * PR_int__ functions touch internal PR data structs and are only safe
seanhalle@260 303 * to be used inside the master lock. However, occasionally, they appear
seanhalle@260 304 * in wrapper-lib or plugin code. In those cases, very careful analysis
seanhalle@260 305 * has been done to be sure no concurrency issues could arise.
seanhalle@260 306 *
seanhalle@260 307 * PR_WL__ functions are all safe for use outside the master lock.
seanhalle@260 308 *
seanhalle@260 309 * PROS are only safe for applications to use -- they're like a second
seanhalle@260 310 * language mixed in -- but they can't be used inside plugin code, and
seanhalle@260 311 * aren't meant for use in wrapper libraries, because they are themselves
seanhalle@260 312 * wrapper-library calls!
seanhalle@260 313 */
seanhalle@260 314 //========== Startup and shutdown ==========
seanhalle@260 315 void
seanhalle@260 316 PR__start();
seanhalle@260 317
seanhalle@260 318 void
seanhalle@260 319 PR_SS__start_the_work_then_wait_until_done();
seanhalle@260 320
seanhalle@260 321 SlaveVP*
seanhalle@260 322 PR_SS__create_shutdown_slave();
seanhalle@260 323
seanhalle@260 324 void
seanhalle@260 325 PR_SS__shutdown();
seanhalle@260 326
seanhalle@260 327 void
seanhalle@260 328 PR_SS__cleanup_at_end_of_shutdown();
seanhalle@260 329
seanhalle@260 330 void
seanhalle@260 331 PR_SS__register_langlets_semEnv( PRSemEnv *semEnv, int32 VSs_MAGIC_NUMBER,
seanhalle@260 332 SlaveVP *seedVP );
seanhalle@260 333
seanhalle@260 334
seanhalle@260 335 //============== ===============
seanhalle@260 336
seanhalle@260 337 inline SlaveVP *
seanhalle@260 338 PR_int__create_slaveVP( TopLevelFnPtr fnPtr, void *dataParam );
seanhalle@260 339 #define PR_PI__create_slaveVP PR_int__create_slaveVP
seanhalle@260 340 #define PR_WL__create_slaveVP PR_int__create_slaveVP
seanhalle@260 341
seanhalle@260 342 //Use this to create processor inside entry point & other places outside
seanhalle@260 343 // the PR system boundary (IE, don't animate with a SlaveVP or MasterVP)
seanhalle@260 344 SlaveVP *
seanhalle@260 345 PR_ext__create_slaveVP( TopLevelFnPtr fnPtr, void *dataParam );
seanhalle@260 346
seanhalle@260 347 inline SlaveVP *
seanhalle@260 348 PR_int__create_slaveVP_helper( SlaveVP *newSlv, TopLevelFnPtr fnPtr,
seanhalle@260 349 void *dataParam, void *stackLocs );
seanhalle@260 350
seanhalle@260 351 inline void
seanhalle@260 352 PR_int__reset_slaveVP_to_TopLvlFn( SlaveVP *slaveVP, TopLevelFnPtr fnPtr,
seanhalle@260 353 void *dataParam);
seanhalle@260 354
seanhalle@260 355 inline void
seanhalle@260 356 PR_int__point_slaveVP_to_OneParamFn( SlaveVP *slaveVP, void *fnPtr,
seanhalle@260 357 void *param);
seanhalle@260 358
seanhalle@260 359 inline void
seanhalle@260 360 PR_int__point_slaveVP_to_TwoParamFn( SlaveVP *slaveVP, void *fnPtr,
seanhalle@260 361 void *param1, void *param2);
seanhalle@260 362
seanhalle@260 363 void
seanhalle@260 364 PR_int__dissipate_slaveVP( SlaveVP *slaveToDissipate );
seanhalle@260 365 #define PR_PI__dissipate_slaveVP PR_int__dissipate_slaveVP
seanhalle@260 366 //WL: dissipate a SlaveVP by sending a request
seanhalle@260 367
seanhalle@260 368 void
seanhalle@260 369 PR_ext__dissipate_slaveVP( SlaveVP *slaveToDissipate );
seanhalle@260 370
seanhalle@260 371 void
seanhalle@260 372 PR_int__throw_exception( char *msgStr, SlaveVP *reqstSlv, PRExcp *excpData );
seanhalle@260 373 #define PR_PI__throw_exception PR_int__throw_exception
seanhalle@260 374 void
seanhalle@260 375 PR_WL__throw_exception( char *msgStr, SlaveVP *reqstSlv, PRExcp *excpData );
seanhalle@260 376 #define PR_App__throw_exception PR_WL__throw_exception
seanhalle@260 377
seanhalle@260 378 void *
seanhalle@260 379 PR_int__give_sem_env_for( SlaveVP *animSlv );
seanhalle@260 380 #define PR_PI__give_sem_env_for PR_int__give_sem_env_for
seanhalle@260 381 #define PR_SS__give_sem_env_for PR_int__give_sem_env_for
seanhalle@260 382 //No WL version -- not safe! if use in WL, be sure data rd & wr is stable
seanhalle@260 383
seanhalle@260 384
seanhalle@260 385 inline void
seanhalle@260 386 PR_int__get_master_lock();
seanhalle@260 387
seanhalle@260 388 #define PR_int__release_master_lock() _PRMasterEnv->masterLock = UNLOCKED
seanhalle@260 389
seanhalle@260 390 inline uint32_t
seanhalle@260 391 PR_int__randomNumber();
seanhalle@260 392
seanhalle@260 393 //============== Request Related ===============
seanhalle@260 394
seanhalle@260 395 void
seanhalle@260 396 PR_int__suspend_slaveVP_and_send_req( SlaveVP *callingSlv );
seanhalle@260 397
seanhalle@260 398 inline void
seanhalle@260 399 PR_WL__add_sem_request_in_mallocd_PRReqst( void *semReqData, SlaveVP *callingSlv );
seanhalle@260 400
seanhalle@260 401 inline void
seanhalle@260 402 PR_WL__send_sem_request( void *semReqData, SlaveVP *callingSlv );
seanhalle@260 403
seanhalle@260 404 void
seanhalle@260 405 PR_WL__send_create_slaveVP_req( void *semReqData, SlaveVP *reqstingSlv );
seanhalle@260 406
seanhalle@260 407 void inline
seanhalle@260 408 PR_WL__send_dissipate_req( SlaveVP *prToDissipate );
seanhalle@260 409
seanhalle@260 410 inline void
seanhalle@260 411 PR_WL__send_PRSem_request( void *semReqData, SlaveVP *callingSlv );
seanhalle@260 412
seanhalle@260 413 PRReqst *
seanhalle@260 414 PR_PI__take_next_request_out_of( SlaveVP *slaveWithReq );
seanhalle@260 415 //#define PR_PI__take_next_request_out_of( slave ) slave->requests
seanhalle@260 416
seanhalle@260 417 //inline void *
seanhalle@260 418 //PR_PI__take_sem_reqst_from( PRReqst *req );
seanhalle@260 419 #define PR_PI__take_sem_reqst_from( req ) req->semReqData
seanhalle@260 420
seanhalle@260 421 void inline
seanhalle@260 422 PR_PI__handle_PRSemReq( PRReqst *req, SlaveVP *requestingSlv, void *semEnv,
seanhalle@260 423 ResumeSlvFnPtr resumeSlvFnPtr );
seanhalle@260 424
seanhalle@260 425 //======================== MEASUREMENT ======================
seanhalle@260 426 uint64
seanhalle@260 427 PR_WL__give_num_plugin_cycles();
seanhalle@260 428 uint32
seanhalle@260 429 PR_WL__give_num_plugin_animations();
seanhalle@260 430
seanhalle@260 431
seanhalle@260 432 //========================= Utilities =======================
seanhalle@260 433 inline char *
seanhalle@260 434 PR_int__strDup( char *str );
seanhalle@260 435
seanhalle@260 436
seanhalle@260 437 //========================= Probes =======================
seanhalle@260 438 #include "Services_Offered_by_PR/Measurement_and_Stats/probes.h"
seanhalle@260 439
seanhalle@260 440 //================================================
seanhalle@260 441 #endif /* _PR_H */
seanhalle@260 442