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 /*! @} */ 274