]>
Commit | Line | Data |
---|---|---|
5f520819 | 1 | /* |
2eab9666 | 2 | * Copyright 2010-2015 Intel Corporation. |
5f520819 KY |
3 | * |
4 | * This library is free software; you can redistribute it and/or modify it | |
5 | * under the terms of the GNU Lesser General Public License as published | |
6 | * by the Free Software Foundation, version 2.1. | |
7 | * | |
8 | * This library is distributed in the hope that it will be useful, | |
9 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
10 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
11 | * Lesser General Public License for more details. | |
12 | * | |
13 | * You should have received a copy of the GNU Lesser General Public | |
14 | * License along with this library; if not, write to the Free Software | |
15 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA | |
16 | * 02110-1301 USA. | |
17 | * | |
18 | * Disclaimer: The codes contained in these modules may be specific | |
19 | * to the Intel Software Development Platform codenamed Knights Ferry, | |
20 | * and the Intel product codenamed Knights Corner, and are not backward | |
21 | * compatible with other Intel products. Additionally, Intel will NOT | |
22 | * support the codes or instruction set in future products. | |
23 | * | |
24 | * Intel offers no warranty of any kind regarding the code. This code is | |
25 | * licensed on an "AS IS" basis and Intel is not obligated to provide | |
26 | * any support, assistance, installation, training, or other services | |
27 | * of any kind. Intel is also not obligated to provide any updates, | |
28 | * enhancements or extensions. Intel specifically disclaims any warranty | |
29 | * of merchantability, non-infringement, fitness for any particular | |
30 | * purpose, and any other warranty. | |
31 | * | |
32 | * Further, Intel disclaims all liability of any kind, including but | |
33 | * not limited to liability for infringement of any proprietary rights, | |
34 | * relating to the use of the code, even if Intel is notified of the | |
35 | * possibility of such liability. Except as expressly stated in an Intel | |
36 | * license agreement provided with this code and agreed upon with Intel, | |
37 | * no license, express or implied, by estoppel or otherwise, to any | |
38 | * intellectual property rights is granted herein. | |
39 | */ | |
40 | /** | |
41 | Description: | |
42 | Define APIs of MYO for compiler or pre-processor to transfer original programs. | |
43 | */ | |
44 | ||
45 | #ifndef _MYO_IMPL_H_ | |
46 | #define _MYO_IMPL_H_ | |
47 | ||
48 | /** @ingroup MYO | |
49 | * @addtogroup MYOIMPL_API | |
50 | @{ | |
51 | * @file myoimpl.h | |
52 | */ | |
53 | ||
54 | #ifdef __cplusplus | |
55 | extern "C" { | |
56 | #define EXTERN_C extern "C" | |
57 | #else | |
58 | #define EXTERN_C /* nothing */ | |
59 | #endif | |
60 | ||
61 | # define MYOACCESSAPI /* nothing */ | |
62 | ||
63 | #ifdef DEFINE_ARENA_API_CILK_SHARED | |
64 | #define CILK_SHARED _Cilk_shared | |
65 | #else | |
66 | #define CILK_SHARED /* nothing */ | |
67 | #endif | |
68 | ||
69 | /* **************************************************************************** *\ | |
70 | APIs to enable functions being remotely called | |
71 | \* **************************************************************************** */ | |
72 | ||
73 | typedef void *(*MyoiRemoteFuncType)(void *); | |
74 | ||
75 | /** @fn extern MyoError myoiRemoteFuncRegister(MyoiRemoteFuncType in_pFuncAddr, | |
76 | * const char *in_pFuncName) | |
77 | * @brief Register a function so that it can be remotely called. This should be | |
78 | * done in myoiUserInit or before calling myoiLibInit. After myoiLibInit, | |
79 | * there will be a table on all peers, which contains the information for | |
80 | * all remotely callable functions. | |
81 | * | |
82 | * @param in_pWrapFuncAddr address of the wrapper function. | |
83 | * @param in_pFuncName name of the function. | |
84 | * @return | |
85 | * MYO_SUCCESS; or | |
86 | * an error number to indicate the error. | |
87 | **/ | |
88 | ||
89 | MYOACCESSAPI | |
90 | MyoError myoiRemoteFuncRegister(MyoiRemoteFuncType in_pFuncAddr, | |
91 | const char *in_pFuncName); | |
92 | /** @fn extern MyoError myoiRemoteFuncLookupByName(char *in_pFuncName, | |
93 | * MyoiRemoteFuncType *out_pWrapFuncAddr) | |
94 | * @brief Get the address of the wrapper function by looking up the table | |
95 | * by name. This API can be used when assigning a function pointer to | |
96 | * remotely callable functions. | |
97 | * | |
98 | * @param in_pFuncName name of the function. | |
99 | * @param out_pWrapFuncAddr address of the wrapper function. | |
100 | * @return | |
101 | * MYO_SUCCESS; or | |
102 | * an error number to indicate the error. | |
103 | **/ | |
104 | MYOACCESSAPI MyoError myoiRemoteFuncLookupByName(char *in_pFuncName, | |
105 | MyoiRemoteFuncType *out_pWrapFuncAddr); | |
106 | ||
107 | /** @fn extern MyoError myoiRemoteFuncLookupByAddr(MyoiRemoteFuncType | |
108 | * in_pWrapFuncAddr,char **out_pFuncName) | |
109 | * @brief Get the name of a remote function by looking up the table by | |
110 | * the address. This API can be used when calling a remotely callable | |
111 | * function by a function pointer. | |
112 | * | |
113 | * @param in_pWrapFuncAddr address of the function. | |
114 | * @param out_pFuncName name of the function. | |
115 | * @return | |
116 | * MYO_SUCCESS; or | |
117 | * an error number to indicate the error. | |
118 | **/ | |
119 | MYOACCESSAPI MyoError myoiRemoteFuncLookupByAddr(MyoiRemoteFuncType in_pWrapFuncAddr, | |
120 | char **out_pFuncName); | |
121 | ||
122 | //! Host Side Shared Function Pointer Entry Struct | |
123 | typedef struct { | |
124 | //! Function Name | |
125 | const char *funcName; | |
126 | //! Function Address | |
127 | void *funcAddr; | |
128 | //! Local Thunk Address | |
129 | void *localThunkAddr; | |
130 | } MyoiHostSharedFptrEntry; | |
131 | ||
132 | //! Target Side Shared Function Pointer Entry Struct | |
133 | typedef struct { | |
134 | //! Function Name | |
135 | const char *funcName; | |
136 | //! Function Address | |
137 | void *funcAddr; | |
138 | //! Wrap Function Address | |
139 | void *wrapFuncAddr; | |
140 | //! Locak Thunk Address | |
141 | void *localThunkAddr; | |
142 | } MyoiTargetSharedFptrEntry; | |
143 | ||
144 | /** | |
145 | * @cond INCLUDE_MYO_INTERNAL_DOCUMENTATION | |
146 | * @fn extern MyoError myoiHostFptrTableRegister(void *in_pAddrOfFptrTable, | |
147 | * int in_NumEntry, int in_Ordered) | |
148 | * @brief Register shared functions on host side. A 16 byte thunk will be | |
149 | * allocated for each function entry in non-coherent shared memory. The | |
150 | * thunk will contain a jump instruction to the local version of the | |
151 | * shared function, which is provided by the second item of the function | |
152 | * entry. Also, the address of the thunk will be stored to the 3rd item | |
153 | * of the function entry for Compiler usage. | |
154 | * | |
155 | * @param in_pAddrOfFptrTable start address of the shared function | |
156 | * table, assuming it follows the format of MyoiHostSharedFptrEntry. | |
157 | * @param in_NumEntry number of entry in the table. | |
158 | * @param in_Ordered whether the table is ordered by function name. | |
159 | * @return | |
160 | * MYO_SUCCESS; or | |
161 | * an error number to indicate the error. | |
162 | **/ | |
163 | MYOACCESSAPI | |
164 | MyoError myoiHostFptrTableRegister( | |
165 | void *in_pAddrOfFptrTable, int in_NumEntry, int in_Ordered); | |
166 | ||
167 | /** @fn extern MyoError myoiTargetFptrTableRegister(void *in_pAddrOfFptrTable, | |
168 | * int in_NumEntry, int in_Ordered) | |
169 | * @brief Register shared functions on target side. This function is the | |
170 | * same as myoiHostFptrTableRegister, except it does not need to allocate | |
171 | * thunks from non-coherent shared memory for each function entry, but | |
172 | * instead looks up this information from a table retrieved from the | |
173 | * Host side. | |
174 | * | |
175 | * @param in_pAddrOfFptrTable start address of the shared function | |
176 | * table, assuming it follows the format of MyoiTargetSharedFptrEntry. | |
177 | * @param in_NumEntry number of entry in the table. | |
178 | * @param in_Ordered whether the table is ordered by function name. | |
179 | * @return | |
180 | * MYO_SUCCESS; or | |
181 | * an error number to indicate the error. | |
182 | **/ | |
183 | extern MyoError myoiTargetFptrTableRegister( | |
184 | void *in_pAddrOfFptrTable, int in_NumEntry, int in_Ordered); | |
185 | /** | |
186 | * @endcond | |
187 | **/ | |
188 | ||
189 | /* *************************************************************************** *\ | |
190 | APIs for remote function calls | |
191 | \* *************************************************************************** */ | |
192 | ||
193 | typedef void * MyoiRFuncCallHandle; | |
194 | ||
195 | /** @fn extern MyoiRFuncCallHandle myoiRemoteCall(char *in_pFuncName, | |
196 | * void *in_pArgs, int in_deviceNum) | |
197 | * @brief Call a remote callable function. If there are multiple arguments | |
198 | * for the function, pack them to a shared buffer beforehand and take the | |
199 | * address of the shared buffer as this function. After receiving the call | |
200 | * requests from other peers, the arguments should be unpacked from the | |
201 | * shared buffer before calling the target function. The shared buffer | |
202 | * can also be used to store the return value of the function. | |
203 | * | |
204 | * @param in_pFuncName name of the function. | |
205 | * @param in_pArgs address of the shared buffer. | |
206 | * @return | |
207 | * Handle used to check the result. | |
208 | **/ | |
209 | MYOACCESSAPI | |
210 | MyoiRFuncCallHandle myoiRemoteCall(const char *in_pFuncName, void *in_pArgs, int in_deviceNum); | |
211 | ||
212 | /** | |
213 | * @cond INCLUDE_MYO_INTERNAL_DOCUMENTATION | |
214 | * @fn extern MyoError myoiRemoteThunkCall(void *in_funcThunkAddr, void *in_pArgs, int in_deviceNum) | |
215 | * @brief Call a remote callable function. If there are multiple arguments for | |
216 | * the function, pack them to a shared buffer beforehand and take the address | |
217 | * of the shared buffer as this function. After receiving the call requests | |
218 | * from other peers, the arguments should be unpacked from the shared buffer | |
219 | * before calling the target function. The shared buffer can also be used to | |
220 | * store the return value of the function. | |
221 | * | |
222 | * @param in_funcThunkAddr pointer to function thunk in the non-coherent | |
223 | * shared memory. | |
224 | * @param in_pArgs address of the shared buffer. | |
225 | * @PARAM in_deviceNum: device ID (0-N-1) for the MIC device to run | |
226 | * function call. -1 request causes MYO to schedule an available device. | |
227 | * For RPC from device to host, in_deviceNum should always be -1. | |
228 | * @return | |
229 | * MYO_SUCCESS; or | |
230 | * an error number to indicate the error. | |
231 | **/ | |
232 | MYOACCESSAPI | |
233 | MyoError myoiRemoteThunkCall(void *in_funcThunkAddr, void *in_pArgs, int in_deviceNum); | |
234 | /** | |
235 | * @endcond | |
236 | **/ | |
237 | ||
238 | /** @fn extern MyoError myoiCheckResult(MyoiRFuncCallHandle in_Handle) | |
239 | * @brief Check whether the remote call is done. | |
240 | * | |
241 | * @param in_Handle handle of the remote call. | |
242 | * @return | |
243 | * MYO_SUCCESS (done); or | |
244 | * an error number to indicate the error. | |
245 | **/ | |
246 | extern MyoError myoiCheckResult(MyoiRFuncCallHandle in_Handle); | |
247 | ||
248 | /** @fn extern MyoError myoiGetResult(MyoiRFuncCallHandle in_Handle) | |
249 | * @brief Wait till the remote call is done. | |
250 | * | |
251 | * @param in_Handle handle of the remote call. | |
252 | * @return | |
253 | * MYO_SUCCESS; or | |
254 | * an error number to indicate the error. | |
255 | **/ | |
256 | MYOACCESSAPI | |
257 | MyoError myoiGetResult(MyoiRFuncCallHandle in_Handle); | |
258 | ||
259 | /* **************************************************************************** *\ | |
260 | APIs related with shared variables. | |
261 | \* **************************************************************************** */ | |
262 | ||
263 | /* | |
264 | * It is Compiler's responsibility to make sure all shared variables | |
265 | * located in shared memory space and have the same address in all sides. | |
266 | * However, it is hard for Compiler to do this. So we propose a solution | |
267 | * which is changing the definition of all shared variables and accessing | |
268 | * them indirectly, and making sure all shared variables pointing | |
269 | * to the same shared space on all sides. For example, | |
270 | * | |
271 | * "shared int a;" is changed to "shared int *a"; | |
272 | * Also all the accesses to "a" is change to "*a". | |
273 | * | |
274 | * We suppose the shared memory for each shared variable is allocated on | |
275 | * host side by Compiler. For the upper example, Compiler can call: | |
276 | * | |
277 | * a = (shared int *) myoSharedMalloc(sizeof(shared int)); | |
278 | * | |
279 | * Now the issue is how to make "a" on other sides also pointing to the | |
280 | * same shared memory on other sides. We provide two methods to do this. | |
281 | * They can be used in a hybrid way. | |
282 | */ | |
283 | ||
284 | /* | |
285 | * The first method is calling myoiVarRegister for each shared variable | |
286 | * on all sides in myoiUserInit. On host side, we will get a table containing | |
287 | * a table containing the shared address and name of each shared variable. | |
288 | * After calling myoiUserInit, we will propagate the table to other sides. | |
289 | * On card side, after getting the table from host, myoiUserInit is called. | |
290 | * When calling myoiVarRegister in myoiUserInit, we will make local pointer | |
291 | * of each shared variable pointing to the same shared memory with the local | |
292 | * pointer on host side of the same shared variable pointing to. | |
293 | */ | |
294 | ||
295 | /* | |
296 | * The second method suppose that Compiler already have a table on all sides. | |
297 | * On host side, the table contains the name and the shared address of each | |
298 | * shared variable. On card side, the table contains the name of each shared | |
299 | * variable and the address of the local pointer which will pointing to shared | |
300 | * memory space. | |
301 | * | |
302 | * On host side, Compiler generates a call to myoiHostVarTablePropagate | |
303 | * after initializing MYO runtime and making the host side table ready. | |
304 | * On card side, Compiler uses myoiMicVarTableRegister to tell | |
305 | * the runtime where the card side table is. | |
306 | * | |
307 | * Since there may be multiple libraries on card side for the same application, | |
308 | * myoiHostVarTablePropagate and myoiMicVarTableRegister can be called multiple | |
309 | * times and called simultaneously. | |
310 | * | |
311 | * Inside runtime, the local pointer of the same shared variable on all sides | |
312 | * will be make sure pointing to the same shared space by using the information | |
313 | * of the Compiler provided tables. | |
314 | */ | |
315 | ||
316 | /* | |
317 | * Comipler knows the following two structures to make sure the var table | |
318 | * has the following format. | |
319 | */ | |
320 | ||
321 | /* | |
322 | * This is structure of the Shared var table entry. This table contains | |
323 | * the shared address and name of each shared variable | |
324 | */ | |
325 | ||
326 | /** @fn extern MyoError myoiVarRegister(void *in_pAddrOfLocalPtrToShared, char *in_pSVarName) | |
327 | * @brief Register shared variables. Call it on all sides in myoiUserInit. | |
328 | * On host side, make sure calling it after allocating shared memory for | |
329 | * the shared variables by calling myoSharedMalloc. | |
330 | * | |
331 | * @param in_pAddrOfLocalPtrToShared the address assigned by the compiler | |
332 | * for the shared variable, which is the address of a local pointer, | |
333 | * pointing to shared memory space. | |
334 | * @param in_pSVarName name of shared variable. | |
335 | * @return | |
336 | * MYO_SUCCESS; or | |
337 | * an error number to indicate the error. | |
338 | **/ | |
339 | MYOACCESSAPI | |
340 | MyoError myoiVarRegister( | |
341 | void *in_pAddrOfLocalPtrToShared, const char *in_pSVarName); | |
342 | ||
343 | /* | |
344 | * Compiler knows the following two structures to make sure the var table | |
345 | * has the following format. | |
346 | */ | |
347 | ||
348 | /** | |
349 | * This is structure of the Shared var table entry. This table contains | |
350 | * the shared address and name of each shared variable | |
351 | **/ | |
352 | typedef struct { | |
353 | //! Variable Name | |
354 | const char *varName; | |
355 | //! Shared Address | |
356 | void *sharedAddr; | |
357 | } MyoiSharedVarEntry; | |
358 | ||
359 | //! Structure of the var table entry on host | |
360 | typedef struct { | |
361 | //! Variable Name | |
362 | const char *varName; | |
363 | //! Variable Size | |
364 | int size; | |
365 | //! Local pointer to Shared var | |
366 | void *ptrToLocalPtrToShared; | |
367 | } MyoiHostSharedVarEntry; | |
368 | ||
369 | //! Structure of the var table entry on card | |
370 | typedef struct { | |
371 | //! Variable Name | |
372 | const char *varName; | |
373 | //! Local pointer to Shared var | |
374 | void *ptrToLocalPtrToShared; | |
375 | } MyoiMicSharedVarEntry; | |
376 | ||
377 | /** @fn extern MyoError myoiHostVarTablePropagate(void *in_pAddrOfSVarTable, int in_NumEntry) | |
378 | * @brief Send the host side var table to the card side. Card side will also | |
379 | * have a copy of the host side var table after this propagation, although it | |
380 | * is in an internal format different than the original host side var table, | |
381 | * due to implementation convenience. | |
382 | * | |
383 | * @param in_pAddrOfSVarTable start address of the host side var table, | |
384 | * assuming it follows the format of MyoiSharedVarEntry. | |
385 | * @param in_NumEntry number of entry in the table. | |
386 | * @return | |
387 | * MYO_SUCCESS; or | |
388 | * an error number to indicate the error. | |
389 | **/ | |
390 | MYOACCESSAPI MyoError myoiHostVarTablePropagate( | |
391 | void *in_pAddrOfSVarTable, int in_NumEntry); | |
392 | ||
393 | /** | |
394 | * @cond INCLUDE_MYO_INTERNAL_DOCUMENTATION | |
395 | * @fn extern MyoError myoiMicVarTableRegister(void *in_pAddrOfSVarTable, int in_NumEntry) | |
396 | * @brief Tell the runtime where the card side table is. | |
397 | * | |
398 | * @param in_pAddrOfSVarTable start address of the card side var | |
399 | * table, assuming it follows the format of MyoiMicSharedVarEntry. | |
400 | * @param in_NumEntry number of entry in the table. | |
401 | * @return | |
402 | * MYO_SUCCESS; or | |
403 | * an error number to indicate the error. | |
404 | **/ | |
405 | extern MyoError myoiMicVarTableRegister( | |
406 | void *in_pAddrOfSVarTable, int in_NumEntry); | |
407 | /** | |
408 | * @endcond | |
409 | **/ | |
410 | ||
411 | /** @fn MyoError myoiHostSharedMallocTableRegister(void *in_pAddrOfSVarTable, int in_NumEntry, int in_Ordered) | |
412 | * @brief Allocate shared memory for all shared variables in the table. | |
413 | * Also update local address of the shared variable with new shared address. | |
414 | * | |
415 | * @param in_pAddrOfSVarTable start address of the shared variable table, | |
416 | * assuming it follows the format of MyoiHostSharedVarEntry. | |
417 | * @param in_NumEntry number of entry in the table. | |
418 | * @param in_Ordered whether the table ordered by name. | |
419 | * @return | |
420 | * MYO_SUCCESS; or | |
421 | * an error number to indicate the error. | |
422 | **/ | |
423 | MYOACCESSAPI | |
424 | MyoError myoiHostSharedMallocTableRegister( | |
425 | void *in_pAddrOfSVarTable, int in_NumEntry, int in_Ordered); | |
426 | ||
427 | /** @fn extern MyoError myoiTargetSharedMallocTableRegister(void *in_pAddrOfSVarTable, int in_NumEntry, int in_Ordered) | |
428 | * @brief Register the shared variables on the target side. | |
429 | * | |
430 | * @param in_pAddrOfSVarTable start address of the shared varaible table, | |
431 | * assuming it follows the format of MyoiMicSharedVarEntry. | |
432 | * @param in_NumEntry number of entry in the table. | |
433 | * @param in_Ordered whether the table ordered by name. | |
434 | * @return | |
435 | * MYO_SUCCESS; or | |
436 | * an error number to indicate the error. | |
437 | **/ | |
438 | extern MyoError myoiTargetSharedMallocTableRegister( | |
439 | void *in_pAddrOfSVarTable, int in_NumEntry, int in_Ordered); | |
440 | ||
441 | /** @fn MyoError myoiLibInit(void * in_args, void (*userInitFunc)) | |
442 | * @brief Init entry of the MYO library responsible for initializing | |
443 | * the runtime. | |
444 | * | |
445 | * @param in_args mechanism to pass arguments to the Initialization | |
446 | * routine. The default value of NULL would mean the host is blocked | |
447 | * on the completion of myoiLibInit() on all nodes. A subset of the | |
448 | * installed cards can be intialized by passing an array of | |
449 | * MyoiUserParams. For example, in a system with two cards, to run a | |
450 | * MYO application only on the second card, intialize the array as | |
451 | * follows: | |
452 | * @code | |
453 | * MyoiUserParams UserParas[64]; | |
454 | * UserParas[0].type = MYOI_USERPARAMS_DEVID; | |
455 | * UserParas[0].nodeid = 2; | |
456 | * UserParas[1].type = MYOI_USERPARAMS_LAST_MSG; | |
457 | * if(MYO_SUCCESS != myoiLibInit(&UserParas, (void*)&myoiUserInit)) { | |
458 | * printf("Failed to initialize MYO runtime\n"); | |
459 | * return -1; | |
460 | * } | |
461 | * @endcode | |
2eab9666 IV |
462 | * This intialization is required only in the client/host side |
463 | * of the application. The server/card side executable should be | |
464 | * executed only on the second card in this case. | |
465 | * | |
466 | * Another capability for the MyoiUserParams structure in MYO is specifying | |
467 | * a remote procedure call to be executed on the host or card, immediately after | |
468 | * myoiLibInit() completes. This capability is useful because some calls in | |
469 | * MYO return immediately, but do not actually complete until after the MYO | |
470 | * library is completely initialized on all peers. An example follows, | |
471 | * showing how to cause MYO to execute the registered function named | |
472 | * "PostMyoLibInitFunction" on the first card only: | |
473 | * @code | |
474 | * MyoiUserParams UserParas[64]; | |
475 | * UserParas[0].type = MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC; | |
476 | * UserParas[0].nodeid = 1; | |
477 | * SetPostLibInitFuncName(UserParas[1], "PostMyoLibInitFunction"); | |
478 | * UserParas[2].type = MYOI_USERPARAMS_LAST_MSG; | |
479 | * if(MYO_SUCCESS != myoiLibInit(&UserParas, (void*)&myoiUserInit)) { | |
480 | * printf("Failed to initialize MYO runtime\n"); | |
481 | * return -1; | |
482 | * } | |
483 | * @endcode | |
484 | * | |
485 | * Note, to cause PostMyoLibInitFunction to be executed on ALL cards, | |
486 | * specify: MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC_ALL_NODES for the nodeid. | |
487 | * That is: | |
488 | * @code | |
489 | * UserParas[0].nodeid = MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC_ALL_NODES; | |
490 | * @endcode | |
5f520819 | 491 | * |
2eab9666 | 492 | * @param userInitFunc Shared variables and remote functions are |
5f520819 KY |
493 | * registered in this routine, which is called by the runtime during |
494 | * library initialization. | |
495 | * @return | |
496 | * MYO_SUCCESS; | |
497 | * MYO_ERROR; | |
498 | **/ | |
499 | MYOACCESSAPI | |
500 | MyoError myoiLibInit(void * in_args, void *userInitFunc /*userInitFunc must be: MyoError (*userInitFunc)(void) */); | |
501 | ||
2eab9666 IV |
502 | /** @fn extern MyoError myoiSupportsFeature(MyoFeatureType myoFeature) |
503 | * @brief Supports runtime query to determine whether a feature is supported | |
504 | * by the myo that is installed on the system. This function is intended to | |
505 | * support client code to query the myo library to determine whether its set | |
506 | * of capabilities are able to support the client's needs. | |
507 | * | |
508 | * @param myoFeature The feature that is to be inquired about. | |
509 | * @return | |
510 | * MYO_SUCCESS; if the feature is supported. | |
511 | * MYO_FEATURE_NOT_IMPLEMENTED if the feature is not supported. | |
512 | * | |
513 | * (For more information, please also see the declaration of the MyoFeatureType enum declaration.) | |
514 | **/ | |
515 | MYOACCESSAPI | |
516 | MyoError myoiSupportsFeature(MyoFeatureType myoFeature); | |
517 | ||
5f520819 KY |
518 | /** @fn void myoiLibFini() |
519 | * @brief Finalize the MYO library, all resources held by the runtime are | |
520 | * released by this routine. | |
521 | * | |
522 | * @return | |
523 | **/ | |
524 | MYOACCESSAPI | |
525 | void myoiLibFini(); | |
526 | ||
527 | /* *************************************************************************** *\ | |
528 | APIs to set shared memory space consistent/non-consistent. | |
529 | \* *************************************************************************** */ | |
530 | ||
531 | /** @fn extern MyoError myoiSetMemNonConsistent(void *in_pAddr, size_t in_Size) | |
532 | * @brief Set part of the shared memory space to be non-consistent, which | |
533 | * means that the consistency of this part of shared memory space does not | |
534 | * need to be maintained between HOST and cards. | |
535 | * | |
536 | * @param in_pAddr The start address of the specified shared memory space; | |
537 | * @param in_Size The size of the specified shared memory space; | |
538 | * @return | |
539 | * MYO_SUCCESS; or | |
540 | * an error number to indicate the error. | |
541 | **/ | |
542 | MYOACCESSAPI | |
543 | MyoError myoiSetMemNonConsistent(void *in_pAddr, size_t in_Size); | |
544 | ||
545 | /** @fn extern MyoError myoiSetMemConsistent(void *in_pAddr, size_t in_Size) | |
546 | * @brief Set part of the shared memory space to be consistent, which | |
547 | * means that the consistency of this part of shared memory space needs | |
548 | * to be maintained between HOST and cards. | |
549 | * | |
550 | * @param in_pAddr The start address of the specified shared | |
551 | * memory space. | |
552 | * @param in_size The size of the specified shared memory space. | |
553 | * @return | |
554 | * MYO_SUCCESS; or | |
555 | * an error number to indicate the error. | |
556 | **/ | |
557 | MYOACCESSAPI | |
558 | MyoError myoiSetMemConsistent(void *in_pAddr, size_t in_Size); | |
559 | ||
560 | /* A collection of external data symbols */ | |
561 | EXTERN_C MYOACCESSAPI unsigned int myoiMyId; /* MYO_MYID if on accelerators */ | |
562 | EXTERN_C MYOACCESSAPI volatile int myoiInitFlag; | |
563 | ||
2eab9666 IV |
564 | //! Structure of the array element that is passed to myoiLibInit() to initialize a subset of the available cards, or |
565 | //! to specify a remote call function to be called after successful myo library initialization: | |
566 | typedef struct { | |
567 | //!type = MYOI_USERPARAMS_DEVID or MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC for each element in the array except | |
568 | //!the last element, type should be: MYOI_USERPARAMS_LAST_MSG. | |
5f520819 | 569 | int type; |
2eab9666 IV |
570 | //! nodeid refers to the 'one-based' card index. Specifying, 1 represents the first card, mic0, 2 represents the |
571 | // second card, mic1, 3 represents the third card, mic2, ....). | |
572 | // NOTE: for type == MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC, specifying MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC_ALL_NODES | |
573 | // for nodeid, will execute the named function, on each card in the system, mic0, mic1, mic2, .... micn. | |
5f520819 | 574 | int nodeid; |
2eab9666 IV |
575 | } MyoiUserParams; |
576 | ||
577 | //!The following two types are dealt with entirely with just one MyoiUserParams structure: | |
578 | //!MYOI_USERPARAMS_DEVID maps node ids. | |
579 | #define MYOI_USERPARAMS_DEVID 1 | |
580 | //!MYOI_USERPARAMS_LAST_MSG terminates the array of MyoiUserParams. | |
581 | #define MYOI_USERPARAMS_LAST_MSG -1 | |
582 | ||
583 | //!The following type requires setting the node id in a MyoiUserParams structure, and then following the struct | |
584 | //!with a MyoiUserParamsPostLibInit union: | |
585 | #define MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC 2 | |
586 | //!nodeid can be one of the following macros, or a number >=1, corresponding to the card number (1 == mic0, | |
587 | //!2 == mic1, 3 == mic2, ....) | |
588 | //!Setting nodeid to MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC_ALL_NODES causes the function to be called on all | |
589 | //!cards: | |
590 | #define MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC_ALL_NODES 0 | |
591 | //!Setting nodeid to MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC_HOST_NODE causes the function to be called on the | |
592 | //!host instead of the card: | |
593 | #define MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC_HOST_NODE -1 | |
594 | ||
595 | //!The postLibInit union contains two members that serves two different purposes: | |
596 | //!1. It can be used to stipulate the name of the function to be remotely called from host to card, on successful | |
597 | //!myo library initialization, (member postLibInitRemoveFuncName) using the type: | |
598 | //!MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC. OR | |
599 | //!2. It can be an actual function pointer (member name: postLibInitHostFuncAddress) that will be called on the host, | |
600 | //!on successful myo library initialization, using the type: MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC, with nodeid: | |
601 | //!MYOI_USERPARAMS_POST_MYO_LIB_INIT_FUNC_HOST_NODE | |
602 | typedef union { | |
603 | const char *postLibInitRemoveFuncName; | |
604 | void (*postLibInitHostFuncAddress)(void); | |
605 | } MyoiUserParamsPostLibInit; | |
606 | ||
607 | /* These are two macros to help get the information in a MyoiUserParamsPostLibInit union from a MyoiUserParams struct; */ | |
608 | #define GetPostLibInitFuncName(USERPARAMS) ((MyoiUserParamsPostLibInit *) (& (USERPARAMS)))->postLibInitRemoveFuncName | |
609 | #define GetPostLibInitFuncAddr(USERPARAMS) ((MyoiUserParamsPostLibInit *) (& (USERPARAMS)))->postLibInitHostFuncAddress | |
610 | ||
611 | /* These are two macros to help set the information in a MyoiUserParamsPostLibInit union from a MyoiUserParams struct; */ | |
612 | #define SetPostLibInitFuncName(USERPARAMS,FUNC_NAME) GetPostLibInitFuncName(USERPARAMS) = FUNC_NAME | |
613 | #define SetPostLibInitFuncAddr(USERPARAMS,FUNC_ADDR) GetPostLibInitFuncAddr(USERPARAMS) = FUNC_ADDR | |
5f520819 KY |
614 | |
615 | #ifdef __cplusplus | |
616 | } | |
617 | #endif | |
618 | #endif // _MYO_IMPL_H_ | |
619 | /*! @} */ |