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']) diff --git a/scripts/tools/EXT_Exp_MetricTracer.rst b/scripts/tools/EXT_Exp_MetricTracer.rst new file mode 100644 index 000000000..fc584745a --- /dev/null +++ b/scripts/tools/EXT_Exp_MetricTracer.rst @@ -0,0 +1,195 @@ +<% +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_tracer_exp_version_t + + * ${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 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. + +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 +------------ + +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()); + + // Enable the tracer + ${t}MetricTracerEnableExp(hMetricTracer, true); + + // 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); + std::vectorrawData(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); + 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: + std::cout << ".\t value: " << metricEntry.value.ui32 << std::endl; + break; + case ${T}_VALUE_TYPE_UINT64: + std::cout << ".\t value: " << metricEntry.value.ui64 << std::endl; + break; + case ${T}_VALUE_TYPE_FLOAT32: + std::cout << ".\t value: " << metricEntry.value.fp32 << std::endl; + break; + case ${T}_VALUE_TYPE_FLOAT64: + std::cout << ".\t value: " << metricEntry.value.fp64 << std::endl; + break; + case ${T}_VALUE_TYPE_BOOL8: + if( metricEntry.value.b8 ){ + std::cout << ".\t value: true" << std::endl; + else + std::cout << ".\t value: false" << std::endl; + } + 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..a7537d7bd 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: EVENT_EXP_TIMESTAMP + desc: "Metric type: event with only timestamp and value has no meaning" + version: "1.10" + - name: EVENT_EXP_START + desc: "Metric type: the first event of a start/end event pair" + version: "1.10" + - name: EVENT_EXP_END + desc: "Metric type: the second event of a start/end event pair" + version: "1.10" + - 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" --- #-------------------------------------------------------------------------- type: enum diff --git a/scripts/tools/metricTracer.yml b/scripts/tools/metricTracer.yml new file mode 100644 index 000000000..0d2edaa8f --- /dev/null +++ b/scripts/tools/metricTracer.yml @@ -0,0 +1,280 @@ +# +# Copyright (C) 2024 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: 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" +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: $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." +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 support 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: "phMetricGroups" + 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: "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" + 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() + 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: "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" + 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() + 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" +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: hMetricTracer + 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 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 + 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