From 5c0ed747b4856d49d343ddff34d1911d621a29ca Mon Sep 17 00:00:00 2001 From: Matias Cabral Date: Fri, 15 Mar 2024 13:27:53 -0700 Subject: [PATCH 1/6] Fix scripts to support two digits minor version (#292) * Fix scripts to support two digits minor version * Extend `all_versions` array to include 1.8-1.10. * Add `ignore_git_revision` flag to run script. Signed-off-by: Matias Cabral Co-authored-by: Will Damon --- scripts/parse_specs.py | 108 +++++++++++++++++++++++++++-------------- scripts/run.py | 7 ++- 2 files changed, 77 insertions(+), 38 deletions(-) diff --git a/scripts/parse_specs.py b/scripts/parse_specs.py index f2d4c7c56..ccc42977c 100644 --- a/scripts/parse_specs.py +++ b/scripts/parse_specs.py @@ -14,7 +14,7 @@ from templates.helper import param_traits, type_traits, value_traits default_version = "1.0" -all_versions = ["1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "2.0"] +all_versions = ["1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "1.8", "1.9", "1.10", "2.0"] """ preprocess object @@ -99,15 +99,7 @@ def __validate_version(d, prefix="", base_version=default_version): if not isinstance(d['version'], str): raise Exception(prefix+"'version' must be a string: '%s'"%type(d['version'])) - try: - version = str(float(d['version'])) - except: - version = None - - if version != d['version']: - raise Exception(prefix+"'version' invalid value: '%s'"%d['version']) - - return float(d.get('version', base_version)) + return d.get('version', base_version) def __validate_tag(d, key, tags, case): for x in tags: @@ -121,14 +113,6 @@ def __validate_desc(desc): if not isinstance(k, str): raise Exception(prefix+"'version' must be a string: '%s'"%type(k)) - try: - version = str(float(k)) - except: - version = None - - if version != k: - raise Exception(prefix+"'version' invalid value: '%s'"%k) - for x in ['[in]', '[out]', '[in,out]']: if v.startswith(x): return x @@ -197,7 +181,7 @@ def __validate_etors(d, tags): value = -1 d_ver = d.get('version', default_version) - max_ver = float(d_ver) + max_ver = d_ver for i, item in enumerate(d['etors']): prefix="'etors'[%s] "%i if not isinstance(item, dict): @@ -220,7 +204,7 @@ def __validate_etors(d, tags): ver = __validate_version(item, prefix=prefix, base_version=d_ver) if item.get('value'): max_ver = ver - if ver < max_ver: + if _version_compare_less(ver, max_ver): raise Exception(prefix+"'version' must be increasing: %s"%item['version']) max_ver = ver @@ -250,7 +234,7 @@ def __validate_members(d, tags): raise Exception("'members' must be a sequence: '%s'"%type(d['members'])) d_ver = d.get('version', default_version) - max_ver = float(d_ver) + max_ver = d_ver for i, item in enumerate(d['members']): prefix="'members'[%s] "%i if not isinstance(item, dict): @@ -270,7 +254,7 @@ def __validate_members(d, tags): raise Exception(prefix+"'type' must not be '*_flag_t': %s"%item['type']) ver = __validate_version(item, prefix=prefix, base_version=d_ver) - if ver < max_ver: + if _version_compare_less(ver, max_ver): raise Exception(prefix+"'version' must be increasing: %s"%item['version']) max_ver = ver @@ -282,7 +266,7 @@ def __validate_params(d, tags): raise Exception("'params' must be a sequence: '%s'"%type(d['params'])) d_ver = d.get('version', default_version) - max_ver = float(d_ver) + max_ver = d_ver min = {'[in]': None, '[out]': None, '[in,out]': None} for i, item in enumerate(d['params']): prefix="'params'[%s] "%i @@ -309,7 +293,7 @@ def __validate_params(d, tags): raise Exception(prefix+"'type' must not be '*_flag_t': %s"%item['type']) ver = __validate_version(item, prefix=prefix, base_version=d_ver) - if ver < max_ver: + if _version_compare_greater(ver, max_ver): raise Exception(prefix+"'version' must be increasing: %s"%item['version']) max_ver = ver @@ -414,15 +398,65 @@ def __validate_params(d, tags): """ filters object by version """ +def _version_compare_greater(a, b): + a_major = int(a.split('.')[0]) + a_minor = int(a.split('.')[1]) + + b_major = int(b.split('.')[0]) + b_minor = int(b.split('.')[1]) + + return ((a_major > b_major) or (a_minor > b_minor)) + +def _version_compare_less(a, b): + a_major = int(a.split('.')[0]) + a_minor = int(a.split('.')[1]) + + b_major = int(b.split('.')[0]) + b_minor = int(b.split('.')[1]) + + if a_major > b_major: + return False + + if a_major < b_major: + return True + + # a_major == b_major + if a_minor < b_minor: + return True + + return False + +def _version_compare_lequal(a, b): + # print("lequal: %s, %s" % (a, b)) + + a_major = int(a.split('.')[0]) + a_minor = int(a.split('.')[1]) + + b_major = int(b.split('.')[0]) + b_minor = int(b.split('.')[1]) + + if a_major > b_major: + return False + + if a_major < b_major: + return True + + # a_major == b_major + if a_minor <= b_minor: + return True + + return False + def _filter_version(d, max_ver): - ver = float(d.get('version', default_version)) - if ver > max_ver: + ver = d.get('version', default_version) + + if _version_compare_greater(ver, max_ver): return None def __filter_desc(d): if 'desc' in d and isinstance(d['desc'], dict): for k, v in d['desc'].items(): - if float(k) <= max_ver: + if _version_compare_lequal(k, max_ver): desc = v d['desc'] = desc return d @@ -435,7 +469,7 @@ def __filter_detail(det): version = float(k) except: return det - if version <= max_ver: + if _version_compare_lequal(k, max_ver): detail = v return detail return det @@ -452,8 +486,8 @@ def __filter_detail(det): type = d['type'] if 'enum' == type: for e in d['etors']: - ver = float(e.get('version', default_version)) - if ver <= max_ver: + ver = e.get('version', default_version) + if _version_compare_lequal(ver, max_ver): flt.append(__filter_desc(e)) if d['name'].endswith('version_t'): flt.append({ @@ -465,15 +499,15 @@ def __filter_detail(det): elif 'function' == type: for p in d['params']: - ver = float(p.get('version', default_version)) - if ver <= max_ver: + ver = p.get('version', default_version) + if _version_compare_lequal(ver, max_ver): flt.append(__filter_desc(p)) d['params'] = flt elif 'struct' == type or 'union' == type or 'class' == type: for m in d.get('members',[]): - ver = float(m.get('version', default_version)) - if ver <= max_ver: + ver = m.get('version', default_version) + if _version_compare_lequal(ver, max_ver): flt.append(__filter_desc(m)) d['members'] = flt @@ -487,10 +521,10 @@ def _make_versions(d, max_ver): type = d['type'] if 'function' == type or 'struct' == type: for ver in all_versions: - if float(ver) > max_ver: + if _version_compare_greater(ver, max_ver): break - dv = _filter_version(copy.deepcopy(d), float(ver)) + dv = _filter_version(copy.deepcopy(d), ver) if not dv: continue @@ -794,7 +828,7 @@ def parse(section, version, tags, meta, ref): if not _validate_doc(f, d, tags, line_nums[i]): continue - d = _filter_version(d, float(version)) + d = _filter_version(d, version) if not d: continue diff --git a/scripts/run.py b/scripts/run.py index f7a12626b..fc20cfd06 100644 --- a/scripts/run.py +++ b/scripts/run.py @@ -96,10 +96,15 @@ def main(): add_argument(parser, "html", "generation of HTML files.", True) add_argument(parser, "pdf", "generation of PDF file.") add_argument(parser, "rst", "generation of reStructuredText files.", True) + add_argument(parser, "ignore_git_revision", "use command-line verison (ver) as revision instead of git tag.", False) parser.add_argument("--update_spec", type=str, help="root of integrated spec directory to update") parser.add_argument("--ver", type=str, default="1.4", required=False, help="specification version to generate.") + args = vars(parser.parse_args()) - args['rev'] = revision() + if (args['ignore_git_revision']): + args['rev'] = args['ver'] + else: + args['rev'] = revision() print("--------------------------------------------") print("Building Level Zero Spec Version: %s" % args['rev']) From dd4b58b42bb6a2684741e94418cfe52db622ab50 Mon Sep 17 00:00:00 2001 From: Matias Cabral Date: Wed, 13 Mar 2024 08:27:50 -0700 Subject: [PATCH 2/6] Add experimental extension for metric tracer Signed-off-by: Matias Cabral --- scripts/tools/EXT_Exp_MetricTracer.rst | 164 ++++++++++++++++ scripts/tools/common.yml | 4 + scripts/tools/metric.yml | 16 +- scripts/tools/metricTracer.yml | 255 +++++++++++++++++++++++++ 4 files changed, 438 insertions(+), 1 deletion(-) create mode 100644 scripts/tools/EXT_Exp_MetricTracer.rst create mode 100644 scripts/tools/metricTracer.yml 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 From 7d8f334843195bea3f49474c481995f8b60b886e Mon Sep 17 00:00:00 2001 From: Matias Cabral Date: Fri, 15 Mar 2024 01:54:04 -0700 Subject: [PATCH 3/6] Add experimental extension for metric tracer Signed-off-by: Matias Cabral --- scripts/tools/EXT_Exp_MetricTracer.rst | 20 ++++++++-------- scripts/tools/metricTracer.yml | 32 +++++++++++++++----------- 2 files changed, 29 insertions(+), 23 deletions(-) diff --git a/scripts/tools/EXT_Exp_MetricTracer.rst b/scripts/tools/EXT_Exp_MetricTracer.rst index 40323440a..98800f756 100644 --- a/scripts/tools/EXT_Exp_MetricTracer.rst +++ b/scripts/tools/EXT_Exp_MetricTracer.rst @@ -54,7 +54,7 @@ API * ${t}MetricDecoderGetDecodableMetricsExp * ${t}MetricTracerDecodeExp -Metric MetricTracer +Metric Tracer ~~~~~~~~~~~~~~~~~~~ Support collection of metrics from events produced in an asynchronous mode. Application can use ${t}MetricGroupGet to enumerate the list of metric groups @@ -91,7 +91,7 @@ The following pseudo-code demonstrates how to enumerate Tracer based metric grou ${x}EventCreate( hEventPool, &eventDesc, &hNotificationEvent ); // Create tracer - ${t}MetricTracerCreateExp(hContext, hDevice, 1, hMetricGroup , &tracerDescriptor, hNotificationEvent, &hMetricTracer); + ${t}MetricTracerCreateExp(hContext, hDevice, 1, &hMetricGroup , &tracerDescriptor, hNotificationEvent, &hMetricTracer); // create decoder ${t}MetricDecoderCreateExp( hMetricTracer, &hMetricDecoder); @@ -112,7 +112,7 @@ The following pseudo-code demonstrates how to enumerate Tracer based metric grou // Read raw data size_t rawDataSize = 0; ${t}MetricTracerReadDataExp(hMetricTracer, &rawDataSize, nullptr); - uint8_t* rawData = malloc(rawDataSize); + std::vectorrawData(rawDataSize); ${t}MetricTracerReadDataExp(hMetricTracer, &rawDataSize, rawData.data()); // decode @@ -125,27 +125,27 @@ The following pseudo-code demonstrates how to enumerate Tracer based metric grou ${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); + std::cout << "Component: " << metricProperties.component ". Decodable metric name: " << 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; + std::cout << ".\t value: " << metricEntry.value.ui32 << std::endl; break; case ${T}_VALUE_TYPE_UINT64: - printf "\t value: %llu \n" << metricEntry.value.ui64; + std::cout << ".\t value: " << metricEntry.value.ui64 << std::endl; break; case ${T}_VALUE_TYPE_FLOAT32: - printf "\t value: %f \n" << metricEntry.value.fp32; + std::cout << ".\t value: " << metricEntry.value.fp32 << std::endl; break; case ${T}_VALUE_TYPE_FLOAT64: - printf "\t value: %f \n" << metricEntry.value.fp64; + std::cout << ".\t value: " << metricEntry.value.fp64 << std::endl; break; case ${T}_VALUE_TYPE_BOOL8: if( metricEntry.value.b8 ){ - printf(" Value: true\n" ); + std::cout << ".\t value: true" << std::endl; else - printf(" Value: false\n" ); + std::cout << ".\t value: false" << std::endl; } break; default: diff --git a/scripts/tools/metricTracer.yml b/scripts/tools/metricTracer.yml index 8bf1ce707..e79c7cd00 100644 --- a/scripts/tools/metricTracer.yml +++ b/scripts/tools/metricTracer.yml @@ -1,5 +1,5 @@ # -# Copyright (C) 2023 Intel Corporation +# Copyright (C) 2024 Intel Corporation # # SPDX-License-Identifier: MIT # @@ -69,7 +69,7 @@ details: - "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" + - "Metric groups must support sampling type ZET_METRIC_SAMPLING_TYPE_EXP_FLAG_TRACER_BASED" - "All metric groups must be first activated" params: - type: $t_context_handle_t @@ -81,8 +81,8 @@ params: - type: uint32_t name: "metricGroupCount" desc: "[in] metric group count" - - type: "$t_metric_group_handle_t" - name: "hMetricGroups" + - type: "$t_metric_group_handle_t*" + name: "phMetricGroups" desc: "[in][range(0, metricGroupCount )] handles of the metric groups to trace" - type: "$t_metric_tracer_exp_desc_t*" name: desc @@ -116,12 +116,15 @@ 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 + - type: "$t_metric_tracer_exp_handle_t" + name: hMetricTracer 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()" + desc: | + [in] request synchronous behavior. Confirmation of successful asynchronous operation is done by calling $tMetricTracerReadDataExp() + and checking the return status: $X_RESULT_NOT_READY will be returned when the tracer is inactive. $X_RESULT_SUCCESS will be returned + when the tracer is active. --- #-------------------------------------------------------------------------- type: function desc: "Lightweight call that stops the event collections" @@ -131,12 +134,15 @@ 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 + - type: "$t_metric_tracer_exp_handle_t" + name: hMetricTracer 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()" + desc: | + [in] request synchronous behavior. Confirmation of successful asynchronous operation is done by calling $tMetricTracerReadDataExp() + and checking the return status: $X_RESULT_SUCCESS will be returned when the tracer is active or when it is inactive but still has data. + $X_RESULT_NOT_READY will be returned when the tracer is inactive and has no more data to be retrieved. --- #-------------------------------------------------------------------------- type: function desc: "Read data from the metric tracer" @@ -147,8 +153,8 @@ 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 + - type: "$t_metric_tracer_exp_handle_t" + name: hMetricTracer desc: "[in] handle of the metric tracer" - type: size_t* name: pRawDataSize @@ -200,7 +206,7 @@ class: $tMetricDecoder name: GetDecodableMetricsExp params: - type: $t_metric_decoder_exp_handle_t - name: phMetricDecoder + name: hMetricDecoder desc: "[in] handle of the metric decoder object" - type: uint32_t* name: pCount From 1be524bdaffbc590909bb879c5a835c32ddff0e8 Mon Sep 17 00:00:00 2001 From: Matias Cabral Date: Fri, 15 Mar 2024 01:56:27 -0700 Subject: [PATCH 4/6] Add experimental extension for metric trace Signed-off-by: Matias Cabral --- scripts/tools/EXT_Exp_MetricTracer.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scripts/tools/EXT_Exp_MetricTracer.rst b/scripts/tools/EXT_Exp_MetricTracer.rst index 98800f756..36fc8b37b 100644 --- a/scripts/tools/EXT_Exp_MetricTracer.rst +++ b/scripts/tools/EXT_Exp_MetricTracer.rst @@ -102,6 +102,9 @@ The following pseudo-code demonstrates how to enumerate Tracer based metric grou std::vectordecodableMetrics(numDecodableMetrics); ${t}MetricDecoderGetDecodableMetricsExp(hMetricDecoder, &numDecodableMetrics, decodableMetrics.data()); + // Enable the tracer + ${t}MetricTracerEnableExp(hMetricTracer, true); + // Run your workload Workload(hDevice); From c7f88fc9b20be65fb21554d69150bb8ecda08429 Mon Sep 17 00:00:00 2001 From: Matias Cabral Date: Thu, 21 Mar 2024 12:09:21 -0700 Subject: [PATCH 5/6] Add experimental extension for metric tracer Signed-off-by: Matias Cabral --- scripts/tools/EXT_Exp_MetricTracer.rst | 32 ++++++++++++++++++++++++-- scripts/tools/metric.yml | 8 +++---- scripts/tools/metricTracer.yml | 27 ++++++++++++++++------ 3 files changed, 54 insertions(+), 13 deletions(-) diff --git a/scripts/tools/EXT_Exp_MetricTracer.rst b/scripts/tools/EXT_Exp_MetricTracer.rst index 36fc8b37b..f50f7d743 100644 --- a/scripts/tools/EXT_Exp_MetricTracer.rst +++ b/scripts/tools/EXT_Exp_MetricTracer.rst @@ -19,6 +19,7 @@ Metric Tracer Experimental Extension API ---- * Enumerations + * ${t}_metric_tracer_exp_version_t * ${t}_metric_group_sampling_type_flags_t @@ -57,8 +58,35 @@ API Metric Tracer ~~~~~~~~~~~~~~~~~~~ -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 +Metrics collection model that allows retrieving metrics from events generated in asynchronous fashion. A Metrics Tracer is a software interface that allows +configuration for collection of such metrics. Collected raw data can be converted into parsable data with the use of a decoder object. + +Enumeration +----------- + +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. + +Configuration +------------- + +Use the ${t}ContextActivateMetricGroups API call to configure the device for data collection. + +Collection +---------- + +Metric Tracer based collection mode allows the creation of a tracer object for multiple metric groups than can be collected concurrently. Once metric groups are +activated the tracer can be created using ${t}MetricTracerCreateExp. Tracers are created in disabled state, applications have the flexibility to to enable +(${t}MetricTracerEnableExp) and disable (${t}MetricTracerDisableExp) during workload execution to selectively decide sections on which to collect metrics. +ata can be retrieved from the tracer with ${t}MetricTracerReadDataExp. + +Decoding +-------- +Metric Tracer collects the data in device specific, raw form that is not suitable for application processing. To convert data into a format that allows +application parsing a decoder object can be used. The decoder object is created with ${t}MetricDecoderCreateExp and data can be converted using +${t}MetricTracerDecodeExp. Each event in the data is associated with a decodable metric, which can be retrieved with ${t}MetricDecoderGetDecodableMetricsExp. + + Sample Code ------------ diff --git a/scripts/tools/metric.yml b/scripts/tools/metric.yml index c34b44cce..a7537d7bd 100644 --- a/scripts/tools/metric.yml +++ b/scripts/tools/metric.yml @@ -121,16 +121,16 @@ etors: - name: IP desc: "Metric type: instruction pointer" version: "1.7" - - name: EXP_EVENT_NO_VALUE + - name: EVENT_EXP_TIMESTAMP desc: "Metric type: event with only timestamp and value has no meaning" version: "1.10" - - name: EXP_EVENT_START + - name: EVENT_EXP_START desc: "Metric type: the first event of a start/end event pair" version: "1.10" - - name: EXP_EVENT_END + - name: EVENT_EXP_END desc: "Metric type: the second event of a start/end event pair" version: "1.10" - - name: EXP_EVENT_MONOTONIC_WRAPS_VALUE + - name: EVENT_EXP_MONOTONIC_WRAPS_VALUE desc: "Metric type: value of the event is a monotonically increasing value that can wrap around" version: "1.10" value: "0x7ffffffe" diff --git a/scripts/tools/metricTracer.yml b/scripts/tools/metricTracer.yml index e79c7cd00..0e51cdd2b 100644 --- a/scripts/tools/metricTracer.yml +++ b/scripts/tools/metricTracer.yml @@ -16,6 +16,15 @@ version: "1.10" name: $T_METRICS_TRACER_EXP_NAME value: '"$XT_experimental_metric_tracer"' --- #-------------------------------------------------------------------------- +type: enum +desc: "Metric Tracer Experimental Extension Version(s)" +version: "1.10" +name: $t_metric_tracer_exp_version_t +etors: + - name: "1_0" + value: "$X_MAKE_VERSION( 1, 0 )" + desc: "version 1.0" +--- #-------------------------------------------------------------------------- type: handle desc: "Handle of metric tracer's object" version: "1.10" @@ -109,11 +118,12 @@ params: desc: "[in] handle of the metric tracer" --- #-------------------------------------------------------------------------- type: function -desc: "Lightweight call that starts the event collections" +desc: "Start events collection" version: "1.10" class: $tMetricTracer name: EnableExp details: + - "Driver implementations must make this API call have as minimal overhead as possible, to allow applications start/stop event collection at any point during execution" - "The application must **not** call this function from simultaneous threads with the same metric tracer handle." params: - type: "$t_metric_tracer_exp_handle_t" @@ -127,11 +137,12 @@ params: when the tracer is active. --- #-------------------------------------------------------------------------- type: function -desc: "Lightweight call that stops the event collections" +desc: "Stop events collection" version: "1.10" class: $tMetricTracer name: DisableExp details: + - "Driver implementations must make this API call have as minimal overhead as possible, to allow applications start/stop event collection at any point during execution" - "The application must **not** call this function from simultaneous threads with the same metric tracer handle." params: - type: "$t_metric_tracer_exp_handle_t" @@ -196,14 +207,16 @@ params: 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." +desc: "Return the list of the decodable metrics from the decoder." version: "1.10" class: $tMetricDecoder name: GetDecodableMetricsExp +details: + - "The decodable metrics handles returned by this API are defined by the metric groups in the tracer + on which the decoder was created." + - "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." params: - type: $t_metric_decoder_exp_handle_t name: hMetricDecoder From 9e914c36c001b6ec269cc44795aa39a165b7d52b Mon Sep 17 00:00:00 2001 From: Matias Cabral Date: Thu, 4 Apr 2024 07:47:31 -0700 Subject: [PATCH 6/6] Add experimental extension for metric tracer Signed-off-by: Matias Cabral --- scripts/tools/EXT_Exp_MetricTracer.rst | 22 +++++++++++----------- scripts/tools/metricTracer.yml | 14 ++++++++++---- 2 files changed, 21 insertions(+), 15 deletions(-) diff --git a/scripts/tools/EXT_Exp_MetricTracer.rst b/scripts/tools/EXT_Exp_MetricTracer.rst index f50f7d743..fc584745a 100644 --- a/scripts/tools/EXT_Exp_MetricTracer.rst +++ b/scripts/tools/EXT_Exp_MetricTracer.rst @@ -28,7 +28,7 @@ API * ${t}_metric_type_t New Values - ${T}_METRIC_TYPE_EXP_EVENT_NO_VALUE + ${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. @@ -58,14 +58,14 @@ API Metric Tracer ~~~~~~~~~~~~~~~~~~~ -Metrics collection model that allows retrieving metrics from events generated in asynchronous fashion. A Metrics Tracer is a software interface that allows -configuration for collection of such metrics. Collected raw data can be converted into parsable data with the use of a decoder object. +Metrics collection model that allows retrieving metrics from events generated in asynchronous fashion. A Metrics Tracer is a software interface that allows +configuration for collection of such metrics. Collected raw data can be converted into parsable data with the use of a decoder object. Enumeration ----------- -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. +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. Configuration ------------- @@ -83,7 +83,7 @@ ata can be retrieved from the tracer with ${t}MetricTracerReadDataExp. Decoding -------- Metric Tracer collects the data in device specific, raw form that is not suitable for application processing. To convert data into a format that allows -application parsing a decoder object can be used. The decoder object is created with ${t}MetricDecoderCreateExp and data can be converted using +application parsing a decoder object can be used. The decoder object is created with ${t}MetricDecoderCreateExp and data can be converted using ${t}MetricTracerDecodeExp. Each event in the data is associated with a decodable metric, which can be retrieved with ${t}MetricDecoderGetDecodableMetricsExp. @@ -115,13 +115,13 @@ The following pseudo-code demonstrates how to enumerate Tracer based metric grou ${x}EventPoolCreate( hContext, &eventPoolDesc, 1, &hDevice, &hEventPool ); eventDesc.index = 0; eventDesc.signal = ${X}_EVENT_SCOPE_FLAG_HOST; - eventDesc.wait = ${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 + // create decoder ${t}MetricDecoderCreateExp( hMetricTracer, &hMetricDecoder); // Get decodable metrics @@ -133,10 +133,10 @@ The following pseudo-code demonstrates how to enumerate Tracer based metric grou // Enable the tracer ${t}MetricTracerEnableExp(hMetricTracer, true); - // Run your workload + // Run your workload Workload(hDevice); - // Wait for data, optional in this example + // Wait for data, optional in this example ${x}EventHostSynchronize( hNotificationEvent, 1000 /\*timeout\*/ ); // reset the event if it fired @@ -144,7 +144,7 @@ The following pseudo-code demonstrates how to enumerate Tracer based metric grou size_t rawDataSize = 0; ${t}MetricTracerReadDataExp(hMetricTracer, &rawDataSize, nullptr); std::vectorrawData(rawDataSize); - ${t}MetricTracerReadDataExp(hMetricTracer, &rawDataSize, rawData.data()); + ${t}MetricTracerReadDataExp(hMetricTracer, &rawDataSize, rawData.data()); // decode uint32_t numEntries =0; diff --git a/scripts/tools/metricTracer.yml b/scripts/tools/metricTracer.yml index 0e51cdd2b..0d2edaa8f 100644 --- a/scripts/tools/metricTracer.yml +++ b/scripts/tools/metricTracer.yml @@ -65,7 +65,13 @@ members: 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()" + desc: "[out] index to the decodable metric handle in the input array (phMetric) in $tMetricTracerDecode()." + - type: $x_bool_t + name: "onSubdevice" + desc: "[out] True if the event occurred on a sub-device; false means the device on which the metric tracer was opened does not have sub-devices." + - type: uint32_t + name: "subdeviceId" + desc: "[out] If onSubdevice is true, this gives the ID of the sub-device." --- #-------------------------------------------------------------------------- type: function desc: "Create a metric tracer for a device." @@ -212,10 +218,10 @@ version: "1.10" class: $tMetricDecoder name: GetDecodableMetricsExp details: - - "The decodable metrics handles returned by this API are defined by the metric groups in the tracer + - "The decodable metrics handles returned by this API are defined by the metric groups in the tracer on which the decoder was created." - - "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 + - "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." params: - type: $t_metric_decoder_exp_handle_t