diff options
| author | kyukhin <kyukhin@138bc75d-0d04-0410-961f-82ee72b054a4> | 2014-11-13 14:03:17 +0000 |
|---|---|---|
| committer | kyukhin <kyukhin@138bc75d-0d04-0410-961f-82ee72b054a4> | 2014-11-13 14:03:17 +0000 |
| commit | d3a7dd3225284710484510ed9c3aa0f3f05b0966 (patch) | |
| tree | 55be4bcc0740fab528054e3f28398e4513f34e4d /liboffloadmic/include | |
| parent | 9ec260f0908cc670f002f111cb0ac779eb57abf0 (diff) | |
| download | gcc-d3a7dd3225284710484510ed9c3aa0f3f05b0966.tar.gz | |
[PATCH 2/4] OpenMP 4.0 offloading to Intel MIC: liboffloadmic.
* Makefile.def: Add liboffloadmic to target_modules. Make
liboffloadmic depend on libgomp's configure, libstdc++ and libgcc.
* Makefile.in: Regenerate.
* configure: Regenerate.
* configure.ac: Add liboffloadmic to target binaries.
Restrict liboffloadmic for POSIX and i*86, and x86_64 architectures.
Add liboffloadmic to noconfig list when C++ is not supported.
config/
* target-posix: New file.
libcilkrts/
* configure.tgt: Use config/target-posix.
liboffloadmic/
Initial commit. Imported from upstream:
https://www.openmprtl.org/sites/default/files/liboffload_oss.tgz
* Makefile.am: New file.
* Makefile.in: New file, generated by automake.
* aclocal.m4: New file, generated by aclocal.
* configure: New file, generated by autoconf.
* configure.ac: New file.
* configure.tgt: Ditto.
* doc/doxygen/config: Ditto.
* doc/doxygen/header.tex: Ditto.
* include/coi/common/COIEngine_common.h: Ditto.
* include/coi/common/COIMacros_common.h: Ditto.
* include/coi/common/COIPerf_common.h : Ditto.
* include/coi/common/COIResult_common.h : Ditto.
* include/coi/common/COITypes_common.h: Ditto.
* include/coi/sink/COIBuffer_sink.h: Ditto.
* include/coi/sink/COIPipeline_sink.h: Ditto.
* include/coi/sink/COIProcess_sink.h: Ditto.
* include/coi/source/COIBuffer_source.h: Ditto.
* include/coi/source/COIEngine_source.h: Ditto.
* include/coi/source/COIEvent_source.h: Ditto.
* include/coi/source/COIPipeline_source.h: Ditto.
* include/coi/source/COIProcess_source.h: Ditto.
* include/myo/myo.h: Ditto.
* include/myo/myoimpl.h: Ditto.
* include/myo/myotypes.h: Ditto.
* liboffloadmic_host.spec.in: Ditto.
* liboffloadmic_target.spec.in: Ditto.
* runtime/cean_util.cpp: Ditto.
* runtime/cean_util.h: Ditto.
* runtime/coi/coi_client.cpp: Ditto.
* runtime/coi/coi_client.h: Ditto.
* runtime/coi/coi_server.cpp: Ditto.
* runtime/coi/coi_server.h: Ditto.
* runtime/compiler_if_host.cpp: Ditto.
* runtime/compiler_if_host.h: Ditto.
* runtime/compiler_if_target.cpp: Ditto.
* runtime/compiler_if_target.h: Ditto.
* runtime/dv_util.cpp: Ditto.
* runtime/dv_util.h: Ditto.
* runtime/emulator/coi_common.h: Ditto.
* runtime/emulator/coi_device.cpp: Ditto.
* runtime/emulator/coi_device.h: Ditto.
* runtime/emulator/coi_host.cpp: Ditto.
* runtime/emulator/coi_host.h: Ditto.
* runtime/emulator/coi_version_asm.h: Ditto.
* runtime/emulator/coi_version_linker_script.map: Ditto.
* runtime/emulator/myo_client.cpp: Ditto.
* runtime/emulator/myo_service.cpp: Ditto.
* runtime/emulator/myo_service.h: Ditto.
* runtime/emulator/myo_version_asm.h: Ditto.
* runtime/emulator/myo_version_linker_script.map: Ditto.
* runtime/liboffload_error.c: Ditto.
* runtime/liboffload_error_codes.h: Ditto.
* runtime/liboffload_msg.c: Ditto.
* runtime/liboffload_msg.h: Ditto.
* runtime/mic_lib.f90: Ditto.
* runtime/offload.h: Ditto.
* runtime/offload_common.cpp: Ditto.
* runtime/offload_common.h: Ditto.
* runtime/offload_engine.cpp: Ditto.
* runtime/offload_engine.h: Ditto.
* runtime/offload_env.cpp: Ditto.
* runtime/offload_env.h: Ditto.
* runtime/offload_host.cpp: Ditto.
* runtime/offload_host.h: Ditto.
* runtime/offload_myo_host.cpp: Ditto.
* runtime/offload_myo_host.h: Ditto.
* runtime/offload_myo_target.cpp: Ditto.
* runtime/offload_myo_target.h: Ditto.
* runtime/offload_omp_host.cpp: Ditto.
* runtime/offload_omp_target.cpp: Ditto.
* runtime/offload_orsl.cpp: Ditto.
* runtime/offload_orsl.h: Ditto.
* runtime/offload_table.cpp: Ditto.
* runtime/offload_table.h: Ditto.
* runtime/offload_target.cpp: Ditto.
* runtime/offload_target.h: Ditto.
* runtime/offload_target_main.cpp: Ditto.
* runtime/offload_timer.h: Ditto.
* runtime/offload_timer_host.cpp: Ditto.
* runtime/offload_timer_target.cpp: Ditto.
* runtime/offload_trace.cpp: Ditto.
* runtime/offload_trace.h: Ditto.
* runtime/offload_util.cpp: Ditto.
* runtime/offload_util.h: Ditto.
* runtime/ofldbegin.cpp: Ditto.
* runtime/ofldend.cpp: Ditto.
* runtime/orsl-lite/include/orsl-lite.h: Ditto.
* runtime/orsl-lite/lib/orsl-lite.c: Ditto.
* runtime/orsl-lite/version.txt: Ditto.
* runtime/use_mpss2.txt: Ditto.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@217498 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'liboffloadmic/include')
| -rw-r--r-- | liboffloadmic/include/coi/common/COIEngine_common.h | 108 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/common/COIMacros_common.h | 69 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/common/COIPerf_common.h | 87 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/common/COIResult_common.h | 145 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/common/COITypes_common.h | 85 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/sink/COIBuffer_sink.h | 130 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/sink/COIPipeline_sink.h | 137 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/sink/COIProcess_sink.h | 103 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/source/COIBuffer_source.h | 1311 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/source/COIEngine_source.h | 247 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/source/COIEvent_source.h | 192 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/source/COIPipeline_source.h | 426 | ||||
| -rw-r--r-- | liboffloadmic/include/coi/source/COIProcess_source.h | 971 | ||||
| -rw-r--r-- | liboffloadmic/include/myo/myo.h | 619 | ||||
| -rw-r--r-- | liboffloadmic/include/myo/myoimpl.h | 538 | ||||
| -rw-r--r-- | liboffloadmic/include/myo/myotypes.h | 116 |
16 files changed, 5284 insertions, 0 deletions
diff --git a/liboffloadmic/include/coi/common/COIEngine_common.h b/liboffloadmic/include/coi/common/COIEngine_common.h new file mode 100644 index 00000000000..87123128cf9 --- /dev/null +++ b/liboffloadmic/include/coi/common/COIEngine_common.h @@ -0,0 +1,108 @@ +/* + * 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. + */ + +#ifndef _COIENGINE_COMMON_H +#define _COIENGINE_COMMON_H + +/** @ingroup COIEngine + * @addtogroup COIEnginecommon +@{ +* @file common/COIEngine_common.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" + +#ifdef __cplusplus +extern "C" { +#endif +#endif // DOXYGEN_SHOULD_SKIP_THIS + +#define COI_MAX_ISA_x86_64_DEVICES 1 +#define COI_MAX_ISA_MIC_DEVICES 128 +#define COI_MAX_ISA_KNF_DEVICES COI_MAX_ISA_MIC_DEVICES +#define COI_MAX_ISA_KNC_DEVICES COI_MAX_ISA_MIC_DEVICES + + +/////////////////////////////////////////////////////////////////////////////// +/// +/// List of ISA types of supported engines. +/// +typedef enum +{ + COI_ISA_INVALID = 0, ///< Represents an invalid ISA. + COI_ISA_x86_64, ///< The ISA for an x86_64 host engine. + COI_ISA_MIC, ///< Special value used to represent any device + ///< in the Intel(R) Many Integrated Core + ///< architecture family. + COI_ISA_KNF, ///< ISA for L1OM devices. + COI_ISA_KNC ///< ISA for K1OM devices. +} COI_ISA_TYPE; + + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Get the information about the COIEngine executing this function call. +/// +/// @param out_pType +/// [out] The COI_ISA_TYPE of the engine. +/// +/// @param out_pIndex +/// [out] The zero-based index of this engine in the collection of +/// engines of the ISA returned in out_pType. +/// +/// @return COI_INVALID_POINTER if the any of the parameters are NULL. +/// +/// @return COI_SUCCESS +/// +COIACCESSAPI +COIRESULT +COIEngineGetIndex( + COI_ISA_TYPE* out_pType, + uint32_t* out_pIndex); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIENGINE_COMMON_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/common/COIMacros_common.h b/liboffloadmic/include/coi/common/COIMacros_common.h new file mode 100644 index 00000000000..6abddfedaf3 --- /dev/null +++ b/liboffloadmic/include/coi/common/COIMacros_common.h @@ -0,0 +1,69 @@ +/* + * 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. + */ + +#ifndef _COIMACROS_COMMON_H +#define _COIMACROS_COMMON_H + +/// @file common/COIMacros_common.h +/// Commonly used macros + +// Note that UNUSUED_ATTR means that it is "possibly" unused, not "definitely". +// This should compile out in release mode if indeed it is unused. + #define UNUSED_ATTR __attribute__((unused)) +#ifndef UNREFERENCED_CONST_PARAM +#define UNREFERENCED_CONST_PARAM(P) { void* x UNUSED_ATTR = \ + (void*)(uint64_t)P; \ + } +#endif + +// This seems to work on everything. +#ifndef UNREFERENCED_PARAM +#define UNREFERENCED_PARAM(P) (P = P) +#endif + +#ifndef SYMBOL_VERSION + +/* Linux support: */ + + #define SYMBOL_VERSION( SYMBOL , VERSION ) SYMBOL ## VERSION + +#endif + +#endif /* _COIMACROS_COMMON_H */ diff --git a/liboffloadmic/include/coi/common/COIPerf_common.h b/liboffloadmic/include/coi/common/COIPerf_common.h new file mode 100644 index 00000000000..b81756f1cc1 --- /dev/null +++ b/liboffloadmic/include/coi/common/COIPerf_common.h @@ -0,0 +1,87 @@ +/* + * 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. + */ + +#ifndef _COIPERF_COMMON_H +#define _COIPERF_COMMON_H + +/** @ingroup COIPerf + * @addtogroup COIPerfCommon +@{ + +* @file common/COIPerf_common.h +* Performance Analysis API */ +#ifndef DOXYGEN_SHOULD_SKIP_THIS +#include "../common/COITypes_common.h" + +#ifdef __cplusplus +extern "C" { +#endif + +#endif // DOXYGEN_SHOULD_SKIP_THIS + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Returns a performance counter value +/// +/// This function returns a performance counter value that increments +/// at a constant rate for all time and is coherent across all cores. +/// +/// @return Current performance counter value or 0 if no performance counter +///// is available +/// +/// +COIACCESSAPI +uint64_t COIPerfGetCycleCounter(void); + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Returns the calculated system frequency in hertz. +/// +/// @return Current system frequency in hertz. +/// +COIACCESSAPI +uint64_t COIPerfGetCycleFrequency(void); + +#ifdef __cplusplus +} /* extern "C" */ +#endif +/*! @} */ + +#endif /* _COIPERF_COMMON_H */ diff --git a/liboffloadmic/include/coi/common/COIResult_common.h b/liboffloadmic/include/coi/common/COIResult_common.h new file mode 100644 index 00000000000..df8a4f68149 --- /dev/null +++ b/liboffloadmic/include/coi/common/COIResult_common.h @@ -0,0 +1,145 @@ +/* + * 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. + */ + +#ifndef _COIRESULT_COMMON_H +#define _COIRESULT_COMMON_H + +/** @ingroup COIResult + * @addtogroup COIResultCommon +@{ + +* @file common/COIResult_common.h +* Result codes and definitions. */ + +#include "../common/COITypes_common.h" + +#ifdef __cplusplus +extern "C" { +#endif + +typedef enum COIRESULT +{ + COI_SUCCESS = 0, ///< The function succeeded without error. + COI_ERROR, ///< Unspecified error. + COI_NOT_INITIALIZED, ///< The function was called before the + ///< system was initialized. + COI_ALREADY_INITIALIZED, ///< The function was called after the + ///< system was initialized. + COI_ALREADY_EXISTS, ///< Cannot complete the request due to + ///< the existence of a similar object. + COI_DOES_NOT_EXIST, ///< The specified object was not found. + COI_INVALID_POINTER, ///< One of the provided addresses was not + ///< valid. + COI_OUT_OF_RANGE, ///< One of the arguments contains a value + ///< that is invalid. + COI_NOT_SUPPORTED, ///< This function is not currently + ///< supported as used. + COI_TIME_OUT_REACHED, ///< The specified time out caused the + ///< function to abort. + COI_MEMORY_OVERLAP, ///< The source and destination range + ///< specified overlaps for the same + ///< buffer. + COI_ARGUMENT_MISMATCH, ///< The specified arguments are not + ///< compatible. + COI_SIZE_MISMATCH, ///< The specified size does not match the + ///< expected size. + COI_OUT_OF_MEMORY, ///< The function was unable to allocate + ///< the required memory. + COI_INVALID_HANDLE, ///< One of the provided handles was not + ///< valid. + COI_RETRY, ///< This function currently can't + ///< complete, but might be able to later. + COI_RESOURCE_EXHAUSTED, ///< The resource was not large enough. + COI_ALREADY_LOCKED, ///< The object was expected to be + ///< unlocked, but was locked. + COI_NOT_LOCKED, ///< The object was expected to be locked, + ///< but was unlocked. + COI_MISSING_DEPENDENCY, ///< One or more dependent components + ///< could not be found. + COI_UNDEFINED_SYMBOL, ///< One or more symbols the component + ///< required was not defined in any + ///< library. + COI_PENDING, ///< Operation is not finished + COI_BINARY_AND_HARDWARE_MISMATCH, ///< A specified binary will not run on + ///< the specified hardware. + COI_PROCESS_DIED, + COI_INVALID_FILE, ///< The file is invalid for its intended + ///< usage in the function. + COI_EVENT_CANCELED, ///< Event wait on a user event that + ///< was unregistered or is being + ///< unregistered returns + ///< COI_EVENT_CANCELED. + COI_VERSION_MISMATCH, ///< The version of Intel(R) Coprocessor + ///< Offload Infrastructure on the host + ///< is not compatible with the version + ///< on the device. + COI_BAD_PORT, ///< The port that the host is set to + ///< connect to is invalid. + COI_AUTHENTICATION_FAILURE, ///< The daemon was unable to authenticate + ///< the user that requested an engine. + ///< Only reported if daemon is set up for + ///< authorization. + COI_NUM_RESULTS ///< Reserved, do not use. +} +COIRESULT; + +////////////////////////////////////////////////////////////////////////////// +/// +/// Returns the string version of the passed in COIRESULT. Thus if +/// COI_RETRY is passed in, this function returns the string "COI_RETRY". If +/// the error code passed ins is not valid then "COI_ERROR" will be returned. +/// +/// @param in_ResultCode +/// [in] COIRESULT code to return the string version of. +/// +/// @return String version of the passed in COIRESULT code. +/// +COIACCESSAPI +const char* +COIResultGetName( + COIRESULT in_ResultCode); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIRESULT_COMMON_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/common/COITypes_common.h b/liboffloadmic/include/coi/common/COITypes_common.h new file mode 100644 index 00000000000..78180dce81b --- /dev/null +++ b/liboffloadmic/include/coi/common/COITypes_common.h @@ -0,0 +1,85 @@ +/* + * 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. + */ + +#ifndef _COITYPES_COMMON_H +#define _COITYPES_COMMON_H + +/** @ingroup COITypes + * @addtogroup COITypesSource +@{ + +* @file common/COITypes_common.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + #include <stdint.h> + #include <wchar.h> + #define COIACCESSAPI /* nothing */ + #define COIACCESSAPI2 /* nothing */ +#endif /* DOXYGEN_SHOULD_SKIP_THIS */ + + +#ifdef __cplusplus +extern "C" { +#endif + + +struct coievent { uint64_t opaque[2]; }; + +typedef struct coiprocess * COIPROCESS; +typedef struct coipipeline * COIPIPELINE; +typedef struct coifunction * COIFUNCTION; +typedef struct coiengine * COIENGINE; +typedef struct coievent COIEVENT; +typedef struct coibuffer * COIBUFFER; +typedef struct coilibrary * COILIBRARY; +typedef struct coimapinst * COIMAPINSTANCE; + +typedef uint64_t COI_CPU_MASK[16]; + +/** + * On Windows, coi_wchar_t is a uint32_t. On Windows, wchar_t is 16 bits wide, and on Linux it is 32 bits wide, so uint32_t is used for portability. + */ +typedef wchar_t coi_wchar_t; + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COITYPES_COMMON_H */ diff --git a/liboffloadmic/include/coi/sink/COIBuffer_sink.h b/liboffloadmic/include/coi/sink/COIBuffer_sink.h new file mode 100644 index 00000000000..66d0549010d --- /dev/null +++ b/liboffloadmic/include/coi/sink/COIBuffer_sink.h @@ -0,0 +1,130 @@ +/* + * 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. + */ + +#ifndef _COIBUFFER_SINK_H +#define _COIBUFFER_SINK_H + +/** @ingroup COIBuffer + * @addtogroup COIBufferSink +@{ + +* @file sink\COIBuffer_sink.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" +#endif // DOXYGEN_SHOULD_SKIP_THIS + +#ifdef __cplusplus +extern "C" { +#endif + +////////////////////////////////////////////////////////////////////////////// +/// +/// Adds a reference to the memory of a buffer. The memory of the buffer +/// will remain on the device until both a corresponding COIBufferReleaseRef() +/// call is made and the run function that delivered the buffer returns. +/// +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) streaming buffers should not be AddRef'd. Doing so may result in +/// unpredictable results or may cause the sink process to crash. +/// +/// @warning 1.It is possible for enqueued run functions to be unable to +/// execute due to all card memory being occupied by addref'ed +/// buffers. As such, it is important that whenever a buffer is +/// addref'd that there be no dependencies on future run functions +/// for progress to be made towards releasing the buffer. +/// 2.It is important that AddRef is called within the scope of +/// run function that carries the buffer to be addref'ed. +/// +/// @param in_pBuffer +/// [in] Pointer to the start of a buffer being addref'ed, that was +/// passed in at the start of the run function. +/// +/// @return COI_SUCCESS if the buffer ref count was successfully incremented. +/// +/// @return COI_INVALID_POINTER if the buffer pointer is NULL. +/// +/// @return COI_INVALID_HANDLE if the buffer pointer is invalid. +/// +COIRESULT +COIBufferAddRef( + void* in_pBuffer); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Removes a reference to the memory of a buffer. The memory of the buffer +/// will be eligible for being freed on the device when the following +/// conditions are met: the run function that delivered the buffer +/// returns, and the number of calls to COIBufferReleaseRef() matches the +/// number of calls to COIBufferAddRef(). +/// +/// @warning When a buffer is addref'ed it is assumed that it is in use and all +/// other operations on that buffer waits for ReleaseRef() to happen. +/// So you cannot pass the addref'ed buffer's handle to RunFunction +/// that calls ReleaseRef(). This is a circular dependency and will +/// cause a deadlock. Buffer's pointer (buffer's sink side +/// address/pointer which is different than source side BUFFER handle) +/// needs to be stored somewhere to retrieve it later to use in +/// ReleaseRef. +/// +/// @param in_pBuffer +/// [in] Pointer to the start of a buffer previously addref'ed, that +/// was passed in at the start of the run function. +/// +/// @return COI_SUCCESS if the buffer refcount was successfully decremented. +/// +/// @return COI_INVALID_POINTER if the buffer pointer was invalid. +/// +/// @return COI_INVALID_HANDLE if the buffer did not have COIBufferAddRef() +/// previously called on it. +/// +COIRESULT +COIBufferReleaseRef( + void* in_pBuffer); + + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIBUFFER_SINK_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/sink/COIPipeline_sink.h b/liboffloadmic/include/coi/sink/COIPipeline_sink.h new file mode 100644 index 00000000000..ccfde205dea --- /dev/null +++ b/liboffloadmic/include/coi/sink/COIPipeline_sink.h @@ -0,0 +1,137 @@ +/* + * 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. + */ + +#ifndef _COIPIPELINE_SINK_H +#define _COIPIPELINE_SINK_H + +/** @ingroup COIPipeline + * @addtogroup COIPipelineSink +@{ +* @file sink/COIPipeline_sink.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" + +#ifdef __FreeBSD__ +#define COINATIVELIBEXPORT_VISIBILITY "extern" +#else +#define COINATIVELIBEXPORT_VISIBILITY "default" +#endif + +#ifdef __cplusplus +#define COINATIVELIBEXPORT \ + extern "C" __attribute__ ((visibility(COINATIVELIBEXPORT_VISIBILITY))) +#else +#define COINATIVELIBEXPORT \ + __attribute__ ((visibility(COINATIVELIBEXPORT_VISIBILITY))) +#endif + +#ifdef __cplusplus +extern "C" { +#endif +#endif // DOXYGEN_SHOULD_SKIP_THIS + +////////////////////////////////////////////////////////////////////////////// +/// +/// This is the prototype that run functions should follow. +/// +/// @param in_BufferCount +/// The number of buffers passed to the run function. +/// +/// @param in_ppBufferPointers +/// An array that is in_BufferCount in length that contains the +/// sink side virtual addresses for each buffer passed in to +/// the run function. +/// +/// @param in_pBufferLengths +/// An array that is in_BufferCount in length of uint32_t integers +/// describing the length of each passed in buffer in bytes. +/// +/// @param in_pMiscData +/// Pointer to the MiscData passed in when the run function +/// was enqueued on the source. +/// +/// @param in_MiscDataLen +/// Length in bytes of the MiscData passed in when the run function +/// was enqueued on the source. +/// +/// @param in_pReturnValue +/// Pointer to the location where the return value from this run +/// function will be stored. +/// +/// @param in_ReturnValueLength +/// Length in bytes of the user-allocated ReturnValue pointer. +/// +/// @return A uint64_t that can be retrieved in the out_UserData parameter +/// from the COIPipelineWaitForEvent function. +/// +typedef void +(*RunFunctionPtr_t)( + uint32_t in_BufferCount, + void** in_ppBufferPointers, + uint64_t* in_pBufferLengths, + void* in_pMiscData, + uint16_t in_MiscDataLength, + void* in_pReturnValue, + uint16_t in_ReturnValueLength); + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Start processing pipelines on the Sink. This should be done after any +/// required initialization in the Sink's application has finished. No +/// run functions will actually be executed (although they may be queued) +/// until this function is called. +/// +/// +/// @return COI_SUCCESS if the pipelines were successfully started. +/// +COIRESULT +COIPipelineStartExecutingRunFunctions(); + + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIPIPELINE_SINK_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/sink/COIProcess_sink.h b/liboffloadmic/include/coi/sink/COIProcess_sink.h new file mode 100644 index 00000000000..90603262c8b --- /dev/null +++ b/liboffloadmic/include/coi/sink/COIProcess_sink.h @@ -0,0 +1,103 @@ +/* + * 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. + */ + +#ifndef _COIPROCESS_SINK_H +#define _COIPROCESS_SINK_H + +/** @ingroup COIProcess + * @addtogroup COIProcessSink +@{ +* @file sink/COIProcess_sink.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" + +#ifdef __cplusplus +extern "C" { +#endif +#endif // DOXYGEN_SHOULD_SKIP_THIS + +////////////////////////////////////////////////////////////////////////////// +/// +/// This call will block while waiting for the source to send a process destroy +/// message. This provides the sink side application with an event to keep the +/// main() function from exiting until it is directed to by the source. When +/// the shutdown message is received this function will stop any future run +/// functions from executing but will wait for any current run functions to +/// complete. All Intel® Coprocessor Offload Infrastructure (Intel® COI) resources will be cleaned up and no additional Intel® Coprocessor Offload Infrastructure (Intel® COI) APIs +/// should be called after this function returns. This function does not +/// invoke exit() so the application can perform any of its own cleanup once +/// this call returns. +/// +/// @return COI_SUCCESS once the process receives the shutdown message. +/// +COIRESULT +COIProcessWaitForShutdown(); + +////////////////////////////////////////////////////////////////////////////// +/// +/// This call will block until all stdout and stderr output has been proxied +/// to and written by the source. This call guarantees that any output in a +/// run function is transmitted to the source before the run function signals +/// its completion event back to the source. +/// +/// Note that having an additional thread printing forever while another +/// calls COIProxyFlush may lead to a hang because the process will be forced +/// to wait until all that output can be flushed to the source before returning +/// from this call. +/// +/// @return COI_SUCCESS once the proxy output has been flushed to and written +/// written by the host. Note that Intel® Coprocessor Offload Infrastructure (Intel® COI) on the source writes to stdout +/// and stderr, but does not flush this output. +/// @return COI_SUCCESS if the process was created without enabling +/// proxy IO this function. +/// +COIRESULT +COIProcessProxyFlush(); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIPROCESS_SINK_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/source/COIBuffer_source.h b/liboffloadmic/include/coi/source/COIBuffer_source.h new file mode 100644 index 00000000000..4a08856f5d1 --- /dev/null +++ b/liboffloadmic/include/coi/source/COIBuffer_source.h @@ -0,0 +1,1311 @@ +/* + * 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. + */ + +#ifndef _COIBUFFER_SOURCE_H +#define _COIBUFFER_SOURCE_H + +/** @ingroup COIBuffer + * @addtogroup COIBufferSource +@{ + +* @file source\COIBuffer_source.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" +#endif // DOXYGEN_SHOULD_SKIP_THIS + +#ifdef __cplusplus +extern "C" { +#endif + + +/////////////////////////////////////////////////////////////////////////////// +/// The valid buffer types that may be created using COIBufferCreate. +/// Please see the COI_VALID_BUFFER_TYPES_AND_FLAGS matrix +/// below which describes the valid combinations of buffer types and flags. +/// +typedef enum COI_BUFFER_TYPE +{ + /// Normal buffers exist as a single physical buffer in either Source or + /// Sink physical memory. Mapping the buffer may stall the pipelines. + COI_BUFFER_NORMAL = 1, + + /// A streaming buffer creates new versions each time it is passed to + /// Runfunction. These new versions are consumed by run functions. + + /// To_SINK buffers are used to send data from SOURCE to SINK + /// These buffers are SOURCE write only buffers. If read, won't + /// get Data written by SINK + COI_BUFFER_STREAMING_TO_SINK, + + /// To_SOURCE buffers are used to get data from SINK to SOURCE + /// These buffers are SOURCE Read only buffers. If written, data + /// won't get reflected on SINK side. + COI_BUFFER_STREAMING_TO_SOURCE, + + /// A pinned buffer exists in a shared memory region and is always + /// available for read or write operations. + COI_BUFFER_PINNED, + + /// OpenCL buffers are similar to Normal buffers except they don't + /// stall pipelines and don't follow any read write dependencies. + COI_BUFFER_OPENCL + +} COI_BUFFER_TYPE; + + +/// @name COIBUFFER creation flags. +/// Please see the COI_VALID_BUFFER_TYPES_AND_FLAGS matrix +/// below which describes the valid combinations of buffer types and flags. +//@{ + +/// Create the buffer such that it has the same virtual address on all of the +/// sink processes with which it is associated. +#define COI_SAME_ADDRESS_SINKS 0x00000001 + +/// Create the buffer such that it has the same virtual address on all of the +/// sink processes with which it is associated and in the source process. +#define COI_SAME_ADDRESS_SINKS_AND_SOURCE 0x00000002 + +/// Hint to the runtime that the source will frequently read the buffer +#define COI_OPTIMIZE_SOURCE_READ 0x00000004 + +/// Hint to the runtime that the source will frequently write the buffer +#define COI_OPTIMIZE_SOURCE_WRITE 0x00000008 + +/// Hint to the runtime that the sink will frequently read the buffer +#define COI_OPTIMIZE_SINK_READ 0x00000010 + +/// Hint to the runtime that the sink will frequently write the buffer +#define COI_OPTIMIZE_SINK_WRITE 0x00000020 + +/// Used to delay the pinning of memory into physical pages, until required +/// for DMA. This can be used to delay the cost of time spent pinning memory +/// until absolutely necessary. Might speed up the execution of COIBufferCreate +/// calls, but slow down the first access of the buffer in +/// COIPipelineRunFunction(s) or other COIBuffer access API's. +/// Also of important note, that with this flag enabled COI will not be able to +/// check to see if this memory is read only. Ordinarily this is checked +/// and an error is thrown upon buffer creation. With this flag, the error +/// might occur later, and cause undetermined behavior. Be sure to always +/// use writeable memory for COIBuffers. +#define COI_OPTIMIZE_NO_DMA 0x00000040 + +/// Hint to the runtime to try to use huge page sizes for backing store on the +/// sink. Is currently not compatible with PINNED buffers or the SAME_ADDRESS +/// flags or the SINK_MEMORY flag. +#define COI_OPTIMIZE_HUGE_PAGE_SIZE 0x00000080 + +/// Used to tell Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI) +/// to create a buffer using memory that has already been +/// allocated on the sink. This flag is only valid when passed in to the +/// COIBufferCreateFromMemory API. +#define COI_SINK_MEMORY 0x00000100 + +//@} + +#ifndef DOXYGEN_SHOULD_SKIP_THIS +// Make the flag mask +#ifdef F +#undef F +#endif +#define F 0 +#ifdef T +#undef T +#endif +#define T 1 +#define MTM(_BUFFER, B1, B2, B3, B4, B5, B6, B7, B8, B9) \ +(B1 | B2<<1 | B3<<2 | B4<<3 | B5<<4 | B6<<5 | B7<<6 | B8<<7 | B9<<8) +#endif + +/// \enum COI_BUFFER_TYPE +/// This matrix shows the valid combinations of buffer types and buffer flags +/// that may be passed in to COIBufferCreate and COIBufferCreateFromMemory. +/// \code +static const uint64_t +COI_VALID_BUFFER_TYPES_AND_FLAGS[COI_BUFFER_OPENCL+1] = { +/* | | SAME | | | | | | | | + | SAME | ADDR | OPT | OPT | OPT | OPT | OPT | HUGE | COI | + | ADDR | SINK | SRC | SRC | SINK | SINK | NO | PAGE | SINK | + | SINKS | SRC | READ | WRITE | READ | WRITE | DMA | SIZE | MEM | + +-------+------+------+-------+------+-------+-----+------+-----*/ +MTM(INVALID , F , F , F , F , F , F , F , F , F ), +MTM(NORMAL , T , T , T , T , T , T , T , T , T ), +MTM(TO_SINK , F , F , F , T , T , T , F , F , F ), +MTM(TO_SOURCE, F , F , T , F , F , T , F , F , F ), +MTM(PINNED , T , T , T , T , T , T , F , F , F ), +MTM(OPENCL , T , T , T , T , T , T , T , T , F ), +}; +///\endcode +#undef MTM + +////////////////////////////////////////////////////////////////////////////// +/// These flags control how the buffer will be accessed on the source after +/// it is mapped. +/// Please see the COI_VALID_BUFFER_TYPES_AND_MAP matrix below for the +/// valid buffer type and map operation combinations. +typedef enum COI_MAP_TYPE +{ + /// Allows the application to read and write the contents of the buffer + /// after it is mapped. + COI_MAP_READ_WRITE = 1, + + /// If this flag is set then the application must only read from the + /// buffer after it is mapped. If the application writes to the buffer + /// the contents will not be reflected back to the sink or stored for + /// the next time the buffer is mapped on the source. + /// This allows the runtime to make significant performance optimizations + /// in buffer handling. + COI_MAP_READ_ONLY, + + /// Setting this flag means that the source will overwrite the entire + /// buffer once it is mapped. The app must not read from the buffer and + /// must not expect the contents of the buffer to be synchronized from + /// the sink side during the map operation. + /// This allows the runtime to make significant performance optimizations + /// in buffer handling. + COI_MAP_WRITE_ENTIRE_BUFFER +} COI_MAP_TYPE; + +#ifndef DOXYGEN_SHOULD_SKIP_THIS +// Make the flag mask +#define MMM(_BUFFER, B1, B2, B3) \ + { F , B1, B2, B3} +#endif +/// \enum COI_MAP_TYPE +/// This matrix shows the valid combinations of buffer types and map +/// operations that may be passed in to COIBufferMap. +/// \code +static const uint64_t +COI_VALID_BUFFER_TYPES_AND_MAP +[COI_BUFFER_OPENCL+1][COI_MAP_WRITE_ENTIRE_BUFFER+1] = { +/* | MAP | MAP | MAP | + | READ | READ | WRITE | + | WRITE | ONLY | ENTIRE| + +-------+-------+-------+*/ +MMM(INVALID , F , F , F ), +MMM(NORMAL , T , T , T ), +MMM(STREAMING_TO_SINK , F , F , T ), +MMM(STREAMING_TO_SOURCE , F , T , F ), +MMM(PINNED , T , T , T ), +MMM(OPENCL , T , T , T ), +}; +///\endcode +#undef MMM +#ifndef DOXYGEN_SHOULD_SKIP_THIS +#undef F +#undef T +#endif + +////////////////////////////////////////////////////////////////////////////// +/// The valid copy operation types for the COIBufferWrite, COIBufferRead, +/// and COIBufferCopy APIs. +/// +typedef enum COI_COPY_TYPE +{ + /// The runtime can pick the best suitable way to copy the data. + COI_COPY_UNSPECIFIED = 0, + + /// The runtime should use DMA to copy the data. + COI_COPY_USE_DMA, + + /// The runtime should use a CPU copy to copy the data. + /// CPU copy is a synchronous copy. So the resulting operations are always + /// blocking (even though a out_pCompletion event is specified). + COI_COPY_USE_CPU + +} COI_COPY_TYPE; + + +////////////////////////////////////////////////////////////////////////////// +/// The buffer states are used to indicate whether a buffer is available for +/// access in a COIPROCESS. This is used with COIBufferSetState. +/// +/// Buffer state holds only for NORMAL Buffers and OPENCL buffers. Pinned +/// buffers are always valid everywhere they get created. Streaming buffers +/// do not follow the state transition rules, as a new version of the +/// buffer is created every time it is Mapped or you issue a RunFunction. +/// +/// Rules on State Transition of the buffer: +/// -. When a Buffer is created by default it is valid only on the source, +/// except for buffers created with COI_SINK_MEMORY flag which are valid +/// only on the sink where the memory lies when created. +/// -. Apart from SetState following APIs also alters the state of the buffer +/// internally: +/// +/// - COIBufferMap alters state of buffer depending on the COI_MAP_TYPE. +/// COI_MAP_READ_ONLY: Makes Valid on the Source. Doesn't affect the state +/// of the buffer on the other devices. +/// COI_MAP_READ_WRITE: Makes it Valid only the Source and Invalid +/// everywhere else. OPENCL buffers are invalidated +/// only if it is not in use. +/// COI_MAP_WRITE_ENTIRE_BUFFER: Makes it valid only on the Source. OPENCL +/// buffers are invalidated only if not in use. +/// +/// - COIPipelineRunfunction alters the state of the buffer depending on the +/// COI_ACCESS_FLAGS +/// COI_SINK_READ: Makes it valid on the sink where RunFunction is being +/// issued. Doesn't affect the state of the buffer on other +/// devices. +/// COI_SINK_WRITE: Makes it valid only on the sink where Runfunction is +/// being issued and invalid everywhere else. OPENCL +/// buffers are invalidated only if the buffer is not in +/// use. +/// COI_SINK_WRITE_ENTIRE: Makes it valid only on the sink where +/// Runfunction is being issued and invalid everywhere else +/// OPENCL buffers are invalidated only if the buffer is +/// not in use. +/// +/// - COIBufferWrite makes the buffer exclusively valid where the write +/// happens. Write gives preference to Source over Sink. In other words +/// if a buffer is valid on the Source and multiple Sinks, Write will +/// happen on the Source and will Invalidate all other Sinks. If the +/// buffer is valid on multiple Sinks ( and not on the Source) then +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// selects process handle with the lowest numerical value to do the +/// exclusive write Again, OPENCL buffers are invalidated only if the +/// buffer is not in use on that SINK/SOURCE. +/// +/// The preference rule mentioned above holds true even for SetState API, +/// when data needs to be moved from a valid location. The selection of +/// valid location happens as stated above. +/// +/// - It is possible to alter only parts of the buffer and change it state +/// In other words it is possible for different parts of the buffer to have +/// different states on different devices. A byte is the minimum size at +/// which state can be maintained internally. Granularity level is completely +/// determined by how the buffer gets fragmented. +/// +/// Note: Buffer is considered 'in use' if is +/// - Being used in RunFunction : In use on a Sink +/// - Mapped: In use on a Source +/// - AddRef'd: In use on Sink +/// + +////////////////////////////////////////////////////////////////////////////// +/// The buffer states used with COIBufferSetState call to indicate the new +/// state of the buffer on a given process +/// +typedef enum { + COI_BUFFER_VALID = 0, // Buffer is valid and up-to-date on the process + COI_BUFFER_INVALID , // Buffer is not valid, need valid data + COI_BUFFER_VALID_MAY_DROP, // Same as valid but will drop the content when + // evicted to avoid overwriting the shadow + // memory + COI_BUFFER_RESERVED // Reserved for internal use +} COI_BUFFER_STATE; +/// +/// Note: A VALID_MAY_DROP declares a buffer's copy as secondary on a given +/// process. This means that there needs to be at least one primary copy of the +/// the buffer somewhere in order to mark the buffer as VALID_MAY_DROP on a +/// process. In other words to make a buffer VALID_MAY_DROP on a given process +/// it needs to be in COI_BUFFER_VALID state somewhere else. The operation gets +/// ignored (or is a nop) if there is no primary copy of the buffer. The nature +/// of this state to "drop the content" when evicted is a side effect of +/// marking the buffer as secondary copy. So when a buffer marked +/// VALID_MAY_DROP is evicted Intel® Coprocessor Offload Infrastructure +/// (Intel® COI) doesn't back it up as it is assumed that +/// there is a primary copy somewhere. + +////////////////////////////////////////////////////////////////////////////// +/// The buffer move flags are used to indicate when a buffer should be moved +/// when it's state is changed. This is used with COIBufferSetState. +typedef enum { + COI_BUFFER_MOVE = 0,// Dirty data is moved if state change requires it + COI_BUFFER_NO_MOVE // Change state without moving data +} COI_BUFFER_MOVE_FLAG; + +// A process handle for COIBufferSetState call to indicate all the sink +// processes where the given buffer is valid +#define COI_SINK_OWNERS ((COIPROCESS)-2) + +////////////////////////////////////////////////////////////////////////////// +/// +/// Creates a buffer that can be used in RunFunctions that are queued in +/// pipelines. The address space for the buffer is reserved when it is +/// created although the memory may not be committed until the buffer is +/// used for the first time. Please note that the Intel® Coprocessor Offload +/// Infrastructure (Intel® COI) runtime may also +/// allocate space for the source process to use as shadow memory for +/// certain types of buffers. If Intel® Coprocessor Offload Infrastructure +/// (Intel® COI) does allocate this memory it will not +/// be released or reallocated until the COIBuffer is destroyed. +/// +/// @param in_Size +/// [in] The number of bytes to allocate for the buffer. If in_Size +/// is not page aligned, it will be rounded up. +/// +/// @param in_Type +/// [in] The type of the buffer to create. +/// +/// @param in_Flags +/// [in] A bitmask of attributes for the newly created buffer. +/// Some of these flags are required for correctness while others +/// are provided as hints to the runtime system so it can make +/// certain performance optimizations. +/// +/// @param in_pInitData +/// [in] If non-NULL the buffer will be initialized with the data +/// pointed to by pInitData. The memory at in_pInitData must hold +/// at least in_Size bytes. +/// +/// @param in_NumProcesses +/// [in] The number of processes with which this buffer might be used. +/// +/// @param in_pProcesses +/// [in] An array of COIPROCESS handles identifying the processes with +/// which this buffer might be used. +/// +/// @param out_pBuffer +/// [out] Pointer to a buffer handle. The handle will be filled in +/// with a value that uniquely identifies the newly created buffer. +/// This handle should be disposed of via COIBufferDestroy() +/// once it is no longer needed. +/// +/// @return COI_SUCCESS if the buffer was created +/// +/// @return COI_ARGUMENT_MISMATCH if the in_Type and in_Flags parameters +/// are not compatible with one another. Please see the +/// COI_VALID_BUFFER_TYPES_AND_FLAGS map above for information about +/// which flags and types are compatible. +/// +/// @return COI_OUT_OF_RANGE if in_Size is zero, if the bits set in +/// the in_Flags parameter are not recognized flags, or if +/// in_NumProcesses is zero. +/// +/// @return COI_INVALID_POINTER if the in_pProcesses or out_pBuffer parameter +/// is NULL. +/// +/// @return COI_NOT_SUPPORTED if one of the in_Flags is COI_SINK_MEMORY. +/// +/// @return COI_NOT_SUPPORTED if the flags include either +/// COI_SAME_ADDRESS_SINKS or COI_SAME_ADDRESS_SINKS_AND_SOURCE and +/// COI_OPTIMIZE_HUGE_PAGE_SIZE. +/// +/// @return COI_INVALID_HANDLE if one of the COIPROCESS handles in the +/// in_pProcesses array does not identify a valid process. +/// +/// @return COI_OUT_OF_MEMORY if allocating the buffer fails. +/// +/// @return COI_RESOURCE_EXHAUSTED if the sink is out of buffer memory. +/// +COIACCESSAPI +COIRESULT +COIBufferCreate( + uint64_t in_Size, + COI_BUFFER_TYPE in_Type, + uint32_t in_Flags, + const void* in_pInitData, + uint32_t in_NumProcesses, + const COIPROCESS* in_pProcesses, + COIBUFFER* out_pBuffer); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Creates a buffer from some existing memory that can be used in +/// RunFunctions that are queued in pipelines. If the flag COI_SINK_MEMORY +/// is specified then Intel® Coprocessor Offload I +/// nfrastructure (Intel® COI) will use that memory for the buffer on the sink. +/// If that flag isn't set then the memory provided is used as backing store +/// for the buffer on the source. In either case the memory must not be freed +/// before the buffer is destroyed. +/// While the user still owns the memory passed in they must use the +/// appropriate access flags when accessing the buffer in COIPipelinRunFunction +/// or COIBufferMap calls so that the runtime knows when the +/// memory has been modified. If the user just writes directly to the memory +/// location then those changes may not be visible when the corresponding +/// buffer is accessed. +/// Whatever values are already present in the memory location when this call +/// is made are preserved. The memory values are also preserved when +/// COIBufferDestroy is called. +/// +/// @warning: Use of this function is highly discouraged if the calling program +/// program forks at all (including calls to system(3), popen(3), or similar +/// functions) during the life of this buffer. See the discussion around the +/// in_Memory parameter below regarding this. +/// +/// @param in_Size +/// [in] The size of in_Memory in bytes. If in_Size +/// is not page aligned, it will be rounded up. +/// +/// @param in_Type +/// [in] The type of the buffer to create. Note that streaming buffers +/// can not be created from user memory. Only COI_BUFFER_NORMAL and +/// COI_BUFFER_PINNED buffer types are supported. +/// +/// @param in_Flags +/// [in] A bitmask of attributes for the newly created buffer. +/// Some of these flags are required for correctness while others +/// are provided as hints to the runtime system so it can make +/// certain performance optimizations. Note that the flag +/// COI_SAME_ADDRESS_SINKS_AND_SOURCE is still valid but may fail +/// if the same address as in_Memory can not be allocated on the sink. +/// +/// @param in_Memory +/// [in] A pointer to an already allocated memory region +/// that should be turned into a COIBUFFER. Although the user still +/// owns this memory they should not free it before calling +/// COIBufferDestroy. They must also only access the memory using +/// COIBUFFER semantics, for example using COIBufferMap/COIBufferUnmap +/// when they wish to read or write the data. There are no alignment +/// or size requirements for this memory region. +/// +/// WARNING: +/// Since the backing memory passed in can be the target of a DMA +/// the caller must ensure that there is no call to clone(2) (without +/// the CLONE_VM argument) during the life of this buffer. This +/// includes higher level functions that call clone such as fork(2), +/// system(3), popen(3), among others). +/// +/// For forked processes, Linux uses copy-on-write semantics for +/// performances reasons. Conseqeuently, if the parent forks and then +/// writes to this memory, the physical page mapping changes causing +/// the DMA to fail (and thus data corruption). +/// +/// In Linux you can mark a set of pages to not be copied across +/// across the clone by calling madvise(2) with an argument of +/// MADV_DONTFORK and then safely use that memory in this scenario. +/// Alternately, if the memory is from a region marked MAP_SHARED, +/// this will work. +/// +/// @param in_NumProcesses +/// [in] The number of processes with which this buffer might be used. +/// If the flag COI_SINK_MEMORY is specified then this must be 1. +/// +/// @param in_pProcesses +/// [in] An array of COIPROCESS handles identifying the processes with +/// which this buffer might be used. +/// +/// @param out_pBuffer +/// [out] Pointer to a buffer handle. The handle will be filled in +/// with a value that uniquely identifies the newly created buffer. +/// This handle should be disposed of via COIBufferDestroy() +/// once it is no longer needed. +/// +/// @return COI_SUCCESS if the buffer was created +/// +/// @return COI_NOT_SUPPORTED if the in_Type value is not COI_BUFFER_NORMAL or +/// COI_BUFFER_PINNED. +/// +/// @return COI_NOT_SUPPORTED if in_Memory is read-only memory +/// +/// @return COI_NOT_SUPPORTED if one of the in_Flags is COI_SINK_MEMORY and +/// in_Type is not COI_BUFFER_NORMAL +/// +/// @return COI_NOT_SUPPORTED if the flag COI_SAME_ADDRESS_SINKS is set +/// +/// @return COI_NOT_SUPPORTED if the flag COI_SAME_ADDRESS_SINKS_AND_SOURCE is +/// set +/// +/// @return COI_ARGUMENT_MISMATCH if the in_Type and in_Flags parameters +/// are not compatible with one another. Please see the +/// COI_VALID_BUFFER_TYPES_AND_FLAGS map above for information about +/// which flags and types are compatible. +/// +/// @return COI_ARGUMENT_MISMATCH if the flag COI_SINK_MEMORY is specified and +/// in_NumProcesses > 1. +/// +/// @return COI_ARGUMENT_MISMATCH if the flags COI_SINK_MEMORY and +/// COI_OPTIMIZE_HUGE_PAGE_SIZE are both set. +/// +/// @return COI_OUT_OF_RANGE if in_Size is zero, if the bits set in +/// the in_Flags parameter are not recognized flags, or if +/// in_NumProcesses is zero. +/// +/// @return COI_INVALID_POINTER if in_Memory, in_pProcesses or +/// out_pBuffer parameter is NULL. +/// +/// @return COI_INVALID_HANDLE if one of the COIPROCESS handles in the +/// in_pProcesses array does not identify a valid process. +/// +COIACCESSAPI +COIRESULT +COIBufferCreateFromMemory( + uint64_t in_Size, + COI_BUFFER_TYPE in_Type, + uint32_t in_Flags, + void* in_Memory, + uint32_t in_NumProcesses, + const COIPROCESS* in_pProcesses, + COIBUFFER* out_pBuffer); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Destroys a buffer. Will block on completion of any operations on the +/// buffer, such as COIPipelineRunFunction or COIBufferCopy. Will block until +/// all COIBufferAddRef calls have had a matching COIBufferReleaseRef call +/// made. Will not block on an outstanding COIBufferUnmap but will instead +/// return COI_RETRY. +/// +/// @param in_Buffer +/// [in] Handle of the buffer to destroy. +/// +/// @return COI_SUCCESS if the buffer was destroyed. +/// +/// @return COI_INVALID_HANDLE if the buffer handle was invalid. +/// +/// @return COI_RETRY if the buffer is currently mapped. The buffer must +/// first be unmapped before it can be destroyed. +/// +/// @return COI_RETRY if the sub-buffers created from this buffer are not yet +/// destroyed +/// +COIACCESSAPI +COIRESULT +COIBufferDestroy( + COIBUFFER in_Buffer); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// This call initiates a request to access a region of a buffer. Multiple +/// overlapping (or non overlapping) regions can be mapped simultaneously for +/// any given buffer. If a completion event is specified this call will +/// queue a request for the data which will be satisfied when the buffer is +/// available. Once all conditions are met the completion event will be +/// signaled and the user can access the data at out_ppData. The user can call +/// COIEventWait with out_pCompletion to find out when the map operation has +/// completed. If the user accesses the data before the map operation is +/// complete the results are undefined. If out_pCompletion is NULL then this +/// call blocks until the map operation completes and when this call returns +/// out_ppData can be safely accessed. This call returns a map instance handle +/// in an out parameter which must be passed into COIBufferUnmap when the user +/// no longer needs access to that region of the buffer. +/// +/// The address returned from COIBufferMap may point to memory that +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// manages on behalf of the user. The user must not free or reallocate this +/// memory, Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// will perform any necessary cleanup when the buffer is +/// destroyed. +/// +/// Note that different types of buffers behave differently when mapped. +/// For instance, mapping a COI_BUFFER_NORMAL for write must stall if the +/// buffer is currently being written to by a run function. Mapping a +/// COI_BUFFER_STREAMING_TO_SINK will create a new physical copy of the buffer +/// and make it available immediately. Mapping a COI_BUFFER_PINNED buffer will +/// not affect other functions that use that buffer since a COI_BUFFER_PINNED +/// buffer can be mapped at any time. +/// The asynchronous operation of COIBufferMap will likely be most useful when +/// paired with a COI_BUFFER_NORMAL. +/// +/// @param in_Buffer +/// [in] Handle for the buffer to map. +/// +/// @param in_Offset +/// [in] Offset into the buffer that a pointer should be returned +/// for. The value 0 can be passed in to signify that the mapped +/// region should start at the beginning of the buffer. +/// +/// @param in_Length +/// [in] Length of the buffer area to map. This parameter, in +/// combination with in_Offset, allows the caller to specify +/// that only a subset of an entire buffer need be mapped. A +/// value of 0 can be passed in only if in_Offset is 0, to signify +/// that the mapped region is the entire buffer. +/// +/// @param in_Type +/// [in] The access type that is needed by the application. This will +/// affect how the data can be accessed once the map operation +/// completes. See the COI_MAP_TYPE enum for more details. +/// +/// @param in_NumDependencies +/// [in] The number of dependencies specified in the in_pDependencies +/// array. This may be 0 if the caller does not want the map +/// call initiation to wait for any events to be signaled before +/// starting the map operations. +/// +/// @param in_pDependencies +/// [in] An optional array of handles to previously created COIEVENT +/// objects that this map operation will wait for before starting. +/// This allows the user to create dependencies between asynchronous +/// map calls and other operations such as run functions or other +/// asynchronous map calls. The user may pass in NULL if they do not +/// wish to wait for any dependencies to complete before initiating map +/// operations. +/// +/// @param out_pCompletion +/// [out] An optional pointer to a COIEVENT object +/// that will be signaled when a map call with the passed in buffer +/// would complete immediately, that is, the buffer memory has been +/// allocated on the source and its contents updated. The user may pass +/// in NULL if the user wants COIBufferMap to perform a blocking map +/// operation. +/// +/// @param out_pMapInstance +/// [out] A pointer to a COIMAPINSTANCE which represents this mapping +/// of the buffer and must be passed in to COIBufferUnmap when access +/// to this region of the buffer data is no longer needed. +/// +/// @param out_ppData +/// [out] Pointer to the buffer data. The data will only be valid +/// when the completion object is signaled, or for a synchronous +/// map operation with the call to map returns. +/// +/// +/// @return COI_SUCCESS if the map request succeeds. +/// +/// @return COI_OUT_OF_RANGE if in_Offset of (in_Offset + in_Length) exceeds +/// the size of the buffer. +/// +/// @return COI_OUT_OF_RANGE if in_Length is 0, but in_Offset is not 0. +/// +/// @return COI_OUT_OF_RANGE if in_Type is not a valid COI_MAP_TYPE. +/// +/// @return COI_ARGUMENT_MISMATCH if in_NumDependencies is non-zero while +/// in_pDependencies was passed in as NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is non-NULL but +/// in_NumDependencies is zero. +/// +/// @return COI_ARGUMENT_MISMATCH if the in_Type of map is not a valid type +/// for in_Buffer's type of buffer. +/// +/// @return COI_RESOURCE_EXHAUSTED if could not create a version for TO_SINK +/// streaming buffer. It can fail if enough memory is not available to +/// register. This call will succeed eventually when the registered +/// memory becomes available. +/// +/// @return COI_INVALID_HANDLE if in_Buffer is not a valid buffer handle. +/// +/// @return COI_INVALID_POINTER if out_pMapInstance or out_ppData is NULL. +/// +COIACCESSAPI +COIRESULT +COIBufferMap( + COIBUFFER in_Buffer, + uint64_t in_Offset, + uint64_t in_Length, + COI_MAP_TYPE in_Type, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + COIEVENT* out_pCompletion, + COIMAPINSTANCE* out_pMapInstance, + void** out_ppData); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Disables Source access to the region of the buffer that was provided +/// through the corresponding call to COIBufferMap. The number of calls to +/// COIBufferUnmap() should always match the number of calls made to +/// COIBufferMap(). The data pointer returned from the COIBufferMap() call +/// will be invalid after this call. +/// +/// @param in_MapInstance +/// [in] buffer map instance handle to unmap. +/// +/// @param in_NumDependencies +/// [in] The number of dependencies specified in the in_pDependencies +/// array. This may be 0 if the caller does not want the unmap call to +/// wait for any events to be signaled before performing the unmap +/// operation. +/// +/// @param in_pDependencies +/// [in] An optional array of handles to previously created COIEVENT +/// objects that this unmap operation will wait for before starting. +/// This allows the user to create dependencies between asynchronous +/// unmap calls and other operations such as run functions or other +/// asynchronous unmap calls. The user may pass in NULL if they do not +/// wish to wait for any dependencies to complete before initiating +/// unmap operations. +/// +/// @param out_pCompletion +/// [out] An optional pointer to a COIEVENT object that will be +/// signaled when the unmap is complete. The user may pass in NULL if +/// the user wants COIBufferUnmap to perform a blocking unmap +/// operation. +/// +/// @return COI_SUCCESS upon successful unmapping of the buffer instance. +/// +/// @return COI_INVALID_HANDLE if the passed in map instance handle was NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but +/// in_NumDependencies is 0. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but +/// in_NumDependencies is not 0. +/// +COIACCESSAPI +COIRESULT +COIBufferUnmap( + COIMAPINSTANCE in_MapInstance, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + COIEVENT* out_pCompletion); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Gets the Sink's virtual address of the buffer. This is the same +/// address that is passed to the run function on the Sink. The virtual +/// address assigned to the buffer for use on the sink is fixed; +/// the buffer will always be present at that virtual address on the sink +/// and will not get a different virtual address across different +/// RunFunctions. +/// This address is only valid on the Sink and should not be dereferenced on +/// the Source (except for the special case of buffers created with the +/// COI_SAME_ADDRESS flag). +/// +/// @param in_Buffer +/// [in] Buffer handle +/// +/// @param out_pAddress +/// [out] pointer to a uint64_t* that will be filled with the address. +/// +/// @return COI_SUCCESS upon successful return of the buffer's address. +/// +/// @return COI_INVALID_HANDLE if the passed in buffer handle was invalid. +/// +/// @return COI_INVALID_POINTER if the out_pAddress parameter was invalid. +/// +/// @return COI_NOT_SUPPORTED if the buffer passed in is of type +/// COI_BUFFER_STREAMING_TO_SOURCE or COI_BUFFER_STREAMING_TO_SINK. +/// +COIACCESSAPI +COIRESULT +COIBufferGetSinkAddress( + COIBUFFER in_Buffer, + uint64_t* out_pAddress); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Copy data from a normal virtual address into an existing COIBUFFER. +/// Note that it is not possible to use this API with any type of +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) Streaming Buffers. +/// Please note that COIBufferWrite does not follow implicit buffer +/// dependencies. If a buffer is in use in a run function or has been added +/// to a process using COIBufferAddRef the call to COIBufferWrite will not +/// wait, it will still copy data immediately. +/// This is to facilitate a usage model where a buffer is being used outside +/// of a run function, for example in a spawned thread, but data still needs +/// to be transferred to or from the buffer. +/// +/// @param in_DestBuffer +/// [in] Buffer to write into. +/// +#ifdef COI_PROTOTYPE_TARGET_PROCESS +/// @param in_DestProcess +/// [in] A pointer to the processes which are used as hints +/// to to COI. Buffers are updated upon these processes first. +/// Can be left NULL and default behavior will be chosen, which +/// chooses the lowest SCIF node with an active regions first. Others +/// buffer regions are invalidated in both cases. Will only update a single +/// process at this time. +#endif +/// +/// @param in_Offset +/// [in] Location in the buffer to start writing to. +/// +/// @param in_pSourceData +/// [in] A pointer to local memory that should be copied into the +/// provided buffer. +/// +/// @param in_Length +/// [in] The number of bytes to write from in_pSourceData into +/// in_DestBuffer. Must not be larger than the size of in_DestBuffer +/// and must not over run in_DestBuffer if an in_Offset is provided. +/// +/// @param in_Type +/// [in] The type of copy operation to use, one of either +/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU. +/// +/// @param in_NumDependencies +/// [in] The number of dependencies specified in the in_pDependencies +/// array. This may be 0 if the caller does not want the write call to +/// wait for any additional events to be signaled before starting the +/// write operation. +/// +/// @param in_pDependencies +/// [in] An optional array of handles to previously created COIEVENT +/// objects that this write operation will wait for before starting. +/// This allows the user to create dependencies between buffer write +/// calls and other operations such as run functions and map calls. The +/// user may pass in NULL if they do not wish to wait for any +/// additional dependencies to complete before doing the write. +/// +/// @param out_pCompletion +/// [out] An optional event to be signaled when the write has +/// completed. This event can be used as a dependency to order +/// the write with regard to future operations. +/// If no completion event is passed in then the write is +/// synchronous and will block until the transfer is complete. +/// +/// +/// @return COI_SUCCESS if the buffer was copied successfully. +/// +/// @return COI_INVALID_HANDLE if the buffer handle was invalid. +/// +/// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer. +/// +/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but +/// in_NumDependencies is 0. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but +/// in_NumDependencies is not 0. +/// +/// @return COI_NOT_SUPPORTED if the source buffer is of type +/// COI_BUFFER_STREAMING_TO_SINK or COI_BUFFER_STREAMING_TO_SOURCE. +/// +/// @return COI_INVALID_POINTER if the in_pSourceData pointer is NULL. +/// +/// @return COI_OUT_OF_RANGE if in_Offset + in_Length exceeds the size of +/// the buffer. +/// +/// @return COI_OUT_OF_RANGE if in_Length is 0. +/// +/// @return COI_RETRY if in_DestBuffer is mapped and is not a COI_BUFFER_PINNED +/// buffer or COI_BUFFER_OPENCL buffer. +/// +#ifdef COI_PROTOTYPE_TARGET_PROCESS +COIACCESSAPI +COIRESULT +COIBufferWrite( + COIBUFFER in_DestBuffer, + const COIPROCESS in_DestProcess, + uint64_t in_Offset, + const void* in_pSourceData, + uint64_t in_Length, + COI_COPY_TYPE in_Type, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + COIEVENT* out_pCompletion); +__asm__(".symver COIBufferWrite,COIBufferWrite@COI_2.0"); +#else +COIACCESSAPI +COIRESULT +COIBufferWrite( + COIBUFFER in_DestBuffer, + uint64_t in_Offset, + const void* in_pSourceData, + uint64_t in_Length, + COI_COPY_TYPE in_Type, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + COIEVENT* out_pCompletion); +__asm__(".symver COIBufferWrite,COIBufferWrite@COI_1.0"); +#endif + +////////////////////////////////////////////////////////////////////////////// +/// +/// Copy data from a buffer into local memory. +/// Note that it is not possible to use this API with any type of +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) Streaming Buffers. +/// Please note that COIBufferRead does not follow implicit buffer +/// dependencies. If a buffer is in use in a run function or has been added +/// to a process using COIBufferAddRef the call to COIBufferRead will not +/// wait, it will still copy data immediately. +/// This is to facilitate a usage model where a buffer is being used outside +/// of a run function, for example in a spawned thread, but data still needs +/// to be transferred to or from the buffer. +/// +/// +/// @param in_SourceBuffer +/// [in] Buffer to read from. +/// +/// @param in_Offset +/// [in] Location in the buffer to start reading from. +/// +/// @param in_pDestData +/// [in] A pointer to local memory that should be written into from +/// the provided buffer. +/// +/// @param in_Length +/// [in] The number of bytes to write from in_SourceBuffer into +/// in_pDestData. Must not be larger than the size of in_SourceBuffer +/// and must not over run in_SourceBuffer if an in_Offset is provided. +/// +/// @param in_Type +/// [in] The type of copy operation to use, one of either +/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU. +/// +/// @param in_NumDependencies +/// [in] The number of dependencies specified in the in_pDependencies +/// array. This may be 0 if the caller does not want the read call to +/// wait for any additional events to be signaled before starting the +/// read operation. +/// +/// @param in_pDependencies +/// [in] An optional array of handles to previously created COIEVENT +/// objects that this read operation will wait for before starting. +/// This allows the user to create dependencies between buffer read +/// calls and other operations such as run functions and map calls. The +/// user may pass in NULL if they do not wish to wait for any +/// additional dependencies to complete before doing the read. +/// +/// @param out_pCompletion +/// [out] An optional event to be signaled when the read has +/// completed. This event can be used as a dependency to order +/// the read with regard to future operations. +/// If no completion event is passed in then the read is +/// synchronous and will block until the transfer is complete. +/// +/// @return COI_SUCCESS if the buffer was copied successfully. +/// +/// @return COI_INVALID_HANDLE if the buffer handle was invalid. +/// +/// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer. +/// +/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but +/// in_NumDependencies is 0. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but +/// in_NumDependencies is not 0. +/// +/// @return COI_NOT_SUPPORTED if the source buffer is of type +/// COI_BUFFER_STREAMING_TO_SINK or COI_BUFFER_STREAMING_TO_SOURCE. +/// +/// @return COI_OUT_OF_RANGE if in_Offset + in_Length exceeds the size of +/// the buffer. +/// +/// @return COI_OUT_OF_RANGE if in_Length is 0. +/// +/// @return COI_INVALID_POINTER if the in_pDestData pointer is NULL. +/// +/// @return COI_RETRY if in_SourceBuffer is mapped and is not a +/// COI_BUFFER_PINNED buffer or COI_BUFFER_OPENCL buffer. +/// +COIACCESSAPI +COIRESULT +COIBufferRead( + COIBUFFER in_SourceBuffer, + uint64_t in_Offset, + void* in_pDestData, + uint64_t in_Length, + COI_COPY_TYPE in_Type, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + COIEVENT* out_pCompletion); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Copy data between two buffers. It also allows copying within the same +/// buffer. For copy within the same buffer, if source and destination regions +/// overlap then this API returns error. +/// Note that it is not possible to use this API with any type of +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) Streaming Buffers. +/// Please note that COIBufferCopy does not follow implicit buffer +/// dependencies. If a buffer is in use in a run function or has been added +/// to a process using COIBufferAddRef the call to COIBufferCopy will not +/// wait, it will still copy data immediately. +/// This is to facilitate a usage model where a buffer is being used outside +/// of a run function, for example in a spawned thread, but data still needs +/// to be transferred to or from the buffer. +/// +/// @param in_DestBuffer +/// [in] Buffer to copy into. +#ifdef COI_PROTOTYPE_TARGET_PROCESS +/// @param in_DestProcess +/// [in] A pointer to the processes which are used as hints +/// to to COI. Buffers are updated upon these processes first. +/// Can be left NULL and default behavior will be chosen, which +/// chooses the lowest SCIF node with an active regions first. Others +/// buffer regions are invalidated in both cases. Will only update a single +/// process at this time. +#endif +/// +/// @param in_SourceBuffer +/// [in] Buffer to copy from. +/// +/// @param in_DestOffset +/// [in] Location in the destination buffer to start writing to. +/// +/// @param in_SourceOffset +/// [in] Location in the source buffer to start reading from. +/// +/// @param in_Length +/// [in] The number of bytes to copy from in_SourceBuffer into +/// in_DestinationBuffer. +/// If the length is specified as zero then length to be copied +// is entire destination buffer's length. +/// Must not be larger than the size of in_SourceBuffer or +/// in_DestBuffer and must not over run in_SourceBuffer or +/// in_DestBuffer if offsets are specified. +/// +/// @param in_Type +/// [in] The type of copy operation to use, one of either +/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU. +/// +/// @param in_NumDependencies +/// [in] The number of dependencies specified in the in_pDependencies +/// array. This may be 0 if the caller does not want the copy call to +/// wait for any additional events to be signaled before starting the +/// copy operation. +/// +/// @param in_pDependencies +/// [in] An optional array of handles to previously created COIEVENT +/// objects that this copy operation will wait for before starting. +/// This allows the user to create dependencies between buffer copy +/// calls and other operations such as run functions and map calls. The +/// user may pass in NULL if they do not wish to wait for any +/// additional dependencies to complete before doing the copy. +/// +/// @param out_pCompletion +/// [out] An optional event to be signaled when the copy has +/// completed. This event can be used as a dependency to order +/// the copy with regard to future operations. +/// If no completion event is passed in then the copy is +/// synchronous and will block until the transfer is complete. +/// +/// @return COI_SUCCESS if the buffer was copied successfully. +/// +/// @return COI_INVALID_HANDLE if either buffer handle was invalid. +/// +/// @return COI_MEMORY_OVERLAP if in_SourceBuffer and in_DestBuffer are the +/// same buffer(or have the same parent buffer) and the source and +/// destination regions overlap +/// +/// @return COI_OUT_OF_RANGE if in_DestOffset is is beyond the end of +/// in_DestBuffer +/// +/// @return COI_OUT_OF_RANGE if in_SourceOffset is beyond the end of +/// in_SourceBuffer. +/// +/// @return COI_OUT_OF_RANGE if in_DestOffset + in_Length exceeds the size of +/// the in_DestBuffer +/// +/// @return COI_OUT_OF_RANGE if in_SourceOffset + in_Length exceeds +/// the size of in_SourceBuffer. +/// +/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but +/// in_NumDependencies is 0. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but +/// in_NumDependencies is not 0. +/// +/// @return COI_NOT_SUPPORTED if the source or destination buffers are of type +/// COI_BUFFER_STREAMING_TO_SINK or COI_BUFFER_STREAMING_TO_SOURCE. +/// +/// @return COI_NOT_SUPPORTED if either buffer is of type +/// COI_BUFFER_STREAMING_TO_SINK or COI_BUFFER_STREAMING_TO_SOURCE. +/// +/// @return COI_RETRY if in_DestBuffer or in_SourceBuffer are mapped and not +/// COI_BUFFER_PINNED buffers or COI_BUFFER_OPENCL buffers. +/// +#ifdef COI_PROTOTYPE_TARGET_PROCESS +COIACCESSAPI +COIRESULT +COIBufferCopy( + COIBUFFER in_DestBuffer, + const COIPROCESS in_DestProcess, + COIBUFFER in_SourceBuffer, + uint64_t in_DestOffset, + uint64_t in_SourceOffset, + uint64_t in_Length, + COI_COPY_TYPE in_Type, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + COIEVENT* out_pCompletion); +__asm__(".symver COIBufferCopy,COIBufferCopy@COI_2.0"); +#else +COIACCESSAPI +COIRESULT +COIBufferCopy( + COIBUFFER in_DestBuffer, + COIBUFFER in_SourceBuffer, + uint64_t in_DestOffset, + uint64_t in_SourceOffset, + uint64_t in_Length, + COI_COPY_TYPE in_Type, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + COIEVENT* out_pCompletion); +__asm__(".symver COIBufferCopy,COIBufferCopy@COI_1.0"); +#endif +////////////////////////////////////////////////////////////////////////////// +/// +/// This API allows an experienced Intel® Coprocessor Offload Infrastructure +/// (Intel® COI) developer to set where a COIBUFFER is +/// located and when the COIBUFFER's data is moved. This functionality is +/// useful when the developer knows when and where a buffer is going to be +/// accessed. It allows the data movement to happen sooner than if the +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// runtime tried to manage the buffer placement itself. The advantage of +/// this API is that the developer knows much more about their own +/// application's data access patterns and can therefore optimize the data +/// access to be much more efficient than the Intel® Coprocessor Offload +/// Infrastructure (Intel® COI) runtime. Using this API may yield better +/// memory utilization, lower latency and overall improved workload +/// throughput. +/// This API does respect implicit dependencies for buffer read/write hazards. +/// For example, if the buffer is being written in one COIPROCESS and the user +/// requests the buffer be placed in another COIPROCESS then this API will wait +/// for the first access to complete before moving the buffer. +/// This API is not required for program correctness. It is intended solely +/// for advanced Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// developers who wish to fine tune their application performance +/// Cases where "a change in state" is an error condition the change just gets +/// ignored without any error. This is because the SetState can be a +/// nonblocking call and in such cases we can't rely on the state of the buffer +/// at the time of the call. We can do the transition checks only at the time +/// when the actual state change happens (which is something in future). +/// Currently there is no way to report an error from something that happens in +/// future and that is why such state transitions are nop. One example is using +/// VALID_MAY_DROP with COI_SINK_OWNERS when buffer is not valid at source. +/// This operation will be a nop if at the time of actual state change the +/// buffer is not valid at source. +/// +/// @param in_Buffer +/// [in] The buffer to modify. +/// +/// @param in_Process +/// [in] The process where the state is being modified for this +/// buffer. To modify buffer's state on source process use +/// COI_PROCESS_SOURCE as process handle. To modify buffer's +/// state on all processes where buffer is valid use COI_SINK_OWNERS +/// as the process handle. +/// +/// @param in_State +/// [in] The new state for the buffer. The buffer's state could be +/// set to invalid on one of the sink processes where it is being +/// used. +/// +/// @param in_DataMove +/// [in] A flag to indicate if the buffer's data should be moved +/// when the state is changed. For instance, a buffer's state may +/// be set to valid on a process and the data move flag may be set to +/// COI_BUFFER_MOVE which would cause the buffer contents to be +/// copied to the process where it is now valid. +/// +/// @param in_NumDependencies +/// [in] The number of dependencies specified in the in_pDependencies +/// array. This may be 0 if the caller does not want the SetState call +/// to wait for any additional events to be signaled before starting +/// this operation. +/// +/// @param in_pDependencies +/// [in] An optional array of handles to previously created COIEVENT +/// objects that this SetState operation will wait for before starting +/// This allows the user to create dependencies between buffer +/// SetState calls and other operations such as run functions and map +/// calls. The user may pass in NULL if they do not wish to wait for +/// any additional dependencies to complete before doing the SetState +/// +/// @param out_pCompletion +/// [out] An optional event to be signaled when the SetState has +/// completed. This event can be used as a dependency to order +/// the SetState with regard to future operations. +/// If no completion event is passed in then the is +/// synchronous and will block until the SetState and dma transfers +/// related to this operation are complete. +/// +/// @return COI_SUCCESS if the buffer's state was changed successfully. +/// +/// @return COI_INVALID_HANDLE if in_Buffer or in_Process is invalid. +/// +/// @return COI_NOT_SUPPORTED if the in_Buffer is of any type other than +/// COI_BUFFER_NORMAL or COI_BUFFER_OPENCL. +/// +/// @return COI_ARGUMENT_MISMATCH if the in_State is COI_BUFFER_VALID_MAY_DROP +/// and the in_Process is COI_PROCESS_SOURCE. +/// +/// @return COI_ARGUMENT_MISMATCH if the in_Process is COI_SINK_OWNERS and the +/// COI_BUFFER_MOVE is passed as move flag. +/// +/// @return COI_MISSING_DEPENDENCY if buffer was not created on the process +/// handle that was passed in. +/// + +COIACCESSAPI +COIRESULT +COIBufferSetState( + COIBUFFER in_Buffer, + COIPROCESS in_Process, + COI_BUFFER_STATE in_State, + COI_BUFFER_MOVE_FLAG in_DataMove, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + COIEVENT* out_pCompletion); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Creates a sub-buffer that is a reference to a portion of an existing +/// buffer. The returned buffer handle can be used in all API calls that the +/// original buffer handle could be used in except COIBufferCreateSubBuffer. +/// Sub buffers out of Huge Page Buffer are also supported but the original +/// buffer needs to be a OPENCL buffer created with COI_OPTIMIZE_HUGE_PAGE_SIZE +/// flag. +/// +/// When the sub-buffer is used only the corresponding sub-section of the +/// original buffer is used or affected. +/// +/// @param in_Buffer +/// [in] The original buffer that this new sub-buffer is a reference +/// to. +/// +/// @param in_Length +/// [in] The length of the sub-buffer in number of bytes. +/// +/// @param in_Offset +/// [in] Where in the original buffer to start this sub-buffer. +/// +/// @param out_pSubBuffer +/// [out] Pointer to a buffer handle that is filled in with the newly +/// created sub-buffer. +/// +/// @return COI_SUCCESS if the sub-buffer was created +/// +/// @return COI_INVALID_HANDLE if in_Buffer is not a valid buffer handle. +/// +/// @return COI_OUT_OF_RANGE if in_Length is zero, or if in_Offset + in_Length +/// is greater than the size of the original buffer. +/// +/// @return COI_OUT_OF_MEMORY if allocating the buffer fails. +/// +/// @return COI_INVALID_POINTER if the out_pSubBuffer pointer is NULL. +/// +/// @return COI_NOT_SUPPORTED if the in_Buffer is of any type other than +/// COI_BUFFER_OPENCL +/// +COIACCESSAPI +COIRESULT +COIBufferCreateSubBuffer( + COIBUFFER in_Buffer, + uint64_t in_Length, + uint64_t in_Offset, + COIBUFFER* out_pSubBuffer); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIBUFFER_SOURCE_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/source/COIEngine_source.h b/liboffloadmic/include/coi/source/COIEngine_source.h new file mode 100644 index 00000000000..19a63e43409 --- /dev/null +++ b/liboffloadmic/include/coi/source/COIEngine_source.h @@ -0,0 +1,247 @@ +/* + * 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. + */ + +#ifndef _COIENGINE_SOURCE_H +#define _COIENGINE_SOURCE_H + +/** @ingroup COIEngine + * @addtogroup COIEngineSource +@{ + +* @file source\COIEngine_source.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS +#include <wchar.h> +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" +#include "../common/COIEngine_common.h" +#endif // DOXYGEN_SHOULD_SKIP_THIS + +#ifdef __cplusplus +extern "C" { +#endif + +#define COI_MAX_DRIVER_VERSION_STR_LEN 255 + +#define COI_MAX_HW_THREADS 1024 + +/////////////////////////////////////////////////////////////////////////////// +/// This enum defines miscellaneous information returned from the +/// COIGetEngineInfo() function. +/// +typedef enum +{ + COI_ENG_ECC_DISABLED = 0, //ECC is not enabled on this engine + COI_ENG_ECC_ENABLED = 0x00000001, //ECC is enabled on this engine + COI_ENG_ECC_UNKNOWN = 0x00000002 //ECC is mode is unknown +} coi_eng_misc; + + +/////////////////////////////////////////////////////////////////////////////// +/// This structure returns information about an Intel(r) Xeon Phi(tm) +/// coprocessor. +/// A pointer to this structure is passed into the COIGetEngineInfo() function, +/// which fills in the data before returning to the caller. +/// +typedef struct COI_ENGINE_INFO +{ + /// The version string identifying the driver. + coi_wchar_t DriverVersion[COI_MAX_DRIVER_VERSION_STR_LEN]; + + /// The ISA supported by the engine. + COI_ISA_TYPE ISA; + + /// The number of cores on the engine. + uint32_t NumCores; + + /// Miscellaneous fields + coi_eng_misc MiscFlags; + + /// The number of hardware threads on the engine. + uint32_t NumThreads; + + /// The maximum frequency (in MHz) of the cores on the engine. + uint32_t CoreMaxFrequency; + + /// The load percentage for each of the hardware threads on the engine. + uint32_t Load[COI_MAX_HW_THREADS]; + + /// The amount of physical memory managed by the OS. + uint64_t PhysicalMemory; + + /// The amount of free physical memory in the OS. + uint64_t PhysicalMemoryFree; + + /// The amount of swap memory managed by the OS. + uint64_t SwapMemory; + + /// The amount of free swap memory in the OS. + uint64_t SwapMemoryFree; + + /// The pci config vendor id + uint16_t VendorId; + + /// The pci config device id + uint16_t DeviceId; + + /// The pci config subsystem id + uint16_t SubSystemId; + + /// The stepping of the board, A0, A1, C0, D0 etc. + uint16_t BoardStepping; + + /// The SKU of the stepping, EB, ED, etc. + uint16_t BoardSKU; +} COI_ENGINE_INFO; + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Returns information related to a specified engine. Note that if Intel® Coprocessor Offload Infrastructure (Intel® COI) is +/// unable to query a value it will be returned as zero but the call will +/// still succeed. +/// +/// +/// @param in_EngineHandle +/// [in] The COIENGINE structure as provided from COIEngineGetHandle() +/// which to query for device level information. +/// +/// @param in_EngineInfoSize +/// [in] The size of the structure that out_pEngineInfo points to. +/// Used for version safety of the function call. +/// +/// @param out_pEngineInfo +/// [out] The address of a user allocated COI_ENGINE_INFO structure. +/// Upon success, the contents of the structure will be updated +/// to contain information related to the specified engine. +/// +/// +/// @return COI_SUCCESS if the function completed without error. +/// +/// @return COI_INVALID_HANDLE if the in_EngineHandle handle is not valid. +/// +/// @return COI_SIZE_MISMATCH if in_EngineInfoSize does not match any current +/// or previous COI_ENGINE_INFO structure sizes. +/// +/// @return COI_INVALID_POINTER if the out_pEngineInfo pointer is NULL. +/// +COIACCESSAPI +COIRESULT +COIEngineGetInfo( + COIENGINE in_EngineHandle, + uint32_t in_EngineInfoSize, + COI_ENGINE_INFO* out_pEngineInfo); + + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Returns the number of engines in the system that match the provided ISA. +/// +/// Note that while it is possible to enumerate different types of Intel(r) +/// Xeon Phi(tm) coprocessors on a single host this is not currently +/// supported. Intel® Coprocessor Offload Infrastructure (Intel® COI) makes an assumption that all Intel(r) Xeon Phi(tm) +/// coprocessors found in the system are the same architecture as the first +/// coprocessor device. +/// +/// Also, note that this function returns the number of engines that Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// is able to detect. Not all of them may be online. +/// +/// @param in_ISA +/// [in] Specifies the ISA type of the engine requested. +/// +/// @param out_pNumEngines +/// [out] The number of engines available. This can be used to index +/// into the engines using COIEngineGetHandle(). +/// +/// @return COI_SUCCESS if the function completed without error. +/// +/// @return COI_DOES_NOT_EXIST if the in_ISA parameter is not valid. +/// +/// @return COI_INVALID_POINTER if the out_pNumEngines parameter is NULL. +/// +COIACCESSAPI +COIRESULT +COIEngineGetCount( + COI_ISA_TYPE in_ISA, + uint32_t* out_pNumEngines); + + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Returns the handle of a user specified engine. +/// +/// @param in_ISA +/// [in] Specifies the ISA type of the engine requested. +/// +/// @param in_EngineIndex +/// [in] A unsigned integer which specifies the zero-based position of +/// the engine in a collection of engines. The makeup of this +/// collection is defined by the in_ISA parameter. +/// +/// @param out_pEngineHandle +/// [out] The address of an COIENGINE handle. +/// +/// @return COI_SUCCESS if the function completed without error. +/// +/// @return COI_DOES_NOT_EXIST if the in_ISA parameter is not valid. +/// +/// @return COI_OUT_OF_RANGE if in_EngineIndex is greater than or equal to +/// the number of engines that match the in_ISA parameter. +/// +/// @return COI_INVALID_POINTER if the out_pEngineHandle parameter is NULL. +/// +/// @return COI_VERSION_MISMATCH if the version of Intel® Coprocessor Offload Infrastructure (Intel® COI) on the host is not +/// compatible with the version on the device. +/// +/// @return COI_NOT_INITIALIZED if the engine requested exists but is offline. +/// +COIACCESSAPI +COIRESULT +COIEngineGetHandle( + COI_ISA_TYPE in_ISA, + uint32_t in_EngineIndex, + COIENGINE* out_pEngineHandle); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIENGINE_SOURCE_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/source/COIEvent_source.h b/liboffloadmic/include/coi/source/COIEvent_source.h new file mode 100644 index 00000000000..99fa00d6a27 --- /dev/null +++ b/liboffloadmic/include/coi/source/COIEvent_source.h @@ -0,0 +1,192 @@ +/* + * 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. + */ + +#ifndef _COIEVENT_SOURCE_H +#define _COIEVENT_SOURCE_H + +/** @ingroup COIEvent + * @addtogroup COIEventSource +@{ +* @file source/COIEvent_source.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" + +#ifdef __cplusplus +extern "C" { +#endif +#endif // DOXYGEN_SHOULD_SKIP_THIS +/////////////////////////////////////////////////////////////////////////////// +/// +/// Special case event values which can be passed in to APIs to specify +/// how the API should behave. In COIBuffer APIs passing in NULL for the +/// completion event is the equivalent of passing COI_EVENT_SYNC. For +/// COIPipelineRunFunction passing in NULL is the equivalent of +/// COI_EVENT_ASYNC. +/// Note that passing COI_EVENT_ASYNC can be used when the caller wishes the +/// operation to be performed asynchronously but does not care when the +/// operation completes. This can be useful for opertions that by definition +/// must complete in order (DMAs, run functions on a single pipeline). If +/// the caller does care when the operation completes then they should pass +/// in a valid completion event which they can later wait on. +/// +#define COI_EVENT_ASYNC ((COIEVENT*)1) +#define COI_EVENT_SYNC ((COIEVENT*)2) + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Wait for an arbitrary number of COIEVENTs to be signaled as completed, +/// eg when the run function or asynchronous map call associated with an event +/// has finished execution. +/// If the user sets in_WaitForAll = True and not all of the events are +/// signaled when the timeout period is reached then COI_TIME_OUT_REACHED will +/// be returned. +/// If the user sets in_WaitForAll = False then if at least one event is +/// signaled when the timeout is reached then COI_SUCCESS is returned. +/// +/// @param in_NumEvents +/// [in] The number of events to wait for. +/// +/// @param in_pEvents +/// [in] The array of COIEVENT handles to wait for. +/// +/// @param in_Timeout +/// [in] The time in milliseconds to wait for the event. 0 polls +/// and returns immediately, -1 blocks indefinitely. +/// +/// @param in_WaitForAll +/// [in] Boolean value specifying behavior. If true, wait for all +/// events to be signaled, or for timeout, whichever happens first. +/// If false, return when any event is signaled, or at timeout. +/// +/// @param out_pNumSignaled +/// [out] The number of events that were signaled. If in_NumEvents +/// is 1 or in_WaitForAll = True, this parameter is optional. +/// +/// @param out_pSignaledIndices +/// [out] Pointer to an array of indicies into the original event +/// array. Those denoted have been signaled. The user must provide an +/// array that is no smaller than the in_Events array. If in_NumEvents +/// is 1 or in_WaitForAll = True, this parameter is optional. +/// +/// @return COI_SUCCESS once an event has been signaled completed. +/// +/// @return COI_TIME_OUT_REACHED if the events are still in use when the +/// timeout is reached or timeout is zero (a poll). +/// +/// @return COI_OUT_OF_RANGE if a negative value other than -1 is passed in to +/// the in_Timeout parameter. +/// +/// @return COI_OUT_OF_RANGE if in_NumEvents is 0. +/// +/// @return COI_INVALID_POINTER if in_pEvents is NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if in_NumEvents > 1 and if in_WaitForAll +/// is not true and out_pSignaled or out_pSignaledIndicies are NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if out_pNumSignaled is not NULL +/// and out_pSignaledIndices is NULL (or vice versa). +/// +/// @return COI_EVENT_CANCELED if while waiting on a user event, it gets +/// unregistered this returns COI_EVENT_CANCELED +/// +/// @return COI_PROCESS_DIED if the remote process died. See COIProcessDestroy +/// for more details. +/// +COIACCESSAPI +COIRESULT +COIEventWait( + uint16_t in_NumEvents, + const COIEVENT* in_pEvents, + int32_t in_TimeoutMilliseconds, + uint8_t in_WaitForAll, + uint32_t* out_pNumSignaled, + uint32_t* out_pSignaledIndices); + + + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Register a User COIEVENT so that it can be fired. Registered event is +/// a one shot User event; in other words once signaled it cannot be used +/// again for signaling. You have to unregister and register again to enable +/// signaling. An event will be reset if it is re-registered without +/// unregistering, resulting in loss of all outstanding signals. +/// +/// @param out_pEvent +/// [out] Pointer to COIEVENT handle being Registered +/// +/// @return COI_SUCCESS an event is successfully registered +/// +/// @return COI_INVALID_POINTER if out_pEvent is NULL +/// +COIACCESSAPI +COIRESULT +COIEventRegisterUserEvent( + COIEVENT* out_pEvent); + + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Unregister a User COIEVENT. Unregistering a unsignaled event is similar +/// to firing an event. Except Calling COIEventWait on an event that is +/// being unregistered returns COI_EVENT_CANCELED +/// +/// @param in_Event +/// [in] Event Handle to be unregistered. +/// +/// @return COI_INVALID_HANDLE if in_Event is not a UserEvent +/// +/// @return COI_SUCCESS an event is successfully registered +/// +COIACCESSAPI +COIRESULT +COIEventUnregisterUserEvent( + COIEVENT in_Event); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIEVENT_SOURCE_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/source/COIPipeline_source.h b/liboffloadmic/include/coi/source/COIPipeline_source.h new file mode 100644 index 00000000000..d210a1f5025 --- /dev/null +++ b/liboffloadmic/include/coi/source/COIPipeline_source.h @@ -0,0 +1,426 @@ +/* + * 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. + */ + +#ifndef _COIPIPELINE_SOURCE_H +#define _COIPIPELINE_SOURCE_H + +/** @ingroup COIPipeline + * @addtogroup COIPipelineSource +@{ +* @file source/COIPipeline_source.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" + +#ifdef __cplusplus +extern "C" { +#endif +#endif // DOXYGEN_SHOULD_SKIP_THIS + + + +////////////////////////////////////////////////////////////////////////////// +/// These flags specify how a buffer will be used within a run function. They +/// allow Intel® Coprocessor Offload Infrastructure (Intel® COI) to make optimizations in how it moves data around the system. +/// These flags can affect the correctness of an application, so they must be +/// set properly. For example, if a buffer is used in a run function with the +/// COI_SINK_READ flag and then mapped on the source, Intel® Coprocessor Offload Infrastructure (Intel® COI) may use a previously +/// cached version of the buffer instead of retrieving data from the sink. +typedef enum COI_ACCESS_FLAGS +{ + /// Specifies that the run function will only read the associated buffer. + COI_SINK_READ = 1, + + /// Specifies that the run function will write to the associated buffer. + COI_SINK_WRITE, + + /// Specifies that the run function will overwrite the entire associated + /// buffer and therefore the buffer will not be synchronized with the + /// source before execution. + COI_SINK_WRITE_ENTIRE +} COI_ACCESS_FLAGS; + +#define COI_PIPELINE_MAX_PIPELINES 512 +#define COI_PIPELINE_MAX_IN_BUFFERS 16384 +#define COI_PIPELINE_MAX_IN_MISC_DATA_LEN 32768 + + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Create a pipeline assoiated with a remote process. This pipeline can +/// then be used to execute remote functions and to share data using +/// COIBuffers. +/// +/// @param in_Process +/// [in] A handle to an already existing process that the pipeline +/// will be associated with. +/// +/// @param in_Mask +/// [in] An optional mask of the set of hardware threads on which the +/// sink pipeline command processing thread could run. +/// +/// @param in_StackSize +/// [in] An optional value that will be used when the pipeline +/// processing thread is created on the sink. If the user passes in +/// 0 the OS default stack size will be used. Otherwise the value +/// must be PTHREAD_STACK_MIN (16384) bytes or larger and must be +/// a multiple of a page (4096 bytes). +/// +/// @param out_pPipeline +/// [out] Handle returned to uniquely identify the pipeline that was +/// created for use in later API calls. +/// +/// +/// @return COI_SUCCESS if the pipeline was successfully created. +/// +/// @return COI_INVALID_HANDLE if the in_Process handle passed in was invalid. +/// +/// @return COI_INVALID_POINTER if the out_pPipeline pointer was NULL. +/// +/// @return COI_RESOURCE_EXHAUSTED if no more COIPipelines can be created. The +/// maximum number of pipelines allowed is COI_PIPELINE_MAX_PIPELINES. +/// It is recommended in most cases to not exceed the number of CPU's +/// that are reported on the offload device, performance will suffer. +/// +/// +/// @return COI_OUT_OF_RANGE if the in_StackSize > 0 && +/// in_StackSize < PTHREAD_STACK_MIN or if in_StackSize is not a +/// multiple of a page (4096 bytes). +/// +/// @return COI_OUT_OF_RANGE if the in_Mask is set to all zeroes. If no mask +/// is desired then the in_Mask should be passed as NULL, otherwise +/// at least one thread must be set. +/// +/// @return COI_TIME_OUT_REACHED if establishing the communication channel with +/// the remote pipeline timed out. +/// +/// @return COI_RETRY if the pipeline cannot be created due to the number of +/// source-to-sink connections in use. A subsequent call to +/// COIPipelineCreate may succeed if resources are freed up. +/// +/// @return COI_PROCESS_DIED if in_Process died. +/// +COIACCESSAPI +COIRESULT +COIPipelineCreate( + COIPROCESS in_Process, + COI_CPU_MASK in_Mask, + uint32_t in_StackSize, + COIPIPELINE* out_pPipeline); + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Destroys the inidicated pipeline, releasing its resources. +/// +/// @param in_Pipeline +/// [in] Pipeline to destroy. +/// +/// +/// @return COI_SUCCESS if the pipeline was destroyed +/// +COIACCESSAPI +COIRESULT +COIPipelineDestroy( + COIPIPELINE in_Pipeline); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Enqueues a function in the remote process binary to be executed. The +/// function execution is asynchronous in regards to the Source and all +/// run functions enqueued on a pipeline are executed in-order. The run +/// function will only execute when all of the required buffers are present +/// in the Sink's memory. +/// +/// Potential Hazards while using Runfunctions: +/// +/// 1. Proper care has to be taken while setting the input dependencies for +/// RunFunctions. Setting it incorrectly can lead to cyclic dependencies +/// and can cause the respective pipeline (as a result Intel® Coprocessor Offload Infrastructure (Intel® COI) Runtime) to +/// stall. +/// 2. RunFunctions can also segfault if enough memory space is not available +/// on the sink for the buffers passed in. Pinned buffers and buffers that +/// are AddRef'd need to be accounted for available memory space. In other +/// words, this memory is not available for use until it is freed up. +/// 3. Unexpected segmentation faults or erroneous behaviour can occur if +/// handles or data passed in to Runfunction gets destroyed before the +/// RunFunction finishes. +/// For example, if a variable passed in as Misc data or the buffer gets +/// destroyed before the Intel® Coprocessor Offload Infrastructure (Intel® COI) runtime receives the completion notification +/// of the Runfunction, it can cause unexpected behaviour. So it is always +/// recommended to wait for RunFunction completion event before any related +/// destroy event occurs. +/// +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) Runtime expects users to handle such scenarios. COIPipelineRunFunction +/// returns COI_SUCCESS for above cases because it was queued up successfully. +/// Also if you try to destroy a pipeline with a stalled function then the +/// destroy call will hang. COIPipelineDestroy waits until all the functions +/// enqueued are finished executing. +/// +/// @param in_Pipeline +/// [in] Handle to a previously created pipeline that this run +/// function should be enqueued to. +/// +/// @param in_Function +/// [in] Previously returned handle from a call to +/// COIPipelineGetFunctionHandle() that represents a function in the +/// application running on the Sink process. +/// +/// @param in_NumBuffers +/// [in] The number of buffers that are being passed to the run +/// function. This number must match the number of buffers in the +/// in_pBuffers and in_pBufferAccessFlags arrays. Must be less than +/// COI_PIPELINE_MAX_IN_BUFFERS. +/// +/// @param in_pBuffers +/// [in] An array of COIBUFFER handles that the function is expected +/// to use during its execution. Each buffer when it arrives at the +/// Sink process will be at least 4k page aligned, thus, using a very +/// large number of small buffers is memory inefficient and should be +/// avoided. +/// +/// @param in_pBufferAccessFlags +/// [in] An array of flag values which correspond to the buffers +/// passed in the in_pBuffers parameter. These flags are used to +/// track dependencies between different run functions being +/// executed from different pipelines. +/// +/// @param in_NumDependencies +/// [in] The number of dependencies specified in the in_pDependencies +/// array. This may be 0 if the caller does not want the run function +/// to wait for any dependencies. +/// +/// @param in_pDependencies +/// [in] An optional array of COIEVENT objects that this run +/// function will wait for before executing. This allows the user to +/// create dependencies between run functions in different pipelines. +/// The user may pass in NULL if they do not wish to wait for any +/// dependencies to complete. +/// +/// @param in_pMiscData +/// [in] Pointer to user defined data, typically used to pass +/// parameters to Sink side functions. Should only be used for small +/// amounts data since the data will be placed directly in the +/// Driver's command buffer. COIBuffers should be used to pass large +/// amounts of data. +/// +/// @param in_MiscDataLen +/// [in] Size of the in_pMiscData in bytes. Must be less than +/// COI_PIPELINE_MAX_IN_MISC_DATA_LEN, and should usually be much +/// smaller, see documentation for the parameter in_pMiscData. +/// +/// @param out_pAsyncReturnValue +/// [out] Pointer to user-allocated memory where the return value from +/// the run function will be placed. This memory should not be read +/// until out_pCompletion has been signalled. +/// +/// @param in_AsyncReturnValueLen +/// [in] Size of the out_pAsyncReturnValue in bytes. +/// +/// @param out_pCompletion +/// [out] An optional pointer to a COIEVENT object +/// that will be signaled when this run function has completed +/// execution. The user may pass in NULL if they do not wish to signal +/// any COIEVENTs when this run function completes. +/// +/// @return COI_SUCCESS if the function was successfully placed in a +/// pipeline for future execution. Note that the actual +/// execution of the function will occur in the future. +/// +/// @return COI_OUT_OF_RANGE if in_NumBuffers is greater than +/// COI_PIPELINE_MAX_IN_BUFFERS or if in_MiscDataLen is greater than +/// COI_PIPELINE_MAX_IN_MISC_DATA_LEN. +/// +/// @return COI_INVALID_HANDLE if the pipeline handle passed in was invalid. +/// +/// @return COI_INVALID_HANDLE if the function handle passed in was invalid. +/// +/// @return COI_INVALID_HANDLE if any of the buffers passed in are invalid. +/// +/// @return COI_ARGUMENT_MISMATCH if in_NumDependencies is non-zero while +/// in_pDependencies was passed in as NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is non-NULL but +/// in_NumDependencies is zero. +/// +/// @return COI_ARGUMENT_MISMATCH if in_MiscDataLen is non-zero while +/// in_pMiscData was passed in as NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pMiscData is non-NULL but +/// in_MiscDataLen is zero. +/// +/// @return COI_ARGUMENT_MISMATCH if in_NumBuffers is non-zero and in_pBuffers +/// or in_pBufferAccessFlags are NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pBuffers is non-NULL but +/// in_NumBuffers is zero. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pBufferAccessFlags is non-NULL but +/// in_NumBuffers is zero. +/// +/// @return COI_ARGUMENT_MISMATCH if in_ReturnValueLen is non-zero while +/// in_pReturnValue was passed in as NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pReturnValue is non-NULL but +/// in_ReturnValueLen is zero. +/// +/// @return COI_ARGUMENT_MISMATCH if a COI_BUFFER_STREAMING_TO_SOURCE buffer +/// is not passed with COI_SINK_WRITE_ENTIRE access flag. +/// +/// @return COI_RESOURCE_EXHAUSTED if could not create a version for TO_SOURCE +/// streaming buffer. It can fail if enough memory is not available to +/// register. This call will succeed eventually when the registered +/// memory becomes available. +/// +/// @return COI_RETRY if any input buffers, which are not pinned buffers, +/// are still mapped when passed to the run function. +/// +/// @return COI_MISSING_DEPENDENCY if buffer was not created on the process +/// associated with the pipeline that was passed in. +/// +/// @return COI_OUT_OF_RANGE if any of the access flags in +/// in_pBufferAccessFlags is not a valid COI_ACCESS_FLAGS. +/// +COIACCESSAPI +COIRESULT +COIPipelineRunFunction( + COIPIPELINE in_Pipeline, + COIFUNCTION in_Function, + uint32_t in_NumBuffers, + const COIBUFFER* in_pBuffers, + const COI_ACCESS_FLAGS* in_pBufferAccessFlags, + uint32_t in_NumDependencies, + const COIEVENT* in_pDependencies, + const void* in_pMiscData, + uint16_t in_MiscDataLen, + void* out_pAsyncReturnValue, + uint16_t in_AsyncReturnValueLen, + COIEVENT* out_pCompletion); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Retrieve the engine that the pipeline is associated with. +/// +/// @param in_Pipeline +/// [in] Pipeline to query. +/// +/// @param out_pEngine +/// [out] The handle of the Engine. +/// +/// @return COI_SUCCESS if the engine was retrieved. +/// +/// @return COI_INVALID_HANDLE if the pipeline handle passed in was invalid. +/// +/// @return COI_INVALID_POINTER if the out_pEngine parameter is NULL. +/// +/// @return COI_PROCESS_DIED if the process associated with this engine died. +/// +COIACCESSAPI +COIRESULT +COIPipelineGetEngine( + COIPIPELINE in_Pipeline, + COIENGINE* out_pEngine); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Add a particular core:thread pair to a COI_CPU_MASK. +/// +/// @param in_Process +/// [in] A handle to an already existing process that the pipeline +/// will be associated with. +/// +/// @param in_CoreID +/// [in] Core to affinitize to; must be less than the number of cores +/// on the device. +/// +/// @param in_ThreadID +/// [in] Thread on the core to affinitize to (0 - 3). +/// +/// @param out_pMask +/// [out] Pointer to the mask to set. +/// +/// @warning Unless it is explicitly done, the contents of the mask may not +/// be zero when creating or declaring a COI_CPU_MASK variable. +/// +/// @return COI_SUCCESS if the mask was set. +/// +/// @return COI_OUT_OF_RANGE if the in_CoreID or in_ThreadID is out of range. +/// +/// @return COI_INVALID_POINTER if out_pMask is invalid. +/// +/// @return COI_INVALID_HANDLE if in_Process is invalid. +/// +COIACCESSAPI +COIRESULT +COIPipelineSetCPUMask( + COIPROCESS in_Process, + uint32_t in_CoreID, + uint8_t in_ThreadID, + COI_CPU_MASK* out_pMask); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Clears a given mask. Note that the memory contents of COI_CPU_MASK are not +/// guaranteed to be zero when declaring a COI_CPU_MASK variable. Thus, prior +/// to setting a specific affinity to in_Mask it is important to call this +/// function first. +/// +/// @param in_Mask +/// [in] Pointer to the mask to clear. +/// +/// @return COI_SUCCESS if the mask was cleared. +/// +/// @return COI_INVALID_POINTER if in_Mask is invalid. +/// +COIACCESSAPI +COIRESULT +COIPipelineClearCPUMask( + COI_CPU_MASK* in_Mask); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIPIPELINE_SOURCE_H */ + +/*! @} */ diff --git a/liboffloadmic/include/coi/source/COIProcess_source.h b/liboffloadmic/include/coi/source/COIProcess_source.h new file mode 100644 index 00000000000..b60e5522515 --- /dev/null +++ b/liboffloadmic/include/coi/source/COIProcess_source.h @@ -0,0 +1,971 @@ +/* + * 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. + */ + +#ifndef _COIPROCESS_SOURCE_H +#define _COIPROCESS_SOURCE_H + +/** @ingroup COIProcess + * @addtogroup COIProcessSource +@{ +* @file source/COIProcess_source.h +*/ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + +#include "../common/COITypes_common.h" +#include "../common/COIResult_common.h" + +#ifdef __cplusplus +extern "C" { +#endif +#endif // DOXYGEN_SHOULD_SKIP_THIS + + +/////////////////////////////////////////////////////////////////////////////// +/// This is a special COIPROCESS handle that can be used to indicate that +/// the source process should be used for an operation. +/// +#define COI_PROCESS_SOURCE ((COIPROCESS)-1) + +#define COI_MAX_FILE_NAME_LENGTH 256 + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Create a remote process on the Sink and start executing its main() +/// function. +/// +/// For more details about creating a process see COIProcessCreateFromMemory. +/// +/// @param in_Engine +/// [in] A handle retrieved via a call to COIEngineGetHandle() that +/// indicates which device to create the process on. This is +/// necessary because there can be more than one device +/// within the system. +/// +/// @param in_pBinaryName +/// [in] Pointer to a null-terminated string that contains the +/// path to the program binary to be instantiated as a process on +/// the sink device. The file name will be accessed via +/// fopen and fread, as such, the passed in binary name must +/// be locatable via these commands. Also, the file name (without +/// directory information) will be used automatically by the system +/// to create the argv[0] of the new process. +/// +/// @param in_Argc +/// [in] The number of arguments being passed in to the process in the +/// in_ppArgv parameter. +/// +/// @param in_ppArgv +/// [in] An array of strings that represent the arguments being passed +/// in. The system will auto-generate argv[0] using in_pBinaryName and +/// thus that parameter cannot be passed in using in_ppArgv. Instead, +/// in_ppArgv contains the rest of the parameters being passed in. +/// +/// @param in_DupEnv +/// [in] A boolean that indicates whether the process that is being +/// created should inherit the environment of the caller. +/// +/// @param in_ppAdditionalEnv +/// [in] An array of strings that represent additional environment +/// variables. This parameter must terminate the array with a NULL +/// string. For convenience it is also allowed to be NULL if there are +/// no additional environment variables that need adding. Note that +/// any environment variables specified here will be in addition to +/// but override those that were inherited via in_DupEnv. +/// +/// @param in_ProxyActive +/// [in] A boolean that specifies whether the process that is to be +/// created wants I/O proxy support. If this flag is enabled, then +/// stdout and stderr are forwarded back to the calling process's +/// output and error streams. +/// +/// @param in_Reserved +/// Reserved for future use, best set at NULL. +/// +/// @param in_InitialBufferSpace +/// [in] The initial memory (in bytes) that will be pre-allocated at +/// process creation for use by buffers associated with this remote +/// process. In addition to allocating, Intel® Coprocessor Offload +/// Infrastructure (Intel® COI) will also fault in the +/// memory during process creation. If the total size of the buffers +/// in use by this process exceed this initial size, memory on the +/// sink may continue to be allocated on demand, as needed, subject +/// to the system constraints on the sink. +/// +///@param in_LibrarySearchPath +/// [in] a path to locate dynamic libraries dependencies for the sink +/// application. If not NULL, this path will override the environment +/// variable SINK_LD_LIBRARY_PATH. If NULL it will use +/// SINK_LD_LIBRARY_PATH to locate dependencies. +/// +/// @param out_pProcess +/// [out] Handle returned to uniquely identify the process that was +/// created for use in later API calls. +/// +/// @return COI_SUCCESS if the remote process was successfully created. +/// +/// @return COI_INVALID_POINTER if in_pBinaryName was NULL. +/// +/// @return COI_INVALID_FILE if in_pBinaryName is not a "regular file" as +/// determined by stat or if its size is 0. +/// +/// @return COI_DOES_NOT_EXIST if in_pBinaryName cannot be found. +/// +/// @return See COIProcessCreateFromMemory for additional errors. +/// +COIACCESSAPI +COIRESULT +COIProcessCreateFromFile( + COIENGINE in_Engine, + const char* in_pBinaryName, + int in_Argc, + const char** in_ppArgv, + uint8_t in_DupEnv, + const char** in_ppAdditionalEnv, + uint8_t in_ProxyActive, + const char* in_Reserved, + uint64_t in_InitialBufferSpace, + const char* in_LibrarySearchPath, + COIPROCESS* out_pProcess); + +/////////////////////////////////////////////////////////////////////////////// +/// +/// Create a remote process on the Sink and start executing its main() +/// function. This will also automatically load any dependent shared objects +/// on to the device. Once the process is created, remote calls can be +/// initiated by using the RunFunction mechanism found in the COIPipeline APIs. +/// +/// If instead of creating a process you only wish to check for dynamic +/// library dependencies set the environment variable +/// SINK_LD_TRACE_LOADED_OBJECTS to be non empty before making this call. +/// +/// If there are dynamic link libraries on the source file system that need to +/// be preloaded when the process is created on the device, callers of this +/// API can set the environment variable SINK_LD_PRELOAD to a colon separated +/// list of libraries that need to be copied to the sink and preloaded as part +/// of process creation. +/// +/// For more information on how dependencies are loaded, see +/// COIProcessLoadLibraryFromMemory. +/// +/// @param in_Engine +/// [in] A handle retrieved via a call to COIEngineGetHandle() that +/// indicates which device to create the process on. This is +/// necessary because there can be more than one device +/// within the system. +/// +/// @param in_pBinaryName +/// [in] Pointer to a null-terminated string that contains the name to +/// give the process that will be created. Note that the final name +/// will strip out any directory information from in_pBinaryName and +/// use the file information to generate an argv[0] for the new +/// process. +/// +/// @param in_pBinaryBuffer +/// [in] Pointer to a buffer whose contents represent the sink-side +/// process that we want to create. +/// +/// @param in_BinaryBufferLength +/// [in] Number of bytes in in_pBinaryBuffer. +/// +/// @param in_Argc +/// [in] The number of arguments being passed in to the process in the +/// in_ppArgv parameter. +/// +/// @param in_ppArgv +/// [in] An array of strings that represent the arguments being passed +/// in. The system will auto-generate argv[0] using in_pBinaryName and +/// thus that parameter cannot be passed in using in_ppArgv. Instead, +/// in_ppArgv contains the rest of the parameters being passed in. +/// +/// @param in_DupEnv +/// [in] A boolean that indicates whether the process that is being +/// created should inherit the environment of the caller. +/// +/// @param in_ppAdditionalEnv +/// [in] An array of strings that represent additional environment +/// variables. This parameter must terminate the array with a NULL +/// string. For convenience it is also allowed to be NULL if there are +/// no additional environment variables that need adding. Note that +/// any environment variables specified here will be in addition to +/// but override those that were inherited via in_DupEnv. +/// +/// @param in_ProxyActive +/// [in] A boolean that specifies whether the process that is to be +/// created wants I/O proxy support. +/// +/// @param in_Reserved +/// Reserved for future use, best set to NULL. +/// +/// @param in_InitialBufferSpace +/// [in] The initial memory (in bytes) that will be pre-allocated at +/// process creation for use by buffers associated with this remote +/// process. In addition to allocating, Intel® Coprocessor +/// Offload Infrastructure (Intel® COI) will also fault in the +/// memory during process creation. If the total size of the buffers +/// in use by this process exceed this initial size, memory on the +/// sink may continue to be allocated on demand, as needed, subject +/// to the system constraints on the sink. +/// +/// @param in_LibrarySearchPath +/// [in] A path to locate dynamic libraries dependencies for the sink +/// application. If not NULL, this path will override the environment +/// variable SINK_LD_LIBRARY_PATH. If NULL it will use +/// SINK_LD_LIBRARY_PATH to locate dependencies. +/// +/// @param in_FileOfOrigin +/// [in] If not NULL, this parameter indicates the file from which the +/// in_pBinaryBuffer was obtained. This parameter is optional. +/// +/// @param in_FileOfOriginOffset +/// [in] If in_FileOfOrigin is not NULL, this parameter indicates the +/// offset within that file where in_pBinaryBuffer begins. +/// +/// @param out_pProcess +/// [out] Handle returned to uniquely identify the process that was +/// created for use in later API calls. +/// +/// @return COI_SUCCESS if the remote process was successfully created. +/// +/// @return COI_INVALID_HANDLE if the in_Engine handle passed in was invalid. +/// +/// @return COI_INVALID_POINTER if out_pProcess was NULL. +/// +/// @return COI_INVALID_POINTER if in_pBinaryName or in_pBinaryBuffer was NULL. +/// +/// @return COI_MISSING_DEPENDENCY if a dependent library is missing from +/// either SINK_LD_LIBRARY_PATH or the in_LibrarySearchPath parameter. +/// +/// @return COI_BINARY_AND_HARDWARE_MISMATCH if in_pBinaryName or any of its +/// recursive dependencies were built for a target machine that does +/// not match the engine specified. +/// +/// @return COI_RESOURCE_EXHAUSTED if no more COIProcesses can be created, +/// possibly, but not necessarily because in_InitialBufferSpace is too +/// large. +/// +/// @return COI_ARGUMENT_MISMATCH if in_Argc is 0 and in_ppArgv is not NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if in_Argc is greater than 0 and in_ppArgv is +/// NULL. +/// +/// @return COI_OUT_OF_RANGE if in_Argc is less than 0. +/// +/// @return COI_OUT_OF_RANGE if the length of in_pBinaryName is greater than or +/// equal to COI_MAX_FILE_NAME_LENGTH. +/// +/// @return COI_OUT_OF_RANGE if in_BinaryBufferLength is 0. +/// +/// @return COI_TIME_OUT_REACHED if establishing the communication channel with +/// the remote process timed out. +/// +/// @return COI_DOES_NOT_EXIST if in_FileOfOrigin is not NULL and does not +/// exist. +/// +/// @return COI_ARGUMENT_MISMATCH if in_FileOfOrigin is NULL and +/// in_FileOfOriginOffset is not 0. +/// +/// @return COI_INVALID_FILE if in_FileOfOrigin is not a "regular file" as +/// determined by stat or if its size is 0. +/// +/// @return COI_OUT_OF_RANGE if in_FileOfOrigin exists but its size is +/// less than in_FileOfOriginOffset + in_BinaryBufferLength. +/// +/// @return COI_NOT_INITIALIZED if the environment variable +/// SINK_LD_TRACE_LOADED_OBJECTS is set to a non empty string and there +/// are no errors locating the shared library dependencies. +/// +/// @return COI_PROCESS_DIED if at some point during the loading of the remote +/// process the remote process terminated abnormally. +/// +/// @return COI_VERSION_MISMATCH if the version of Intel® Coprocessor +/// Offload Infrastructure (Intel® COI) on the host is not +/// compatible with the version on the device. +/// +COIACCESSAPI +COIRESULT +COIProcessCreateFromMemory( + COIENGINE in_Engine, + const char* in_pBinaryName, + const void* in_pBinaryBuffer, + uint64_t in_BinaryBufferLength, + int in_Argc, + const char** in_ppArgv, + uint8_t in_DupEnv, + const char** in_ppAdditionalEnv, + uint8_t in_ProxyActive, + const char* in_Reserved, + uint64_t in_InitialBufferSpace, + const char* in_LibrarySearchPath, + const char* in_FileOfOrigin, + uint64_t in_FileOfOriginOffset, + COIPROCESS* out_pProcess); + +////////////////////////////////////////////////////////////////////////////// +/// +/// Destroys the indicated process, releasing its resources. Note, this +/// will destroy any outstanding pipelines created in this process as well. +/// +/// @param in_Process +/// [in] Process to destroy. +/// +/// @param in_WaitForMainTimeout +/// [in] The number of milliseconds to wait for the main() function +/// to return in the sink process before timing out. -1 means to wait +/// indefinitely. +/// +/// @param in_ForceDestroy +/// [in] If this flag is set to true, then the sink process will be +/// forcibly terminated after the timeout has been reached. A timeout +/// value of 0 will kill the process immediately, while a timeout of +/// -1 is invalid. If the flag is set to false then a message will +/// be sent to the sink process requesting a clean shutdown. A value +/// of false along with a timeout of 0 does not send a shutdown +/// message, instead simply polls the process to see if it is alive. +/// In most cases this flag should be set to false. If a sink process +/// is not responding then it may be necessary to set this flag to +/// true. +/// +/// @param out_pProcessReturn +/// [out] The value returned from the main() function executing in +/// the sink process. This is an optional parameter. If the caller +/// is not interested in the return value from the remote process +/// they may pass in NULL for this parameter. The output value of +/// this pointer is only meaningful if COI_SUCCESS is returned. +/// +/// @param out_pTerminationCode +/// [out] This parameter specifies the termination code. This will +/// be 0 if the remote process exited cleanly. If the remote process +/// exited abnormally this will contain the termination code given +/// by the operating system of the remote process. This is an optional +/// parameter and the caller may pass in NULL if they are not +/// interested in the termination code. The output value of this +/// pointer is only meaningful if COI_SUCCESS is returned. +/// +/// @return COI_SUCCESS if the process was destroyed. +/// +/// @return COI_INVALID_HANDLE if the process handle passed in was invalid. +/// +/// @return COI_OUT_OF_RANGE for any negative in_WaitForMainTimeout value +/// except -1. +/// +/// @return COI_ARGUMENT_MISMATCH if in_WaitForMainTimeout is -1 and +/// in_ForceDestroy is true. +/// +/// @return COI_TIME_OUT_REACHED if the sink process is still running after +/// waiting in_WaitForMainTimeout milliseconds and in_ForceDestroy +/// is false. This is true even if in_WaitForMainTimeout was 0. +/// In this case, out_pProcessReturn and out_pTerminationCode +/// are undefined. +/// +COIACCESSAPI +COIRESULT +COIProcessDestroy( + COIPROCESS in_Process, + int32_t in_WaitForMainTimeout, + uint8_t in_ForceDestroy, + int8_t* out_pProcessReturn, + uint32_t* out_pTerminationCode); + + +#define COI_MAX_FUNCTION_NAME_LENGTH 256 + +////////////////////////////////////////////////////////////////////////////// +/// +/// Given a loaded native process, gets an array of function handles that can +/// be used to schedule run functions on a pipeline associated with that +/// process. See the documentation for COIPipelineRunFunction() for +/// additional information. All functions that are to be retrieved in this +/// fashion must have the define COINATIVEPROCESSEXPORT preceeding their type +/// specification. For functions that are written in C++, either the entries +/// in in_pFunctionNameArray in must be pre-mangled, or the functions must be +/// declared as extern "C". It is also necessary to link the binary containing +/// the exported functions with the -rdynamic linker flag. +/// It is possible for this call to successfully find function handles for +/// some of the names passed in but not all of them. If this occurs +/// COI_DOES_NOT_EXIST will return and any handles not found will be returned +/// as NULL. +/// +/// @param in_Process +/// [in] Process handle previously returned via COIProcessCreate(). +/// +/// @param in_NumFunctions +/// [in] Number of function names passed in to the in_pFunctionNames +/// array. +/// +/// @param in_ppFunctionNameArray +/// [in] Pointer to an array of null-terminated strings that match +/// the name of functions present in the code of the binary +/// previously loaded via COIProcessCreate(). Note that if a C++ +/// function is used, then the string passed in must already be +/// properly name-mangled, or extern "C" must be used for where +/// the function is declared. +/// +/// @param out_pFunctionHandleArray +/// [in out] Pointer to a location created by the caller large +/// enough to hold an array of COIFUNCTION sized elements that has +/// in_numFunctions entries in the array. +/// +/// @return COI_SUCCESS if all function names indicated were found. +/// +/// @return COI_INVALID_HANDLE if the in_Process handle passed in was invalid. +/// +/// @return COI_OUT_OF_RANGE if in_NumFunctions is zero. +/// +/// @return COI_INVALID_POINTER if the in_ppFunctionNameArray or +/// out_pFunctionHandleArray pointers was NULL. +/// +/// @return COI_DOES_NOT_EXIST if one or more function names were not +/// found. To determine the function names that were not found, +/// check which elements in the out_pFunctionHandleArray +/// are set to NULL. +/// +/// @return COI_OUT_OF_RANGE if any of the null-terminated strings passed in +/// via in_ppFunctionNameArray were more than +/// COI_MAX_FUNCTION_NAME_LENGTH characters in length including +/// the null. +/// +/// @warning This operation can take several milliseconds so it is recommended +/// that it only be be done at load time. +/// +COIACCESSAPI +COIRESULT +COIProcessGetFunctionHandles( + COIPROCESS in_Process, + uint32_t in_NumFunctions, + const char** in_ppFunctionNameArray, + COIFUNCTION* out_pFunctionHandleArray); + +#if COI_LIBRARY_VERSION >= 2 +/// @name COIProcessLoadLibrary* flags, named after the corresponding +/// RTLD flags that are passed into dlopen(). +/// Please consult a Linux manual for more information about these flags. +//@{ +#define COI_LOADLIBRARY_LOCAL 0x00000 +#define COI_LOADLIBRARY_GLOBAL 0x00100 + +#define COI_LOADLIBRARY_LAZY 0x00001 +#define COI_LOADLIBRARY_NOW 0x00002 +#define COI_LOADLIBRARY_NOLOAD 0x00004 +#define COI_LOADLIBRARY_DEEPBIND 0x00008 +#define COI_LOADLIBRARY_NODELETE 0x01000 + +/// Flags to replicate the behavior of the original version of +/// COIProcessLoadLibrary* APIs. +#define COI_LOADLIBRARY_V1_FLAGS (COI_LOADLIBRARY_GLOBAL|COI_LOADLIBRARY_NOW) + +//@} + +#endif + +////////////////////////////////////////////////////////////////////////////// +/// +/// Loads a shared library into the specified remote process, akin to using +/// dlopen() on a local process in Linux or LoadLibrary() in Windows. +/// Dependencies for this library that are not listed with absolute paths +/// are searched for first in current working directory, then in the +/// colon-delimited paths in the environment variable SINK_LD_LIBRARY_PATH, +/// and finally on the sink in the standard search paths as defined by the +/// sink's operating system / dynamic loader. +/// +/// @param in_Process +/// [in] Process to load the library into. +/// +/// @param in_pLibraryBuffer +/// [in] The memory buffer containing the shared library to load. +/// +/// @param in_LibraryBufferLength +/// [in] The number of bytes in the memory buffer in_pLibraryBuffer. +/// +/// @param in_pLibraryName +/// [in] Name for the shared library. This optional parameter can +/// be specified in case the dynamic library doesn't have an +/// SO_NAME field. If specified, it will take precedence over +/// the SO_NAME if it exists. If it is not specified then +/// the library must have a valid SO_NAME field. +/// +///@param in_LibrarySearchPath +/// [in] A path to locate dynamic libraries dependencies for the +/// library being loaded. If not NULL, this path will override the +/// environment variable SINK_LD_LIBRARY_PATH. If NULL it will use +/// SINK_LD_LIBRARY_PATH to locate dependencies. +/// +///@param in_LibrarySearchPath +/// [in] A path to locate dynamic libraries dependencies for the sink +/// application. If not NULL, this path will override the environment +/// variable SINK_LD_LIBRARY_PATH. If NULL it will use +/// SINK_LD_LIBRARY_PATH to locate dependencies. +/// +/// @param in_FileOfOrigin +/// [in] If not NULL, this parameter indicates the file from which the +/// in_pBinaryBuffer was obtained. This parameter is optional. +/// +/// @param in_FileOfOriginOffset +/// [in] If in_FileOfOrigin is not NULL, this parameter indicates the +/// offset within that file where in_pBinaryBuffer begins. +/// +#if COI_LIBRARY_VERSION >= 2 +/// @param in_Flags +/// [in] Bitmask of the flags that will be passed in as the dlopen() +/// "flag" parameter on the sink. +/// +#endif +/// +/// @param out_pLibrary +/// [out] If COI_SUCCESS or COI_ALREADY_EXISTS is returned, the handle +/// that uniquely identifies the loaded library. +/// +/// @return COI_SUCCESS if the library was successfully loaded. +/// +/// @return COI_INVALID_HANDLE if the process handle passed in was invalid. +/// +/// @return COI_OUT_OF_RANGE if in_LibraryBufferLength is 0. +/// +/// @return COI_INVALID_FILE if in_pLibraryBuffer does not represent a valid +/// shared library file. +/// +/// @return COI_MISSING_DEPENDENCY if a dependent library is missing from +/// either SINK_LD_LIBRARY_PATH or the in_LibrarySearchPath parameter. +/// +/// @return COI_ARGUMENT_MISMATCH if the shared library is missing an SONAME +/// and in_pLibraryName is NULL. +/// +/// @return COI_ARGUMENT_MISMATCH if in_pLibraryName is the same as that of +/// any of the dependencies (recursive) of the library being loaded. +/// +/// @return COI_ALREADY_EXISTS if there is an existing COILIBRARY handle +/// that identifies this library, and this COILIBRARY hasn't been +/// unloaded yet. +/// +/// @return COI_BINARY_AND_HARDWARE_MISMATCH if the target machine of the +/// binary or any of its recursive dependencies does not match the +/// engine associated with in_Process. +/// +/// @return COI_UNDEFINED_SYMBOL if we are unable to load the library due to +/// an undefined symbol. +/// +/// @return COI_PROCESS_DIED if loading the library on the device caused +/// the remote process to terminate. +/// +/// @return COI_DOES_NOT_EXIST if in_FileOfOrigin is not NULL and does not +/// exist. +/// +/// @return COI_ARGUMENT_MISMATCH if in_FileOfOrigin is NULL and +/// in_FileOfOriginOffset is not 0. +/// +/// @return COI_INVALID_FILE if in_FileOfOrigin is not a "regular file" as +/// determined by stat or if its size is 0. +/// +/// @return COI_OUT_OF_RANGE if in_FileOfOrigin exists but its size is +/// less than in_FileOfOriginOffset + in_BinaryBufferLength. +/// +/// @return COI_INVALID_POINTER if out_pLibrary or in_pLibraryBuffer are NULL. +/// +#if COI_LIBRARY_VERSION >= 2 +COIACCESSAPI +COIRESULT +COIProcessLoadLibraryFromMemory( + COIPROCESS in_Process, + const void* in_pLibraryBuffer, + uint64_t in_LibraryBufferLength, + const char* in_pLibraryName, + const char* in_LibrarySearchPath, + const char* in_FileOfOrigin, + uint64_t in_FileOfOriginOffset, + uint32_t in_Flags, + COILIBRARY* out_pLibrary); +__asm__(".symver COIProcessLoadLibraryFromMemory," + "COIProcessLoadLibraryFromMemory@COI_2.0"); +#else + +COIRESULT +COIProcessLoadLibraryFromMemory( +COIPROCESS in_Process, + const void* in_pLibraryBuffer, + uint64_t in_LibraryBufferLength, + const char* in_pLibraryName, + const char* in_LibrarySearchPath, + const char* in_FileOfOrigin, + uint64_t in_FileOfOriginOffset, + COILIBRARY* out_pLibrary); +__asm__(".symver COIProcessLoadLibraryFromMemory," + "COIProcessLoadLibraryFromMemory@COI_1.0"); +#endif + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Loads a shared library into the specified remote process, akin to using +/// dlopen() on a local process in Linux or LoadLibrary() in Windows. +/// +/// For more details, see COIProcessLoadLibraryFromMemory. +/// +/// @param in_Process +/// [in] Process to load the library into. +/// +/// @param in_pFileName +/// [in] The name of the shared library file on the source's file +/// system that is being loaded. If the file name is not an absolute +/// path, the file is searched for in the same manner as dependencies. +/// +/// @param in_pLibraryName +/// [in] Name for the shared library. This optional parameter can +/// be specified in case the dynamic library doesn't have an +/// SO_NAME field. If specified, it will take precedence over +/// the SO_NAME if it exists. If it is not specified then +/// the library must have a valid SO_NAME field. +/// +///@param in_LibrarySearchPath +/// [in] a path to locate dynamic libraries dependencies for the +/// library being loaded. If not NULL, this path will override the +/// environment variable SINK_LD_LIBRARY_PATH. If NULL it will use +/// SINK_LD_LIBRARY_PATH to locate dependencies. +/// +#if COI_LIBRARY_VERSION >= 2 +/// @param in_Flags +/// [in] Bitmask of the flags that will be passed in as the dlopen() +/// "flag" parameter on the sink. +/// +#endif +/// +/// @param out_pLibrary +/// [out] If COI_SUCCESS or COI_ALREADY_EXISTS is returned, the handle +/// that uniquely identifies the loaded library. +/// +/// @return COI_SUCCESS if the library was successfully loaded. +/// +/// @return COI_INVALID_POINTER if in_pFileName is NULL. +/// +/// @return COI_DOES_NOT_EXIST if in_pFileName cannot be found. +/// +/// @return COI_INVALID_FILE if the file is not a valid shared library. +/// +/// @return See COIProcessLoadLibraryFromMemory for additional errors. +/// +#if COI_LIBRARY_VERSION >= 2 + +COIACCESSAPI +COIRESULT +COIProcessLoadLibraryFromFile( + COIPROCESS in_Process, + const char* in_pFileName, + const char* in_pLibraryName, + const char* in_LibrarySearchPath, + uint32_t in_Flags, + COILIBRARY* out_pLibrary); +__asm__(".symver COIProcessLoadLibraryFromFile," + "COIProcessLoadLibraryFromFile@COI_2.0"); +#else + +COIRESULT +COIProcessLoadLibraryFromFile( + COIPROCESS in_Process, + const char* in_pFileName, + const char* in_pLibraryName, + const char* in_LibrarySearchPath, + COILIBRARY* out_pLibrary); +__asm__(".symver COIProcessLoadLibraryFromFile," + "COIProcessLoadLibraryFromFile@COI_1.0"); +#endif + +////////////////////////////////////////////////////////////////////////////// +/// +/// Unloads a a previously loaded shared library from the specified +/// remote process. +/// +/// @param in_Process +/// [in] Process that we are unloading a library from. +/// +/// @param in_Library +/// [in] Library that we want to unload. +/// +/// @return COI_SUCCESS if the library was successfully loaded. +/// +/// @return COI_INVALID_HANDLE if the process or library handle were invalid. +/// +COIACCESSAPI +COIRESULT +COIProcessUnloadLibrary( + COIPROCESS in_Process, + COILIBRARY in_Library); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Registers shared libraries that are already in the host process's memory +/// to be used during the shared library dependency resolution steps that take +/// place during subsequent calls to COIProcessCreate* and +/// COIProcessLoadLibrary*. If listed as a dependency, the registered library +/// will be used to satisfy the dependency, even if there is another library +/// on disk that also satisfies that dependency. +/// +/// Addresses registered must remain valid during subsequent calls to +/// COIProcessCreate* and COIProcessLoadLibrary*. +/// +/// If the Sink is Linux, the shared libraries must have a library name +/// (DT_SONAME field). On most compilers this means built with -soname. +/// +/// If successful, this API registers all the libraries. Otherwise none +/// are registered. +/// +/// @param in_NumLibraries +/// [in] The number of libraries that are being registered. +/// +/// @param in_ppLibraryArray +/// [in] An array of pointers that point to the starting addresses +/// of the libraries. +/// +/// @param in_pLibrarySizeArray +/// [in] An array of pointers that point to the number of bytes in +/// each of the libraries. +/// +/// @param in_ppFileOfOriginArray +/// [in] An array of strings indicating the file from which the +/// library was obtained. This parameter is optional. Elements +/// in the array may be set to NULL. +/// +/// @param in_pFileOfOriginOffSetArray +/// [in] If the corresponding entry in in_ppFileOfOriginArray is not +/// NULL, this parameter indicates the offsets within those files +/// where the corresponding libraries begin. +/// +/// @return COI_SUCCESS if the libraries were registered successfully. +/// +/// @return COI_OUT_OF_RANGE if in_NumLibraries is 0. +/// +/// @return COI_INVALID_POINTER if in_ppLibraryArray or in_pLibrarySizeArray +/// are NULL. +/// +/// @return COI_INVALID_POINTER if any of the pointers in in_ppLibraryArray +/// are NULL. +/// +/// @return COI_OUT_OF_RANGE if any of the values in in_pLibrarySizeArray is 0. +/// +/// @return COI_ARGUMENT_MISMATCH if either one of in_ppFileOfOriginArray +/// and in_pFileOfOriginOffSetArray is NULL and the other is not. +/// +/// @return COI_OUT_OF_RANGE if one of the addresses being registered does not +/// represent a valid library. +/// +COIACCESSAPI +COIRESULT +COIProcessRegisterLibraries( + uint32_t in_NumLibraries, + const void** in_ppLibraryArray, + const uint64_t* in_pLibrarySizeArray, + const char** in_ppFileOfOriginArray, + const uint64_t* in_pFileOfOriginOffSetArray); + + +////////////////////////////////////////////////////////////////////////////// +/// The user can choose to have notifications for these internal events +/// so that they can build their own profiling and performance layer on +/// top of Intel® Coprocessor Offload Infrastructure (Intel® COI) . +/// +typedef enum COI_NOTIFICATIONS +{ + /// This event occurs when all explicit and implicit dependencies are + /// satisified and Intel® Coprocessor Offload Infrastructure + /// (Intel® COI) schedules the run function to begin execution. + RUN_FUNCTION_READY = 0, + + /// This event occurs just before the run function actually starts + /// executing. There may be some latency between the ready and start + /// events if other run functions are already queued and ready to run. + RUN_FUNCTION_START, + + /// This event occurs when the run function finishes. This is when the + /// completion event for that run function would be signaled. + RUN_FUNCTION_COMPLETE, + + /// This event occurs when all explicit and implicit dependencies are + /// met for the pending buffer operation. Assuming buffer needs to be + /// moved, copied, read, etc... Will not be invoked if no actual memory + /// is moved, copied, read, etc. This means that COIBufferUnmap will + /// never result in a callback as it simply updates the status of the + /// buffer but doesn't initiate any data movement. COIBufferMap, + /// COIBufferSetState, COIBufferWrite, COIBufferRead and COIBufferCopy + /// do initiate data movement and therefore will invoke the callback. + BUFFER_OPERATION_READY, + + /// This event occurs when the buffer operation is completed. + BUFFER_OPERATION_COMPLETE, + + /// This event occurs when a user event is signaled from the remotely + /// a sink process. Local (source triggered) events do not trigger this. + USER_EVENT_SIGNALED +} COI_NOTIFICATIONS; + +////////////////////////////////////////////////////////////////////////////// +/// +/// A callback that will be invoked to notify the user of an internal +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// event. Note that the callback is registered per process so any of the +/// above notifications that happen on the registered process will receive +/// the callback. +/// As with any callback mechanism it is up to the user to make sure that +/// there are no possible deadlocks due to reentrancy (ie the callback being +/// invoked in the same context that triggered the notification) and also +/// that the callback does not slow down overall processing. If the user +/// performs too much work within the callback it could delay further +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// processing. +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) +/// promises to invoke the callback for an internal event prior to +/// signaling the corresponding COIEvent. For example, if a user is waiting +/// for a COIEvent associated with a run function completing they will +/// receive the callback before the COIEvent is marked as signaled. +/// +/// +/// @param in_Type +/// [in] The type of internal event that has occurred. +/// +/// @param in_Process +/// [in] The process associated with the operation. +/// +/// @param in_Event +/// [in] The completion event that is associated with the +/// operation that is being notified. +/// +/// @param in_UserData +/// [in] Opaque data that was provided when the callback was +/// registered. Intel® Coprocessor Offload Infrastructure (Intel® COI) simply passes this back to the user so that +/// they can interpret it as they choose. +/// +typedef void (*COI_NOTIFICATION_CALLBACK)( + COI_NOTIFICATIONS in_Type, + COIPROCESS in_Process, + COIEVENT in_Event, + const void* in_UserData); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Register a callback to be invoked to notify that an internal +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) event +/// has occured on the process that is associated with the callback. +/// Note that it is legal to have more than one callback registered with +/// a given process but those must all be unique callback pointers. +/// Note that setting a UserData value with COINotificationCallbackSetContext +/// will override a value set when registering the callback. +/// +/// @param in_Process +/// [in] Process that the callback is associated with. The callback +/// will only be invoked to notify an event for this specific process. +/// +/// @param in_Callback +/// [in] Pointer to a user function used to signal a notification. +/// +/// @param in_UserData +/// [in] Opaque data to pass to the callback when it is invoked. +/// +/// @return COI_SUCCESS if the callback was registered successfully. +/// +/// @return COI_INVALID_HANDLE if the in_Process parameter does not identify +/// a valid process. +/// +/// @return COI_INVALID_POINTER if the in_Callback parameter is NULL. +/// +/// @return COI_ALREADY_EXISTS if the user attempts to reregister the same +/// callback for a process. +/// +COIACCESSAPI +COIRESULT COIRegisterNotificationCallback( + COIPROCESS in_Process, + COI_NOTIFICATION_CALLBACK in_Callback, + const void* in_UserData); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Unregisters a callback, notifications will no longer be signaled. +/// +/// @param in_Process +/// [in] Process that we are unregistering. +/// +/// @param in_Callback +/// [in] The specific callback to unregister. +/// +/// @return COI_SUCCESS if the callback was unregistered. +/// +/// @return COI_INVALID_HANDLE if the in_Process parameter does not identify +/// a valid process. +/// +/// @return COI_INVALID_POINTER if the in_Callback parameter is NULL. +/// +/// @return COI_DOES_NOT_EXIST if in_Callback was not previously registered +/// for in_Process. +/// +COIACCESSAPI +COIRESULT COIUnregisterNotificationCallback( + COIPROCESS in_Process, + COI_NOTIFICATION_CALLBACK in_Callback); + + +////////////////////////////////////////////////////////////////////////////// +/// +/// Set the user data that will be returned in the notification callback. +/// This data is sticky and per thread so must be set prior to the +/// Intel® Coprocessor Offload Infrastructure (Intel® COI) // +/// operation being invoked. If you wish to set the context to be returned +/// for a specific instance of a user event notification then the context +/// must be set using this API prior to registering that user event with +/// COIEventRegisterUserEvent. +/// The value may be set prior to each Intel® Coprocessor Offload +/// Infrastructure (Intel® COI) operation being called to +/// effectively have a unique UserData per callback. +/// Setting this value overrides any value that was set when the +/// callback was registered and will also override any future registrations +/// that occur. +/// +/// @param in_UserData +/// [in] Opaque data to pass to the callback when it is invoked. +/// Note that this data is set per thread. +/// +COIACCESSAPI +void COINotificationCallbackSetContext( + const void* in_UserData); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* _COIPROCESS_SOURCE_H */ + +/*! @} */ diff --git a/liboffloadmic/include/myo/myo.h b/liboffloadmic/include/myo/myo.h new file mode 100644 index 00000000000..c6e5f56ede2 --- /dev/null +++ b/liboffloadmic/include/myo/myo.h @@ -0,0 +1,619 @@ +/* + * 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 + **/ + +/*! @} */ diff --git a/liboffloadmic/include/myo/myoimpl.h b/liboffloadmic/include/myo/myoimpl.h new file mode 100644 index 00000000000..d998ef3feb6 --- /dev/null +++ b/liboffloadmic/include/myo/myoimpl.h @@ -0,0 +1,538 @@ +/* + * 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: + Define APIs of MYO for compiler or pre-processor to transfer original programs. + */ + +#ifndef _MYO_IMPL_H_ +#define _MYO_IMPL_H_ + +/** @ingroup MYO + * @addtogroup MYOIMPL_API +@{ +* @file myoimpl.h +*/ + +#ifdef __cplusplus +extern "C" { +#define EXTERN_C extern "C" +#else +#define EXTERN_C /* nothing */ +#endif + +# define MYOACCESSAPI /* nothing */ + +#ifdef DEFINE_ARENA_API_CILK_SHARED +#define CILK_SHARED _Cilk_shared +#else +#define CILK_SHARED /* nothing */ +#endif + +/* **************************************************************************** *\ + APIs to enable functions being remotely called +\* **************************************************************************** */ + +typedef void *(*MyoiRemoteFuncType)(void *); + +/** @fn extern MyoError myoiRemoteFuncRegister(MyoiRemoteFuncType in_pFuncAddr, + * const char *in_pFuncName) + * @brief Register a function so that it can be remotely called. This should be + * done in myoiUserInit or before calling myoiLibInit. After myoiLibInit, + * there will be a table on all peers, which contains the information for + * all remotely callable functions. + * + * @param in_pWrapFuncAddr address of the wrapper function. + * @param in_pFuncName name of the function. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ + +MYOACCESSAPI +MyoError myoiRemoteFuncRegister(MyoiRemoteFuncType in_pFuncAddr, + const char *in_pFuncName); +/** @fn extern MyoError myoiRemoteFuncLookupByName(char *in_pFuncName, + * MyoiRemoteFuncType *out_pWrapFuncAddr) + * @brief Get the address of the wrapper function by looking up the table + * by name. This API can be used when assigning a function pointer to + * remotely callable functions. + * + * @param in_pFuncName name of the function. + * @param out_pWrapFuncAddr address of the wrapper function. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI MyoError myoiRemoteFuncLookupByName(char *in_pFuncName, + MyoiRemoteFuncType *out_pWrapFuncAddr); + +/** @fn extern MyoError myoiRemoteFuncLookupByAddr(MyoiRemoteFuncType + * in_pWrapFuncAddr,char **out_pFuncName) + * @brief Get the name of a remote function by looking up the table by + * the address. This API can be used when calling a remotely callable + * function by a function pointer. + * + * @param in_pWrapFuncAddr address of the function. + * @param out_pFuncName name of the function. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI MyoError myoiRemoteFuncLookupByAddr(MyoiRemoteFuncType in_pWrapFuncAddr, + char **out_pFuncName); + +//! Host Side Shared Function Pointer Entry Struct +typedef struct { + //! Function Name + const char *funcName; + //! Function Address + void *funcAddr; + //! Local Thunk Address + void *localThunkAddr; +} MyoiHostSharedFptrEntry; + +//! Target Side Shared Function Pointer Entry Struct +typedef struct { + //! Function Name + const char *funcName; + //! Function Address + void *funcAddr; + //! Wrap Function Address + void *wrapFuncAddr; + //! Locak Thunk Address + void *localThunkAddr; +} MyoiTargetSharedFptrEntry; + +/** + * @cond INCLUDE_MYO_INTERNAL_DOCUMENTATION + * @fn extern MyoError myoiHostFptrTableRegister(void *in_pAddrOfFptrTable, + * int in_NumEntry, int in_Ordered) + * @brief Register shared functions on host side. A 16 byte thunk will be + * allocated for each function entry in non-coherent shared memory. The + * thunk will contain a jump instruction to the local version of the + * shared function, which is provided by the second item of the function + * entry. Also, the address of the thunk will be stored to the 3rd item + * of the function entry for Compiler usage. + * + * @param in_pAddrOfFptrTable start address of the shared function + * table, assuming it follows the format of MyoiHostSharedFptrEntry. + * @param in_NumEntry number of entry in the table. + * @param in_Ordered whether the table is ordered by function name. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI +MyoError myoiHostFptrTableRegister( + void *in_pAddrOfFptrTable, int in_NumEntry, int in_Ordered); + +/** @fn extern MyoError myoiTargetFptrTableRegister(void *in_pAddrOfFptrTable, + * int in_NumEntry, int in_Ordered) + * @brief Register shared functions on target side. This function is the + * same as myoiHostFptrTableRegister, except it does not need to allocate + * thunks from non-coherent shared memory for each function entry, but + * instead looks up this information from a table retrieved from the + * Host side. + * + * @param in_pAddrOfFptrTable start address of the shared function + * table, assuming it follows the format of MyoiTargetSharedFptrEntry. + * @param in_NumEntry number of entry in the table. + * @param in_Ordered whether the table is ordered by function name. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +extern MyoError myoiTargetFptrTableRegister( + void *in_pAddrOfFptrTable, int in_NumEntry, int in_Ordered); +/** + * @endcond + **/ + +/* *************************************************************************** *\ + APIs for remote function calls +\* *************************************************************************** */ + +typedef void * MyoiRFuncCallHandle; + +/** @fn extern MyoiRFuncCallHandle myoiRemoteCall(char *in_pFuncName, + * void *in_pArgs, int in_deviceNum) + * @brief Call a remote callable function. If there are multiple arguments + * for the function, pack them to a shared buffer beforehand and take the + * address of the shared buffer as this function. After receiving the call + * requests from other peers, the arguments should be unpacked from the + * shared buffer before calling the target function. The shared buffer + * can also be used to store the return value of the function. + * + * @param in_pFuncName name of the function. + * @param in_pArgs address of the shared buffer. + * @return + * Handle used to check the result. + **/ +MYOACCESSAPI +MyoiRFuncCallHandle myoiRemoteCall(const char *in_pFuncName, void *in_pArgs, int in_deviceNum); + +/** + * @cond INCLUDE_MYO_INTERNAL_DOCUMENTATION + * @fn extern MyoError myoiRemoteThunkCall(void *in_funcThunkAddr, void *in_pArgs, int in_deviceNum) + * @brief Call a remote callable function. If there are multiple arguments for + * the function, pack them to a shared buffer beforehand and take the address + * of the shared buffer as this function. After receiving the call requests + * from other peers, the arguments should be unpacked from the shared buffer + * before calling the target function. The shared buffer can also be used to + * store the return value of the function. + * + * @param in_funcThunkAddr pointer to function thunk in the non-coherent + * shared memory. + * @param in_pArgs address of the shared buffer. + * @PARAM in_deviceNum: device ID (0-N-1) for the MIC device to run + * function call. -1 request causes MYO to schedule an available device. + * For RPC from device to host, in_deviceNum should always be -1. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI +MyoError myoiRemoteThunkCall(void *in_funcThunkAddr, void *in_pArgs, int in_deviceNum); +/** + * @endcond + **/ + +/** @fn extern MyoError myoiCheckResult(MyoiRFuncCallHandle in_Handle) + * @brief Check whether the remote call is done. + * + * @param in_Handle handle of the remote call. + * @return + * MYO_SUCCESS (done); or + * an error number to indicate the error. + **/ +extern MyoError myoiCheckResult(MyoiRFuncCallHandle in_Handle); + +/** @fn extern MyoError myoiGetResult(MyoiRFuncCallHandle in_Handle) + * @brief Wait till the remote call is done. + * + * @param in_Handle handle of the remote call. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI +MyoError myoiGetResult(MyoiRFuncCallHandle in_Handle); + +/* **************************************************************************** *\ + APIs related with shared variables. +\* **************************************************************************** */ + +/* + * It is Compiler's responsibility to make sure all shared variables + * located in shared memory space and have the same address in all sides. + * However, it is hard for Compiler to do this. So we propose a solution + * which is changing the definition of all shared variables and accessing + * them indirectly, and making sure all shared variables pointing + * to the same shared space on all sides. For example, + * + * "shared int a;" is changed to "shared int *a"; + * Also all the accesses to "a" is change to "*a". + * + * We suppose the shared memory for each shared variable is allocated on + * host side by Compiler. For the upper example, Compiler can call: + * + * a = (shared int *) myoSharedMalloc(sizeof(shared int)); + * + * Now the issue is how to make "a" on other sides also pointing to the + * same shared memory on other sides. We provide two methods to do this. + * They can be used in a hybrid way. + */ + +/* + * The first method is calling myoiVarRegister for each shared variable + * on all sides in myoiUserInit. On host side, we will get a table containing + * a table containing the shared address and name of each shared variable. + * After calling myoiUserInit, we will propagate the table to other sides. + * On card side, after getting the table from host, myoiUserInit is called. + * When calling myoiVarRegister in myoiUserInit, we will make local pointer + * of each shared variable pointing to the same shared memory with the local + * pointer on host side of the same shared variable pointing to. + */ + +/* + * The second method suppose that Compiler already have a table on all sides. + * On host side, the table contains the name and the shared address of each + * shared variable. On card side, the table contains the name of each shared + * variable and the address of the local pointer which will pointing to shared + * memory space. + * + * On host side, Compiler generates a call to myoiHostVarTablePropagate + * after initializing MYO runtime and making the host side table ready. + * On card side, Compiler uses myoiMicVarTableRegister to tell + * the runtime where the card side table is. + * + * Since there may be multiple libraries on card side for the same application, + * myoiHostVarTablePropagate and myoiMicVarTableRegister can be called multiple + * times and called simultaneously. + * + * Inside runtime, the local pointer of the same shared variable on all sides + * will be make sure pointing to the same shared space by using the information + * of the Compiler provided tables. + */ + +/* + * Comipler knows the following two structures to make sure the var table + * has the following format. + */ + +/* + * This is structure of the Shared var table entry. This table contains + * the shared address and name of each shared variable + */ + +/** @fn extern MyoError myoiVarRegister(void *in_pAddrOfLocalPtrToShared, char *in_pSVarName) + * @brief Register shared variables. Call it on all sides in myoiUserInit. + * On host side, make sure calling it after allocating shared memory for + * the shared variables by calling myoSharedMalloc. + * + * @param in_pAddrOfLocalPtrToShared the address assigned by the compiler + * for the shared variable, which is the address of a local pointer, + * pointing to shared memory space. + * @param in_pSVarName name of shared variable. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI +MyoError myoiVarRegister( + void *in_pAddrOfLocalPtrToShared, const char *in_pSVarName); + +/* + * Compiler knows the following two structures to make sure the var table + * has the following format. + */ + +/** + * This is structure of the Shared var table entry. This table contains + * the shared address and name of each shared variable + **/ +typedef struct { + //! Variable Name + const char *varName; + //! Shared Address + void *sharedAddr; +} MyoiSharedVarEntry; + +//! Structure of the var table entry on host +typedef struct { + //! Variable Name + const char *varName; + //! Variable Size + int size; + //! Local pointer to Shared var + void *ptrToLocalPtrToShared; +} MyoiHostSharedVarEntry; + +//! Structure of the var table entry on card +typedef struct { + //! Variable Name + const char *varName; + //! Local pointer to Shared var + void *ptrToLocalPtrToShared; +} MyoiMicSharedVarEntry; + +/** @fn extern MyoError myoiHostVarTablePropagate(void *in_pAddrOfSVarTable, int in_NumEntry) + * @brief Send the host side var table to the card side. Card side will also + * have a copy of the host side var table after this propagation, although it + * is in an internal format different than the original host side var table, + * due to implementation convenience. + * + * @param in_pAddrOfSVarTable start address of the host side var table, + * assuming it follows the format of MyoiSharedVarEntry. + * @param in_NumEntry number of entry in the table. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI MyoError myoiHostVarTablePropagate( + void *in_pAddrOfSVarTable, int in_NumEntry); + +/** + * @cond INCLUDE_MYO_INTERNAL_DOCUMENTATION + * @fn extern MyoError myoiMicVarTableRegister(void *in_pAddrOfSVarTable, int in_NumEntry) + * @brief Tell the runtime where the card side table is. + * + * @param in_pAddrOfSVarTable start address of the card side var + * table, assuming it follows the format of MyoiMicSharedVarEntry. + * @param in_NumEntry number of entry in the table. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +extern MyoError myoiMicVarTableRegister( + void *in_pAddrOfSVarTable, int in_NumEntry); +/** + * @endcond + **/ + +/** @fn MyoError myoiHostSharedMallocTableRegister(void *in_pAddrOfSVarTable, int in_NumEntry, int in_Ordered) + * @brief Allocate shared memory for all shared variables in the table. + * Also update local address of the shared variable with new shared address. + * + * @param in_pAddrOfSVarTable start address of the shared variable table, + * assuming it follows the format of MyoiHostSharedVarEntry. + * @param in_NumEntry number of entry in the table. + * @param in_Ordered whether the table ordered by name. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI +MyoError myoiHostSharedMallocTableRegister( + void *in_pAddrOfSVarTable, int in_NumEntry, int in_Ordered); + +/** @fn extern MyoError myoiTargetSharedMallocTableRegister(void *in_pAddrOfSVarTable, int in_NumEntry, int in_Ordered) + * @brief Register the shared variables on the target side. + * + * @param in_pAddrOfSVarTable start address of the shared varaible table, + * assuming it follows the format of MyoiMicSharedVarEntry. + * @param in_NumEntry number of entry in the table. + * @param in_Ordered whether the table ordered by name. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +extern MyoError myoiTargetSharedMallocTableRegister( + void *in_pAddrOfSVarTable, int in_NumEntry, int in_Ordered); + +/** @fn MyoError myoiLibInit(void * in_args, void (*userInitFunc)) + * @brief Init entry of the MYO library responsible for initializing + * the runtime. + * + * @param in_args mechanism to pass arguments to the Initialization + * routine. The default value of NULL would mean the host is blocked + * on the completion of myoiLibInit() on all nodes. A subset of the + * installed cards can be intialized by passing an array of + * MyoiUserParams. For example, in a system with two cards, to run a + * MYO application only on the second card, intialize the array as + * follows: + * @code + * MyoiUserParams UserParas[64]; + * UserParas[0].type = MYOI_USERPARAMS_DEVID; + * UserParas[0].nodeid = 2; + * UserParas[1].type = MYOI_USERPARAMS_LAST_MSG; + * if(MYO_SUCCESS != myoiLibInit(&UserParas, (void*)&myoiUserInit)) { + * printf("Failed to initialize MYO runtime\n"); + * return -1; + * } + * @endcode + * This intialization is required only in the client/host side + * of the application. The server/card side executable should be + * executed only on the second card in this case. + * + * @param userInitFunc Shared variables and remote funtions are + * registered in this routine, which is called by the runtime during + * library initialization. + * @return + * MYO_SUCCESS; + * MYO_ERROR; + **/ +MYOACCESSAPI +MyoError myoiLibInit(void * in_args, void *userInitFunc /*userInitFunc must be: MyoError (*userInitFunc)(void) */); + +/** @fn void myoiLibFini() + * @brief Finalize the MYO library, all resources held by the runtime are + * released by this routine. + * + * @return + **/ +MYOACCESSAPI +void myoiLibFini(); + +/* *************************************************************************** *\ + APIs to set shared memory space consistent/non-consistent. +\* *************************************************************************** */ + +/** @fn extern MyoError myoiSetMemNonConsistent(void *in_pAddr, size_t in_Size) + * @brief Set part of the shared memory space to be non-consistent, which + * means that the consistency of this part of shared memory space does not + * need to be maintained between HOST and cards. + * + * @param in_pAddr The start address of the specified shared memory space; + * @param in_Size The size of the specified shared memory space; + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI +MyoError myoiSetMemNonConsistent(void *in_pAddr, size_t in_Size); + +/** @fn extern MyoError myoiSetMemConsistent(void *in_pAddr, size_t in_Size) + * @brief Set part of the shared memory space to be consistent, which + * means that the consistency of this part of shared memory space needs + * to be maintained between HOST and cards. + * + * @param in_pAddr The start address of the specified shared + * memory space. + * @param in_size The size of the specified shared memory space. + * @return + * MYO_SUCCESS; or + * an error number to indicate the error. + **/ +MYOACCESSAPI +MyoError myoiSetMemConsistent(void *in_pAddr, size_t in_Size); + +/* A collection of external data symbols */ +EXTERN_C MYOACCESSAPI unsigned int myoiMyId; /* MYO_MYID if on accelerators */ +EXTERN_C MYOACCESSAPI volatile int myoiInitFlag; + + + //! Structure of the array element that is passed to myoiLibInit() to initialize a subset of the available cards. +typedef struct{ + //!type = MYOI_USERPARAMS_DEVID for each element in the array except the last element ; type = MYOI_USERPARAMS_LAST_MSG for the last element in the array. + int type; + //!nodeid refers to the card index. + int nodeid; +}MyoiUserParams; + +#define MYOI_USERPARAMS_DEVID 1 +#define MYOI_USERPARAMS_LAST_MSG -1 + +#ifdef __cplusplus +} +#endif +#endif // _MYO_IMPL_H_ +/*! @} */ diff --git a/liboffloadmic/include/myo/myotypes.h b/liboffloadmic/include/myo/myotypes.h new file mode 100644 index 00000000000..81464d1666f --- /dev/null +++ b/liboffloadmic/include/myo/myotypes.h @@ -0,0 +1,116 @@ +/* + * 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: Define the types used by APIs of MYO programming. + */ + +#ifndef _MYO_TYPES_H_ +#define _MYO_TYPES_H_ + +#include <string.h> /* For size_t */ + +/** @ingroup MYO + * @addtogroup MYOTYPES +@{ +* @file myotypes.h +*/ + +#ifdef __cplusplus +extern "C" { +#endif + +/*! MYO Status + */ +typedef enum { + MYO_SUCCESS = 0, /*!< Success */ + MYO_ERROR, /*!< Error */ + + MYO_INVALID_ENV, /*!< Invalid Env */ + MYO_INVALID_ARGUMENT, /*!< Invalid Argument */ + + MYO_NOT_INITIALIZED, /*!< Not Initialized */ + MYO_ALREADY_FINALIZED,/*!< Already Finalized */ + + MYO_BUF_ERROR, /*!< Buffer Error */ + MYO_OUT_OF_RANGE, /*!< Out of Range */ + MYO_OUT_OF_MEMORY, /*!< Out of Memory */ + + MYO_ALREADY_EXISTS, /*!< Already Exists */ + + MYO_EOF, /*!< EOF */ +} MyoError; + + +/*! Arena Ownership */ +typedef enum { + MYO_ARENA_MINE = 1, /*!< Arena MINE Ownership */ + MYO_ARENA_OURS, /*!< Arena OURS Ownership */ +} MyoOwnershipType; + +/************************************************************* + * define the property of MYO Arena + ***********************************************************/ +#define MYO_CONSISTENCY_MODE 0x3 +#define MYO_RELEASE_CONSISTENCY 0x1 +#define MYO_STRONG_RELEASE_CONSISTENCY 0x2 +#define MYO_STRONG_CONSISTENCY 0x3 +#define MYO_UPDATE_ON_DEMAND 0x8 +#define MYO_UPDATE_ON_ACQUIRE 0x10 +#define MYO_RECORD_DIRTY 0x20 +#define MYO_NOT_RECORD_DIRTY 0x40 +#define MYO_ONE_VERSION 0x80 +#define MYO_MULTI_VERSIONS 0x100 +#define MYO_CONSISTENCY 0x200 +#define MYO_NO_CONSISTENCY 0x400 +#define MYO_HOST_TO_DEVICE 0x800 +#define MYO_DEVICE_TO_HOST 0x1000 +#define MYO_HYBRID_UPDATE 0x2000 +typedef unsigned int MyoArena; + +typedef void * MyoMutex; +typedef void * MyoSem; +typedef void * MyoBarrier; + + +#ifdef __cplusplus +} +#endif +#endif // _MYO_TYPES_H_ +/*! @} */ |