'\" t
.\"     Title: clCreateSubDevices
.\"    Author: The Khronos Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/14/2021
.\"    Manual: OpenCL Manual
.\"    Source: The Khronos Group
.\"  Language: English
.\"
.TH "CLCREATESUBDEVICES" "3clc" "01/14/2021" "The Khronos Group" "OpenCL Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
clCreateSubDevices \- Creates an array of sub\-devices that each reference a non\-intersecting set of compute units within in_device\&.
.SH ""
.HP \w'cl_int\ clCreateSubDevices('u
.BI "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" ");"
.SH "PARAMETERS"
.PP
\fIin_device\fR
.RS 4
The device to be partitioned\&.
.RE
.PP
\fIproperties\fR
.RS 4
Specifies how
\fIin_device\fR
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
\fIproperties\fR\&.
.TS
allbox tab(:);
lB lB.
T{
cl_device_partition_
property enum (Partition value)
T}:T{
Description
T}
.T&
l l
l l
l l.
T{
CL_DEVICE_PARTITION_EQUALLY (unsigned int)
T}:T{
Split the aggregate device into as many smaller
aggregate devices as can be created, each
containing \fIn\fR compute
units\&.  The value \fIn\fR is
passed as the value accompanying this property\&. If
\fIn\fR does not divide evenly into
\fBCL_DEVICE_PARTITION_MAX_COMPUTE_UNITS\fR,
then the remaining compute units are not used\&.
T}
T{
CL_DEVICE_PARTITION_BY_COUNTS (unsigned int)
T}:T{
This property is followed by a
\fBCL_DEVICE_PARTITION_BY_COUNTS_LIST_END\fR
terminated list of compute unit counts\&. For
each nonzero count \fIm\fR
in the list, a sub\-device is created with
\fIm\fR compute units in it\&.
\fBCL_DEVICE_PARTITION_BY_COUNTS_LIST_END\fR
is defined to be 0\&.

The number of non\-zero count entries in the list may not exceed
\fBCL_DEVICE_PARTITION_MAX_SUB_DEVICES\fR\&.
.sp
The total number of compute units specified may not exceed
\fBCL_DEVICE_PARTITION_MAX_COMPUTE_UNITS\fR\&.
T}
T{
CL_DEVICE_PARTITION_BY_\-
AFFINITY_DOMAIN (cl_device_affinity_domain)
T}:T{
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:

\fBCL_DEVICE_AFFINITY_DOMAIN_NUMA\fR
\- Split the device into sub\-devices comprised of compute units that share a NUMA node\&.
.sp
\fBCL_DEVICE_AFFINITY_DOMAIN_L4_CACHE\fR
\- Split the device into sub\-devices comprised of compute units that share a level 4 data cache\&.
.sp
\fBCL_DEVICE_AFFINITY_DOMAIN_L3_CACHE\fR
\- Split the device into sub\-devices comprised of compute units that share a level 3 data cache\&.
.sp
\fBCL_DEVICE_AFFINITY_DOMAIN_L2_CACHE\fR
\- Split the device into sub\-devices comprised of compute units that share a level 2 data cache\&.
.sp
\fBCL_DEVICE_AFFINITY_DOMAIN_L1_CACHE\fR
\- Split the device into sub\-devices comprised of compute units that share a level 1 data cache\&.
.sp
\fBCL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE\fR
\- 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\&.
.sp
The user may determine what happened by calling
\fBclGetDeviceInfo\fR(3clc)
(\fBCL_DEVICE_PARTITION_TYPE\fR) on the sub\-devices\&.
T}
.TE
.sp 1
.RE
.PP
\fInum_devices\fR
.RS 4
Size of memory pointed to by
\fIout_devices\fR
specified as the number of
\fBcl_device_id\fR
entries\&.
.RE
.PP
\fIout_devices\fR
.RS 4
The buffer where the OpenCL sub\-devices will be returned\&. If
\fIout_devices\fR
is NULL, this argument is ignored\&. If
\fIout_devices\fR
is not NULL,
\fInum_devices\fR
must be greater than or equal to the number of sub\-devices that
\fIdevice\fR
may be partitioned into according to the partitioning scheme specified in
\fIproperties\fR\&.
.RE
.PP
\fInum_devices_ret\fR
.RS 4
Returns the number of sub\-devices that device may be partitioned into according to the partitioning scheme specified in
\fIproperties\fR\&. If
\fInum_devices_ret\fR
is NULL, it is ignored\&.
.RE
.SH "NOTES"
.PP
Creates an array of sub\-devices that each reference a non\-intersecting set of compute units within
\fIin_device\fR, according to a partition scheme given by
\fIproperties\fR\&. 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
\fBclCreateSubDevices\fR
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\&.
.SH "ERRORS"
.PP
Returns
CL_SUCCESS
if the partition is created successfully\&. Otherwise, it returns a null value with the following error values returned in
\fIerrcode_ret\fR:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CL_INVALID_DEVICE if \fIin_device\fR is not valid\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CL_INVALID_VALUE if values specified in
\fIproperties\fR are not valid or if values specified in
\fIproperties\fR are valid but not supported by the device\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CL_INVALID_VALUE if \fIout_devices\fR is not
NULL and \fInum_devices\fR is less than the number of sub\-devices
created by the partition scheme\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CL_DEVICE_PARTITION_FAILED if the partition name is
supported by the implementation but \fIin_device\fR could not be
further partitioned\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CL_INVALID_DEVICE_PARTITION_COUNT if
the partition name specified in \fIproperties\fR is
\fBCL_DEVICE_PARTITION_BY_COUNTS\fR and the number of sub\-devices
requested exceeds \fBCL_DEVICE_PARTITION_MAX_SUB_DEVICES\fR
or the total number of compute units requested exceeds
\fBCL_DEVICE_PARTITION_MAX_COMPUTE_UNITS\fR for
\fIin_device\fR, 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 \fBCL_DEVICE_PARTITION_MAX_COMPUTE_UNITS\fR
for \fIin_device\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CL_OUT_OF_RESOURCES if there is a failure to allocate
resources required by the OpenCL implementation on the device\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate
resources required by the OpenCL implementation on the host\&.
.RE
.SS "Example"
.PP
A few examples that describe how to specify partition properties in
\fIproperties\fR
argument to
\fBclCreateSubDevices\fR
are given below\&.
.PP
To partition a device containing 16 compute units into two sub\-devices, each containing 8 compute units, pass the following in
\fIproperties\fR:
.TS
tab(:);
l.
T{
{ CL_DEVICE_PARTITION_EQUALLY, 8, 0 }
T}
.TE
.sp 1
.PP
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
\fIproperties\fR
argument:
.TS
tab(:);
l.
T{
{ CL_DEVICE_PARTITION_BY_COUNTS,
3, 1, CL_DEVICE_PARTITION_BY_COUNTS_LIST_END, 0 }
T}
.TE
.sp 1
.PP
To split a device along the outermost cache line (if any), pass the following in
\fIproperties\fR
argument:
.TS
tab(:);
l.
T{
{ CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN,
CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE, 0 }
T}
.TE
.sp 1
.SH "SPECIFICATION"
.PP
\m[blue]\fBOpenCL Specification\fR\m[]\&\s-2\u[1]\d\s+2
.SH "SEE ALSO"
.PP
\fBclGetDeviceInfo\fR(3clc)
.SH "AUTHORS"
.PP
\fBThe Khronos Group\fR
.SH "COPYRIGHT"
.br
Copyright \(co 2007-2011 The Khronos Group Inc.
.br
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.
.sp
.SH "NOTES"
.IP " 1." 4
OpenCL Specification
.RS 4
\%page 49, section 4.3 - Partitioning a Device
.RE