C Specification

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

// Provided by CL_VERSION_1_0
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 support a subset of the OpenCL runtime APIs for directed tasks but are not OpenCL conformant. A custom device must implement all of the OpenCL runtime APIs, but may not support all of the required minimum device capabilities and may return implementation-defined error codes for unsupported functionality.

CL_DEVICE_TYPE_DEFAULT

The default OpenCL device in the platform. One device in the platform must be returned as the CL_DEVICE_TYPE_DEFAULT device when passed as the device_type to clGetDeviceIDs. CL_DEVICE_TYPE_DEFAULT is only used to query OpenCL devices using clGetDeviceIDs or to create OpenCL contexts using clCreateContextFromType, and will never be returned in CL_DEVICE_TYPE for any OpenCL device. The default OpenCL device must not be a CL_DEVICE_TYPE_CUSTOM device unless it is the only device in the platform.

CL_DEVICE_TYPE_ALL

All OpenCL devices in the platform. CL_DEVICE_TYPE_ALL is only used to query OpenCL devices using clGetDeviceIDs or to create OpenCL contexts using clCreateContextFromType, and will never be returned in CL_DEVICE_TYPE for any OpenCL device.

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

    • 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

CL_VERSION_1_0, cl_device_id, cl_device_type, cl_platform_id, cl_uint

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

Copyright 2014-2026 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.