1// Copyright (c) 2018-2020 Intel Corporation 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5ifdef::VK_INTEL_performance_query[] 6[[queries-performance-intel]] 7== Intel performance queries 8 9Intel performance queries allow an application to capture performance data 10for a set of commands. 11Performance queries are used in a similar way than other types of queries. 12A main difference with existing queries is that the resulting data should be 13handed over to a library capabable to produce human readable results rather 14than being read directly by an application. 15 16[open,refpage='vkInitializePerformanceApiINTEL',desc='Initialize a device for performance queries',type='protos'] 17-- 18Prior to creating a performance query pool, initialize the device for 19performance queries with the call: 20 21include::{generated}/api/protos/vkInitializePerformanceApiINTEL.txt[] 22 23 * pname:device is the logical device used for the queries. 24 * pname:pInitializeInfo is a pointer to a 25 slink:VkInitializePerformanceApiInfoINTEL structure specifying 26 initialization parameters. 27 28include::{generated}/validity/protos/vkInitializePerformanceApiINTEL.txt[] 29-- 30 31[open,refpage='VkInitializePerformanceApiInfoINTEL',desc='Structure specifying parameters of initialize of the device',type='structs'] 32-- 33The sname:VkInitializePerformanceApiInfoINTEL structure is defined as : 34 35include::{generated}/api/structs/VkInitializePerformanceApiInfoINTEL.txt[] 36 37 * pname:sType is the type of this structure. 38 * pname:pNext is `NULL` or a pointer to a structure extending this 39 structure. 40 * pname:pUserData is a pointer for application data. 41 42include::{generated}/validity/structs/VkInitializePerformanceApiInfoINTEL.txt[] 43-- 44 45[open,refpage='vkUninitializePerformanceApiINTEL',desc='Uninitialize a device for performance queries',type='protos'] 46-- 47Once performance query operations have completed, uninitalize the device for 48performance queries with the call: 49 50include::{generated}/api/protos/vkUninitializePerformanceApiINTEL.txt[] 51 52 * pname:device is the logical device used for the queries. 53 54include::{generated}/validity/protos/vkUninitializePerformanceApiINTEL.txt[] 55-- 56 57[open,refpage='vkGetPerformanceParameterINTEL',desc='Query performance capabilities of the device',type='protos'] 58-- 59Some performance query features of a device can be discovered with the call: 60 61include::{generated}/api/protos/vkGetPerformanceParameterINTEL.txt[] 62 63 * pname:device is the logical device to query. 64 * pname:parameter is the parameter to query. 65 * pname:pValue is a pointer to a slink:VkPerformanceValueINTEL structure 66 in which the type and value of the parameter are returned. 67 68include::{generated}/validity/protos/vkGetPerformanceParameterINTEL.txt[] 69-- 70 71[open,refpage='VkPerformanceParameterTypeINTEL',desc='Parameters that can be queried',type='enums'] 72-- 73Possible values of flink:vkGetPerformanceParameterINTEL::pname:parameter, 74specifying a performance query feature, are: 75 76include::{generated}/api/enums/VkPerformanceParameterTypeINTEL.txt[] 77 78 * ename:VK_PERFORMANCE_PARAMETER_TYPE_HW_COUNTERS_SUPPORTED_INTEL has a 79 boolean result which tells whether hardware counters can be captured. 80 * ename:VK_PERFORMANCE_PARAMETER_TYPE_STREAM_MARKER_VALID_BITS_INTEL has a 81 32 bits integer result which tells how many bits can be written into the 82 sname:VkPerformanceValueINTEL value. 83-- 84 85[open,refpage='VkPerformanceValueINTEL',desc='Container for value and types of parameters that can be queried',type='structs'] 86-- 87The sname:VkPerformanceValueINTEL structure is defined as: 88 89include::{generated}/api/structs/VkPerformanceValueINTEL.txt[] 90 91 * pname:type is a elink:VkPerformanceValueTypeINTEL value specifying the 92 type of the returned data. 93 * pname:data is a slink:VkPerformanceValueDataINTEL union specifying the 94 value of the returned data. 95 96include::{generated}/validity/structs/VkPerformanceValueINTEL.txt[] 97-- 98 99[open,refpage='VkPerformanceValueTypeINTEL',desc='Type of the parameters that can be queried',type='enums'] 100-- 101Possible values of slink:VkPerformanceValueINTEL::pname:type, specifying the 102type of the data returned in slink:VkPerformanceValueINTEL::pname:data, are: 103 104 * ename:VK_PERFORMANCE_VALUE_TYPE_UINT32_INTEL specifies that unsigned 105 32-bit integer data is returned in pname:data.value32. 106 * ename:VK_PERFORMANCE_VALUE_TYPE_UINT64_INTEL specifies that unsigned 107 64-bit integer data is returned in pname:data.value64. 108 * ename:VK_PERFORMANCE_VALUE_TYPE_FLOAT_INTEL specifies that 109 floating-point data is returned in pname:data.valueFloat. 110 * ename:VK_PERFORMANCE_VALUE_TYPE_BOOL_INTEL specifies that 111 basetype:Bool32 data is returned in pname:data.valueBool. 112 * ename:VK_PERFORMANCE_VALUE_TYPE_STRING_INTEL specifies that a pointer to 113 a null-terminated UTF-8 string is returned in pname:data.valueString. 114 The pointer is valid for the lifetime of the pname:device parameter 115 passed to flink:vkGetPerformanceParameterINTEL. 116 117include::{generated}/api/enums/VkPerformanceValueTypeINTEL.txt[] 118-- 119 120[open,refpage='VkPerformanceValueDataINTEL',desc='Values returned for the parameters',type='structs'] 121-- 122The sname:VkPerformanceValueDataINTEL union is defined as: 123 124include::{generated}/api/structs/VkPerformanceValueDataINTEL.txt[] 125 126 * pname:data.value32 represents 32-bit integer data. 127 * pname:data.value64 represents 64-bit integer data. 128 * pname:data.valueFloat represents floating-point data. 129 * pname:data.valueBool represents basetype:Bool32 data. 130 * pname:data.valueString represents a pointer to a null-terminated UTF-8 131 string. 132 133The correct member of the union is determined by the associated 134elink:VkPerformanceValueTypeINTEL value. 135 136include::{generated}/validity/structs/VkPerformanceValueDataINTEL.txt[] 137-- 138 139[open,refpage='VkQueryPoolPerformanceQueryCreateInfoINTEL',desc='Structure specifying parameters to create a pool of performance queries',type='structs',alias='VkQueryPoolCreateInfoINTEL'] 140-- 141The sname:VkQueryPoolPerformanceQueryCreateInfoINTEL structure is defined 142as: 143 144include::{generated}/api/structs/VkQueryPoolPerformanceQueryCreateInfoINTEL.txt[] 145 146include::{generated}/api/structs/VkQueryPoolCreateInfoINTEL.txt[] 147 148To create a pool for Intel performance queries, set 149slink:VkQueryPoolCreateInfo::pname:queryType to 150ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL and add a 151sname:VkQueryPoolPerformanceQueryCreateInfoINTEL structure to the 152pname:pNext chain of the slink:VkQueryPoolCreateInfo structure. 153 154 * pname:sType is the type of this structure. 155 * pname:pNext is `NULL` or a pointer to a structure extending this 156 structure. 157 * pname:performanceCountersSampling describe how performance queries 158 should be captured. 159 160include::{generated}/validity/structs/VkQueryPoolPerformanceQueryCreateInfoINTEL.txt[] 161-- 162 163[open,refpage='VkQueryPoolSamplingModeINTEL',desc='Enum specifying how performance queries should be captured',type='enums'] 164-- 165Possible values of 166slink:VkQueryPoolPerformanceQueryCreateInfoINTEL::pname:performanceCountersSampling 167are: 168 169include::{generated}/api/enums/VkQueryPoolSamplingModeINTEL.txt[] 170 171 * ename:VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL is the default mode in 172 which the application calls flink:vkCmdBeginQuery and 173 flink:vkCmdEndQuery to record performance data. 174-- 175 176[open,refpage='vkCmdSetPerformanceMarkerINTEL',desc='Markers',type='protos'] 177-- 178To help associate query results with a particular point at which an 179application emitted commands, markers can be set into the command buffers 180with the call: 181 182include::{generated}/api/protos/vkCmdSetPerformanceMarkerINTEL.txt[] 183 184The last marker set onto a command buffer before the end of a query will be 185part of the query result. 186 187include::{generated}/validity/protos/vkCmdSetPerformanceMarkerINTEL.txt[] 188-- 189 190[open,refpage='VkPerformanceMarkerInfoINTEL',desc='Structure specifying performance markers',type='structs'] 191-- 192The sname:VkPerformanceMarkerInfoINTEL structure is defined as: 193 194include::{generated}/api/structs/VkPerformanceMarkerInfoINTEL.txt[] 195 196 * pname:sType is the type of this structure. 197 * pname:pNext is `NULL` or a pointer to a structure extending this 198 structure. 199 * pname:marker is the marker value that will be recorded into the opaque 200 query results. 201 202include::{generated}/validity/structs/VkPerformanceMarkerInfoINTEL.txt[] 203-- 204 205[open,refpage='vkCmdSetPerformanceStreamMarkerINTEL',desc='Markers',type='protos'] 206-- 207When monitoring the behavior of an application wihtin the dataset generated 208by the entire set of applications running on the system, it is useful to 209identify draw calls within a potentially huge amount of performance data. 210To do so, application can generate stream markers that will be used to trace 211back a particular draw call with a particular performance data item. 212 213include::{generated}/api/protos/vkCmdSetPerformanceStreamMarkerINTEL.txt[] 214 215include::{generated}/validity/protos/vkCmdSetPerformanceStreamMarkerINTEL.txt[] 216-- 217 218[open,refpage='VkPerformanceStreamMarkerInfoINTEL',desc='Structure specifying stream performance markers',type='structs'] 219-- 220The sname:VkPerformanceStreamMarkerInfoINTEL structure is defined as: 221 222include::{generated}/api/structs/VkPerformanceStreamMarkerInfoINTEL.txt[] 223 224 * pname:sType is the type of this structure. 225 * pname:pNext is `NULL` or a pointer to a structure extending this 226 structure. 227 * pname:marker is the marker value that will be recorded into the reports 228 consumed by an external application. 229 230.Valid Usage 231**** 232 * [[VUID-VkPerformanceStreamMarkerInfoINTEL-marker-02735]] 233 The value written by the application into pname:marker must: only used 234 the valid bits as reported by flink:vkGetPerformanceParameterINTEL with 235 the ename:VK_PERFORMANCE_PARAMETER_TYPE_STREAM_MARKER_VALID_BITS_INTEL 236**** 237 238include::{generated}/validity/structs/VkPerformanceStreamMarkerInfoINTEL.txt[] 239-- 240 241[open,refpage='vkCmdSetPerformanceOverrideINTEL',desc='Performance override settings',type='protos'] 242-- 243Some applications might want measure the effect of a set of commands with a 244different settings. 245It is possible to override a particular settings using : 246 247include::{generated}/api/protos/vkCmdSetPerformanceOverrideINTEL.txt[] 248 249 * pname:commandBuffer is the command buffer where the override takes 250 place. 251 * pname:pOverrideInfo is a pointer to a 252 slink:VkPerformanceOverrideInfoINTEL structure selecting the parameter 253 to override. 254 255.Valid Usage 256**** 257 * [[VUID-vkCmdSetPerformanceOverrideINTEL-pOverrideInfo-02736]] 258 pname:pOverrideInfo must: not be used with a 259 elink:VkPerformanceOverrideTypeINTEL that is not reported available by 260 fname:vkGetPerformanceParameterINTEL 261**** 262 263include::{generated}/validity/protos/vkCmdSetPerformanceOverrideINTEL.txt[] 264-- 265 266[open,refpage='VkPerformanceOverrideInfoINTEL',desc='Performance override information',type='structs'] 267-- 268The sname:VkPerformanceOverrideInfoINTEL structure is defined as: 269 270include::{generated}/api/structs/VkPerformanceOverrideInfoINTEL.txt[] 271 272 * pname:type is the particular elink:VkPerformanceOverrideTypeINTEL to 273 set. 274 * pname:enable defines whether the override is enabled. 275 * pname:parameter is a potential required parameter for the override. 276 277include::{generated}/validity/structs/VkPerformanceOverrideInfoINTEL.txt[] 278-- 279 280[open,refpage='VkPerformanceOverrideTypeINTEL',desc='Performance override type',type='enums'] 281-- 282Possible values of slink:VkPerformanceOverrideInfoINTEL::pname:type, 283specifying performance override types, are: 284 285include::{generated}/api/enums/VkPerformanceOverrideTypeINTEL.txt[] 286 287 * ename:VK_PERFORMANCE_OVERRIDE_TYPE_NULL_HARDWARE_INTEL turns all 288 rendering operations into noop. 289 * ename:VK_PERFORMANCE_OVERRIDE_TYPE_FLUSH_GPU_CACHES_INTEL stalls the 290 stream of commands until all previously emitted commands have completed 291 and all caches been flushed and invalidated. 292-- 293 294[open,refpage='VkPerformanceConfigurationINTEL',desc='Device configuration for performance queries',type='handles'] 295-- 296Before submitting command buffers containing performance queries commands to 297a device queue, the application must acquire and set a performance query 298configuration. 299The configuration can be released once all command buffers containing 300performance query commands are not in a pending state. 301 302include::{generated}/api/handles/VkPerformanceConfigurationINTEL.txt[] 303-- 304 305[open,refpage='vkAcquirePerformanceConfigurationINTEL',desc='Acquire the performance query capability',type='protos'] 306-- 307To acquire a device performance configuration, call: 308 309include::{generated}/api/protos/vkAcquirePerformanceConfigurationINTEL.txt[] 310 311 * pname:device is the logical device that the performance query commands 312 will be submitted to. 313 * pname:pAcquireInfo is a pointer to a 314 slink:VkPerformanceConfigurationAcquireInfoINTEL structure, specifying 315 the performance configuration to acquire. 316 * pname:pConfiguration is a pointer to a 317 sname:VkPerformanceConfigurationINTEL handle in which the resulting 318 configuration object is returned. 319 320include::{generated}/validity/protos/vkAcquirePerformanceConfigurationINTEL.txt[] 321-- 322 323[open,refpage='VkPerformanceConfigurationAcquireInfoINTEL',desc='Acquire a configuration to capture performance data',type='structs'] 324-- 325The sname:VkPerformanceConfigurationAcquireInfoINTEL structure is defined 326as: 327 328include::{generated}/api/structs/VkPerformanceConfigurationAcquireInfoINTEL.txt[] 329 330 * pname:sType is the type of this structure. 331 * pname:pNext is `NULL` or a pointer to a structure extending this 332 structure. 333 * pname:type is one of the elink:VkPerformanceConfigurationTypeINTEL type 334 of performance configuration that will be acquired. 335 336include::{generated}/validity/structs/VkPerformanceConfigurationAcquireInfoINTEL.txt[] 337-- 338 339[open,refpage='VkPerformanceConfigurationTypeINTEL',desc='Type of performance configuration',type='enums'] 340-- 341Possible values of 342slink:VkPerformanceConfigurationAcquireInfoINTEL::pname:type, specifying 343performance configuration types, are: 344 345include::{generated}/api/enums/VkPerformanceConfigurationTypeINTEL.txt[] 346-- 347 348[open,refpage='vkQueueSetPerformanceConfigurationINTEL',desc='Set a performance query',type='protos'] 349-- 350To set a performance configuration, call: 351 352include::{generated}/api/protos/vkQueueSetPerformanceConfigurationINTEL.txt[] 353 354 * pname:queue is the queue on which the configuration will be used. 355 * pname:configuration is the configuration to use. 356 357include::{generated}/validity/protos/vkQueueSetPerformanceConfigurationINTEL.txt[] 358-- 359 360[open,refpage='vkReleasePerformanceConfigurationINTEL',desc='Release a configuration to capture performance data',type='protos'] 361-- 362To release a device performance configuration, call: 363 364include::{generated}/api/protos/vkReleasePerformanceConfigurationINTEL.txt[] 365 366 * pname:device is the device associated to the configuration object to 367 release. 368 * pname:configuration is the configuration object to release. 369 370.Valid Usage 371**** 372 * [[VUID-vkReleasePerformanceConfigurationINTEL-configuration-02737]] 373 pname:configuration must: not be released before all command buffers 374 submitted while the configuration was set are in 375 <<commandbuffers-lifecycle, pending state>> 376**** 377 378include::{generated}/validity/protos/vkReleasePerformanceConfigurationINTEL.txt[] 379-- 380endif::VK_INTEL_performance_query[] 381