src/arch/template/machine.C

   1 /** @file
   2  * Templated machine layer
   3  * @ingroup Machine
   4  *
   5  * This file explains what the machine layer has to provide (which functions
   6  * need to be implemented). Depending on the flags set in the files
   7  * conv-common.h, conv-mach.h and the possible other suboption file
   8  * conv-mach-suboption.h, some additional functions may be needed to be
   9  * implemented.
  10
  11  * Throughout the file, "#if CMK_VARIABLE" means it was set to 1 in the .h
  12  * files, "#if ! CMK_VARIABLE" means it was set to 0.
  13
  14 /*@{*/
  15
  16 /*==========================================================*/
  17 /*==========================================================*/
  18 /*==========================================================*/
  19
  20 /** FUNCTIONS ALWAYS TO BE IMPLEMENTED
  21
  22  * This first section of the file reports which methods must always be
  23  * implemented inside the machine layer.
  24  */
  25
  26 void ConverseInit(int, char**, CmiStartFn, int, int);
  27 void ConverseExit(int exitcode);
  28
  29 void CmiAbort(const char *);
  30
  31 void          CmiSyncSendFn(int, int, char *);
  32 void          CmiFreeSendFn(int, int, char *);
  33
  34 void          CmiSyncBroadcastFn(int, char *);
  35 void          CmiFreeBroadcastFn(int, char *);
  36
  37 void          CmiSyncBroadcastAllFn(int, char *);
  38 void          CmiFreeBroadcastAllFn(int, char *);
  39
  40 /* Poll the network for messages */
  41 //Different machine layers have different names for this function
  42
  43 /* Poll the network and when a message arrives and insert this arrived
  44    message into the local queue. For SMP this message would have to be
  45    inserted into the thread's queue with the correct rank **/
  46 //Pump messages is called when the processor goes idle
  47 void PumpMessages();
  48
  49 /* Free network resources when the messages have been sent out. Also
  50 called when machine goes idle and at other places depending on the
  51 implementation *********/
  52 void CmiReleaseSentMessages();
  53
  54 //Called when the processor goes idle. Typically calls pump messages
  55 //and releaseSentMessages. The idle handler has to be explicitly
  56 //registered in ConverseInit through a call to CcdCallOnConditionKeep
  57 void CmiNotifyIdle();
  58
  59
  60 /*==========================================================*/
  61 /*==========================================================*/
  62 /*==========================================================*/
  63
  64 /************ Recommended routines ***********************/
  65 /************ You dont have to implement these but they are supported
  66  in the converse syntax and some rare programs may crash. But most
  67  programs dont need them. *************/
  68
  69 CmiCommHandle CmiAsyncSendFn(int, int, char *);
  70 CmiCommHandle CmiAsyncBroadcastFn(int, char *);
  71 CmiCommHandle CmiAsyncBroadcastAllFn(int, char *);
  72
  73 int           CmiAsyncMsgSent(CmiCommHandle handle);
  74 void          CmiReleaseCommHandle(CmiCommHandle handle);
  75
  76
  77 /*==========================================================*/
  78 /*==========================================================*/
  79 /*==========================================================*/
  80
  81 //Optional routines which could use common code which is shared with
  82 //other machine layer implementations.
  83
  84 /* MULTICAST/VECTOR SENDING FUNCTIONS
  85
  86  * In relations to some flags, some other delivery functions may be needed.
  87  */
  88
  89 #if ! CMK_MULTICAST_LIST_USE_COMMON_CODE
  90 void          CmiSyncListSendFn(int, int *, int, char*);
  91 CmiCommHandle CmiAsyncListSendFn(int, int *, int, char*);
  92 void          CmiFreeListSendFn(int, int *, int, char*);
  93 #endif
  94
  95 #if ! CMK_MULTICAST_GROUP_USE_COMMON_CODE
  96 void          CmiSyncMulticastFn(CmiGroup, int, char*);
  97 CmiCommHandle CmiAsyncMulticastFn(CmiGroup, int, char*);
  98 void          CmiFreeMulticastFn(CmiGroup, int, char*);
  99 #endif
 100
 101 #if ! CMK_VECTOR_SEND_USES_COMMON_CODE
 102 void          CmiSyncVectorSend(int, int, int *, char **);
 103 CmiCommHandle CmiAsyncVectorSend(int, int, int *, char **);
 104 void          CmiSyncVectorSendAndFree(int, int, int *, char **);
 105 #endif
 106
 107
 108 /** NODE SENDING FUNCTIONS
 109
 110  * If there is a node queue, and we consider also nodes as entity (tipically in
 111  * SMP versions), these functions are needed.
 112  */
 113
 114 #if CMK_NODE_QUEUE_AVAILABLE
 115
 116 void          CmiSyncNodeSendFn(int, int, char *);
 117 CmiCommHandle CmiAsyncNodeSendFn(int, int, char *);
 118 void          CmiFreeNodeSendFn(int, int, char *);
 119
 120 void          CmiSyncNodeBroadcastFn(int, char *);
 121 CmiCommHandle CmiAsyncNodeBroadcastFn(int, char *);
 122 void          CmiFreeNodeBroadcastFn(int, char *);
 123
 124 void          CmiSyncNodeBroadcastAllFn(int, char *);
 125 CmiCommHandle CmiAsyncNodeBroadcastAllFn(int, char *);
 126 void          CmiFreeNodeBroadcastAllFn(int, char *);
 127
 128 #endif
 129
 130
 131 /** GROUPS DEFINITION
 132
 133  * For groups of processors (establishing and managing) some more functions are
 134  * needed, they also con be found in common code (convcore.C) or here.
 135  */
 136
 137 #if ! CMK_MULTICAST_DEF_USE_COMMON_CODE
 138 void     CmiGroupInit(void);
 139 CmiGroup CmiEstablishGroup(int npes, int *pes);
 140 void     CmiLookupGroup(CmiGroup grp, int *npes, int **pes);
 141 #endif
 142
 143
 144 /** MESSAGE DELIVERY FUNCTIONS
 145
 146  * In order to deliver the messages to objects (either converse register
 147  * handlers, or charm objects), a scheduler is needed. The one implemented in
 148  * convcore.C can be used, or a new one can be implemented here. At present, all
 149  * machines use the default one, exept sim-linux.
 150
 151  * If the one in convcore.C is used, still one function is needed.
 152  */
 153
 154 #if CMK_CMIDELIVERS_USE_COMMON_CODE /* use the default one */
 155
 156 CpvDeclare(void*, CmiLocalQueue);
 157 void *CmiGetNonLocal(void);
 158
 159 #elif /* reimplement the scheduler and delivery */
 160
 161 void CsdSchedulerState_new(CsdSchedulerState_t *state);
 162 void *CsdNextMessage(CsdSchedulerState_t *state);
 163 int  CsdScheduler(int maxmsgs);
 164
 165 void CmiDeliversInit(void);
 166 int  CmiDeliverMsgs(int maxmsgs);
 167 void CmiDeliverSpecificMsg(int handler);
 168
 169 #endif
 170
 171
 172 /** SHARED VARIABLES DEFINITIONS
 173
 174  * In relation to which CMK_SHARED_VARS_ flag is set, different
 175  * functions/variables need to be defined and initialized correctly.
 176  */
 177
 178 #if CMK_SHARED_VARS_UNAVAILABLE /* Non-SMP version of shared vars. */
 179
 180 int _Cmi_mype;
 181 int _Cmi_numpes;
 182 int _Cmi_myrank; /* Normally zero; only 1 during SIGIO handling */
 183
 184 void CmiMemLock(void);
 185 void CmiMemUnlock(void);
 186
 187 #endif
 188
 189 #if CMK_SHARED_VARS_POSIX_THREADS_SMP
 190
 191 int _Cmi_numpes;
 192 int _Cmi_mynodesize;
 193 int _Cmi_mynode;
 194 int _Cmi_numnodes;
 195
 196 int CmiMyPe(void);
 197 int CmiMyRank(void);
 198 int CmiNodeFirst(int node);
 199 int CmiNodeSize(int node);
 200 int CmiNodeOf(int pe);
 201 int CmiRankOf(int pe);
 202
 203 /* optional, these functions are implemented in "machine-smp.C", so including
 204    this file avoid the necessity to reimplement them.
 205  */
 206 void CmiNodeBarrier(void);
 207 void CmiNodeAllBarrier(void);
 208 CmiNodeLock CmiCreateLock(void);
 209 void CmiDestroyLock(CmiNodeLock lock);
 210
 211 #endif
 212
 213 /* NOT VERY USEFUL */
 214 #if CMK_SHARED_VARS_UNIPROCESSOR /*Used only by uth- and sim- versions*/
 215
 216 int _Cmi_mype;
 217 int _Cmi_numpes;
 218
 219 void         CmiLock(CmiNodeLock lock);
 220 void         CmiUnlock(CmiNodeLock lock);
 221 int          CmiTryLock(CmiNodeLock lock);
 222
 223 /* optional, these functions are implemented in "machine-smp.C", so including
 224    this file avoid the necessity to reimplement them.
 225  */
 226 void CmiNodeBarrier(void);
 227 void CmiNodeAllBarrier(void);
 228 CmiNodeLock  CmiCreateLock(void);
 229 void         CmiDestroyLock(CmiNodeLock lock);
 230
 231 #endif
 232
 233 /* NOT VERY USEFUL */
 234 #if CMK_SHARED_VARS_NT_THREADS /*Used only by win32 versions*/
 235
 236 int _Cmi_numpes;
 237 int _Cmi_mynodesize;
 238 int _Cmi_mynode;
 239 int _Cmi_numnodes;
 240
 241 int CmiMyPe(void);
 242 int CmiMyRank(void);
 243 int CmiNodeFirst(int node);
 244 int CmiNodeSize(int node);
 245 int CmiNodeOf(int pe);
 246 int CmiRankOf(int pe);
 247
 248 /* optional, these functions are implemented in "machine-smp.C", so including
 249    this file avoid the necessity to reimplement them.
 250  */
 251 void CmiNodeBarrier(void);
 252 void CmiNodeAllBarrier(void);
 253 CmiNodeLock CmiCreateLock(void);
 254 void CmiDestroyLock(CmiNodeLock lock);
 255
 256 #endif
 257
 258
 259 /** TIMERS DEFINITIONS
 260
 261  * In relation to what CMK_TIMER_USE_ is selected, some * functions may need to
 262  * be implemented.
 263  */
 264
 265 /* If all the CMK_TIMER_USE_ are set to 0, the following timer functions are
 266    needed. */
 267
 268 void   CmiTimerInit(char **argv);
 269 double CmiTimer(void);
 270 double CmiWallTimer(void);
 271 double CmiCpuTimer(void);
 272 int    CmiTimerIsSynchronized(void);
 273
 274 /* If one of the following is set to 1, barriers are needed:
 275    CMK_TIMER_USE_GETRUSAGE
 276    CMK_TIMER_USE_RDTSC
 277 */
 278
 279 int CmiBarrier(void);
 280 int CmiBarrierZero(void);
 281
 282
 283 /** PRINTF FUNCTIONS
 284
 285  * Default code is provided in convcore.C but for particular architectures they
 286  * can be reimplemented. At present only netlrts- versions reimplement them.
 287
 288  */
 289
 290 #if CMK_CMIPRINTF_IS_A_BUILTIN
 291
 292 void CmiPrintf(const char *, ...);
 293 void CmiError(const char *, ...);
 294 int  CmiScanf(const char *, ...);
 295
 296 #endif
 297
 298
 299 /** SPANNING TREE
 300
 301  * During some working operations (such as quiescence detection), spanning trees
 302  * are used. Default code in convcore.C can be used, or a new definition can be
 303  * implemented here.
 304  */
 305
 306 #if ! CMK_SPANTREE_USE_COMMON_CODE
 307
 308 int      CmiNumSpanTreeChildren(int) ;
 309 int      CmiSpanTreeParent(int) ;
 310 void     CmiSpanTreeChildren(int node, int *children);
 311
 312 int      CmiNumNodeSpanTreeChildren(int);
 313 int      CmiNodeSpanTreeParent(int) ;
 314 void     CmiNodeSpanTreeChildren(int node, int *children) ;
 315
 316 #endif
 317
 318
 319
 320 /** IMMEDIATE MESSAGES
 321
 322  * If immediate messages are supported, the following function is needed. There
 323  * is an exeption if the machine progress is also defined (see later for this).
 324
 325  * Moreover, the file "immediate.C" should be included, otherwise all its
 326  * functions and variables have to be redefined.
 327 */
 328
 329 #if CMK_CCS_AVAILABLE
 330
 331 #include "immediate.C"
 332
 333 #if ! CMK_MACHINE_PROGRESS_DEFINED /* Hack for some machines */
 334 void CmiProbeImmediateMsg(void);
 335 #endif
 336
 337 #endif
 338
 339
 340 /** MACHINE PROGRESS DEFINED
 341
 342  * Some machines (like BlueGene/L) do not have coprocessors, and messages need
 343  * to be pulled out of the network manually. For this reason the following
 344  * functions are needed. Notice that the function "CmiProbeImmediateMsg" must
 345  * not be defined anymore.
 346  */
 347
 348 #if CMK_MACHINE_PROGRESS_DEFINED
 349
 350 CpvDeclare(unsigned, networkProgressCount);
 351 int  networkProgressPeriod;
 352
 353 void CmiMachineProgressImpl(void);
 354
 355 #endif