diff --git a/scripts/tools/EXT_Exp_MetricTracer.rst b/scripts/tools/EXT_Exp_MetricTracer.rst new file mode 100644 index 000000000..40323440a --- /dev/null +++ b/scripts/tools/EXT_Exp_MetricTracer.rst @@ -0,0 +1,164 @@ +<% +import re +from templates import helper as th +%><% + OneApi=tags['$OneApi'] + x=tags['$x'] + X=x.upper() + t=tags['$t'] + T=t.upper() +%> +:orphan: + +.. _ZET_experimental_metric_tracer: + +========================================== +Metric Tracer Experimental Extension +========================================== + +API +---- +* Enumerations + + * ${t}_metric_group_sampling_type_flags_t + + New value ${T}_METRIC_GROUP_SAMPLING_TYPE_FLAG_EXP_TRACER_BASED + + * ${t}_metric_type_t + + New Values + ${T}_METRIC_TYPE_EXP_EVENT_NO_VALUE + Metric type: have only timestamp and value has no meaning. + ${T}_METRIC_TYPE_EXP_EVENT_START + Metric type: the first event of a start/stop event pair. + ${T}_METRIC_TYPE_EXP_EVENT_END + Metric type: the second event of a start/stop event pair. + ${T}_METRIC_TYPE_EXP_EVENT_MONOTONIC_WRAPS_VALUE + Metric type: value of the event is a monotonic increasing value that can wrap around. + + +* Structures + + * ${t}_metric_tracer_exp_desc_t + * ${t}_metric_entry_exp_t + +* Functions + + * ${t}MetricTracerCreateExp + * ${t}MetricTracerDestroyExp + * ${t}MetricTracerEnableExp + * ${t}MetricTracerDisableExp + * ${t}MetricTracerReadDataExp + * ${t}MetricDecoderCreateExp + * ${t}MetricDecoderDestroyExp + * ${t}MetricDecoderGetDecodableMetricsExp + * ${t}MetricTracerDecodeExp + +Metric MetricTracer +~~~~~~~~~~~~~~~~~~~ + +Support collection of metrics from events produced in an asynchronous mode. Application can use ${t}MetricGroupGet to enumerate the list of metric groups +and ${t}MetricGroupGetProperties to get metric group sampling type and search for ${T}_METRIC_GROUP_SAMPLING_TYPE_FLAG_EXP_TRACER_BASED + +Sample Code +------------ + +The following pseudo-code demonstrates how to enumerate Tracer based metric groups and collect data. + +.. parsed-literal:: + + + ${t}_metric_group_handle_t hMetricGroup = nullptr; + ${x}_event_handle_t hNotificationEvent = nullptr; + ${x}_event_pool_handle_t hEventPool = nullptr; + ${x}_event_pool_desc_t eventPoolDesc = {${X}_STRUCTURE_TYPE_EVENT_POOL_DESC, nullptr, 0, 1}; + ${x}_event_desc_t eventDesc = {${X}_STRUCTURE_TYPE_EVENT_DESC}; + ${t}_metric_tracer_exp_handle_t hMetricTracer = nullptr; + ${t}_metric_tracer_exp_desc_t tracerDescriptor = { ${T}_STRUCTURE_TYPE_METRIC_TRACER_EXP_DESC, nullptr, 1024}; + ${t}_metric_decoder_exp_handle_t hMetricDecoder = nullptr; + + // Find the first metric group suitable for Tracer Based collection + FindMetricGroup(hDevice, ${T}_METRIC_GROUP_SAMPLING_TYPE_FLAG_EXP_TRACER_BASED, &hMetricGroup ); + + // Configure the HW + ${t}ContextActivateMetricGroups( hContext, hDevice, /\* count= \*/ 1, &hMetricGroup ); + + // Create notification event + ${x}EventPoolCreate( hContext, &eventPoolDesc, 1, &hDevice, &hEventPool ); + eventDesc.index = 0; + eventDesc.signal = ${X}_EVENT_SCOPE_FLAG_HOST; + eventDesc.wait = ${X}_EVENT_SCOPE_FLAG_HOST; + ${x}EventCreate( hEventPool, &eventDesc, &hNotificationEvent ); + + // Create tracer + ${t}MetricTracerCreateExp(hContext, hDevice, 1, hMetricGroup , &tracerDescriptor, hNotificationEvent, &hMetricTracer); + + // create decoder + ${t}MetricDecoderCreateExp( hMetricTracer, &hMetricDecoder); + + // Get decodable metrics + uint32_t numDecodableMetrics = 0; + ${t}MetricDecoderGetDecodableMetricsExp(hMetricDecoder, &numDecodableMetrics, nullptr); + std::vectordecodableMetrics(numDecodableMetrics); + ${t}MetricDecoderGetDecodableMetricsExp(hMetricDecoder, &numDecodableMetrics, decodableMetrics.data()); + + // Run your workload + Workload(hDevice); + + // Wait for data, optional in this example + ${x}EventHostSynchronize( hNotificationEvent, 1000 /\*timeout\*/ ); + // reset the event if it fired + + // Read raw data + size_t rawDataSize = 0; + ${t}MetricTracerReadDataExp(hMetricTracer, &rawDataSize, nullptr); + uint8_t* rawData = malloc(rawDataSize); + ${t}MetricTracerReadDataExp(hMetricTracer, &rawDataSize, rawData.data()); + + // decode + uint32_t numEntries =0; + ${t}MetricTracerDecodeExp(hMetricDecoder, &rawDataSize, rawData.data(), numDecodableMetrics, decodableMetrics.data(), &numEntries, nullptr); + std::vector decodedEntries(numEntries) + ${t}MetricTracerDecodeExp(hMetricDecoder, &rawDataSize, rawData.data(), numDecodableMetrics, decodableMetrics.data(), &numEntries, decodedEntries.data()); + + for (uint32_t index = 0; index < numEntries; index++) { + ${t}_metric_entry_exp_t metricEntry = decodedEntries[index]; + ${t}_metric_properties_t metricProperties = {}; + ${t}MetricGetProperties(decodableMetrics[metricEntry.metricIndex], &metricProperties); + printf ("Component: %s .Decodable metric name: %s ", metricProperties.component, metricProperties.name); + switch (metricProperties.resultType) { + case ${T}_VALUE_TYPE_UINT32: + case ${T}_VALUE_TYPE_UINT8: + case ${T}_VALUE_TYPE_UINT16: + printf "\t value: %lu \n" << metricEntry.value.ui32; + break; + case ${T}_VALUE_TYPE_UINT64: + printf "\t value: %llu \n" << metricEntry.value.ui64; + break; + case ${T}_VALUE_TYPE_FLOAT32: + printf "\t value: %f \n" << metricEntry.value.fp32; + break; + case ${T}_VALUE_TYPE_FLOAT64: + printf "\t value: %f \n" << metricEntry.value.fp64; + break; + case ${T}_VALUE_TYPE_BOOL8: + if( metricEntry.value.b8 ){ + printf(" Value: true\n" ); + else + printf(" Value: false\n" ); + } + break; + default: + break; + } + } + + // Close metric tracer + ${t}MetricTracerDisableExp(hMetricTracer, true); + ${t}MetricDecoderDestroyExp(hMetricDecoder); + ${t}MetricTracerDestroyExp(hMetricTracer); + ${x}EventDestroy( hNotificationEvent ); + ${x}EventPoolDestroy( hEventPool ); + + // Clean device configuration and free memory + ${t}ContextActivateMetricGroups( hContext, hDevice, 0, nullptr ); \ No newline at end of file diff --git a/scripts/tools/common.yml b/scripts/tools/common.yml index 556251e4f..ce9c39abe 100644 --- a/scripts/tools/common.yml +++ b/scripts/tools/common.yml @@ -137,6 +137,10 @@ etors: desc: $t_metric_programmable_param_value_info_exp_t version: "1.9" value: "0x00010005" + - name: METRIC_TRACER_EXP_DESC + desc: $t_metric_tracer_exp_desc_t + version: "1.10" + value: "0x00010006" --- #-------------------------------------------------------------------------- type: struct desc: "Base for all properties types" diff --git a/scripts/tools/metric.yml b/scripts/tools/metric.yml index e958fe333..c34b44cce 100644 --- a/scripts/tools/metric.yml +++ b/scripts/tools/metric.yml @@ -51,6 +51,9 @@ etors: desc: "Event based sampling" - name: TIME_BASED desc: "Time based sampling" + - name: EXP_TRACER_BASED + desc: "Experimental Tracer based sampling" + version: "1.10" --- #-------------------------------------------------------------------------- type: struct desc: "Metric group properties queried using $tMetricGroupGetProperties" @@ -115,10 +118,21 @@ etors: desc: "1.6": "Metric type: instruction pointer" "1.7": "Metric type: instruction pointer. Deprecated, use $T_METRIC_TYPE_IP." - value: "0x7ffffffe" - name: IP desc: "Metric type: instruction pointer" version: "1.7" + - name: EXP_EVENT_NO_VALUE + desc: "Metric type: event with only timestamp and value has no meaning" + version: "1.10" + - name: EXP_EVENT_START + desc: "Metric type: the first event of a start/end event pair" + version: "1.10" + - name: EXP_EVENT_END + desc: "Metric type: the second event of a start/end event pair" + version: "1.10" + - name: EXP_EVENT_MONOTONIC_WRAPS_VALUE + desc: "Metric type: value of the event is a monotonically increasing value that can wrap around" + version: "1.10" value: "0x7ffffffe" --- #-------------------------------------------------------------------------- type: enum diff --git a/scripts/tools/metricTracer.yml b/scripts/tools/metricTracer.yml new file mode 100644 index 000000000..8bf1ce707 --- /dev/null +++ b/scripts/tools/metricTracer.yml @@ -0,0 +1,255 @@ +# +# Copyright (C) 2023 Intel Corporation +# +# SPDX-License-Identifier: MIT +# +# See YaML.md for syntax definition +# +--- #-------------------------------------------------------------------------- +type: header +desc: "Intel $OneApi Level-Zero Tool Experimental Extension for Metrics Tracer" +version: "1.10" +--- #-------------------------------------------------------------------------- +type: macro +desc: "Metric Tracer Experimental Extension Name" +version: "1.10" +name: $T_METRICS_TRACER_EXP_NAME +value: '"$XT_experimental_metric_tracer"' +--- #-------------------------------------------------------------------------- +type: handle +desc: "Handle of metric tracer's object" +version: "1.10" +class: $tMetricTracer +name: "$t_metric_tracer_exp_handle_t" +--- #-------------------------------------------------------------------------- +type: handle +desc: "Handle of metric decoder's object" +version: "1.10" +class: $tMetricDecoder +name: "$t_metric_decoder_exp_handle_t" +--- #-------------------------------------------------------------------------- +type: struct +desc: "Metric tracer descriptor" +version: "1.10" +class: $tMetricTracer +name: $t_metric_tracer_exp_desc_t +base: $t_base_desc_t +members: + - type: uint32_t + name: "notifyEveryNBytes" + desc: > + [in,out] number of collected bytes after which notification event will be signaled. + If the requested value is not supported exactly, then the driver may use a value that + is the closest supported approximation and shall update this member during + $tMetricTracerCreateExp. +--- #-------------------------------------------------------------------------- +type: struct +desc: "Decoded metric entry" +version: "1.10" +name: $t_metric_entry_exp_t +members: + - type: $t_value_t + name: "value" + desc: "[out] value of the decodable metric entry or event. Number is meaningful based on the metric type." + - type: uint64_t + name: "timeStamp" + desc: "[out] timestamp at which the event happened." + - type: uint32_t + name: "metricIndex" + desc: "[out] index to the decodable metric handle in the input array (phMetric) in $tMetricTracerDecode()" +--- #-------------------------------------------------------------------------- +type: function +desc: "Create a metric tracer for a device." +version: "1.10" +class: $tMetricTracer +name: CreateExp +decl: static +details: + - "The notification event must have been created from an event pool that was created using $X_EVENT_POOL_FLAG_HOST_VISIBLE flag." + - "The duration of the signal event created from an event pool that was created using $X_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality." + - "The application must **not** call this function from simultaneous threads with the same device handle." + - "The metric tracer is created in disabled state" + - "Metric groups must be of the sampling type ZET_METRIC_SAMPLING_TYPE_EXP_FLAG_TRACER_BASED" + - "All metric groups must be first activated" +params: + - type: $t_context_handle_t + name: hContext + desc: "[in] handle of the context object" + - type: "$t_device_handle_t" + name: hDevice + desc: "[in] handle of the device" + - type: uint32_t + name: "metricGroupCount" + desc: "[in] metric group count" + - type: "$t_metric_group_handle_t" + name: "hMetricGroups" + desc: "[in][range(0, metricGroupCount )] handles of the metric groups to trace" + - type: "$t_metric_tracer_exp_desc_t*" + name: desc + desc: "[in,out] metric tracer descriptor" + - type: "$x_event_handle_t" + name: hNotificationEvent + desc: "[in][optional] event used for report availability notification. Note: If buffer is not drained when the event it flagged, there is a risk of HW event buffer being overrun" + - type: "$t_metric_tracer_exp_handle_t*" + name: phMetricTracer + desc: "[out] handle of the metric tracer" +returns: + - $X_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT +--- #-------------------------------------------------------------------------- +type: function +desc: "Destroy a metric tracer." +version: "1.10" +class: $tMetricTracer +name: DestroyExp +details: + - "The application must **not** call this function from simultaneous threads with the same metric tracer handle." +params: + - type: "$t_metric_tracer_exp_handle_t" + name: hMetricTracer + desc: "[in] handle of the metric tracer" +--- #-------------------------------------------------------------------------- +type: function +desc: "Lightweight call that starts the event collections" +version: "1.10" +class: $tMetricTracer +name: EnableExp +details: + - "The application must **not** call this function from simultaneous threads with the same metric tracer handle." +params: + - type: "$t_metric_tracer_exp_handle_t*" + name: phMetricTracer + desc: "[in] handle of the metric tracer" + - type: $x_bool_t + name: synchronous + desc: "[in] request synchronous behavior. Confirmation of successful asynchronous operation is done by calling $tMetricTracerReadDataExp()" +--- #-------------------------------------------------------------------------- +type: function +desc: "Lightweight call that stops the event collections" +version: "1.10" +class: $tMetricTracer +name: DisableExp +details: + - "The application must **not** call this function from simultaneous threads with the same metric tracer handle." +params: + - type: "$t_metric_tracer_exp_handle_t*" + name: phMetricTracer + desc: "[in] handle of the metric tracer" + - type: $x_bool_t + name: synchronous + desc: "[in] request synchronous behavior. Confirmation of successful asynchronous operation is done by calling $tMetricTracerReadDataExp()" +--- #-------------------------------------------------------------------------- +type: function +desc: "Read data from the metric tracer" +version: "1.10" +class: $tMetricTracer +name: ReadDataExp +details: + - "The application must **not** call this function from simultaneous threads with the same metric tracer handle." + - "Data can be retrieved after tracer is disabled. When buffers are drained $X_RESULT_NOT_READY will be returned" +params: + - type: "$t_metric_tracer_exp_handle_t*" + name: phMetricTracer + desc: "[in] handle of the metric tracer" + - type: size_t* + name: pRawDataSize + desc: | + [in,out] pointer to size in bytes of raw data requested to read. + if size is zero, then the driver will update the value with the total size in bytes needed for all data available. + if size is non-zero, then driver will only retrieve that amount of data. + if size is larger than size needed for all data, then driver will update the value with the actual size needed. + - type: uint8_t* + name: pRawData + desc: "[in,out][optional][range(0, *pRawDataSize)] buffer containing tracer data in raw format" +returns: + - $X_RESULT_WARNING_DROPPED_DATA: + - "Metric tracer data may have been dropped." + - $X_RESULT_NOT_READY: + - "Metric tracer is disabled and no data is available to read." +--- #-------------------------------------------------------------------------- +type: function +desc: "Create a metric decoder for a given metric tracer." +version: "1.10" +class: $tMetricDecoder +name: CreateExp +params: + - type: "$t_metric_tracer_exp_handle_t" + name: hMetricTracer + desc: "[in] handle of the metric tracer" + - type: $t_metric_decoder_exp_handle_t* + name: phMetricDecoder + desc: "[out] handle of the metric decoder object" +--- #-------------------------------------------------------------------------- +type: function +desc: "Destroy a metric decoder." +version: "1.10" +class: $tMetricDecoder +name: DestroyExp +params: + - type: $t_metric_decoder_exp_handle_t + name: phMetricDecoder + desc: "[in] handle of the metric decoder object" +--- #-------------------------------------------------------------------------- +type: function +desc: | + Return the list of the decodable metrics that can be collected in the tracer for the which the metric decoder + handle was provided. The decodable metrics handles returned by this API are only valid to decode metrics raw data + with $tMetricTracerDecodeExp(). Decodable metric handles are not valid to compare with metrics handles included in + metric groups." +version: "1.10" +class: $tMetricDecoder +name: GetDecodableMetricsExp +params: + - type: $t_metric_decoder_exp_handle_t + name: phMetricDecoder + desc: "[in] handle of the metric decoder object" + - type: uint32_t* + name: pCount + desc: | + [in,out] pointer to number of decodable metric in the hMetricDecoder handle. If count is zero, then the driver shall + update the value with the total number of decodable metrics available in the decoder. if count is greater than zero + but less than the total number of decodable metrics available in the decoder, then only that number will be returned. + if count is greater than the number of decodable metrics available in the decoder, then the driver shall update the + value with the actual number of decodable metrics available. + - type: $t_metric_handle_t* + name: phMetrics + desc: "[in,out] [range(0, pCount)] array of handles of decodable metrics in the hMetricDecoder handle provided." +--- #-------------------------------------------------------------------------- +type: function +desc: "Decode raw events collected from a tracer." +version: "1.10" +class: $tMetricTracer +name: DecodeExp +params: + - type: $t_metric_decoder_exp_handle_t + name: phMetricDecoder + desc: "[in] handle of the metric decoder object" + - type: size_t* + name: pRawDataSize + desc: | + [in,out] size in bytes of raw data buffer. If pMetricEntriesCount is greater than zero but less than total number of + decodable metrics available in the raw data buffer, then driver shall update this value with actual number of raw + data bytes processed. + - type: uint8_t* + name: pRawData + desc: "[in,out][optional][range(0, *pRawDataSize)] buffer containing tracer data in raw format" + - type: uint32_t + name: metricsCount + desc: | + [in] number of decodable metrics in the tracer for which the hMetricDecoder handle was provided. See + $tMetricDecoderGetDecodableMetricsExp(). If metricCount is greater than zero but less than the number decodable + metrics available in the raw data buffer, then driver shall only decode those. + - type: $t_metric_handle_t* + name: phMetrics + desc: | + [in] [range(0, metricsCount)] array of handles of decodable metrics in the decoder for which the hMetricDecoder handle was + provided. Metrics handles are expected to be for decodable metrics, see $tMetricDecoderGetDecodableMetrics() + - type: uint32_t* + name: pMetricEntriesCount + desc: | + [in,out] pointer to number of decodable metric entries to be decoded. If count is zero, then the driver shall update the value + with the total number of decodable metric entries to be decoded. If count is greater than zero but less than the total number + available in the raw data, then only that number of results will be decoded. if count is greater than the number available in + the raw data buffer, then the driver shall update the value with the actual number of decodable metric entries to be decoded. + - type: $t_metric_entry_exp_t* + name: pMetricEntries + desc: "[in,out][optional][range(0, *pMetricEntriesCount)] buffer containing decoded metric entries" \ No newline at end of file