liboffloadmic/include/coi/source/COIEngine_source.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 _COIENGINE_SOURCE_H
  42 #define _COIENGINE_SOURCE_H
  43
  44 /** @ingroup COIEngine
  45  *  @addtogroup COIEngineSource
  46 @{
  47
  48 * @file source\COIEngine_source.h
  49 */
  50 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  51     #include <wchar.h>
  52     #include "../common/COITypes_common.h"
  53     #include "../common/COIResult_common.h"
  54     #include "../common/COIEngine_common.h"
  55 #endif // DOXYGEN_SHOULD_SKIP_THIS
  56
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61 #define COI_MAX_DRIVER_VERSION_STR_LEN 255
  62
  63 #define COI_MAX_HW_THREADS 1024
  64
  65 ///////////////////////////////////////////////////////////////////////////////
  66 /// This enum defines miscellaneous information returned from the
  67 /// COIGetEngineInfo() function.
  68 ///
  69 typedef enum
  70 {
  71     COI_ENG_ECC_DISABLED = 0,            //ECC is not enabled on this engine
  72     COI_ENG_ECC_ENABLED = 0x00000001,    //ECC is enabled on this engine
  73     COI_ENG_ECC_UNKNOWN = 0x00000002     //ECC is mode is unknown
  74 } coi_eng_misc;
  75
  76
  77 ///////////////////////////////////////////////////////////////////////////////
  78 /// This structure returns information about an Intel(R) Xeon Phi(TM)
  79 /// coprocessor.
  80 /// A pointer to this structure is passed into the COIGetEngineInfo() function,
  81 /// which fills in the data before returning to the caller.
  82 ///
  83 typedef struct COI_ENGINE_INFO
  84 {
  85     /// The version string identifying the driver.
  86     coi_wchar_t  DriverVersion[COI_MAX_DRIVER_VERSION_STR_LEN];
  87
  88     /// The DeviceType supported by the engine.
  89     COI_DEVICE_TYPE ISA;
  90
  91     /// The number of cores on the engine.
  92     uint32_t     NumCores;
  93
  94     /// Miscellaneous fields
  95     coi_eng_misc MiscFlags;
  96
  97     /// The number of hardware threads on the engine.
  98     uint32_t     NumThreads;
  99
 100     /// The maximum frequency (in MHz) of the cores on the engine.
 101     uint32_t     CoreMaxFrequency;
 102
 103     /// The load percentage for each of the hardware threads on the engine.
 104     /// Currently this is limited to reporting out a maximum of 1024 HW threads
 105     uint32_t     Load[COI_MAX_HW_THREADS];
 106
 107     /// The amount of physical memory managed by the OS.
 108     uint64_t     PhysicalMemory;
 109
 110     /// The amount of free physical memory in the OS.
 111     uint64_t     PhysicalMemoryFree;
 112
 113     /// The amount of swap memory managed by the OS.
 114     uint64_t     SwapMemory;
 115
 116     /// The amount of free swap memory in the OS.
 117     uint64_t     SwapMemoryFree;
 118
 119     /// The pci config vendor id
 120     uint16_t     VendorId;
 121
 122     /// The pci config device id
 123     uint16_t     DeviceId;
 124
 125     /// The pci config subsystem id
 126     uint16_t     SubSystemId;
 127
 128     /// The stepping of the board, A0, A1, C0, D0 etc.
 129     uint16_t     BoardStepping;
 130
 131     /// The SKU of the stepping, EB, ED, etc.
 132     uint16_t     BoardSKU;
 133 } COI_ENGINE_INFO;
 134
 135 ///////////////////////////////////////////////////////////////////////////////
 136 ///
 137 /// Returns information related to a specified engine. Note that if the runtime
 138 /// is unable to query a value it will be returned as zero but the call will
 139 /// still succeed.
 140 ///
 141 ///
 142 /// @param  in_EngineHandle
 143 ///         [in] The COIENGINE structure as provided from COIEngineGetHandle()
 144 ///         which to query for device level information.
 145 ///
 146 /// @param  in_EngineInfoSize
 147 ///         [in] The size of the structure that out_pEngineInfo points to.
 148 ///         Used for version safety of the function call.
 149 ///
 150 /// @param  out_pEngineInfo
 151 ///         [out] The address of a user allocated COI_ENGINE_INFO structure.
 152 ///         Upon success, the contents of the structure will be updated
 153 ///         to contain information related to the specified engine.
 154 ///
 155 ///
 156 /// @return  COI_SUCCESS if the function completed without error.
 157 ///
 158 /// @return  COI_INVALID_HANDLE if the in_EngineHandle handle is not valid.
 159 ///
 160 /// @return  COI_SIZE_MISMATCH if in_EngineInfoSize does not match any current
 161 ///          or previous COI_ENGINE_INFO structure sizes.
 162 ///
 163 /// @return  COI_INVALID_POINTER if the out_pEngineInfo pointer is NULL.
 164 ///
 165 COIACCESSAPI
 166 COIRESULT
 167 COIEngineGetInfo(
 168     COIENGINE           in_EngineHandle,
 169     uint32_t            in_EngineInfoSize,
 170     COI_ENGINE_INFO    *out_pEngineInfo);
 171
 172
 173 ///////////////////////////////////////////////////////////////////////////////
 174 ///
 175 /// Returns the number of engines in the system that match the provided device type.
 176 ///
 177 /// The number of available coprocessor devices (i.e. cards connected via PCIe)
 178 /// is detected by the COI runtime.
 179 ///
 180 /// @param  in_DeviceType
 181 ///         [in] Specifies the ISA type of the engine requested.
 182 ///
 183 /// @param  out_pNumEngines
 184 ///         [out] The number of engines available. This can be used to index
 185 ///         into the engines using COIEngineGetHandle().
 186 ///
 187 /// @return COI_SUCCESS if the function completed without error.
 188 ///
 189 /// @return COI_DOES_NOT_EXIST if the in_DeviceType parameter is not valid.
 190 ///
 191 /// @return COI_INVALID_POINTER if the out_pNumEngines parameter is NULL.
 192 ///
 193 /// @return COI_OUT_OF_RANGE if number of selected devices is greater than 8.
 194 ///
 195 COIACCESSAPI
 196 COIRESULT
 197 COIEngineGetCount(
 198     COI_DEVICE_TYPE in_DeviceType,
 199     uint32_t       *out_pNumEngines);
 200
 201
 202 ///////////////////////////////////////////////////////////////////////////////
 203 ///
 204 /// Returns the handle of a user specified engine.
 205 ///
 206 /// @param  in_DeviceType
 207 ///         [in] Specifies the ISA type of the engine requested.
 208 ///
 209 /// @param  in_EngineIndex
 210 ///         [in] A unsigned integer which specifies the zero-based position of
 211 ///         the engine in a collection of engines. The makeup of this
 212 ///         collection is defined by the in_DeviceType parameter.
 213 ///
 214 /// @param  out_pEngineHandle
 215 ///         [out] The address of a COIENGINE handle.
 216 ///
 217 /// @return COI_SUCCESS if the function completed without error.
 218 ///
 219 /// @return COI_DOES_NOT_EXIST if the in_DeviceType parameter is not valid.
 220 ///
 221 /// @return COI_OUT_OF_RANGE if in_EngineIndex is greater than or equal to
 222 ///         the number of engines that match the in_DeviceType parameter.
 223 ///
 224 /// @return COI_INVALID_POINTER if the out_pEngineHandle parameter is NULL.
 225 ///
 226 /// @return COI_VERSION_MISMATCH if the version of Intel(R) Coprocessor Offload
 227 ///         Infrastructure (Intel(R) COI) on the host is not
 228 ///         compatible with the version on the device.
 229 ///
 230 /// @return COI_NOT_INITIALIZED if the engine requested exists but is offline.
 231 ///
 232 COIACCESSAPI
 233 COIRESULT
 234 COIEngineGetHandle(
 235     COI_DEVICE_TYPE in_DeviceType,
 236     uint32_t        in_EngineIndex,
 237     COIENGINE      *out_pEngineHandle);
 238
 239 ///////////////////////////////////////////////////////////////////////////////
 240 ///
 241 /// Returns the hostname for a specified COIEngine.
 242 ///
 243 /// @param  in_EngineHandle
 244 ///         [in] The connected COI Engine Handle passed in by the user that is
 245 ///         used to request the hostname of the device connected by this COIEngine.
 246 ///
 247 /// @param  out_Hostname
 248 ///         [out] The hostname of the device connected by this COIEngine.
 249 ///         COI will write at most 4096 bytes and the user must make sure that the size
 250 ///         of the memory pointed by this argument is large enough.
 251 ///
 252 /// @return COI_SUCCESS if the hostname was retrieved without error.
 253 ///
 254 /// @return COI_ERROR if the function was unable to retrieve the hostname and/or
 255 ///         the retrieved out_Hostname is NULL.
 256 ///
 257 /// @return COI_INVALID_HANDLE if the in_EngineHandle is invalid.
 258 ///
 259 /// @return COI_INVALID_POINTER if the out_Hostname is NULL.
 260 ///
 261 COIACCESSAPI
 262 COIRESULT
 263 COIEngineGetHostname(
 264     COIENGINE in_EngineHandle,
 265     char     *out_Hostname);
 266
 267 #ifdef __cplusplus
 268 } /* extern "C" */
 269 #endif
 270
 271 #endif /* _COIENGINE_SOURCE_H */
 272
 273 /*! @} */