C Specification

To create sub-devices partitioning an OpenCL device, call the function:

cl_int clCreateSubDevices(
    cl_device_id in_device,
    const cl_device_partition_property* properties,
    cl_uint num_devices,
    cl_device_id* out_devices,
    cl_uint* num_devices_ret);

Parameters

  • in_device is the device to be partitioned.

  • properties specifies how in_device is to be partitioned, described by a partition name and its corresponding value. Each partition name is immediately followed by the corresponding desired value. The list is terminated with 0. The list of supported partitioning schemes is described in the Subdevice Partition table. Only one of the listed partitioning schemes can be specified in properties.

  • num_devices is the size of memory pointed to by out_devices specified as the number of cl_device_id entries.

  • out_devices is the buffer where the OpenCL sub-devices will be returned. If out_devices is NULL, this argument is ignored. If out_devices is not NULL, num_devices must be greater than or equal to the number of sub-devices that device may be partitioned into according to the partitioning scheme specified in properties.

  • num_devices_ret returns the number of sub-devices that device may be partitioned into according to the partitioning scheme specified in properties. If num_devices_ret is NULL, it is ignored.

Description

clCreateSubDevices creates an array of sub-devices that each reference a non-intersecting set of compute units within in_device, according to the partition scheme given by properties. The output sub-devices may be used in every way that the root (or parent) device can be used, including creating contexts, building programs, further calls to clCreateSubDevices and creating command-queues. When a command-queue is created against a sub-device, the commands enqueued on the queue are executed only on the sub-device.

Table 1. List of supported partition schemes by https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html#clCreateSubDevices
cl_device_partition_property enum Partition value Description

CL_​DEVICE_​PARTITION_​EQUALLY

Missing before version 1.2.

cl_uint

Split the aggregate device into as many smaller aggregate devices as can be created, each containing n compute units. The value n is passed as the value accompanying this property. If n does not divide evenly into CL_​DEVICE_​MAX_​COMPUTE_​UNITS, then the remaining compute units are not used.

CL_​DEVICE_​PARTITION_​BY_​COUNTS

Missing before version 1.2.

cl_uint

This property is followed by a list of compute unit counts terminated with 0 or CL_​DEVICE_​PARTITION_​BY_​COUNTS_​LIST_​END. For each non-zero count m in the list, a sub-device is created with m compute units in it.

The number of non-zero count entries in the list may not exceed CL_​DEVICE_​PARTITION_​MAX_​SUB_​DEVICES.

The total number of compute units specified may not exceed CL_​DEVICE_​MAX_​COMPUTE_​UNITS.

CL_​DEVICE_​PARTITION_​BY_​AFFINITY_​DOMAIN

Missing before version 1.2.

cl_device_affinity_ domain

Split the device into smaller aggregate devices containing one or more compute units that all share part of a cache hierarchy. The value accompanying this property may be drawn from the following list:

CL_​DEVICE_​AFFINITY_​DOMAIN_​NUMA - Split the device into sub-devices comprised of compute units that share a NUMA node.

CL_​DEVICE_​AFFINITY_​DOMAIN_​L4_​CACHE - Split the device into sub-devices comprised of compute units that share a level 4 data cache.

CL_​DEVICE_​AFFINITY_​DOMAIN_​L3_​CACHE - Split the device into sub-devices comprised of compute units that share a level 3 data cache.

CL_​DEVICE_​AFFINITY_​DOMAIN_​L2_​CACHE - Split the device into sub-devices comprised of compute units that share a level 2 data cache.

CL_​DEVICE_​AFFINITY_​DOMAIN_​L1_​CACHE - Split the device into sub-devices comprised of compute units that share a level 1 data cache.

CL_​DEVICE_​AFFINITY_​DOMAIN_​NEXT_​PARTITIONABLE - Split the device along the next partitionable affinity domain. The implementation shall find the first level along which the device or sub-device may be further subdivided in the order NUMA, L4, L3, L2, L1, and partition the device into sub-devices comprised of compute units that share memory subsystems at this level.

The user may determine what happened by calling clGetDeviceInfo(CL_​DEVICE_​PARTITION_​TYPE) on the sub-devices.

clCreateSubDevices returns CL_​SUCCESS if the partition is created successfully. Otherwise, it returns a NULL value with the following error values returned in errcode_ret:

  • CL_​INVALID_​DEVICE if in_device is not a valid device.

  • CL_​INVALID_​VALUE if values specified in properties are not valid or if values specified in properties are valid but not supported by the device.

  • CL_​INVALID_​VALUE if out_devices is not NULL and num_devices is less than the number of sub-devices created by the partition scheme.

  • CL_​DEVICE_​PARTITION_​FAILED if the partition name is supported by the implementation but in_device could not be further partitioned.

  • CL_​INVALID_​DEVICE_​PARTITION_​COUNT if the partition name specified in properties is CL_​DEVICE_​PARTITION_​BY_​COUNTS and the number of sub-devices requested exceeds CL_​DEVICE_​PARTITION_​MAX_​SUB_​DEVICES or the total number of compute units requested exceeds CL_​DEVICE_​MAX_​COMPUTE_​UNITS for in_device, or the number of compute units requested for one or more sub-devices is less than zero or the number of sub-devices requested exceeds CL_​DEVICE_​MAX_​COMPUTE_​UNITS for in_device.

  • 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.

A few examples that describe how to specify partition properties in properties argument to clCreateSubDevices are given below:

To partition a device containing 16 compute units into two sub-devices, each containing 8 compute units, pass the following in properties:

{ CL_DEVICE_PARTITION_EQUALLY, 8, 0 }

To partition a device with four compute units into two sub-devices with one sub-device containing 3 compute units and the other sub-device 1 compute unit, pass the following in properties argument:

{ CL_DEVICE_PARTITION_BY_COUNTS,
  3, 1, CL_DEVICE_PARTITION_BY_COUNTS_LIST_END, 0 }

To split a device along the outermost cache line (if any), pass the following in properties argument:

{ CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN,
  CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE,
  0 }

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.