C Specification

The list of devices available on a platform can be obtained using the function3:

cl_int clGetDeviceIDs(
    cl_platform_id platform,
    cl_device_type device_type,
    cl_uint num_entries,
    cl_device_id* devices,
    cl_uint* num_devices);

Parameters

  • platform refers to the platform ID returned by clGetPlatformIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.

  • device_type is a bitfield that identifies the type of OpenCL device. The device_type can be used to query specific OpenCL devices or all OpenCL devices available. The valid values for device_type are specified in the Device Categories table.

  • num_entries is the number of cl_device_id entries that can be added to devices. If devices is not NULL, the num_entries must be greater than zero.

  • devices returns a list of OpenCL devices found. The cl_device_id values returned in devices can be used to identify a specific OpenCL device. If devices is NULL, this argument is ignored. The number of OpenCL devices returned is the minimum of the value specified by num_entries or the number of OpenCL devices whose type matches device_type.

  • num_devices returns the number of OpenCL devices available that match device_type. If num_devices is NULL, this argument is ignored.

Description

3

clGetDeviceIDs may return all or a subset of the actual physical devices present in the platform and that match device_type.

Table 1. List of supported device_types by https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html#clGetDeviceIDs
cl_device_type Description

CL_​DEVICE_​TYPE_​CPU

An OpenCL device that is the host processor. The host processor runs the OpenCL implementations and is a single or multi-core CPU.

CL_​DEVICE_​TYPE_​GPU

An OpenCL device that is a GPU. By this we mean that the device can also be used to accelerate a 3D API such as OpenGL or DirectX.

CL_​DEVICE_​TYPE_​ACCELERATOR

Dedicated OpenCL accelerators (for example the IBM CELL Blade). These devices communicate with the host processor using a peripheral interconnect such as PCIe.

CL_​DEVICE_​TYPE_​CUSTOM

Missing before version 1.2.

Dedicated accelerators that do not support programs written in an OpenCL kernel language,

CL_​DEVICE_​TYPE_​DEFAULT

The default OpenCL device in the system. The default device cannot be a CL_​DEVICE_​TYPE_​CUSTOM device.

CL_​DEVICE_​TYPE_​ALL

All OpenCL devices available in the system except CL_​DEVICE_​TYPE_​CUSTOM devices..

clGetDeviceIDs returns CL_​SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_​INVALID_​PLATFORM if platform is not a valid platform.

  • CL_​INVALID_​DEVICE_​TYPE if device_type is not a valid value.

  • CL_​INVALID_​VALUE if num_entries is equal to zero and devices is not NULL or if both num_devices and devices are NULL.

  • CL_​DEVICE_​NOT_​FOUND if no OpenCL devices that matched device_type were found.

  • CL_​OUT_​OF_​RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_​OUT_​OF_​HOST_​MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

The application can query specific capabilities of the OpenCL device(s) returned by clGetDeviceIDs. This can be used by the application to determine which device(s) to use.

See Also

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.