table of contents
CLCREATESUBDEVICES(3clc) | OpenCL Manual | CLCREATESUBDEVICES(3clc) |
NAME¶
clCreateSubDevices - 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);
PARAMETERS¶
in_deviceproperties
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 CL_DEVICE_PARTITION_MAX_SUB_DEVICES. The total number of compute units specified may not exceed CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS. |
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: 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(3clc) (CL_DEVICE_PARTITION_TYPE) on the sub-devices. |
num_devices
out_devices
num_devices_ret
NOTES¶
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.ERRORS¶
Returns CL_SUCCESS if the partition is created successfully. Otherwise, it returns a null value with the following error values returned in errcode_ret:Example¶
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 } |
SPECIFICATION¶
OpenCL Specification[1]SEE ALSO¶
clGetDeviceInfo(3clc)AUTHORS¶
The Khronos GroupCOPYRIGHT¶
Copyright © 2007-2011 The Khronos Group Inc.Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.
NOTES¶
- 1.
- OpenCL Specification
06/18/2014 | The Khronos Group |