liboffloadmic/include/coi/sink/COIProcess_sink.h

   1 /*
   2  * Copyright 2010-2016 Intel Corporation.
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License as published
   6  * by the Free Software Foundation, version 2.1.
   7  *
   8  * This library is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  11  * Lesser General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public
  14  * License along with this library; if not, write to the Free Software
  15  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  16  * 02110-1301 USA.
  17  *
  18  * Disclaimer: The codes contained in these modules may be specific
  19  * to the Intel Software Development Platform codenamed Knights Ferry,
  20  * and the Intel product codenamed Knights Corner, and are not backward
  21  * compatible with other Intel products. Additionally, Intel will NOT
  22  * support the codes or instruction set in future products.
  23  *
  24  * Intel offers no warranty of any kind regarding the code. This code is
  25  * licensed on an "AS IS" basis and Intel is not obligated to provide
  26  * any support, assistance, installation, training, or other services
  27  * of any kind. Intel is also not obligated to provide any updates,
  28  * enhancements or extensions. Intel specifically disclaims any warranty
  29  * of merchantability, non-infringement, fitness for any particular
  30  * purpose, and any other warranty.
  31  *
  32  * Further, Intel disclaims all liability of any kind, including but
  33  * not limited to liability for infringement of any proprietary rights,
  34  * relating to the use of the code, even if Intel is notified of the
  35  * possibility of such liability. Except as expressly stated in an Intel
  36  * license agreement provided with this code and agreed upon with Intel,
  37  * no license, express or implied, by estoppel or otherwise, to any
  38  * intellectual property rights is granted herein.
  39  */
  40
  41 #ifndef _COIPROCESS_SINK_H
  42 #define _COIPROCESS_SINK_H
  43
  44 /** @ingroup COIProcess
  45  *  @addtogroup COIProcessSink
  46 @{
  47 * @file sink/COIProcess_sink.h
  48 */
  49 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  50
  51 #include "../common/COITypes_common.h"
  52 #include "../common/COIResult_common.h"
  53
  54 #ifdef __cplusplus
  55 extern "C" {
  56 #endif
  57 #endif // DOXYGEN_SHOULD_SKIP_THIS
  58
  59 //////////////////////////////////////////////////////////////////////////////
  60 ///
  61 /// This call will block while waiting for the source to send a process destroy
  62 /// message. This provides the sink side application with an event to keep the
  63 /// main() function from exiting until it is directed to by the source. When
  64 /// the shutdown message is received this function will stop any future run
  65 /// functions from executing but will wait for any current run functions to
  66 /// complete. All Intel® Coprocessor Offload Infrastructure (Intel® COI)
  67 /// resources will be cleaned up and no additional Intel® Coprocessor Offload
  68 /// Infrastructure (Intel® COI) APIs should be called after this function
  69 /// returns. This function does not invoke exit() so the application
  70 /// can perform any of its own cleanup once this call returns.
  71 ///
  72 /// @return COI_SUCCESS once the process receives the shutdown message.
  73 ///
  74 COIRESULT
  75 COIProcessWaitForShutdown();
  76
  77 //////////////////////////////////////////////////////////////////////////////
  78 ///
  79 /// This call will block until all stdout and stderr output has been proxied
  80 /// to and written by the source. This call guarantees that any output in a
  81 /// run function is transmitted to the source before the run function signals
  82 /// its completion event back to the source.
  83 ///
  84 /// Note that having an additional thread printing forever while another
  85 /// calls COIProxyFlush may lead to a hang because the process will be forced
  86 /// to wait until all that output can be flushed to the source before returning
  87 /// from this call.
  88 ///
  89 /// @return COI_SUCCESS once the proxy output has been flushed to and written
  90 ///         written by the host. Note that Intel® Coprocessor Offload
  91 ///         Infrastructure (Intel® COI) on the source writes to stdout and
  92 ///         stderr, but does not flush this output.
  93 /// @return COI_SUCCESS if the process was created without enabling
  94 ///         proxy IO this function.
  95 ///
  96 COIRESULT
  97 COIProcessProxyFlush();
  98
  99
 100 //////////////////////////////////////////////////////////////////////////////
 101 ///
 102 /// Loads a shared library from host filesystem into the current sink
 103 /// process, akin to using dlopen() on a local process in Linux or
 104 /// LoadLibrary() in Windows.
 105 ///
 106 /// @param  in_pFileName
 107 ///         [in] The name of the shared library file on the source's file
 108 ///         system that is being loaded. If the file name is not an absolute
 109 ///         path, the file is searched for in the same manner as dependencies.
 110 ///
 111 /// @param  in_pLibraryName
 112 ///         [in] Name for the shared library. This optional parameter can
 113 ///         be specified in case the dynamic library doesn't have an
 114 ///         SO_NAME field. If specified, it will take precedence over
 115 ///         the SO_NAME if it exists. If it is not specified then
 116 ///         the library must have a valid SO_NAME field.
 117 ///
 118 ///@param   in_LibrarySearchPath
 119 ///         [in] a path to locate dynamic libraries dependencies for the
 120 ///         library being loaded. If not NULL, this path will override the
 121 ///         environment variable SINK_LD_LIBRARY_PATH. If NULL it will use
 122 ///         SINK_LD_LIBRARY_PATH to locate dependencies.
 123 ///
 124 /// @param  in_Flags
 125 ///         [in] Bitmask of the flags that will be passed in as the dlopen()
 126 ///         "flag" parameter on the sink.
 127 ///
 128 /// @param  out_pLibrary
 129 ///         [out] If COI_SUCCESS or COI_ALREADY_EXISTS is returned, the handle
 130 ///         that uniquely identifies the loaded library.
 131 ///
 132 /// @return COI_SUCCESS if the library was successfully loaded.
 133 ///
 134 /// @return COI_INVALID_POINTER if in_pFileName is NULL.
 135 ///
 136 /// @return COI_DOES_NOT_EXIST if in_pFileName cannot be found.
 137 ///
 138 /// @return COI_INVALID_FILE if the file is not a valid shared library.
 139 ///
 140 /// @return COI_MISSING_DEPENDENCY if a dependent library is missing from
 141 ///         either SINK_LD_LIBRARY_PATH or the in_LibrarySearchPath parameter.
 142 ///
 143 /// @return COI_ARGUMENT_MISMATCH if the shared library is missing an SONAME
 144 ///         and in_pLibraryName is NULL.
 145 ///
 146 /// @return COI_UNDEFINED_SYMBOL if we are unable to load the library due to
 147 ///         an undefined symbol.
 148 ///
 149 /// @return COI_ALREADY_EXISTS if there is an existing COILIBRARY handle
 150 ///         that identifies this library, and this COILIBRARY hasn't been
 151 ///         unloaded yet.
 152 ///
 153 /// @return COI_BINARY_AND_HARDWARE_MISMATCH if the target machine of the
 154 ///         binary or any of its recursive dependencies does not match the
 155 ///         engine associated with Process.
 156 ///
 157 /// @return COI_NOT_INITIALIZED if setup of remote process on host is not
 158 ///         completed yet.
 159 ///
 160 COIRESULT
 161 COIProcessLoadSinkLibraryFromFile(
 162     const   char               *in_pFileName,
 163     const   char               *in_pLibraryName,
 164     const   char               *in_LibrarySearchPath,
 165     uint32_t            in_Flags,
 166     COILIBRARY         *out_pLibrary);
 167
 168 #ifdef __cplusplus
 169 } /* extern "C" */
 170 #endif
 171
 172 #endif /* _COIPROCESS_SINK_H */
 173
 174 /*! @} */