include/hwloc/opencl.h

0001 /*
0002  * SPDX-License-Identifier: BSD-3-Clause
0003  * Copyright © 2012-2023 Inria.  All rights reserved.
0004  * Copyright © 2013, 2018 Université Bordeaux.  All right reserved.
0005  * See COPYING in top-level directory.
0006  */
0007
0008 /** \file
0009  * \brief Macros to help interaction between hwloc and the OpenCL interface.
0010  *
0011  * Applications that use both hwloc and OpenCL may want to
0012  * include this file so as to get topology information for OpenCL devices.
0013  */
0014
0015 #ifndef HWLOC_OPENCL_H
0016 #define HWLOC_OPENCL_H
0017
0018 #include "hwloc.h"
0019 #include "hwloc/autogen/config.h"
0020 #include "hwloc/helper.h"
0021 #ifdef HWLOC_LINUX_SYS
0022 #include "hwloc/linux.h"
0023 #endif
0024
0025 #ifdef __APPLE__
0026 #include <OpenCL/cl.h>
0027 #else
0028 #include <CL/cl.h>
0029 #endif
0030
0031 #include <stdio.h>
0032
0033
0034 #ifdef __cplusplus
0035 extern "C" {
0036 #endif
0037
0038
0039 /* OpenCL extensions aren't always shipped with default headers, and
0040  * they don't always reflect what the installed implementations support.
0041  * Try everything and let the implementation return errors when non supported.
0042  */
0043 /* Copyright (c) 2008-2018 The Khronos Group Inc. */
0044
0045 /* needs "cl_khr_pci_bus_info" device extension, but not strictly required for clGetDeviceInfo() */
0046 typedef struct {
0047     cl_uint pci_domain;
0048     cl_uint pci_bus;
0049     cl_uint pci_device;
0050     cl_uint pci_function;
0051 } hwloc_cl_device_pci_bus_info_khr;
0052 #define HWLOC_CL_DEVICE_PCI_BUS_INFO_KHR 0x410F
0053
0054 /* needs "cl_amd_device_attribute_query" device extension, but not strictly required for clGetDeviceInfo() */
0055 #define HWLOC_CL_DEVICE_TOPOLOGY_AMD 0x4037
0056 typedef union {
0057     struct { cl_uint type; cl_uint data[5]; } raw;
0058     struct { cl_uint type; cl_char unused[17]; cl_char bus; cl_char device; cl_char function; } pcie;
0059 } hwloc_cl_device_topology_amd;
0060 #define HWLOC_CL_DEVICE_TOPOLOGY_TYPE_PCIE_AMD 1
0061
0062 /* needs "cl_nv_device_attribute_query" device extension, but not strictly required for clGetDeviceInfo() */
0063 #define HWLOC_CL_DEVICE_PCI_BUS_ID_NV 0x4008
0064 #define HWLOC_CL_DEVICE_PCI_SLOT_ID_NV 0x4009
0065 #define HWLOC_CL_DEVICE_PCI_DOMAIN_ID_NV 0x400A
0066
0067
0068 /** \defgroup hwlocality_opencl Interoperability with OpenCL
0069  *
0070  * This interface offers ways to retrieve topology information about
0071  * OpenCL devices.
0072  *
0073  * Only AMD and NVIDIA OpenCL implementations currently offer useful locality
0074  * information about their devices.
0075  *
0076  * @{
0077  */
0078
0079 /** \brief Return the domain, bus and device IDs of the OpenCL device \p device.
0080  *
0081  * Device \p device must match the local machine.
0082  *
0083  * \return 0 on success.
0084  * \return -1 on error, for instance if device information could not be found.
0085  */
0086 static __hwloc_inline int
0087 hwloc_opencl_get_device_pci_busid(cl_device_id device,
0088                                unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
0089 {
0090     hwloc_cl_device_topology_amd amdtopo;
0091     hwloc_cl_device_pci_bus_info_khr khrbusinfo;
0092     cl_uint nvbus, nvslot, nvdomain;
0093     cl_int clret;
0094
0095     clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_BUS_INFO_KHR, sizeof(khrbusinfo), &khrbusinfo, NULL);
0096     if (CL_SUCCESS == clret) {
0097         *domain = (unsigned) khrbusinfo.pci_domain;
0098         *bus = (unsigned) khrbusinfo.pci_bus;
0099         *dev = (unsigned) khrbusinfo.pci_device;
0100         *func = (unsigned) khrbusinfo.pci_function;
0101         return 0;
0102     }
0103
0104     clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_TOPOLOGY_AMD, sizeof(amdtopo), &amdtopo, NULL);
0105     if (CL_SUCCESS == clret
0106         && HWLOC_CL_DEVICE_TOPOLOGY_TYPE_PCIE_AMD == amdtopo.raw.type) {
0107         *domain = 0; /* can't do anything better */
0108         /* cl_device_topology_amd stores bus ID in cl_char, dont convert those signed char directly to unsigned int */
0109         *bus = (unsigned) (unsigned char) amdtopo.pcie.bus;
0110         *dev = (unsigned) (unsigned char) amdtopo.pcie.device;
0111         *func = (unsigned) (unsigned char) amdtopo.pcie.function;
0112         return 0;
0113     }
0114
0115     clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_BUS_ID_NV, sizeof(nvbus), &nvbus, NULL);
0116     if (CL_SUCCESS == clret) {
0117         clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_SLOT_ID_NV, sizeof(nvslot), &nvslot, NULL);
0118         if (CL_SUCCESS == clret) {
0119             clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_DOMAIN_ID_NV, sizeof(nvdomain), &nvdomain, NULL);
0120             if (CL_SUCCESS == clret) { /* available since CUDA 10.2 */
0121                 *domain = nvdomain;
0122             } else {
0123                 *domain = 0;
0124             }
0125             *bus = nvbus & 0xff;
0126             /* non-documented but used in many other projects */
0127             *dev = nvslot >> 3;
0128             *func = nvslot & 0x7;
0129             return 0;
0130         }
0131     }
0132
0133     return -1;
0134 }
0135
0136 /** \brief Get the CPU set of processors that are physically
0137  * close to OpenCL device \p device.
0138  *
0139  * Store in \p set the CPU-set describing the locality of the OpenCL device \p device.
0140  *
0141  * Topology \p topology and device \p device must match the local machine.
0142  * I/O devices detection and the OpenCL component are not needed in the topology.
0143  *
0144  * The function only returns the locality of the device.
0145  * If more information about the device is needed, OS objects should
0146  * be used instead, see hwloc_opencl_get_device_osdev()
0147  * and hwloc_opencl_get_device_osdev_by_index().
0148  *
0149  * This function is currently only implemented in a meaningful way for
0150  * Linux with the AMD or NVIDIA OpenCL implementation; other systems will simply
0151  * get a full cpuset.
0152  *
0153  * \return 0 on success.
0154  * \return -1 on error, for instance if the device could not be found.
0155  */
0156 static __hwloc_inline int
0157 hwloc_opencl_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
0158                    cl_device_id device __hwloc_attribute_unused,
0159                    hwloc_cpuset_t set)
0160 {
0161 #if (defined HWLOC_LINUX_SYS)
0162     /* If we're on Linux, try AMD/NVIDIA extensions + the sysfs mechanism to get the local cpus */
0163 #define HWLOC_OPENCL_DEVICE_SYSFS_PATH_MAX 128
0164     char path[HWLOC_OPENCL_DEVICE_SYSFS_PATH_MAX];
0165     unsigned pcidomain, pcibus, pcidev, pcifunc;
0166
0167     if (!hwloc_topology_is_thissystem(topology)) {
0168         errno = EINVAL;
0169         return -1;
0170     }
0171
0172     if (hwloc_opencl_get_device_pci_busid(device, &pcidomain, &pcibus, &pcidev, &pcifunc) < 0) {
0173         hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
0174         return 0;
0175     }
0176
0177     sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.%01x/local_cpus", pcidomain, pcibus, pcidev, pcifunc);
0178     if (hwloc_linux_read_path_as_cpumask(path, set) < 0
0179         || hwloc_bitmap_iszero(set))
0180         hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
0181 #else
0182     /* Non-Linux systems simply get a full cpuset */
0183     hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
0184 #endif
0185   return 0;
0186 }
0187
0188 /** \brief Get the hwloc OS device object corresponding to the
0189  * OpenCL device for the given indexes.
0190  *
0191  * \return The hwloc OS device object describing the OpenCL device
0192  * whose platform index is \p platform_index,
0193  * and whose device index within this platform if \p device_index.
0194  * \return \c NULL if there is none.
0195  *
0196  * The topology \p topology does not necessarily have to match the current
0197  * machine. For instance the topology may be an XML import of a remote host.
0198  * I/O devices detection and the OpenCL component must be enabled in the topology.
0199  *
0200  * \note The corresponding PCI device object can be obtained by looking
0201  * at the OS device parent object (unless PCI devices are filtered out).
0202  */
0203 static __hwloc_inline hwloc_obj_t
0204 hwloc_opencl_get_device_osdev_by_index(hwloc_topology_t topology,
0205                        unsigned platform_index, unsigned device_index)
0206 {
0207     unsigned x = (unsigned) -1, y = (unsigned) -1;
0208     hwloc_obj_t osdev = NULL;
0209     while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
0210         if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
0211                     && osdev->name
0212             && sscanf(osdev->name, "opencl%ud%u", &x, &y) == 2
0213             && platform_index == x && device_index == y)
0214                         return osdev;
0215         }
0216         return NULL;
0217 }
0218
0219 /** \brief Get the hwloc OS device object corresponding to OpenCL device \p deviceX.
0220  *
0221  * \return The hwloc OS device object corresponding to the given OpenCL device \p device.
0222  * \return \c NULL if none could be found, for instance
0223  * if required OpenCL attributes are not available.
0224  *
0225  * This function currently only works on AMD and NVIDIA OpenCL devices that support
0226  * relevant OpenCL extensions. hwloc_opencl_get_device_osdev_by_index()
0227  * should be preferred whenever possible, i.e. when platform and device index
0228  * are known.
0229  *
0230  * Topology \p topology and device \p device must match the local machine.
0231  * I/O devices detection and the OpenCL component must be enabled in the topology.
0232  * If not, the locality of the object may still be found using
0233  * hwloc_opencl_get_device_cpuset().
0234  *
0235  * \note This function cannot work if PCI devices are filtered out.
0236  *
0237  * \note The corresponding hwloc PCI device may be found by looking
0238  * at the result parent pointer (unless PCI devices are filtered out).
0239  */
0240 static __hwloc_inline hwloc_obj_t
0241 hwloc_opencl_get_device_osdev(hwloc_topology_t topology __hwloc_attribute_unused,
0242                   cl_device_id device __hwloc_attribute_unused)
0243 {
0244     hwloc_obj_t osdev;
0245     unsigned pcidomain, pcibus, pcidevice, pcifunc;
0246
0247     if (hwloc_opencl_get_device_pci_busid(device, &pcidomain, &pcibus, &pcidevice, &pcifunc) < 0) {
0248         errno = EINVAL;
0249         return NULL;
0250     }
0251
0252     osdev = NULL;
0253     while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
0254         hwloc_obj_t pcidev = osdev->parent;
0255         if (strncmp(osdev->name, "opencl", 6))
0256             continue;
0257         if (pcidev
0258             && pcidev->type == HWLOC_OBJ_PCI_DEVICE
0259             && pcidev->attr->pcidev.domain == pcidomain
0260             && pcidev->attr->pcidev.bus == pcibus
0261             && pcidev->attr->pcidev.dev == pcidevice
0262             && pcidev->attr->pcidev.func == pcifunc)
0263             return osdev;
0264         /* if PCI are filtered out, we need a info attr to match on */
0265     }
0266
0267     return NULL;
0268 }
0269
0270 /** @} */
0271
0272
0273 #ifdef __cplusplus
0274 } /* extern "C" */
0275 #endif
0276
0277
0278 #endif /* HWLOC_OPENCL_H */