Creates an array of sub-devices that each reference a non-intersecting set of compute units within in_device
.
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
) |
in_device
The device to be partitioned.
properties
Specifies how in_device
is to be partition 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 table below. Only one of the listed partitioning schemes can be
specified in properties
.
cl_device_partition_property enum (Partition value) | Description |
---|---|
CL_DEVICE_PARTITION_EQUALLY (unsigned int) |
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_PARTITION_MAX_COMPUTE_UNITS ,
then the remaining compute units are not used.
|
CL_DEVICE_PARTITION_BY_COUNTS (unsigned int) |
This property is followed by a
CL_DEVICE_PARTITION_BY_COUNTS_LIST_END
terminated list of compute unit counts. For
each nonzero count m
in the list, a sub-device is created with
m compute units in it.
CL_DEVICE_PARTITION_BY_COUNTS_LIST_END
is defined to be 0.
The number of non-zero count
entries in the list may not exceed
The total number of compute
units specified may not exceed
|
CL_DEVICE_PARTITION_BY_- AFFINITY_DOMAIN (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:
The user may determine what happened by calling
clGetDeviceInfo
( |
num_devices
Size of memory pointed to by out_devices
specified as
the number of cl_device_id entries.
out_devices
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.
Creates an array of sub-devices that each reference a non-intersecting set of compute
units within in_device
, according to a 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.
Returns CL_SUCCESS if the partition is created successfully.
Otherwise, it returns a NULL value with the following error values returned in
errcode_ret
:
in_device
is not valid.
properties
are not valid or if values specified in
properties
are valid but not supported by the device.
out_devices
is not
NULL and num_devices
is less than the number of sub-devices
created by the partition scheme.
in_device
could not be
further partitioned.
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_PARTITION_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_PARTITION_MAX_COMPUTE_UNITS
for in_device
.
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 } |