include/hwloc/opencl.h

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