/* * Copyright 2010-2013 Intel Corporation. * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License as published * by the Free Software Foundation, version 2.1. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA * 02110-1301 USA. * * Disclaimer: The codes contained in these modules may be specific * to the Intel Software Development Platform codenamed Knights Ferry, * and the Intel product codenamed Knights Corner, and are not backward * compatible with other Intel products. Additionally, Intel will NOT * support the codes or instruction set in future products. * * Intel offers no warranty of any kind regarding the code. This code is * licensed on an "AS IS" basis and Intel is not obligated to provide * any support, assistance, installation, training, or other services * of any kind. Intel is also not obligated to provide any updates, * enhancements or extensions. Intel specifically disclaims any warranty * of merchantability, non-infringement, fitness for any particular * purpose, and any other warranty. * * Further, Intel disclaims all liability of any kind, including but * not limited to liability for infringement of any proprietary rights, * relating to the use of the code, even if Intel is notified of the * possibility of such liability. Except as expressly stated in an Intel * license agreement provided with this code and agreed upon with Intel, * no license, express or implied, by estoppel or otherwise, to any * intellectual property rights is granted herein. */ /** * Description: * External APIs of MYO runtime (MYO stands for Mine, Yours and Ours). **/ #ifndef _MYO_H_ #define _MYO_H_ #include "myotypes.h" #include "myoimpl.h" /** @ingroup MYO * @addtogroup MYO_API @{ * @file myo.h */ #ifdef __cplusplus extern "C" { #endif /**************************************************************************** Arena-based APIs ***************************************************************************/ /* * Arena is a set of memory pages with the same ownership type. The ownership * type of all the memory pages inside the same arena can only be changed as * a whole. For "OURS", it is also the minimal unit of sync operations to * implement "release consistency". */ /** @fn extern MyoError myoArenaCreate(MyoOwnershipType in_Type, * int in_Property, MyoArena *out_pArena) * @brief Create an arena with specified ownership type and property. * * @param in_Type Specified ownership type (MYO_ARENA_OURS or * MYO_ARENA_MINE). * @param in_Property Specified properties of the arena. Set it * to 0 to use default properties. * * MYO_RELEASE_CONSISTENCY or MYO_STRONG_RELEASE_CONSISTENCY * or MYO_STRONG_CONSISTENCY: * * Consistency modes for "OURS" arenas. For MYO_RELEASE_CONSISTENCY, * there are 2 functions, "Acquire" and "Release", which are * used for memory ordering. "Release" makes all local stores * prior to the release globally visible; "Acquire" syncs up the * local memory with all stores that have been made globally * visible. However, there is no definite answer as to whether * local stores can be globally visible before reaching a release * point, nor whether the newest globally visible stores can be * updated to local before reaching an acquire point. By using * MYO_STRONG_RELEASE_CONSISTENCY, the answer to these questions * is "no". A sequential consistency model is maintained to the * arena when using MYO_STRONG_CONSISTENCY. * MYO_RELEASE_CONSISTENCY is the default property. * * MYO_UPDATE_ON_DEMAND or MYO_UPDATE_ON_ACQUIRE: * * Only apply to "OURS" arenas with "Release Consistency". * MYO_UPDATE_ON_ACQUIRE means that the shared pages of this * arena will be updated on acquire point; MYO_UPDATE_ON_DEMAND * means that the shared pages will not be updated until they * are accessed. MYO_UPDATE_ON_DEMAND is the default property. * * MYO_RECORD_DIRTY or MYO_NOT_RECORD_DIRTY: * * This property controls whether to record dirty pages. * There will be runtime overhead when recording dirty pages, * as it can reduce the communication data. It is a trade-off * for performance. Also when MYO_NOT_RECORD_DIRTY is set for * "OURS" arena, the runtime cannot guarantee the correctness * when the host and card modify the same shared page between * the same sync segment. MYO_RECORD_DIRTY is the default * property. * * MYO_ONE_VERSION or MYO_MULTI_VERSION: * * Only apply to "OURS" arenas with "Release Consistency". When * MYO_MULTI_VERSION is set, this arena can only be "release" on * HOST side and "acquire" on CARD side. Releasing the arena on * HOST will create a new versioned data and put it into a FIFO; * acquiring the arena on CARD will get the versioned data * from the FIFO one by one. MYO_ONE_VERSION is the default * property. * * MYO_CONSISTENCY or MYO_NO_CONSISTENCY: * * Only apply to "OURS" arenas with "Release Consistency". When * MYO_NO_CONSISTENCY is set, the consistency of the arena will * not be maintained. That is, it is a no-op operation when * calling acquire/release for such arenas. MYO_CONSISTENCY is * the default property. * * MYO_HOST_TO_DEVICE and MYO_DEVICE_TO_HOST: * * When it is certain that there is only one communication * direction for this arena, it can be created with only * MYO_HOST_TO_DEVICE or MYO_DEVICE_TO_HOST so the runtime * can perform optimizations. The default property is * MYO_HOST_TO_DEVICE | MYO_DEVICE_TO_HOST. * * @param out_pArena Used to store the handle of the created arena. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI CILK_SHARED MyoError myoArenaCreate(MyoOwnershipType in_Type, int in_Property, MyoArena *out_pArena); /** @fn extern MyoError myoArenaDestroy(MyoArena in_Arena) * @brief Destroy an arena. As a result, the arena can not be * referred any more. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI CILK_SHARED MyoError myoArenaDestroy(MyoArena in_Arena); /** @fn extern void *myoArenaMalloc(MyoArena in_Arena, size_t in_Size) * @brief Allocates size bytes from the specified arena, and returns * the start address of the allocated memory. The memory is not * cleared. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @param in_Size Size (bytes) of the required memory space. * @return * The start address of the allocated memory space. * NULL: Failed. **/ MYOACCESSAPI void *myoArenaMalloc(MyoArena in_Arena, size_t in_Size); /** @fn extern void myoArenaFree(MyoArena in_Arena, void *in_pPtr) * @brief Frees the memory space allocated by myoArenaMalloc to the * specified arena. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @param in_pPtr The start address of the specified memory * space, which must be retured by myoArenaMalloc. * @return **/ MYOACCESSAPI void myoArenaFree(MyoArena in_Arena, void *in_pPtr); /** @fn extern void *myoArenaAlignedMalloc(MyoArena in_Arena, * size_t in_Size, size_t in_Alignment) * @brief Allocates size bytes from the specified arena. The * start address of the allocated memory will be a multiple of the * alignment, which must be a power of two. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @param in_Size Size (bytes) of the required memory space. * @param in_Alignment The alignment value (must be a power * of two). * @return * The start address of the allocated memory space. * NULL: Failed. **/ MYOACCESSAPI void *myoArenaAlignedMalloc(MyoArena in_Arena, size_t in_Size, size_t in_Alignment); /** @fn extern void myoArenaAlignedFree(MyoArena in_Arena, void *in_pPtr) * @brief Frees the memory space allocated by myoArenaAlignedMalloc * to the specified arena. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @param in_pPtr The start address of the specified memory space, * which must be returned by myoArenaAlignedMalloc. * @return **/ MYOACCESSAPI void myoArenaAlignedFree(MyoArena in_Arena, void *in_pPtr); /** @fn extern MyoError myoArenaAcquire(MyoArena in_Arena) * @brief myoArenaAcquire is the sync point for "OURS" arena with * "Release Consistency". myoArenaAcquire is used to obtain all * stores of "OURS" arena that have been made globally visible prior * to this point. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI CILK_SHARED MyoError myoArenaAcquire(MyoArena in_Arena); /** @fn extern MyoError myoArenaRelease(MyoArena in_Arena) * @brief myoArenaRelease is the sync point for "OURS" arena with * "Release Consistency". myoArenaRelease is used to flush all prior * stores of "OURS" arena to be globally visible. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI CILK_SHARED MyoError myoArenaRelease(MyoArena in_Arena); /** @fn extern MyoError myoArenaAcquireOwnership(MyoArena in_Arena) * @brief Changes the ownership type of the arena to MYO_ARENA_MINE. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoArenaAcquireOwnership(MyoArena in_Arena); /** @fn extern MyoError myoArenaReleaseOwnership(MyoArena in_Arena) * @brief Change the ownership type of the arena to MYO_ARENA_OURS. * * @param in_Arena Arena handle returned by previous call to * myoArenaCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoArenaReleaseOwnership(MyoArena in_Arena); /** @fn extern MyoError myoArenaGetHandle(void *in_pPtr, * MyoArena *out_pArena) * @brief Gets the arena handle of the arena that contains the memory * space pointed to by "in_pPtr". This API can be used when it is * not clear which arena handle should be used for other arena * related APIs. * * @param in_pPtr The start address of a chunk of memory space. * @param out_pArena Handle of the arena. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI CILK_SHARED MyoError myoArenaGetHandle(void *in_pPtr, MyoArena *out_pArena); /******************************************************************************** APIs for the default arena *******************************************************************************/ /** * There will be a default arena inside MYO runtime, which will be used when * there is no specified arena. **/ /** @fn extern void* myoSharedMalloc(size_t in_Size) * @brief Allocates size bytes from the default arena, and returns the * start address of the allocated memory. The memory is not cleared. * @param in_Size Size (bytes) of the required memory space. * @return * The start address of the allocated memory space. * NULL: Failed. **/ MYOACCESSAPI void* myoSharedMalloc(size_t in_Size); /** @fn extern void myoSharedFree(void *in_pPtr) * @brief Frees the memory space allocated by myoArenaMalloc to the * default arena. * * @param in_pPtr The start address of the specified memory space, * which must be retured by myoSharedMalloc. * @return **/ MYOACCESSAPI void myoSharedFree(void *in_pPtr); /** @fn extern void* myoSharedAlignedMalloc(size_t in_Size, * size_t in_Alignment) * @brief Allocates size bytes from the default arena. The start * address of the allocated memory will be a multiple of alignment, * which must be a power of two. * * @param in_Size Size (bytes) of the required memory space. * @param in_Alignment The alignment value, which must be an power of two. * @return * The start address of the allocated memory space. * NULL: Failed. **/ MYOACCESSAPI void* myoSharedAlignedMalloc(size_t in_Size, size_t in_Alignment); /** @fn extern void myoSharedAlignedFree(void *in_pPtr) * @brief Frees the memory space allocated by myoArenaAlignedMalloc * to the default arena. * * @param in_pPtr The start address of the specified memory space, * which must be returned by myoArenaAlignedMalloc. * @return **/ MYOACCESSAPI void myoSharedAlignedFree(void *in_pPtr); /** @fn extern MyoError myoAcquire() * @brief myoAcquire is the sync point for the default arena with * "Release Consistency". myoAcquire is used to obtain all stores of * the default arena that have been made globally visible prior to * this point. * * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoAcquire(); /** @fn extern MyoError myoRelease() * @brief myoRelease is the sync point for the default arena with * "Release Consistency". myoRelease is used to flush all prior stores * of the default arena to be globally visible. * * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoRelease(); /** @fn extern MyoError myoAcquireOwnership() * @brief Changes the ownership type of the default arena to * MYO_ARENA_MINE. * * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoAcquireOwnership(); /** @fn extern MyoError myoReleaseOwnership() * @brief Change the ownership type of the default arena to * MYO_ARENA_OURS. * * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoReleaseOwnership(); /***************************************************************************** APIs for global sync operations. *****************************************************************************/ /** @fn extern MyoError myoMutexCreate(MyoMutex *out_pMutex) * @brief Create a mutex and return the mutex handle. * * @param out_pMutex Used to store the handle of the created mutex. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoMutexCreate(MyoMutex *out_pMutex); /** @fn extern MyoError myoMutexLock(MyoMutex in_Mutex) * @brief Lock the mutex. If the mutex is already locked by other peers, * the call blocks until the mutex becomes available. Currently, * attempting to re-acquire the mutex will cause a deadlock. * * @param in_Mutex the mutex handle returned by myoMutexCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoMutexLock(MyoMutex in_Mutex); /** @fn extern MyoError myoMutexUnlock(MyoMutex in_Mutex) * @brief Release the locked mutex. * Currently, attempting to release an unlocked mutex will cause * undefined results. * * @param in_Mutex the mutex handle returned by myoMutexCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoMutexUnlock(MyoMutex in_Mutex); /** @fn extern MyoError myoMutexTryLock(MyoMutex in_Mutex) * @brief Try to lock the mutex. myoMutexTryLock is equivalent to * myoMutexLock, except that myoMutexLock will return immediately if * the mutex is already locked. * * @param in_Mutex the mutex handle returned by myoMutexCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoMutexTryLock(MyoMutex in_Mutex); /** @fn extern MyoError myoMutexDestroy(MyoMutex in_Mutex) * @brief Destroy the mutex. * * @param in_Mutex the mutex handle returned by myoMutexCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoMutexDestroy(MyoMutex in_Mutex); /** @fn extern MyoError myoSemCreate(int in_Value, MyoSem *out_pSem) * @brief Create a semaphore and return the semaphore handle. * * @param in_Value the initial value for the semaphore. * @param out_pSem Used to store the handle of the created semaphore. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoSemCreate(int in_Value, MyoSem *out_pSem); /** @fn extern MyoError myoSemWait(MyoSem in_Sem) * @brief Decrements (locks) the semaphore. If the semaphore value is * greater than zero, then the decrement proceeds and the function * returns immediately, or else the call blocks until the semaphore * value rises above zero. * * @param in_Sem the semaphore handle returned by myoSemCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoSemWait(MyoSem in_Sem); /** @fn extern MyoError myoSemPost(MyoSem in_Sem) * @brief Increments (unlocks) the semaphore. If the semaphore value * becomes greater than zero, one blocked myoSemWait call will be * notified to return. * * @param in_Sem the semaphore handle returned by myoSemCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoSemPost(MyoSem in_Sem); /** @fn extern MyoError myoSemTryWait(MyoSem in_Sem) * @brief Try to lock semaphore. myoSemTryWait is the same as * myoSemAcquire, except that if the decrement cannot be immediately * performed, then the call returns instead of blocking. * * @param in_Sem the semaphore handle returned by myoSemCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoSemTryWait(MyoSem in_Sem); /** @fn extern MyoError myoSemDestroy(MyoSem in_Sem) * @brief Destroy the semaphore. * * @param in_Sem the semaphore handle returned by myoSemCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoSemDestroy(MyoSem in_Sem); /** @fn extern MyoError myoBarrierCreate(int in_Count, MyoBarrier *out_pBarrier) * @brief Create a barrier and return the barrier handle. * * @param in_Count the number of threads that must call * myoBarrierWait before any of them successfully return. * @param out_pBarrier Used to store the handle of the created * barrier. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoBarrierCreate(int in_Count, MyoBarrier *out_pBarrier); /** @fn extern MyoError myoBarrierWait(MyoBarrier in_Barrier) * @brief The caller will block until the required number of threads * have called myoBarrierWait with the same barrier handle. * * @param in_Barrier the barrier handle returned by myoBarrierCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoBarrierWait(MyoBarrier in_Barrier); /** @fn extern MyoError myoBarrierDestroy(MyoBarrier in_Barrier) * @brief Destroy the barrier. * * @param in_Barrier the barrier handle returned by myoBarrierCreate. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoBarrierDestroy(MyoBarrier in_Barrier); /***************************************************************************** MISC APIs. *****************************************************************************/ /** * @cond INCLUDE_MYO_INTERNAL_DOCUMENTATION **/ MYOACCESSAPI int myoMyId(); /* int myoNumNodes() returns the number of peers, minus one, to equal the number of cards in the system. */ MYOACCESSAPI int myoNumNodes(); MYOACCESSAPI unsigned long long myoTicks(); MYOACCESSAPI unsigned long long myoWallTime(); MYOACCESSAPI void myoStatOn(); MYOACCESSAPI void myoStatOff(); /** @fn extern MyoError myoGetMemUsage(uint64 *out_memUsedMB) * @brief Retrieves the amount of shared memory currently used. * myoGetMemUsage() fills in out_memUsedMB when the pointer is not NULL. * * @param out_memUsedBytes, pointer to the current size shared memory used. * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ MYOACCESSAPI MyoError myoGetMemUsage(unsigned int *out_memUsedMB); /** @fn extern MyoError myoHTimeOn(int in_On) * @brief Toggle MYO HTime report feature on/off. * * @param in_On: 1 turn on MYO HTime report * 0 turn off MYO HTime report * @return * MYO_SUCCESS; or * an error number to indicate the error. **/ extern MyoError myoHTimeOn(int in_On); #ifdef __cplusplus } #endif #endif /** * @endcond **/ /*! @} */