src/gromacs/hardware/device_management.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014,2015,2016, by the GROMACS development team.
   5  * Copyright (c) 2017,2018,2019,2020, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \libinternal \file
  37  *  \brief Declares functions to manage GPU resources.
  38  *
  39  *  This has several implementations: one for each supported GPU platform,
  40  *  and a stub implementation if the build does not support GPUs.
  41  *
  42  *  \author Anca Hamuraru <anca@streamcomputing.eu>
  43  *  \author Dimitrios Karkoulis <dimitris.karkoulis@gmail.com>
  44  *  \author Teemu Virolainen <teemu@streamcomputing.eu>
  45  *  \author Mark Abraham <mark.j.abraham@gmail.com>
  46  *  \author Szilárd Páll <pall.szilard@gmail.com>
  47  *  \author Artem Zhmurov <zhmurov@gmail.com>
  48  *
  49  * \inlibraryapi
  50  * \ingroup module_hardware
  51  */
  52 #ifndef GMX_HARDWARE_DEVICE_MANAGEMENT_H
  53 #define GMX_HARDWARE_DEVICE_MANAGEMENT_H
  54
  55 #include <memory>
  56 #include <string>
  57 #include <vector>
  58
  59 #include "gromacs/utility/basedefinitions.h"
  60 #include "gromacs/utility/iserializer.h"
  61
  62 struct DeviceInformation;
  63
  64 /*! \brief Return whether GPUs can be detected.
  65  *
  66  * Returns true when this is a build of GROMACS configured to support
  67  * GPU usage, GPU detection is not disabled by \c GMX_DISABLE_GPU_DETECTION
  68  * environment variable and a valid device driver, ICD, and/or runtime was
  69  * detected. Does not throw.
  70  *
  71  * \param[out] errorMessage  When returning false on a build configured with
  72  *                           GPU support and non-nullptr was passed,
  73  *                           the string contains a descriptive message about
  74  *                           why GPUs cannot be detected.
  75  */
  76 bool canPerformDeviceDetection(std::string* errorMessage);
  77
  78 /*! \brief Return whether GPU detection is enabled
  79  *
  80  * Returns true when this is a build of GROMACS configured to support
  81  * GPU usage and GPU detection is not disabled by \c GMX_DISABLE_GPU_DETECTION
  82  * environment variable.
  83  *
  84  * Does not throw.
  85  */
  86 bool isDeviceDetectionEnabled();
  87
  88 /*! \brief Return whether GPU detection is functioning correctly
  89  *
  90  * Returns true when this is a build of GROMACS configured to support
  91  * GPU usage, and a valid device driver, ICD, and/or runtime was detected.
  92  *
  93  * This function is not intended to be called from build
  94  * configurations that do not support GPUs, and there will be no
  95  * descriptive message in that case.
  96  *
  97  * \param[out] errorMessage  When returning false on a build configured with
  98  *                           GPU support and non-nullptr was passed,
  99  *                           the string contains a descriptive message about
 100  *                           why GPUs cannot be detected.
 101  *
 102  * Does not throw.
 103  */
 104 bool isDeviceDetectionFunctional(std::string* errorMessage);
 105
 106 /*! \brief Checks if one can compute on the GPU
 107  *
 108  * \returns  True if the build supports GPUs and there are at least one available.
 109  */
 110 bool canComputeOnDevice();
 111
 112 /*! \brief Find all GPUs in the system.
 113  *
 114  *  Will detect every GPU supported by the device driver in use.
 115  *  Must only be called if \c canPerformDeviceDetection() has returned true.
 116  *  This routine also checks for the compatibility of each device and fill the
 117  *  deviceInfo array with the required information on each device: ID, device
 118  *  properties, status.
 119  *
 120  *  Note that this function leaves the GPU runtime API error state clean;
 121  *  this is implemented ATM in the CUDA flavor. This invalidates any existing
 122  *  CUDA streams, allocated memory on GPU, etc.
 123  *
 124  *  \todo:  Check if errors do propagate in OpenCL as they do in CUDA and
 125  *          whether there is a mechanism to "clear" them.
 126  *
 127  * \return  Standard vector with the list of devices found
 128  *
 129  *  \throws InternalError if a GPU API returns an unexpected failure (because
 130  *          the call to canDetectGpus() should always prevent this occuring)
 131  */
 132 std::vector<std::unique_ptr<DeviceInformation>> findDevices();
 133
 134 /*! \brief Return a container of the detected GPU ids that are compatible.
 135  *
 136  * This function filters the result of the detection for compatible
 137  * GPUs, based on the previously run compatibility tests.
 138  *
 139  * \param[in] deviceInfoList An information on available devices.
 140  *
 141  * \return  Vector of DeviceInformations on GPUs recorded as compatible
 142  */
 143 std::vector<std::reference_wrapper<DeviceInformation>>
 144 getCompatibleDevices(const std::vector<std::unique_ptr<DeviceInformation>>& deviceInfoList);
 145
 146 /*! \brief Set the active GPU.
 147  *
 148  * This sets the device for which the device information is passed active. Essential in CUDA, where
 149  * the device buffers and kernel launches are not connected to the device context. In OpenCL, checks
 150  * the device vendor and makes vendor-specific performance adjustments.
 151  *
 152  * \param[in] deviceInfo Information on the device to be set.
 153  *
 154  * Issues a fatal error for any critical errors that occur during
 155  * initialization.
 156  */
 157 void setActiveDevice(const DeviceInformation& deviceInfo);
 158
 159 /*! \brief Releases the GPU device used by the active context at the time of calling (CUDA only).
 160  *
 161  * If \c deviceInfo is nullptr, then it is understood that no device
 162  * was selected so no context is active to be freed. Otherwise, the
 163  * context is explicitly destroyed and therefore all data uploaded to
 164  * the GPU is lost. This must only be called when none of this data is
 165  * required anymore, because subsequent attempts to free memory
 166  * associated with the context will otherwise fail.
 167  *
 168  * Calls \c gmx_warning upon errors.
 169  *
 170  * \todo This should go through all the devices, not only the one currently active.
 171  *       Reseting only one device will not work, e.g. in CUDA tests.
 172  *
 173  * \param[in] deviceInfo Information on the device to be released.
 174  */
 175 void releaseDevice(DeviceInformation* deviceInfo);
 176
 177 /*! \brief Formats and returns a device information string for a given GPU.
 178  *
 179  * Given an index *directly* into the array of available GPUs, returns
 180  * a formatted info string for the respective GPU which includes ID, name,
 181  * compute capability, and detection status.
 182  *
 183  * \param[in] deviceInfo  An information on device that is to be set.
 184  *
 185  * \returns A string describing the device.
 186  */
 187 std::string getDeviceInformationString(const DeviceInformation& deviceInfo);
 188
 189 /*! \brief Return a string describing how compatible the GPU with given \c deviceId is.
 190  *
 191  * \param[in] deviceInfoList An information on available devices.
 192  * \param[in] deviceId       An index of the device to check
 193  * \returns                  A string describing the compatibility status, useful for error messages.
 194  */
 195 std::string getDeviceCompatibilityDescription(const std::vector<std::unique_ptr<DeviceInformation>>& deviceInfoList,
 196                                               int deviceId);
 197
 198 /*! \brief Serialization of information on devices for MPI broadcasting.
 199  *
 200  * \param[in] deviceInfoList  The vector with device informations to serialize.
 201  * \param[in] serializer      Serializing object.
 202  */
 203 void serializeDeviceInformations(const std::vector<std::unique_ptr<DeviceInformation>>& deviceInfoList,
 204                                  gmx::ISerializer*                                      serializer);
 205
 206 /*! \brief Deserialization of information on devices after MPI broadcasting.
 207  *
 208  * \param[in] serializer Serializing object.
 209  *
 210  * \return deviceInfoList   Deserialized vector with device informations.
 211  */
 212 std::vector<std::unique_ptr<DeviceInformation>> deserializeDeviceInformations(gmx::ISerializer* serializer);
 213
 214 #endif // GMX_HARDWARE_DEVICE_MANAGEMENT_H