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