Skip to content

Commit 33da8bc

Browse files
rwmcguirrwmcguir
authored
Deprecate ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES (#470)
+ Deprecate in favor of using ZE_STRUCTURE_DEVICE_PROPERTIES_1_2 + Update sample code w/comments to keep users up to date + Also remove some precision loss in sample code * Minor fix on ticks vs tick count for wording Signed-off-by: Russell McGuire <russell.w.mcguire@intel.com>
1 parent b19d5f8 commit 33da8bc

11 files changed

Lines changed: 50 additions & 32 deletions

‎scripts/core/EXT_DeviceUsablememProperties.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ The following psuedo-code demonstrates a sequence for obtaining extended informa
4747
${x}_device_usablemem_size_ext_properties_t* pUsablememProps = allocate(sizeof(${x}_device_usablemem_size_ext_properties_t));
4848
4949
pUsablememProps.stype = ZE_STRUCTURE_TYPE_DEVICE_USABLEMEM_SIZE_EXT_PROPERTIES;
50-
deviceProperties.stype = ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES;
50+
deviceProperties.stype = ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2; // ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
5151
deviceProperties.pNext = pUsablememProps;
5252
5353
//obtain device and extended memory properties

‎scripts/core/EXT_EventQueryKernelTimestamps.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ This extension enables the querying of synchronized event timestamps.
5757
${x}_device_properties_t devProps;
5858
${x}_event_query_kernel_timestamps_ext_properties_t tsProps;
5959
60-
devProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES;
60+
devProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2; // ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
6161
devProps.pNext = &tsProps;
6262
6363
tsProps.stype = ${X}_STRUCTURE_TYPE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_PROPERTIES;

‎scripts/core/EXT_Exp_MutableCommandList.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ API
6565
};
6666
6767
${x}_device_properties_t deviceProps = {
68-
${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES
68+
${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2 // ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
6969
};
7070
deviceProps.pNext = &mutCmdListProps;
7171

‎scripts/core/EXT_Exp_RTASBuilder.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ The next step is to query the target device for acceleration structure propertie
149149
rtasDeviceProps.pNext = nullptr;
150150
151151
${x}_device_properties_t deviceProps;
152-
deviceProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES;
152+
deviceProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2; // ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
153153
deviceProps.pNext = &rtasDeviceProps;
154154
155155
${x}DeviceGetProperties(hDevice, &deviceProps);

‎scripts/core/EXT_RTAS.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ The next step is to query the target device for acceleration structure propertie
148148
rtasDeviceProps.pNext = nullptr;
149149
150150
${x}_device_properties_t deviceProps;
151-
deviceProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES;
151+
deviceProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2; // ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
152152
deviceProps.pNext = &rtasDeviceProps;
153153
154154
${x}DeviceGetProperties(hDevice, &deviceProps);

‎scripts/core/EXT_VirtualMemReadOnlyProperties.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,9 @@ the read-only capability supported by the device.
3939

4040
The ``readonlyCapability`` field reports one of the following values:
4141

42-
- **${X}_DEVICE_READONLY_MEMORY_CAPABILITY_NONE**: The read-only attribute has no effect.
43-
- **${X}_DEVICE_READONLY_MEMORY_CAPABILITY_HINT**: The read-only attribute is forwarded to the OS as a performance hint.
44-
- **${X}_DEVICE_READONLY_MEMORY_CAPABILITY_ENFORCED**: The read-only attribute is hardware-enforced.
42+
- ``${X}_DEVICE_READONLY_MEMORY_CAPABILITY_NONE``: The read-only attribute has no effect.
43+
- ``${X}_DEVICE_READONLY_MEMORY_CAPABILITY_HINT``: The read-only attribute is forwarded to the OS as a performance hint.
44+
- ``${X}_DEVICE_READONLY_MEMORY_CAPABILITY_ENFORCED``: The read-only attribute is hardware-enforced.
4545

4646
The following pseudo-code demonstrates how to query the read-only memory capability:
4747

@@ -53,7 +53,7 @@ The following pseudo-code demonstrates how to query the read-only memory capabil
5353
roProps.pNext = nullptr;
5454
5555
${x}_device_properties_t devProps = {};
56-
devProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES;
56+
devProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2; // ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
5757
devProps.pNext = &roProps;
5858
5959
${x}DeviceGetProperties(hDevice, &devProps);

‎scripts/core/PROG.rst‎

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ The following pseudo-code demonstrates a basic initialization and device discove
9797
9898
for(uint32_t d = 0; d < deviceCount; ++d) {
9999
ze_device_properties_t deviceProperties {};
100-
deviceProperties.stype = ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES;
100+
deviceProperties.stype = ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2; // ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
101101
zeDeviceGetProperties(allDevices[d], &deviceProperties);
102102
103103
if(ZE_DEVICE_TYPE_GPU == deviceProperties.type) {
@@ -1314,9 +1314,20 @@ timestampValidBits and kernelTimestampValidBits members of ${x}_device_propertie
13141314

13151315
.. parsed-literal::
13161316
1317-
// Get timestamp duration
1318-
const double timestampDuration = 1 / deviceProperties.timerResolution; (i.e deviceProperties.timerResolution in cycles/sec)
1319-
const uint64_t timestampMaxValue = ~(-1L << deviceProperties.kernelTimestampValidBits);
1317+
// Note: ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES is deprecated since 1.17 for timer resolution queries.
1318+
// Use ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2 to obtain timerResolution in cycles/sec.
1319+
${x}_device_properties_t deviceProperties {};
1320+
deviceProperties.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2;
1321+
${x}DeviceGetProperties(hDevice, &deviceProperties);
1322+
1323+
// timerResolution is the timer frequency in cycles/sec (Hz) when
1324+
// stype == ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2.
1325+
// Build a mask of kernelTimestampValidBits ones, used to detect counter roll over.
1326+
// (Avoid ~(-1L << bits): shifting a signed value is undefined behavior, and
1327+
// `long` is only 32 bits on some platforms, e.g. Windows.)
1328+
const uint64_t timestampMaxValue = ( deviceProperties.kernelTimestampValidBits >= 64 )
1329+
? ~(uint64_t)0
1330+
: ( (uint64_t)1 << deviceProperties.kernelTimestampValidBits ) - 1;
13201331
13211332
// Create event pool
13221333
${x}_event_pool_desc_t tsEventPoolDesc = {
@@ -1336,7 +1347,7 @@ timestampValidBits and kernelTimestampValidBits members of ${x}_device_propertie
13361347
0 // no additional memory/cache coherency required on wait
13371348
};
13381349
${x}_event_handle_t hTSEvent;
1339-
${x}EventCreate(hEventPool, &tsEventDesc, &hTSEvent);
1350+
${x}EventCreate(hTSEventPool, &tsEventDesc, &hTSEvent);
13401351
13411352
// allocate memory for results
13421353
${x}_device_mem_alloc_desc_t tsResultDesc = {
@@ -1361,13 +1372,20 @@ timestampValidBits and kernelTimestampValidBits members of ${x}_device_propertie
13611372
${x}EventHostSynchronize(hEvent, 0);
13621373
13631374
// Calculation execution time(s)
1364-
double globalTimeInNs = ( tsResult->global.kernelEnd >= tsResult->global.kernelStart )
1365-
? ( tsResult->global.kernelEnd - tsResult->global.kernelStart ) * timestampDuration
1366-
: (( timestampMaxValue - tsResult->global.kernelStart) + tsResult->global.kernelEnd + 1 ) * timestampDuration;
1375+
// First compute the elapsed tick count on each timeline, handling counter roll over.
1376+
uint64_t globalElapsed = ( tsResult->global.kernelEnd >= tsResult->global.kernelStart )
1377+
? ( tsResult->global.kernelEnd - tsResult->global.kernelStart ) // no wrap
1378+
: ( timestampMaxValue - tsResult->global.kernelStart ) + tsResult->global.kernelEnd + 1; // counter wrapped
1379+
1380+
uint64_t contextElapsed = ( tsResult->context.kernelEnd >= tsResult->context.kernelStart )
1381+
? ( tsResult->context.kernelEnd - tsResult->context.kernelStart ) // no wrap
1382+
: ( timestampMaxValue - tsResult->context.kernelStart ) + tsResult->context.kernelEnd + 1; // counter wrapped
13671383
1368-
double contextTimeInNs = ( tsResult->context.kernelEnd >= tsResult->context.kernelStart )
1369-
? ( tsResult->context.kernelEnd - tsResult->context.kernelStart ) * timestampDuration
1370-
: (( timestampMaxValue - tsResult->context.kernelStart) + tsResult->context.kernelEnd + 1 ) * timestampDuration;
1384+
// timerResolution is in cycles/sec (Hz), so nanoseconds = (tick count) / frequency * NS_IN_SEC.
1385+
// Multiply by NS_IN_SEC first to preserve precision.
1386+
const double NS_IN_SEC = 1e9;
1387+
double globalTimeInNs = (double)globalElapsed * NS_IN_SEC / (double)deviceProperties.timerResolution;
1388+
double contextTimeInNs = (double)contextElapsed * NS_IN_SEC / (double)deviceProperties.timerResolution;
13711389
13721390
...
13731391
@@ -2590,7 +2608,7 @@ or sub-device using ${x}DeviceGetProperties.
25902608
25912609
// Query sub-device properties.
25922610
${x}_device_properties_t subdeviceProps {};
2593-
subDeviceProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES;
2611+
subDeviceProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2; // ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
25942612
${x}DeviceGetProperties(hSubdevice, &subdeviceProps);
25952613
25962614
assert(subdeviceProps.flags & ${X}_DEVICE_PROPERTY_FLAG_SUBDEVICE); // Ensure that we have a handle to a sub-device.

‎scripts/core/common.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -336,7 +336,7 @@ etors:
336336
- name: DRIVER_IPC_PROPERTIES
337337
desc: $x_driver_ipc_properties_t
338338
- name: DEVICE_PROPERTIES
339-
desc: $x_device_properties_t
339+
desc: "$x_device_properties_t. @deprecated since 1.17: Use $X_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2 instead."
340340
- name: DEVICE_COMPUTE_PROPERTIES
341341
desc: $x_device_compute_properties_t
342342
- name: DEVICE_MODULE_PROPERTIES

‎scripts/core/device.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,7 @@ members:
194194
"1.0": "[out] Returns the resolution of device timer in nanoseconds used for profiling, timestamps, etc."
195195
"1.1": "[out] Returns the resolution of device timer in cycles per second used for profiling, timestamps, etc."
196196
"1.2": "[out] Returns the resolution of device timer used for profiling, timestamps, etc. When stype==$X_STRUCTURE_TYPE_DEVICE_PROPERTIES the units are in nanoseconds. When stype==$X_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2 units are in cycles/sec"
197+
"1.17": "[out] @deprecated when using $X_STRUCTURE_TYPE_DEVICE_PROPERTIES since 1.17: Use $X_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2 to obtain timerResolution in cycles/sec for profiling and timestamps."
197198
- type: uint32_t
198199
name: timestampValidBits
199200
desc: |

‎scripts/sysman/PROG.rst‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -478,7 +478,7 @@ device:
478478
479479
function ShowDeviceInfo(${s}_device_handle_t hSysmanDevice)
480480
${s}_device_properties_t devProps {}
481-
devProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES
481+
devProps.stype = ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2 // ${X}_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
482482
${s}_device_state_t devState
483483
if (${s}DeviceGetProperties(hSysmanDevice, &devProps) == ${X}_RESULT_SUCCESS)
484484
output(" UUID: %s", devProps.core.uuid.id)
@@ -2366,14 +2366,13 @@ The flow of detecting and recovering from a Survivability mode using Level-Zero
23662366
23672367
# Survivability mode detection
23682368
for(devIndex = 0 .. deviceCount-1){
2369-
ze_device_properties_t device_properties {};
2370-
device_properties.stype = ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES;
2371-
2372-
result = zeDeviceGetProperties(hSysmanDevices[devIndex], &device_properties);
2373-
if(result == ZE_RESULT_ERROR_SURVIVABILITY_MODE_DETECTED){
2374-
# Device is in Survivability mode, flash firmware image to recover the device
2375-
# Recovery using zesDeviceEnumFirmwares(), zesFirmwareFlash() APIs
2376-
}
2369+
ze_device_properties_t device_properties {};
2370+
device_properties.stype = ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2; // ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES deprecated since 1.17
2371+
result = zeDeviceGetProperties(hSysmanDevices[devIndex], &device_properties);
2372+
if(result == ZE_RESULT_ERROR_SURVIVABILITY_MODE_DETECTED){
2373+
# Device is in Survivability mode, flash firmware image to recover the device
2374+
# Recovery using zesDeviceEnumFirmwares(), zesFirmwareFlash() APIs
2375+
}
23772376
}
23782377
free_memory(...)
23792378

0 commit comments

Comments
 (0)