C Specification

The list of devices available on a platform can be obtained using the function [1]:

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 Types 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

Table 1. List of supported device_types by clGetDeviceIDs
Device Type Description

CL_DEVICE_TYPE_CPU

An OpenCL device similar to a traditional CPU (Central Processing Unit). The host processor that executes OpenCL host code may also be considered a CPU OpenCL device.

CL_DEVICE_TYPE_GPU

An OpenCL device similar to a GPU (Graphics Processing Unit). Many systems include a dedicated processor for graphics or rendering that may be considered a GPU OpenCL device.

CL_DEVICE_TYPE_ACCELERATOR

Dedicated devices that may accelerate OpenCL programs, such as FPGAs (Field Programmable Gate Arrays), DSPs (Digital Signal Processors), or AI (Artificial Intelligence) processors.

CL_DEVICE_TYPE_CUSTOM

missing before version 1.2.

Specialized devices that implement some of the OpenCL runtime APIs but do not support all required OpenCL functionality.

CL_DEVICE_TYPE_DEFAULT

The default OpenCL device in the platform. The default OpenCL device must not be a CL_DEVICE_TYPE_CUSTOM device.

CL_DEVICE_TYPE_ALL

All OpenCL devices available in the platform, except for CL_DEVICE_TYPE_CUSTOM devices.

The device type is purely informational and has no semantic meaning.

Some devices may be more than one type. For example, a CL_DEVICE_TYPE_CPU device may also be a CL_DEVICE_TYPE_GPU device, or a CL_DEVICE_TYPE_ACCELERATOR device may also be some other, more descriptive device type. CL_DEVICE_TYPE_CUSTOM devices must not be combined with any other device types.

One device in the platform should be a CL_DEVICE_TYPE_DEFAULT device. The default device should also be a more specific device type, such as CL_DEVICE_TYPE_CPU or CL_DEVICE_TYPE_GPU.

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 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0


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