CLCREATESUBDEVICES(3clc)

📦
version 1.0~svn33624 · 3 versions
, in ubuntu jammy, ubuntu noble

💖 CLCREATESUBDEVICES 💖

okay bestie, welcome to CLCREATESUBDEVICES(3clc) from the OpenCL Manual — this is the one where you take one big device and ✂️ partition it into a lil squad of sub-devices. no cap, it's giving main character energy for real.

✨ NAME ✨

clCreateSubDevices — creates an array of sub-devices, and each one references a non-intersecting set of compute units inside in_device. like, nobody's stepping on anybody's toes here, everyone gets their own lil zone 🫶

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 — the device you wanna partition. the one getting sliced and diced 💅
  • properties — tells everyone how in_device is gonna be partitioned, described by a partition name plus its matching value. each partition name is immediately followed by the corresponding desired value, and the list is terminated with 0. the supported partitioning schemes are listed below 👇 and heads up: only one of the listed partitioning schemes can be specified in properties. pick one, bestie, not all of them.
    • 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. and if n does not divide evenly into CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS, then the remaining compute units are not used. leftovers, sad 😭
    • 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 this 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.

and the user may determine what happened by calling clGetDeviceInfo(3clc) (CL_DEVICE_PARTITION_TYPE) on the sub-devices. so you can always find out which level got picked, iykyk 🔍

  • num_devices — size of the 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. so like, size it right or it's gonna be a whole situation 🙈
  • 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. perfectly fine to pass NULL, she's just not gonna tell you the count 💀

💅 NOTES 💅

so what's actually happening here? clCreateSubDevices 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. 🌸

and here's the slay part: 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. no leaking, no sharing, it stays in its lane fr fr ✨

bestie this is only part 1, don't go anywhere 💖

💥 ERRORS 💥

okay so like, the happy path? Returns CL_SUCCESS when the partition is created successfully. That's it, that's the dream. 🫶

But if it's not giving success, bestie, it returns a null value and drops the tea in errcode_ret instead. And the possible error values are:

  • CL_INVALID_DEVICE — if in_device is not valid. like, that device? not real. 🙈
  • CL_INVALID_VALUE — if the values you put in properties are not valid, or if the values in properties are valid but the device just doesn't support them. valid but unsupported, the audacity. 💀
  • 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. not enough room in the car, babes. 😭
  • CL_DEVICE_PARTITION_FAILED — if the partition name is supported by the implementation, but in_device could not be further partitioned. it wanted to, it just couldn't. 💔
  • 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_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. 💅
  • CL_OUT_OF_RESOURCES — if there's a failure to allocate resources required by the OpenCL implementation on the device.
  • CL_OUT_OF_HOST_MEMORY — if there's a failure to allocate resources required by the OpenCL implementation on the host.

🎀 Example 🎀

here's a few lil examples showing how to specify partition properties in the properties argument to clCreateSubDevices. stan a demo. ✨

Want 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 }

Want to partition a device with four compute units into two sub-devices — one sub-device containing 3 compute units and the other sub-device 1 compute unit? Pass the following in the properties argument:

{ CL_DEVICE_PARTITION_BY_COUNTS, 3, 1,
CL_DEVICE_PARTITION_BY_COUNTS_LIST_END,
0 }

Want to split a device along the outermost cache line (if any)? Pass the following in the properties argument:

{
CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN,
CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE,
0 }

periodt. 💖

📜 SPECIFICATION 📜

OpenCL Specification[1] 🦋

and yes bestie, [1] is the footnote — page 49, section 4.3 - Partitioning a Device. iykyk. 💅

👀 SEE ALSO 👀

👑 AUTHORS 👑

The Khronos Group — icons only, no notes. 🫶

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.

and that's the whole page, bestie!! 💖✨🎀 The Khronos Group wrote this one, dated 01/14/2021, and it lives in the manual as CLCREATESUBDEVICES(3clc). go forth and partition responsibly. 🦋🌸👑

📦 where this page comes from