Skip to content

Commit

Permalink
Stop reporting support for experimental features with extension strings.
Browse files Browse the repository at this point in the history
  • Loading branch information
@aarongreig
aarongreig committed Nov 11, 2024
1 parent 2a134fc commit e791acb
Show file tree
Hide file tree
Showing 25 changed files with 264 additions and 247 deletions.
44 changes: 8 additions & 36 deletions include/ur_api.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1702,6 +1702,13 @@ typedef enum ur_device_info_t {
///< backed 2D sampled image data.
UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP = 0x2020, ///< [::ur_bool_t] returns true if the device supports enqueueing of native
///< work
UR_DEVICE_INFO_LAUNCH_PROPERTIES_SUPPORT_EXP = 0x3000, ///< [::ur_bool_t] Returns true if the device supports the use of kernel
///< launch properties.
UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP = 0x4000, ///< [::ur_bool_t] Returns true if the device supports the USM P2P
///< experimental feature.
UR_DEVICE_INFO_COOPERATIVE_KERNEL_SUPPORT_EXP = 0x5000, ///< [::ur_bool_t] Returns true if the device supports cooperative kernels.
UR_DEVICE_INFO_MULTI_DEVICE_COMPILE_SUPPORT_EXP = 0x7000, ///< [::ur_bool_t] Returns true if the device supports the multi device
///< compile experimental feature.
/// @cond
UR_DEVICE_INFO_FORCE_UINT32 = 0x7fffffff
/// @endcond
Expand All @@ -1727,7 +1734,7 @@ typedef enum ur_device_info_t {
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
/// + `NULL == hDevice`
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
/// + `::UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP < propName`
/// + `::UR_DEVICE_INFO_MULTI_DEVICE_COMPILE_SUPPORT_EXP < propName`
/// - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION
/// + If `propName` is not supported by the adapter.
/// - ::UR_RESULT_ERROR_INVALID_SIZE
Expand Down Expand Up @@ -8282,13 +8289,6 @@ typedef enum ur_exp_command_buffer_command_info_t {

} ur_exp_command_buffer_command_info_t;

///////////////////////////////////////////////////////////////////////////////
#ifndef UR_COMMAND_BUFFER_EXTENSION_STRING_EXP
/// @brief The extension string which defines support for command-buffers which
/// is returned when querying device extensions.
#define UR_COMMAND_BUFFER_EXTENSION_STRING_EXP "ur_exp_command_buffer"
#endif // UR_COMMAND_BUFFER_EXTENSION_STRING_EXP

///////////////////////////////////////////////////////////////////////////////
/// @brief Command-Buffer Descriptor Type
typedef struct ur_exp_command_buffer_desc_t {
Expand Down Expand Up @@ -9383,13 +9383,6 @@ urCommandBufferCommandGetInfoExp(
#if !defined(__GNUC__)
#pragma region cooperative_kernels_(experimental)
#endif
///////////////////////////////////////////////////////////////////////////////
#ifndef UR_COOPERATIVE_KERNELS_EXTENSION_STRING_EXP
/// @brief The extension string which defines support for cooperative-kernels
/// which is returned when querying device extensions.
#define UR_COOPERATIVE_KERNELS_EXTENSION_STRING_EXP "ur_exp_cooperative_kernels"
#endif // UR_COOPERATIVE_KERNELS_EXTENSION_STRING_EXP

///////////////////////////////////////////////////////////////////////////////
/// @brief Enqueue a command to execute a cooperative kernel
///
Expand Down Expand Up @@ -9513,13 +9506,6 @@ urEnqueueTimestampRecordingExp(
#if !defined(__GNUC__)
#pragma region launch_properties_(experimental)
#endif
///////////////////////////////////////////////////////////////////////////////
#ifndef UR_LAUNCH_PROPERTIES_EXTENSION_STRING_EXP
/// @brief The extension string that defines support for the Launch Properties
/// extension, which is returned when querying device extensions.
#define UR_LAUNCH_PROPERTIES_EXTENSION_STRING_EXP "ur_exp_launch_properties"
#endif // UR_LAUNCH_PROPERTIES_EXTENSION_STRING_EXP

///////////////////////////////////////////////////////////////////////////////
/// @brief Specifies a launch property id
///
Expand Down Expand Up @@ -9642,13 +9628,6 @@ urEnqueueKernelLaunchCustomExp(
#if !defined(__GNUC__)
#pragma region multi_device_compile_(experimental)
#endif
///////////////////////////////////////////////////////////////////////////////
#ifndef UR_MULTI_DEVICE_COMPILE_EXTENSION_STRING_EXP
/// @brief The extension string which defines support for test
/// which is returned when querying device extensions.
#define UR_MULTI_DEVICE_COMPILE_EXTENSION_STRING_EXP "ur_exp_multi_device_compile"
#endif // UR_MULTI_DEVICE_COMPILE_EXTENSION_STRING_EXP

///////////////////////////////////////////////////////////////////////////////
/// @brief Produces an executable program from one program, negates need for the
/// linking step.
Expand Down Expand Up @@ -9825,13 +9804,6 @@ urUSMReleaseExp(
#if !defined(__GNUC__)
#pragma region usm_p2p_(experimental)
#endif
///////////////////////////////////////////////////////////////////////////////
#ifndef UR_USM_P2P_EXTENSION_STRING_EXP
/// @brief The extension string that defines support for USM P2P which is
/// returned when querying device extensions.
#define UR_USM_P2P_EXTENSION_STRING_EXP "ur_exp_usm_p2p"
#endif // UR_USM_P2P_EXTENSION_STRING_EXP

///////////////////////////////////////////////////////////////////////////////
/// @brief Supported peer info
typedef enum ur_exp_peer_info_t {
Expand Down
60 changes: 60 additions & 0 deletions include/ur_print.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2646,6 +2646,18 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_device_info_t value) {
case UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP:
os << "UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP";
break;
case UR_DEVICE_INFO_LAUNCH_PROPERTIES_SUPPORT_EXP:
os << "UR_DEVICE_INFO_LAUNCH_PROPERTIES_SUPPORT_EXP";
break;
case UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP:
os << "UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP";
break;
case UR_DEVICE_INFO_COOPERATIVE_KERNEL_SUPPORT_EXP:
os << "UR_DEVICE_INFO_COOPERATIVE_KERNEL_SUPPORT_EXP";
break;
case UR_DEVICE_INFO_MULTI_DEVICE_COMPILE_SUPPORT_EXP:
os << "UR_DEVICE_INFO_MULTI_DEVICE_COMPILE_SUPPORT_EXP";
break;
default:
os << "unknown enumerator";
break;
Expand Down Expand Up @@ -4440,6 +4452,54 @@ inline ur_result_t printTagged(std::ostream &os, const void *ptr, ur_device_info

os << ")";
} break;
case UR_DEVICE_INFO_LAUNCH_PROPERTIES_SUPPORT_EXP: {
const ur_bool_t *tptr = (const ur_bool_t *)ptr;
if (sizeof(ur_bool_t) > size) {
os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_bool_t) << ")";
return UR_RESULT_ERROR_INVALID_SIZE;
}
os << (const void *)(tptr) << " (";

os << *tptr;

os << ")";
} break;
case UR_DEVICE_INFO_USM_P2P_SUPPORT_EXP: {
const ur_bool_t *tptr = (const ur_bool_t *)ptr;
if (sizeof(ur_bool_t) > size) {
os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_bool_t) << ")";
return UR_RESULT_ERROR_INVALID_SIZE;
}
os << (const void *)(tptr) << " (";

os << *tptr;

os << ")";
} break;
case UR_DEVICE_INFO_COOPERATIVE_KERNEL_SUPPORT_EXP: {
const ur_bool_t *tptr = (const ur_bool_t *)ptr;
if (sizeof(ur_bool_t) > size) {
os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_bool_t) << ")";
return UR_RESULT_ERROR_INVALID_SIZE;
}
os << (const void *)(tptr) << " (";

os << *tptr;

os << ")";
} break;
case UR_DEVICE_INFO_MULTI_DEVICE_COMPILE_SUPPORT_EXP: {
const ur_bool_t *tptr = (const ur_bool_t *)ptr;
if (sizeof(ur_bool_t) > size) {
os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_bool_t) << ")";
return UR_RESULT_ERROR_INVALID_SIZE;
}
os << (const void *)(tptr) << " (";

os << *tptr;

os << ")";
} break;
default:
os << "unknown enumerator";
return UR_RESULT_ERROR_INVALID_ENUMERATION;
Expand Down
39 changes: 8 additions & 31 deletions scripts/core/EXP-COMMAND-BUFFER.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,36 +40,14 @@ Querying Command-Buffer Support
--------------------------------------------------------------------------------

Support for command-buffers can be queried for a given device/adapter by using
the device info query with ${X}_DEVICE_INFO_EXTENSIONS. Adapters supporting this
experimental feature will report the string "ur_exp_command_buffer" in the
returned list of supported extensions.

.. hint::
The macro ${X}_COMMAND_BUFFER_EXTENSION_STRING_EXP is defined for the string
returned from extension queries for this feature. Since the actual string
may be subject to change it is safer to use this macro when querying for
support for this experimental feature.
the device info query with ${X}_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP. Adapters
supporting this experimental feature will report ``true``.

.. parsed-literal::
// Retrieve length of extension string
size_t returnedSize;
${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_EXTENSIONS, 0, nullptr,
&returnedSize);
// Retrieve extension string
std::unique_ptr<char[]> returnedExtensions(new char[returnedSize]);
${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_EXTENSIONS, returnedSize,
returnedExtensions.get(), nullptr);
std::string_view ExtensionsString(returnedExtensions.get());
bool CmdBufferSupport =
ExtensionsString.find(${X}_COMMAND_BUFFER_EXTENSION_STRING_EXP)
!= std::string::npos;
.. note::
The ${X}_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP device info query exists to
serve the same purpose as ${X}_COMMAND_BUFFER_EXTENSION_STRING_EXP.
ur_bool_t CmdBufferSupport = false;
${x}DeviceGetInfo(hDevice, ${X}_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP,
sizeof(CmdBufferSupport), &CmdBufferSupport, nullptr);
Command-Buffer Creation
--------------------------------------------------------------------------------
Expand Down Expand Up @@ -396,10 +374,6 @@ ${x}CommandBufferUpdateSignalEventExp there must also have been a non-null
API
--------------------------------------------------------------------------------

Macros
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ${X}_COMMAND_BUFFER_EXTENSION_STRING_EXP

Enums
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ${x}_device_info_t
Expand Down Expand Up @@ -510,6 +484,9 @@ Changelog
+-----------+-------------------------------------------------------+
| 1.6 | Command level synchronization with event objects |
+-----------+-------------------------------------------------------+
| 1.7 | Remove extension string macro, make device info enum |
| | primary mechanism for reporting support. |
+-----------+-------------------------------------------------------+

Contributors
--------------------------------------------------------------------------------
Expand Down
30 changes: 17 additions & 13 deletions scripts/core/EXP-COOPERATIVE-KERNELS.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,10 @@ The functions defined here align with those specified in Level Zero.
API
--------------------------------------------------------------------------------

Macros
Enums
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ${X}_COOPERATIVE_KERNELS_EXTENSION_STRING_EXP
* ${x}_device_info_t
* ${X}_DEVICE_INFO_COOPERATIVE_KERNEL_SUPPORT_EXP

Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -47,22 +48,25 @@ Functions

Changelog
--------------------------------------------------------------------------------
+-----------+------------------------+
| Revision | Changes |
+===========+========================+
| 1.0 | Initial Draft |
+-----------+------------------------+
+-----------+---------------------------------------------+
| Revision | Changes |
+===========+=============================================+
| 1.0 | Initial Draft |
+-----------+---------------------------------------------+
| 1.1 | Switch from extension string macro to |
| | device info enum for reporting support. |
+-----------+---------------------------------------------+

Support
--------------------------------------------------------------------------------

Adapters which support this experimental feature *must* return the valid string
defined in ``${X}_COOPERATIVE_KERNELS_EXTENSION_STRING_EXP``
as one of the options from ${x}DeviceGetInfo when querying for
${X}_DEVICE_INFO_EXTENSIONS. Conversely, before using any of the
functionality defined in this experimental feature the user *must* use the
device query to determine if the adapter supports this feature.
Adapters which support this experimental feature *must* return ``true`` when
queried for ${X}_DEVICE_INFO_COOPERATIVE_KERNEL_SUPPORT_EXP via
${x}DeviceGetInfo. Conversely, before using any of the functionality defined in
this experimental feature the user *must* use the device query to determine if
the adapter supports this feature.

Contributors
--------------------------------------------------------------------------------
* Michael Aziz `[email protected] <[email protected]>`_
* Aaron Greig `[email protected] <[email protected]>`_
21 changes: 13 additions & 8 deletions scripts/core/EXP-LAUNCH-PROPERTIES.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,14 +55,12 @@ cooperative kernels Unified-Runtime extension.
API
--------------------------------------------------------------------------------

Macros
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ${X}_LAUNCH_PROPERTIES_EXTENSION_STRING_EXP

Enums
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ${x}_device_info_t
* ${X}_DEVICE_INFO_LAUNCH_PROPERTIES_SUPPORT_EXP

* ${x}_exp_launch_property_id_t

Unions
Expand All @@ -83,9 +81,12 @@ Functions
Support
--------------------------------------------------------------------------------

Adapters which support this experimental feature *must* return the valid string
defined in ${X}_LAUNCH_PROPERTIES_EXTENSION_STRING_EXP as one of the options from
${x}DeviceGetInfo when querying for ${X}_DEVICE_INFO_EXTENSIONS.
Adapters which support this experimental feature *must* return ``true`` when
queried for ${X}_DEVICE_INFO_LAUNCH_PROPERTIES_SUPPORT_EXP via
${x}DeviceGetInfo. Conversely, before using any of the functionality defined
in this experimental feature the user *must* use the device query to determine
if the adapter supports this feature.


Changelog
--------------------------------------------------------------------------------
Expand All @@ -95,8 +96,12 @@ Changelog
+===========+=============================================+
| 1.0 | Initial Draft |
+-----------+---------------------------------------------+
| 1.1 | Switch from extension string macro to |
| | device info enum for reporting support. |
+-----------+---------------------------------------------+

Contributors
--------------------------------------------------------------------------------

* JackAKirk `[email protected] <[email protected]>`_
* Aaron Greig `[email protected] <[email protected]>`_
30 changes: 19 additions & 11 deletions scripts/core/EXP-MULTI-DEVICE-COMPILE.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ future.
API
--------------------------------------------------------------------------------

Enums
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ${x}_device_info_t
* ${X}_DEVICE_INFO_MULTI_DEVICE_COMPILE_SUPPORT_EXP

Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -42,23 +47,26 @@ Functions
Changelog
--------------------------------------------------------------------------------

+-----------+------------------------+
| Revision | Changes |
+===========+========================+
| 1.0 | Initial Draft |
+-----------+------------------------+
+-----------+---------------------------------------------+
| Revision | Changes |
+===========+=============================================+
| 1.0 | Initial Draft |
+-----------+---------------------------------------------+
| 1.1 | Switch from extension string macro to |
| | device info enum for reporting support. |
+-----------+---------------------------------------------+

Support
--------------------------------------------------------------------------------

Adapters which support this experimental feature *must* return the valid string
defined in ``${X}_MULTI_DEVICE_COMPILE_EXTENSION_STRING_EXP``
as one of the options from ${x}DeviceGetInfo when querying for
${X}_DEVICE_INFO_EXTENSIONS. Conversely, before using any of the
functionality defined in this experimental feature the user *must* use the
device query to determine if the adapter supports this feature.
Adapters which support this experimental feature *must* return ``true`` when
queried for ${X}_DEVICE_INFO_MULTI_DEVICE_COMPILE_SUPPORT_EXP via
${x}DeviceGetInfo. Conversely, before using any of the functionality defined
in this experimental feature the user *must* use the device query to determine
if the adapter supports this feature.

Contributors
--------------------------------------------------------------------------------

* Kenneth Benzie (Benie) `[email protected] <[email protected]>`_
* Aaron Greig `[email protected] <[email protected]>`_
Loading

0 comments on commit e791acb

Please sign in to comment.