1  include::meta/VK_INTEL_performance_query.txt[]
  2  
  3  *Last Modified Date*::
  4      2018-05-16
  5  *IP Status*::
  6      No known IP claims.
  7  *Contributors*::
  8    - Lionel Landwerlin, Intel
  9    - Piotr Maciejewski, Intel
 10  
 11  This extension allows an application to capture performance data to be
 12  interpreted by a external application or library.
 13  
 14  Such a library is available at : https://github.com/intel/metrics-discovery
 15  
 16  Performance analysis tools such as GPA
 17  (https://software.intel.com/en-us/gpa) make use of this extension and the
 18  metrics-discovery library to present the data in a human readable way.
 19  
 20  === New Object Types
 21  
 22    * slink:VkPerformanceConfigurationINTEL
 23  
 24  === New Enum Constants
 25  
 26    * Extending elink:VkStructureType:
 27    ** ename:VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL
 28    ** ename:VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL
 29    ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_MARKER_INFO_INTEL
 30    ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_STREAM_MARKER_INFO_INTEL
 31    ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_OVERRIDE_INFO_INTEL
 32    ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL
 33  
 34    * Extending elink:VkQueryType:
 35    ** ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL
 36  
 37  === New Enums
 38  
 39    * elink:VkPerformanceConfigurationTypeINTEL
 40    * elink:VkQueryPoolSamplingModeINTEL
 41    * elink:VkPerformanceOverrideTypeINTEL
 42    * elink:VkPerformanceParameterTypeINTEL
 43    * elink:VkPerformanceValueTypeINTEL
 44  
 45  === New Structures
 46  
 47    * slink:VkPerformanceValueINTEL
 48    * slink:VkInitializePerformanceApiInfoINTEL
 49    * slink:VkQueryPoolCreateInfoINTEL
 50    * slink:VkPerformanceMarkerInfoINTEL
 51    * slink:VkPerformanceStreamMarkerInfoINTEL
 52    * slink:VkPerformanceOverrideInfoINTEL
 53    * slink:VkPerformanceConfigurationAcquireInfoINTEL
 54  
 55  === New Functions
 56  
 57    * flink:vkInitializePerformanceApiINTEL
 58    * flink:vkUninitializePerformanceApiINTEL
 59    * flink:vkCmdSetPerformanceMarkerINTEL
 60    * flink:vkCmdSetPerformanceOverrideINTEL
 61    * flink:vkCmdSetPerformanceStreamMarkerINTEL
 62    * flink:vkAcquirePerformanceConfigurationINTEL
 63    * flink:vkReleasePerformanceConfigurationINTEL
 64    * flink:vkQueueSetPerformanceConfigurationINTEL
 65    * flink:vkGetPerformanceParameterINTEL
 66  
 67  === Issues
 68  
 69  None.
 70  
 71  === Example Code
 72  
 73  [source,c]
 74  ---------------------------------------------------
 75  
 76  // A previously created device
 77  VkDevice device;
 78  
 79  // A queue from from device
 80  VkQueue queue;
 81  
 82  VkInitializePerformanceApiInfoINTEL performanceApiInfoIntel = {
 83    VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL,
 84    NULL,
 85    NULL
 86  };
 87  
 88  vkInitializePerformanceApiINTEL(
 89    device,
 90    &performanceApiInfoIntel);
 91  
 92  VkQueryPoolCreateInfoINTEL queryPoolIntel = {
 93    VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL,
 94    NULL,
 95    VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL,
 96  };
 97  
 98  VkQueryPoolCreateInfo queryPoolCreateInfo = {
 99    VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
100    &queryPoolIntel,
101    0,
102    VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL,
103    1,
104    0
105  };
106  
107  VkQueryPool queryPool;
108  
109  VkResult result = vkCreateQueryPool(
110    device,
111    &queryPoolCreateInfo,
112    NULL,
113    &queryPool);
114  
115  assert(VK_SUCCESS == result);
116  
117  // A command buffer we want to record counters on
118  VkCommandBuffer commandBuffer;
119  
120  VkCommandBufferBeginInfo commandBufferBeginInfo = {
121    VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
122    NULL,
123    VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
124    NULL
125  };
126  
127  result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);
128  
129  assert(VK_SUCCESS == result);
130  
131  vkCmdResetQueryPool(
132    commandBuffer,
133    queryPool,
134    0,
135    1);
136  
137  vkCmdBeginQuery(
138    commandBuffer,
139    queryPool,
140    0,
141    0);
142  
143  // Perform the commands you want to get performance information on
144  // ...
145  
146  // Perform a barrier to ensure all previous commands were complete before
147  // ending the query
148  vkCmdPipelineBarrier(commandBuffer,
149    VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
150    VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
151    0,
152    0,
153    NULL,
154    0,
155    NULL,
156    0,
157    NULL);
158  
159  vkCmdEndQuery(
160    commandBuffer,
161    queryPool,
162    0);
163  
164  result = vkEndCommandBuffer(commandBuffer);
165  
166  assert(VK_SUCCESS == result);
167  
168  VkPerformanceConfigurationAcquireInfoINTEL performanceConfigurationAcquireInfo = {
169    VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL,
170    NULL,
171    VK_PERFORMANCE_CONFIGURATION_TYPE_COMMAND_QUEUE_METRICS_DISCOVERY_ACTIVATED_INTEL
172  };
173  
174  VkPerformanceConfigurationINTEL performanceConfigurationIntel;
175  
176  result = vkAcquirePerformanceConfigurationINTEL(
177    device,
178    &performanceConfigurationAcquireInfo,
179    &performanceConfigurationIntel);
180  
181  vkQueueSetPerformanceConfigurationINTEL(queue, performanceConfigurationIntel);
182  
183  assert(VK_SUCCESS == result);
184  
185  // Submit the command buffer and wait for its completion
186  // ...
187  
188  result = vkReleasePerformanceConfigurationINTEL(
189    device,
190    performanceConfigurationIntel);
191  
192  assert(VK_SUCCESS == result);
193  
194  // Get the report size from metrics-discovery's QueryReportSize
195  
196  result = vkGetQueryPoolResults(
197    device,
198    queryPool,
199    0, 1, QueryReportSize,
200    data, QueryReportSize, 0);
201  
202  assert(VK_SUCCESS == result);
203  
204  // The data can then be passed back to metrics-discovery from which
205  // human readable values can be queried.
206  
207  ---------------------------------------------------
208  
209  === Version History
210  
211   * Revision 1, 2018-05-16 (Lionel Landwerlin)
212     - Initial revision