2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
5 * Copyright (c) 2001-2010, The GROMACS development team.
6 * Copyright (c) 2012,2013,2014,2015, by the GROMACS development team, led by
7 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
8 * and including many others, as listed in the AUTHORS file in the
9 * top-level source directory and at http://www.gromacs.org.
11 * GROMACS is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public License
13 * as published by the Free Software Foundation; either version 2.1
14 * of the License, or (at your option) any later version.
16 * GROMACS is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with GROMACS; if not, see
23 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
24 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
26 * If you want to redistribute modifications to GROMACS, please
27 * consider that scientific software is very special. Version
28 * control is crucial - bugs must be traceable. We will be happy to
29 * consider code for inclusion in the official distribution, but
30 * derived work must not be called official GROMACS. Details are found
31 * in the README & COPYING files - if they are missing, get the
32 * official version at http://www.gromacs.org.
34 * To help us fund GROMACS development, we humbly ask that you cite
35 * the research papers on the package. Check out http://www.gromacs.org.
37 /*! \libinternal \file
38 * \brief Declare functions for detection and initialization for GPU devices.
40 * \author Szilard Pall <pall.szilard@gmail.com>
41 * \author Mark Abraham <mark.j.abraham@gmail.com>
46 #ifndef GMX_GMXLIB_GPU_UTILS_GPU_UTILS_H
47 #define GMX_GMXLIB_GPU_UTILS_GPU_UTILS_H
49 #include "gromacs/gmxlib/gpu_utils/gpu_macros.h"
50 #include "gromacs/legacyheaders/types/hw_info.h"
51 #include "gromacs/legacyheaders/types/simple.h"
57 struct gmx_gpu_info_t;
59 /*! \brief Detect all GPUs in the system.
61 * Will detect every GPU supported by the device driver in use. Also
62 * check for the compatibility of each and fill the gpu_info->gpu_dev array
63 * with the required information on each the device: ID, device properties,
66 * \param[in] gpu_info pointer to structure holding GPU information.
67 * \param[out] err_str The error message of any GPU API error that caused
68 * the detection to fail (if there was any). The memory
69 * the pointer points to should be managed externally.
70 * \returns non-zero if the detection encountered a failure, zero otherwise.
73 int detect_gpus(struct gmx_gpu_info_t gmx_unused *gpu_info, char gmx_unused *err_str) GPU_FUNC_TERM_WITH_RETURN(-1)
75 /*! \brief Select the compatible GPUs
77 * This function selects the compatible gpus and initializes
78 * gpu_info->dev_use and gpu_info->n_dev_use.
80 * Given the list of GPUs available in the system check each device in
81 * gpu_info->gpu_dev and place the indices of the compatible GPUs into
82 * dev_use with this marking the respective GPUs as "available for use."
83 * Note that \p detect_gpus must have been called before.
85 * \param[in] gpu_info pointer to structure holding GPU information
86 * \param[in,out] gpu_opt pointer to structure holding GPU options
89 void pick_compatible_gpus(const struct gmx_gpu_info_t gmx_unused *gpu_info,
90 gmx_gpu_opt_t gmx_unused *gpu_opt) GPU_FUNC_TERM
92 /*! \brief Check the existence/compatibility of a set of GPUs specified by their device IDs.
94 * Given the a list of gpu_opt->n_dev_use GPU device IDs stored in
95 * gpu_opt->dev_use check the existence and compatibility
96 * of the respective GPUs. Also provide the caller with an array containing
97 * the result of checks in \p checkres.
99 * \param[out] checkres check result for each ID passed in requested_devs
100 * \param[in] gpu_info pointer to structure holding GPU information
101 * \param[out] gpu_opt pointer to structure holding GPU options
102 * \returns TRUE if every the requested GPUs are compatible
105 gmx_bool check_selected_gpus(int gmx_unused *checkres,
106 const struct gmx_gpu_info_t gmx_unused *gpu_info,
107 gmx_gpu_opt_t gmx_unused *gpu_opt) GPU_FUNC_TERM_WITH_RETURN(-1)
109 /*! \brief Frees the gpu_dev and dev_use array fields of \p gpu_info.
111 * \param[in] gpu_info pointer to structure holding GPU information
114 void free_gpu_info(const struct gmx_gpu_info_t gmx_unused *gpu_info) GPU_FUNC_TERM
116 /*! \brief Initializes the GPU with the given index.
118 * The varible \p mygpu is the index of the GPU to initialize in the
119 * gpu_info.gpu_dev array.
121 * \param[out] fplog log file to write to
122 * \param[in] mygpu index of the GPU to initialize
123 * \param[out] result_str the message related to the error that occurred
124 * during the initialization (if there was any).
125 * \param[in] gpu_info GPU info of all detected devices in the system.
126 * \param[in] gpu_opt options for using the GPUs in gpu_info
127 * \returns true if no error occurs during initialization.
130 gmx_bool init_gpu(FILE gmx_unused *fplog,
131 int gmx_unused mygpu,
132 char gmx_unused *result_str,
133 const struct gmx_gpu_info_t gmx_unused *gpu_info,
134 const gmx_gpu_opt_t gmx_unused *gpu_opt) GPU_FUNC_TERM_WITH_RETURN(-1)
136 /*! \brief Frees up the CUDA GPU used by the active context at the time of calling.
138 * The context is explicitly destroyed and therefore all data uploaded to the GPU
139 * is lost. This should only be called when none of this data is required anymore.
141 * \param[in] mygpu index of the GPU clean up for
142 * \param[out] result_str the message related to the error that occurred
143 * during the initialization (if there was any).
144 * \param[in] gpu_info GPU info of all detected devices in the system.
145 * \param[in] gpu_opt options for using the GPUs in gpu_info
146 * \returns true if no error occurs during the freeing.
149 gmx_bool free_cuda_gpu(int gmx_unused mygpu,
150 char gmx_unused *result_str,
151 const gmx_gpu_info_t gmx_unused *gpu_info,
152 const gmx_gpu_opt_t gmx_unused *gpu_opt) CUDA_FUNC_TERM_WITH_RETURN(-1)
154 /*! \brief Returns the device ID of the CUDA GPU currently in use.
156 * The GPU used is the one that is active at the time of the call in the active context.
158 * \returns device ID of the GPU in use at the time of the call
161 int get_current_cuda_gpu_device_id(void) CUDA_FUNC_TERM_WITH_RETURN(-1)
163 /*! \brief Returns the device ID of the CUDA GPU with a given index into the array of used GPUs.
165 * Getter function which, given an index into the array of GPUs in use
166 * (dev_use) -- typically a tMPI/MPI rank --, returns the device ID of the
167 * respective CUDA GPU.
169 * \param[in] gpu_info pointer to structure holding GPU information
170 * \param[in] gpu_opt pointer to structure holding GPU options
171 * \param[in] index index into the array of used GPUs
172 * \returns device ID of the requested GPU
175 int get_cuda_gpu_device_id(const struct gmx_gpu_info_t gmx_unused *gpu_info,
176 const gmx_gpu_opt_t gmx_unused *gpu_opt,
177 int gmx_unused index) CUDA_FUNC_TERM_WITH_RETURN(-1)
179 /*! \brief Formats and returns a device information string for a given GPU.
181 * Given an index *directly* into the array of available GPUs (gpu_dev)
182 * returns a formatted info string for the respective GPU which includes
183 * ID, name, compute capability, and detection status.
185 * \param[out] s pointer to output string (has to be allocated externally)
186 * \param[in] gpu_info pointer to structure holding GPU information
187 * \param[in] index an index *directly* into the array of available GPUs
190 void get_gpu_device_info_string(char gmx_unused *s,
191 const struct gmx_gpu_info_t gmx_unused *gpu_info,
192 int gmx_unused index) GPU_FUNC_TERM
194 /*! \brief Returns the size of the gpu_dev_info struct.
196 * The size of gpu_dev_info can be used for allocation and communication.
198 * \returns size in bytes of gpu_dev_info
201 size_t sizeof_gpu_dev_info(void) GPU_FUNC_TERM_WITH_RETURN(0)
203 /*! \brief Returns a pointer *ptr to page-locked memory of size nbytes.
205 * The allocated memory is suitable to be used for data transfers between host
207 * Error handling should be done within this function.
209 typedef void gmx_host_alloc_t (void **ptr, size_t nbytes);
211 /*! \brief Frees page-locked memory pointed to by *ptr.
213 * NULL should not be passed to this function.
215 typedef void gmx_host_free_t (void *ptr);
217 /*! \brief Set page-locked memory allocation functions used by the GPU host. */
218 void gpu_set_host_malloc_and_free(bool bUseGpuKernels,
219 gmx_host_alloc_t **nb_alloc,
220 gmx_host_free_t **nb_free);