1 //---------------------------------------------------------------------------//
2 // Copyright (c) 2013 Kyle Lutz <kyle.r.lutz@gmail.com>
4 // Distributed under the Boost Software License, Version 1.0
5 // See accompanying file LICENSE_1_0.txt or copy at
6 // http://www.boost.org/LICENSE_1_0.txt
8 // See http://boostorg.github.com/compute for more information.
9 //---------------------------------------------------------------------------//
11 #ifndef BOOST_COMPUTE_DEVICE_HPP
12 #define BOOST_COMPUTE_DEVICE_HPP
18 #include <boost/algorithm/string/split.hpp>
19 #include <boost/algorithm/string/classification.hpp>
21 #include <boost/compute/config.hpp>
22 #include <boost/compute/exception.hpp>
23 #include <boost/compute/types/fundamental.hpp>
24 #include <boost/compute/detail/get_object_info.hpp>
25 #include <boost/compute/detail/assert_cl_success.hpp>
33 /// \brief A compute device.
35 /// Typical compute devices include GPUs and multi-core CPUs. A list
36 /// of all compute devices available on a platform can be obtained
37 /// via the platform::devices() method.
39 /// The default compute device for the system can be obtained with
40 /// the system::default_device() method. For example:
42 /// \snippet test/test_device.cpp default_gpu
44 /// \see platform, context, command_queue
49 cpu = CL_DEVICE_TYPE_CPU,
50 gpu = CL_DEVICE_TYPE_GPU,
51 accelerator = CL_DEVICE_TYPE_ACCELERATOR
54 /// Creates a null device object.
60 /// Creates a new device object for \p id. If \p retain is \c true,
61 /// the reference count for the device will be incremented.
62 explicit device(cl_device_id id, bool retain = true)
66 if(m_id && retain && is_subdevice()){
74 /// Creates a new device object as a copy of \p other.
75 device(const device &other)
79 if(m_id && is_subdevice()){
85 /// Copies the device from \p other to \c *this.
86 device& operator=(const device &other)
90 if(m_id && is_subdevice()){
91 clReleaseDevice(m_id);
98 if(m_id && is_subdevice()){
107 #ifndef BOOST_COMPUTE_NO_RVALUE_REFERENCES
108 /// Move-constructs a new device object from \p other.
109 device(device&& other) BOOST_NOEXCEPT
115 /// Move-assigns the device from \p other to \c *this.
116 device& operator=(device&& other) BOOST_NOEXCEPT
118 #ifdef CL_VERSION_1_2
119 if(m_id && is_subdevice()){
120 clReleaseDevice(m_id);
129 #endif // BOOST_COMPUTE_NO_RVALUE_REFERENCES
131 /// Destroys the device object.
134 #ifdef CL_VERSION_1_2
135 if(m_id && is_subdevice()){
136 BOOST_COMPUTE_ASSERT_CL_SUCCESS(
137 clReleaseDevice(m_id)
143 /// Returns the ID of the device.
144 cl_device_id id() const
149 /// Returns a reference to the underlying OpenCL device id.
150 cl_device_id& get() const
152 return const_cast<cl_device_id&>(m_id);
155 /// Returns the type of the device.
156 cl_device_type type() const
158 return get_info<cl_device_type>(CL_DEVICE_TYPE);
161 #ifdef BOOST_COMPUTE_DOXYGEN_INVOKED
162 /// Returns the platform for the device.
163 platform platform() const;
165 boost::compute::platform platform() const;
168 /// Returns the name of the device.
169 std::string name() const
171 return get_info<std::string>(CL_DEVICE_NAME);
174 /// Returns the name of the vendor for the device.
175 std::string vendor() const
177 return get_info<std::string>(CL_DEVICE_VENDOR);
180 /// Returns the device profile string.
181 std::string profile() const
183 return get_info<std::string>(CL_DEVICE_PROFILE);
186 /// Returns the device version string.
187 std::string version() const
189 return get_info<std::string>(CL_DEVICE_VERSION);
192 /// Returns the driver version string.
193 std::string driver_version() const
195 return get_info<std::string>(CL_DRIVER_VERSION);
198 /// Returns a list of extensions supported by the device.
199 std::vector<std::string> extensions() const
201 std::string extensions_string =
202 get_info<std::string>(CL_DEVICE_EXTENSIONS);
203 std::vector<std::string> extensions_vector;
204 boost::split(extensions_vector,
206 boost::is_any_of("\t "),
207 boost::token_compress_on);
208 return extensions_vector;
211 /// Returns \c true if the device supports the extension with
213 bool supports_extension(const std::string &name) const
215 const std::vector<std::string> extensions = this->extensions();
218 extensions.begin(), extensions.end(), name) != extensions.end();
221 /// Returns the number of address bits.
222 uint_ address_bits() const
224 return get_info<uint_>(CL_DEVICE_ADDRESS_BITS);
227 /// Returns the global memory size in bytes.
228 ulong_ global_memory_size() const
230 return get_info<ulong_>(CL_DEVICE_GLOBAL_MEM_SIZE);
233 /// Returns the local memory size in bytes.
234 ulong_ local_memory_size() const
236 return get_info<ulong_>(CL_DEVICE_LOCAL_MEM_SIZE);
239 /// Returns the clock frequency for the device's compute units.
240 uint_ clock_frequency() const
242 return get_info<uint_>(CL_DEVICE_MAX_CLOCK_FREQUENCY);
245 /// Returns the number of compute units in the device.
246 uint_ compute_units() const
248 return get_info<uint_>(CL_DEVICE_MAX_COMPUTE_UNITS);
252 ulong_ max_memory_alloc_size() const
254 return get_info<ulong_>(CL_DEVICE_MAX_MEM_ALLOC_SIZE);
258 size_t max_work_group_size() const
260 return get_info<size_t>(CL_DEVICE_MAX_WORK_GROUP_SIZE);
264 uint_ max_work_item_dimensions() const
266 return get_info<uint_>(CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS);
269 /// Returns the preferred vector width for type \c T.
271 uint_ preferred_vector_width() const
276 /// Returns the profiling timer resolution in nanoseconds.
277 size_t profiling_timer_resolution() const
279 return get_info<size_t>(CL_DEVICE_PROFILING_TIMER_RESOLUTION);
282 /// Returns \c true if the device is a sub-device.
283 bool is_subdevice() const
285 #if defined(CL_VERSION_1_2)
287 return get_info<cl_device_id>(CL_DEVICE_PARENT_DEVICE) != 0;
289 catch(opencl_error&){
290 // the get_info() call above will throw if the device's opencl version
291 // is less than 1.2 (in which case it can't be a sub-device).
299 /// Returns information about the device.
301 /// For example, to get the number of compute units:
303 /// device.get_info<cl_uint>(CL_DEVICE_MAX_COMPUTE_UNITS);
306 /// Alternatively, the template-specialized version can be used which
307 /// automatically determines the result type:
309 /// device.get_info<CL_DEVICE_MAX_COMPUTE_UNITS>();
312 /// \see_opencl_ref{clGetDeviceInfo}
314 T get_info(cl_device_info info) const
316 return detail::get_object_info<T>(clGetDeviceInfo, m_id, info);
321 typename detail::get_object_info_type<device, Enum>::type
324 #if defined(CL_VERSION_1_2) || defined(BOOST_COMPUTE_DOXYGEN_INVOKED)
325 /// Partitions the device into multiple sub-devices according to
328 /// \opencl_version_warning{1,2}
330 partition(const cl_device_partition_property *properties) const
332 // get sub-device count
334 int_ ret = clCreateSubDevices(m_id, properties, 0, 0, &count);
335 if(ret != CL_SUCCESS){
336 BOOST_THROW_EXCEPTION(opencl_error(ret));
339 // get sub-device ids
340 std::vector<cl_device_id> ids(count);
341 ret = clCreateSubDevices(m_id, properties, count, &ids[0], 0);
342 if(ret != CL_SUCCESS){
343 BOOST_THROW_EXCEPTION(opencl_error(ret));
346 // convert ids to device objects
347 std::vector<device> devices(count);
348 for(size_t i = 0; i < count; i++){
349 devices[i] = device(ids[i], false);
355 /// \opencl_version_warning{1,2}
356 std::vector<device> partition_equally(size_t count) const
358 cl_device_partition_property properties[] = {
359 CL_DEVICE_PARTITION_EQUALLY,
360 static_cast<cl_device_partition_property>(count),
364 return partition(properties);
367 /// \opencl_version_warning{1,2}
369 partition_by_counts(const std::vector<size_t> &counts) const
371 std::vector<cl_device_partition_property> properties;
373 properties.push_back(CL_DEVICE_PARTITION_BY_COUNTS);
374 for(size_t i = 0; i < counts.size(); i++){
375 properties.push_back(
376 static_cast<cl_device_partition_property>(counts[i]));
378 properties.push_back(CL_DEVICE_PARTITION_BY_COUNTS_LIST_END);
379 properties.push_back(0);
381 return partition(&properties[0]);
384 /// \opencl_version_warning{1,2}
386 partition_by_affinity_domain(cl_device_affinity_domain domain) const
388 cl_device_partition_property properties[] = {
389 CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN,
390 static_cast<cl_device_partition_property>(domain),
394 return partition(properties);
396 #endif // CL_VERSION_1_2
398 /// Returns \c true if the device is the same at \p other.
399 bool operator==(const device &other) const
401 return m_id == other.m_id;
404 /// Returns \c true if the device is different from \p other.
405 bool operator!=(const device &other) const
407 return m_id != other.m_id;
411 bool check_version(int major, int minor) const
413 std::stringstream stream;
416 int actual_major, actual_minor;
417 stream.ignore(7); // 'OpenCL '
418 stream >> actual_major;
419 stream.ignore(1); // '.'
420 stream >> actual_minor;
422 return actual_major > major ||
423 (actual_major == major && actual_minor >= minor);
432 inline uint_ device::preferred_vector_width<short_>() const
434 return get_info<uint_>(CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT);
439 inline uint_ device::preferred_vector_width<int_>() const
441 return get_info<uint_>(CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT);
446 inline uint_ device::preferred_vector_width<long_>() const
448 return get_info<uint_>(CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG);
453 inline uint_ device::preferred_vector_width<float_>() const
455 return get_info<uint_>(CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT);
460 inline uint_ device::preferred_vector_width<double_>() const
462 return get_info<uint_>(CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE);
465 /// \internal_ define get_info() specializations for device
466 BOOST_COMPUTE_DETAIL_DEFINE_GET_INFO_SPECIALIZATIONS(device,
467 ((cl_uint, CL_DEVICE_ADDRESS_BITS))
468 ((bool, CL_DEVICE_AVAILABLE))
469 ((bool, CL_DEVICE_COMPILER_AVAILABLE))
470 ((bool, CL_DEVICE_ENDIAN_LITTLE))
471 ((bool, CL_DEVICE_ERROR_CORRECTION_SUPPORT))
472 ((cl_device_exec_capabilities, CL_DEVICE_EXECUTION_CAPABILITIES))
473 ((std::string, CL_DEVICE_EXTENSIONS))
474 ((cl_ulong, CL_DEVICE_GLOBAL_MEM_CACHE_SIZE))
475 ((cl_device_mem_cache_type, CL_DEVICE_GLOBAL_MEM_CACHE_TYPE))
476 ((cl_ulong, CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE))
477 ((cl_ulong, CL_DEVICE_GLOBAL_MEM_SIZE))
478 ((bool, CL_DEVICE_IMAGE_SUPPORT))
479 ((size_t, CL_DEVICE_IMAGE2D_MAX_HEIGHT))
480 ((size_t, CL_DEVICE_IMAGE2D_MAX_WIDTH))
481 ((size_t, CL_DEVICE_IMAGE3D_MAX_DEPTH))
482 ((size_t, CL_DEVICE_IMAGE3D_MAX_HEIGHT))
483 ((size_t, CL_DEVICE_IMAGE3D_MAX_WIDTH))
484 ((cl_ulong, CL_DEVICE_LOCAL_MEM_SIZE))
485 ((cl_device_local_mem_type, CL_DEVICE_LOCAL_MEM_TYPE))
486 ((cl_uint, CL_DEVICE_MAX_CLOCK_FREQUENCY))
487 ((cl_uint, CL_DEVICE_MAX_COMPUTE_UNITS))
488 ((cl_uint, CL_DEVICE_MAX_CONSTANT_ARGS))
489 ((cl_ulong, CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE))
490 ((cl_ulong, CL_DEVICE_MAX_MEM_ALLOC_SIZE))
491 ((size_t, CL_DEVICE_MAX_PARAMETER_SIZE))
492 ((cl_uint, CL_DEVICE_MAX_READ_IMAGE_ARGS))
493 ((cl_uint, CL_DEVICE_MAX_SAMPLERS))
494 ((size_t, CL_DEVICE_MAX_WORK_GROUP_SIZE))
495 ((cl_uint, CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS))
496 ((std::vector<size_t>, CL_DEVICE_MAX_WORK_ITEM_SIZES))
497 ((cl_uint, CL_DEVICE_MAX_WRITE_IMAGE_ARGS))
498 ((cl_uint, CL_DEVICE_MEM_BASE_ADDR_ALIGN))
499 ((cl_uint, CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE))
500 ((std::string, CL_DEVICE_NAME))
501 ((cl_platform_id, CL_DEVICE_PLATFORM))
502 ((cl_uint, CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR))
503 ((cl_uint, CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT))
504 ((cl_uint, CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT))
505 ((cl_uint, CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG))
506 ((cl_uint, CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT))
507 ((cl_uint, CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE))
508 ((std::string, CL_DEVICE_PROFILE))
509 ((size_t, CL_DEVICE_PROFILING_TIMER_RESOLUTION))
510 ((cl_command_queue_properties, CL_DEVICE_QUEUE_PROPERTIES))
511 ((cl_device_fp_config, CL_DEVICE_SINGLE_FP_CONFIG))
512 ((cl_device_type, CL_DEVICE_TYPE))
513 ((std::string, CL_DEVICE_VENDOR))
514 ((cl_uint, CL_DEVICE_VENDOR_ID))
515 ((std::string, CL_DEVICE_VERSION))
516 ((std::string, CL_DRIVER_VERSION))
519 #ifdef CL_DEVICE_DOUBLE_FP_CONFIG
520 BOOST_COMPUTE_DETAIL_DEFINE_GET_INFO_SPECIALIZATIONS(device,
521 ((cl_device_fp_config, CL_DEVICE_DOUBLE_FP_CONFIG))
525 #ifdef CL_DEVICE_HALF_FP_CONFIG
526 BOOST_COMPUTE_DETAIL_DEFINE_GET_INFO_SPECIALIZATIONS(device,
527 ((cl_device_fp_config, CL_DEVICE_HALF_FP_CONFIG))
531 #ifdef CL_VERSION_1_1
532 BOOST_COMPUTE_DETAIL_DEFINE_GET_INFO_SPECIALIZATIONS(device,
533 ((bool, CL_DEVICE_HOST_UNIFIED_MEMORY))
534 ((cl_uint, CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR))
535 ((cl_uint, CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT))
536 ((cl_uint, CL_DEVICE_NATIVE_VECTOR_WIDTH_INT))
537 ((cl_uint, CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG))
538 ((cl_uint, CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT))
539 ((cl_uint, CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE))
540 ((std::string, CL_DEVICE_OPENCL_C_VERSION))
542 #endif // CL_VERSION_1_1
544 #ifdef CL_VERSION_1_2
545 BOOST_COMPUTE_DETAIL_DEFINE_GET_INFO_SPECIALIZATIONS(device,
546 ((std::string, CL_DEVICE_BUILT_IN_KERNELS))
547 ((bool, CL_DEVICE_LINKER_AVAILABLE))
548 ((cl_device_id, CL_DEVICE_PARENT_DEVICE))
549 ((cl_uint, CL_DEVICE_PARTITION_MAX_SUB_DEVICES))
550 ((cl_device_partition_property, CL_DEVICE_PARTITION_PROPERTIES))
551 ((cl_device_affinity_domain, CL_DEVICE_PARTITION_AFFINITY_DOMAIN))
552 ((cl_device_partition_property, CL_DEVICE_PARTITION_TYPE))
553 ((size_t, CL_DEVICE_PRINTF_BUFFER_SIZE))
554 ((bool, CL_DEVICE_PREFERRED_INTEROP_USER_SYNC))
555 ((cl_uint, CL_DEVICE_REFERENCE_COUNT))
557 #endif // CL_VERSION_1_2
559 #ifdef CL_VERSION_2_0
560 BOOST_COMPUTE_DETAIL_DEFINE_GET_INFO_SPECIALIZATIONS(device,
561 ((size_t, CL_DEVICE_GLOBAL_VARIABLE_PREFERRED_TOTAL_SIZE))
562 ((size_t, CL_DEVICE_MAX_GLOBAL_VARIABLE_SIZE))
563 ((cl_uint, CL_DEVICE_MAX_ON_DEVICE_EVENTS))
564 ((cl_uint, CL_DEVICE_MAX_ON_DEVICE_QUEUES))
565 ((cl_uint, CL_DEVICE_MAX_PIPE_ARGS))
566 ((cl_uint, CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS))
567 ((cl_uint, CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS))
568 ((cl_uint, CL_DEVICE_PIPE_MAX_PACKET_SIZE))
569 ((cl_uint, CL_DEVICE_PREFERRED_GLOBAL_ATOMIC_ALIGNMENT))
570 ((cl_uint, CL_DEVICE_PREFERRED_LOCAL_ATOMIC_ALIGNMENT))
571 ((cl_uint, CL_DEVICE_PREFERRED_PLATFORM_ATOMIC_ALIGNMENT))
572 ((cl_uint, CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE))
573 ((cl_uint, CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE))
574 ((cl_command_queue_properties, CL_DEVICE_QUEUE_ON_DEVICE_PROPERTIES))
575 ((cl_device_svm_capabilities, CL_DEVICE_SVM_CAPABILITIES))
576 ((cl_uint, CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT))
577 ((cl_uint, CL_DEVICE_IMAGE_PITCH_ALIGNMENT))
579 #endif // CL_VERSION_2_0
581 } // end compute namespace
582 } // end boost namespace
584 #endif // BOOST_COMPUTE_DEVICE_HPP