Commit b152580e authored by Brice Videau's avatar Brice Videau
Browse files

Added support for new tracing layer.

parent 1405ead9
Pipeline #11753 failed with stage
......@@ -5,17 +5,20 @@ LTTNG_FLAGS=-fPIC -Wall -Wextra -Wno-unused-parameter -Wno-type-limits -Wno-sign
ZE_PROBES_TP = \
ze_tracepoints.tp \
zet_tracepoints.tp \
zes_tracepoints.tp
zes_tracepoints.tp \
zel_tracepoints.tp
ZE_PROBES_INCL = \
ze_tracepoints.h \
zet_tracepoints.h \
zes_tracepoints.h
zes_tracepoints.h \
zel_tracepoints.h
ZE_PROBES_SRC = \
ze_tracepoints.c \
zet_tracepoints.c \
zes_tracepoints.c
zes_tracepoints.c \
zel_tracepoints.h
ZE_STATIC_PROBES_TP = \
ze_profiling.tp \
......@@ -40,7 +43,8 @@ CLEANFILES = \
ML_FILES = \
$(srcdir)/ze_meta_parameters.yaml \
$(srcdir)/zes_meta_parameters.yaml \
$(srcdir)/zet_meta_parameters.yaml
$(srcdir)/zet_meta_parameters.yaml \
$(srcdir)/zel_meta_parameters.yaml
EXTRA_DIST = $(ML_FILES)
......@@ -52,7 +56,8 @@ EXTRA_DIST += extract_base.rb
ZE_EXTRACTED = \
ze_api.yaml \
zet_api.yaml \
zes_api.yaml
zes_api.yaml \
zel_api.yaml
CLEANFILES += $(ZE_EXTRACTED)
......@@ -73,7 +78,10 @@ ZE_EXTRA_HDR = \
$(srcdir)/include/zes_api.h \
$(srcdir)/include/zes_ddi.h \
$(srcdir)/include/zet_api.h \
$(srcdir)/include/zet_ddi.h
$(srcdir)/include/zet_ddi.h \
$(srcdir)/include/loader/ze_loader_api.h \
$(srcdir)/include/layers/zel_tracing_api.h \
$(srcdir)/include/layers/zel_tracing_ddi.h
ZE_HDR = \
$(srcdir)/include/ze_api.h \
$(ZE_EXTRA_HDR)
......@@ -83,7 +91,10 @@ MODIFIED_ZE_EXTRA_HDR = \
modified_include/zes_api.h \
modified_include/zes_ddi.h \
modified_include/zet_api.h \
modified_include/zet_ddi.h
modified_include/zet_ddi.h \
modified_include/loader/ze_loader_api.h \
modified_include/layers/zel_tracing_api.h \
modified_include/layers/zel_tracing_ddi.h
MODIFIED_ZE_HDR = \
modified_include/ze_api.h \
$(MODIFIED_ZE_EXTRA_HDR)
......@@ -106,28 +117,35 @@ clean-local:
EXTRA_DIST += $(srcdir)/include headers.patch
ze_api.yaml: $(MODIFIED_ZE_HDR) $(ZE_EXTRACT) $(srcdir)/extract_ze.rb
SRC_DIR=$(srcdir) $(RUBY) $(srcdir)/extract_ze.rb
ze_api.yaml: $(srcdir)/extract_ze.rb $(MODIFIED_ZE_HDR) $(ZE_EXTRACT)
SRC_DIR=$(srcdir) $(RUBY) $<
zet_api.yaml: $(MODIFIED_ZE_HDR) $(ZE_EXTRACT) $(srcdir)/extract_zet.rb
SRC_DIR=$(srcdir) $(RUBY) $(srcdir)/extract_zet.rb
zet_api.yaml: $(srcdir)/extract_zet.rb $(MODIFIED_ZE_HDR) $(ZE_EXTRACT)
SRC_DIR=$(srcdir) $(RUBY) $<
zes_api.yaml: $(MODIFIED_ZE_HDR) $(ZE_EXTRACT) $(srcdir)/extract_zes.rb
SRC_DIR=$(srcdir) $(RUBY) $(srcdir)/extract_zes.rb
zes_api.yaml: $(srcdir)/extract_zes.rb $(MODIFIED_ZE_HDR) $(ZE_EXTRACT)
SRC_DIR=$(srcdir) $(RUBY) $<
zel_api.yaml: $(srcdir)/extract_zel.rb $(MODIFIED_ZE_HDR) $(ZE_EXTRACT)
SRC_DIR=$(srcdir) $(RUBY) $<
EXTRA_DIST += \
extract_ze.rb \
extract_zet.rb \
extract_zes.rb
extract_zes.rb \
extract_zel.rb
ze_tracepoints.tp: $(srcdir)/gen_ze_tracepoints.rb $(ZE_MODEL) $(srcdir)/gen_probe_base.rb
SRC_DIR=$(srcdir) $(RUBY) $(srcdir)/gen_ze_tracepoints.rb > $@
SRC_DIR=$(srcdir) $(RUBY) $< > $@
zet_tracepoints.tp: $(srcdir)/gen_zet_tracepoints.rb $(ZE_MODEL) $(srcdir)/gen_probe_base.rb
SRC_DIR=$(srcdir) $(RUBY) $(srcdir)/gen_zet_tracepoints.rb > $@
SRC_DIR=$(srcdir) $(RUBY) $< > $@
zes_tracepoints.tp: $(srcdir)/gen_zes_tracepoints.rb $(ZE_MODEL) $(srcdir)/gen_probe_base.rb
SRC_DIR=$(srcdir) $(RUBY) $(srcdir)/gen_zes_tracepoints.rb > $@
SRC_DIR=$(srcdir) $(RUBY) $< > $@
zel_tracepoints.tp: $(srcdir)/gen_zel_tracepoints.rb $(ZE_MODEL) $(srcdir)/gen_probe_base.rb
SRC_DIR=$(srcdir) $(RUBY) $< > $@
ze_profiling.tp: $(srcdir)/gen_ze_custom_probes.rb $(ZE_MODEL)
SRC_DIR=$(srcdir) $(RUBY) $(srcdir)/gen_ze_custom_probes.rb lttng_ust_ze_profiling > $@
......@@ -143,6 +161,7 @@ EXTRA_DIST += \
gen_ze_tracepoints.rb \
gen_zet_tracepoints.rb \
gen_zes_tracepoints.rb \
gen_zel_tracepoints.rb \
gen_probe_base.rb
BUILT_SOURCES = $(ZE_PROBES_INCL) $(ZE_STATIC_PROBES_INCL) babeltrace_ze_callbacks.h
......
......@@ -3,6 +3,7 @@ require_relative 'extract_base.rb'
preprocessed_sources_ze_api = $cpp.preprocess(<<EOF).gsub(/^#.*?$/, '')
#include <ze_api.h>
#include <ze_ddi.h>
#include <loader/ze_loader_api.h>
EOF
ast = $parser.parse(preprocessed_sources_ze_api)
......
require_relative 'extract_base.rb'
preprocessed_sources_ze_api = $cpp.preprocess(<<EOF).gsub(/^#.*?$/, '')
#include <ze_api.h>
#include <ze_ddi.h>
EOF
preprocessed_sources_zel_api = $cpp.preprocess(<<EOF).gsub(/^#.*?$/, '')
#define _ZE_API_H
#include <layers/zel_tracing_api.h>
#include <layers/zel_tracing_ddi.h>
EOF
$parser.parse(preprocessed_sources_ze_api)
ast = $parser.parse(preprocessed_sources_zel_api)
File::open("zel_api.yaml", "w") { |f|
f.puts ast.extract_declarations.to_yaml
}
......@@ -6,6 +6,8 @@ puts <<EOF
#include <zet_ddi.h>
#include <zes_api.h>
#include <zes_ddi.h>
#include <layers/zel_tracing_api.h>
#include <layers/zel_tracing_ddi.h>
#include <babeltrace2/babeltrace.h>
EOF
......@@ -43,7 +45,7 @@ EOF
fields = ["const bt_event *bt_evt",
"const bt_clock_snapshot *bt_clock"]
if dir == :start
fields += (c.parameters+c.tracepoint_parameters).collect { |p|
fields += ((c.parameters ? c.parameters : [] )+c.tracepoint_parameters).collect { |p|
p.to_s
}
fields += c.meta_parameters.select { |m| m.kind_of?(In) }.collect { |m|
......@@ -114,6 +116,12 @@ $zes_commands.each { |c|
gen_event_callback.call(provider, c, :stop)
}
provider = :lttng_ust_zel
$zel_commands.each { |c|
gen_event_callback.call(provider, c, :start)
gen_event_callback.call(provider, c, :stop)
}
ze_events = YAML::load_file(File.join(SRC_DIR,"ze_events.yaml"))
ze_events.each { |provider, es|
......
......@@ -6,6 +6,8 @@ puts <<EOF
#include <zet_ddi.h>
#include <zes_api.h>
#include <zes_ddi.h>
#include <layers/zel_tracing_api.h>
#include <layers/zel_tracing_ddi.h>
#include <babeltrace2/babeltrace.h>
#include "babeltrace_ze.h"
#include "babeltrace_ze_callbacks.h"
......@@ -95,7 +97,7 @@ end
def print_field_members_free(c, dir)
if dir == :start
(c.parameters+c.tracepoint_parameters).each { |p|
((c.parameters ? c.parameters : []) + c.tracepoint_parameters).each { |p|
lttng = p.lttng_type
print_field_member_free(lttng.macro.to_s, p.name)
}
......@@ -139,7 +141,7 @@ end
def print_field_members_access(c, dir)
if dir == :start
i = 0
(c.parameters+c.tracepoint_parameters).each { |p|
((c.parameters ? c.parameters : []) + c.tracepoint_parameters).each { |p|
lttng = p.lttng_type
print_field_member_access(lttng.macro.to_s, p.type, p.name, i)
i += 1;
......@@ -209,7 +211,7 @@ end
def get_fields_decl(c, dir)
if dir == :start
fields = (c.parameters+c.tracepoint_parameters).collect { |p|
fields = ((c.parameters ? c.parameters : []) + c.tracepoint_parameters).collect { |p|
p.to_s + ";"
}
fields += c.meta_parameters.select { |m| m.kind_of?(In) }.collect { |m|
......@@ -227,7 +229,7 @@ end
def get_fields_names(c, dir)
if dir == :start
fields = (c.parameters+c.tracepoint_parameters).collect { |p|
fields = ((c.parameters ? c.parameters : []) + c.tracepoint_parameters).collect { |p|
p.name.to_s
}
fields += c.meta_parameters.select { |m| m.kind_of?(In) }.collect { |m|
......@@ -339,6 +341,12 @@ $zes_commands.each { |c|
gen_event_dispatcher.call(provider, c, :stop)
}
provider = :lttng_ust_zel
$zel_commands.each { |c|
gen_event_dispatcher.call(provider, c, :start)
gen_event_dispatcher.call(provider, c, :stop)
}
ze_events = YAML::load_file(File.join(SRC_DIR,"ze_events.yaml"))
ze_events.each { |provider, es|
......@@ -381,6 +389,12 @@ $zes_commands.each { |c|
gen_event_dispatch_init.call(provider, c, :stop)
}
provider = :lttng_ust_zel
$zel_commands.each { |c|
gen_event_dispatch_init.call(provider, c, :start)
gen_event_dispatch_init.call(provider, c, :stop)
}
ze_events.each { |provider, es|
es["events"].each { |event|
gen_extra_event_dispatch_init.call(provider, event)
......
......@@ -119,6 +119,12 @@ $zes_commands.each { |c|
gen_event_lambda.call(provider, c, :stop)
}
provider = :lttng_ust_zel
$zel_commands.each { |c|
gen_event_lambda.call(provider, c, :start)
gen_event_lambda.call(provider, c, :stop)
}
extra_events = YAML::load_file(File.join(SRC_DIR,"ze_events.yaml"))
extra_events.each { |provider, h|
......
......@@ -29,9 +29,11 @@ EOF
EOF
fields = []
if dir == :start
c.parameters.collect(&:lttng_type).compact.each { |r|
fields.push(r.call_string)
}
if c.parameters
c.parameters.collect(&:lttng_type).compact.each { |r|
fields.push(r.call_string)
}
end
c.meta_parameters.collect(&:lttng_in_type).flatten.compact.each { |r|
fields.push(r.call_string)
}
......
......@@ -9,6 +9,8 @@ puts <<EOF
#include <zet_ddi.h>
#include <zes_api.h>
#include <zes_ddi.h>
#include <layers/zel_tracing_api.h>
#include <layers/zel_tracing_ddi.h>
#include <dlfcn.h>
#include <dlfcn.h>
#include <stdio.h>
......@@ -23,16 +25,17 @@ puts <<EOF
#include "ze_tracepoints.h"
#include "zet_tracepoints.h"
#include "zes_tracepoints.h"
#include "zel_tracepoints.h"
#include "ze_profiling.h"
#include "ze_properties.h"
EOF
($ze_commands + $zet_commands + $zes_commands).each { |c|
all_commands = $ze_commands + $zet_commands + $zes_commands + $zel_commands
(all_commands).each { |c|
puts "#define #{ZE_POINTER_NAMES[c]} #{c.pointer_name}"
}
($ze_commands + $zet_commands + $zes_commands).each { |c|
(all_commands).each { |c|
puts <<EOF
#{c.decl_pointer(c.pointer_type_name)};
......@@ -45,7 +48,7 @@ puts <<EOF
static void find_ze_symbols(void * handle) {
EOF
($ze_commands + $zet_commands + $zes_commands).each { |c|
(all_commands).each { |c|
puts <<EOF
#{ZE_POINTER_NAMES[c]} = (#{c.pointer_type_name})(intptr_t)dlsym(handle, "#{c.name}");
......@@ -62,14 +65,18 @@ EOF
puts File::read(File.join(SRC_DIR,"tracer_ze_helpers.include.c"))
common_block = lambda { |c, provider|
params = c.parameters.collect(&:name)
tp_params = c.parameters.collect { |p|
if p.type.kind_of?(YAMLCAst::Pointer) && p.type.type.kind_of?(YAMLCAst::Function)
"(void *)(intptr_t)" + p.name
else
p.name
end
}
params = c.parameters ? c.parameters.collect(&:name) : []
tp_params = if c.parameters
c.parameters.collect { |p|
if p.type.kind_of?(YAMLCAst::Pointer) && p.type.type.kind_of?(YAMLCAst::Function)
"(void *)(intptr_t)" + p.name
else
p.name
end
}
else
[]
end
tracepoint_params = c.tracepoint_parameters.collect(&:name)
c.tracepoint_parameters.each { |p|
puts " #{p.type} #{p.name};"
......@@ -134,3 +141,6 @@ $zet_commands.each { |c|
$zes_commands.each { |c|
normal_wrapper.call(c, :lttng_ust_zes)
}
$zel_commands.each { |c|
normal_wrapper.call(c, :lttng_ust_zel)
}
require_relative 'ze_model'
require_relative 'gen_probe_base.rb'
$all_types = $ze_api["typedefs"] + $zet_api["typedefs"] + $zes_api["typedefs"]
$all_structs = $ze_api["structs"] + $zet_api["structs"] + $zes_api["structs"]
$all_types = $ze_api["typedefs"] + $zet_api["typedefs"] + $zes_api["typedefs"] + $zel_api["typedefs"]
$all_structs = $ze_api["structs"] + $zet_api["structs"] + $zes_api["structs"] + $zel_api["structs"]
$all_unions = $zet_api["unions"]
$all_enums = $ze_api["enums"] + $zet_api["enums"] + $zes_api["enums"]
$all_funcs = $ze_api["functions"] + $zet_api["functions"] + $zes_api["functions"]
$all_enums = $ze_api["enums"] + $zet_api["enums"] + $zes_api["enums"] + $zel_api["enums"]
$all_funcs = $ze_api["functions"] + $zet_api["functions"] + $zes_api["functions"] + $zel_api["functions"]
$all_enum_names = []
$all_bitfield_names = []
......@@ -33,7 +33,7 @@ $all_types.each { |t|
def to_class_name(name)
mod = to_name_space(name)
n = name.gsub(/_t\z/, "").gsub(/\Aze[st]?_/, "").split("_").collect(&:capitalize).join
n = name.gsub(/_t\z/, "").gsub(/\Aze[stl]?_/, "").split("_").collect(&:capitalize).join
mod << n.gsub("Uuid","UUID").gsub("Dditable", "DDITable").gsub(/\AFp/, "FP").gsub("P2p", "P2P")
end
......@@ -42,7 +42,7 @@ def to_ffi_name(name)
end
def to_name_space(name)
name.match(/\A(ze[st]?)_/)[1].upcase
name.match(/\A(ze[stl]?)_/)[1].upcase
end
$all_types.each { |t|
......@@ -112,18 +112,22 @@ module YAMLCAst
class Function
def to_ffi
t = to_ffi_name(type.name)
p = params.collect { |par|
if par.type.kind_of?(Pointer)
if par.type.type.respond_to?(:name) &&
$all_struct_names.include?(par.type.type.name)
"#{to_class_name(par.type.type.name)}.ptr"
p = if params
params.collect { |par|
if par.type.kind_of?(Pointer)
if par.type.type.respond_to?(:name) &&
$all_struct_names.include?(par.type.type.name)
"#{to_class_name(par.type.type.name)}.ptr"
else
":pointer"
end
else
":pointer"
to_ffi_name(par.type.name)
end
else
to_ffi_name(par.type.name)
end
}
}
else
[]
end
[t, p]
end
end
......
require_relative 'ze_model'
require_relative 'gen_probe_base.rb'
provider = :lttng_ust_zel
puts <<EOF
#include <layers/zel_tracing_api.h>
#include <layers/zel_tracing_ddi.h>
EOF
$zel_commands.each { |c|
next if c.parameters && c.parameters.length > LTTNG_USABLE_PARAMS
$tracepoint_lambda.call(provider, c, :start)
$tracepoint_lambda.call(provider, c, :stop)
}
......@@ -72,7 +72,7 @@ gen_event_callback_name_fields = lambda { |provider, c, dir|
fields = ["const bt_event *bt_evt",
"const bt_clock_snapshot *bt_clock"]
if dir == :start
fields += (c.parameters+c.tracepoint_parameters).collect { |p|
fields += ((c.parameters ? c.parameters : [])+c.tracepoint_parameters).collect { |p|
p.to_s
}
fields += c.meta_parameters.select { |m| m.kind_of?(In) }.collect { |m|
......@@ -130,6 +130,11 @@ provider = :lttng_ust_zes
$dbt_events += $zes_commands.map{ |c| gen_event_callback_name_fields.call(provider, c, :start) } +
$zes_commands.map{ |c| gen_event_callback_name_fields.call(provider, c, :stop) }
provider = :lttng_ust_zel
$dbt_events += $zel_commands.map{ |c| gen_event_callback_name_fields.call(provider, c, :start) } +
$zel_commands.map{ |c| gen_event_callback_name_fields.call(provider, c, :stop) }
ze_events = YAML::load_file(File.join(SRC_DIR,"ze_events.yaml"))
ze_events = YAML::load_file(File.join(SRC_DIR,"ze_events.yaml"))
$dbt_events += ze_events.map{ |provider,es|
es['events'].map{ |event|
......
diff -u4 include/ze_api.h modified_include/ze_api.h
--- include/ze_api.h 2020-08-17 14:38:20.309705000 +0000
+++ modified_include/ze_api.h 2020-08-17 14:46:51.272367000 +0000
diff -u4 -r include/loader/ze_loader_api.h modified_include/loader/ze_loader_api.h
--- include/loader/ze_loader_api.h 2020-10-28 09:54:27.743787112 -0500
+++ modified_include/loader/ze_loader_api.h 2020-10-28 10:05:26.533385647 -0500
@@ -7,9 +7,9 @@
* @file ze_loader_api.cpp
*
*/
-#include "ze_loader.h"
+#include "../ze_api.h"
#if defined(__cplusplus)
extern "C" {
#endif
@@ -25,5 +25,5 @@
#if defined(__cplusplus)
}
-#endif
\ No newline at end of file
+#endif
diff -u4 -r include/ze_api.h modified_include/ze_api.h
--- include/ze_api.h 2020-10-28 09:53:41.847933458 -0500
+++ modified_include/ze_api.h 2020-10-28 09:59:38.258710059 -0500
@@ -14,10 +14,10 @@
#pragma once
#endif
......@@ -328,9 +350,9 @@ diff -u4 include/ze_api.h modified_include/ze_api.h
-#endif // _ZE_API_H
\ No newline at end of file
+#endif // _ZE_API_H
diff -u4 include/zes_api.h modified_include/zes_api.h
--- include/zes_api.h 2020-08-17 14:38:20.316708000 +0000
+++ modified_include/zes_api.h 2020-08-17 14:50:34.068221000 +0000
diff -u4 -r include/zes_api.h modified_include/zes_api.h
--- include/zes_api.h 2020-10-28 09:53:41.847933458 -0500
+++ modified_include/zes_api.h 2020-10-28 09:59:38.258710059 -0500
@@ -182,249 +182,249 @@
} zes_base_capability_t;
......@@ -650,10 +672,9 @@ diff -u4 include/zes_api.h modified_include/zes_api.h
-#endif // _ZES_API_H
\ No newline at end of file
+#endif // _ZES_API_H
Only in modified_include/: .zes_api.h.swp
diff -u4 include/zet_api.h modified_include/zet_api.h
--- include/zet_api.h 2020-08-17 14:38:20.322704000 +0000
+++ modified_include/zet_api.h 2020-08-17 14:46:51.277364000 +0000
diff -u4 -r include/zet_api.h modified_include/zet_api.h
--- include/zet_api.h 2020-10-28 09:53:41.851933445 -0500
+++ modified_include/zet_api.h 2020-10-28 09:59:38.258710059 -0500
@@ -147,81 +147,81 @@
} zet_typed_value_t;
......
/*
* Copyright (C) 2020 Intel Corporation
*
* SPDX-License-Identifier: MIT
*
* @file zel_tracing_api.h
*/
#ifndef _ZEL_TRACING_API_H
#define _ZEL_TRACING_API_H
#if defined(__cplusplus)
#pragma once
#endif
// 'core' API headers
#include "../ze_api.h"
#if defined(__cplusplus)
extern "C" {
#endif
// Intel 'oneAPI' Level-Zero Loader Layer Extension APIs for API Tracing
#if !defined(__GNUC__)
#pragma region zel_tracing
#endif
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of tracer object
typedef struct _zel_tracer_handle_t *zel_tracer_handle_t;
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
#ifndef ZEL_API_TRACING_NAME
/// @brief API Tracing Extension Name
#define ZEL_API_TRACING_NAME "ZEL_api_tracing"
#endif // ZEL_API_TRACING_NAME
///////////////////////////////////////////////////////////////////////////////
/// @brief API Tracing Extension Version(s)
typedef enum _zel_api_tracing_version_t
{
ZEL_API_TRACING_VERSION_1_0 = ZE_MAKE_VERSION( 1, 0 ), ///< version 1.0
ZEL_API_TRACING_VERSION_CURRENT = ZE_MAKE_VERSION( 1, 0 ), ///< latest known version
ZEL_API_TRACING_VERSION_FORCE_UINT32 = 0x7fffffff
} zel_api_tracing_version_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Alias the existing callbacks definition for 'core' callbacks
typedef ze_callbacks_t zel_core_callbacks_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Defines structure types
typedef enum _zel_structure_type_t
{
ZEL_STRUCTURE_TYPE_TRACER_EXP_DESC = 0x1 ,///< ::zel_tracer_desc_t
ZEL_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
} zel_structure_type_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Tracer descriptor
typedef struct _zel_tracer_desc_t
{
zel_structure_type_t stype; ///< [in] type of this structure
const void* pNext; ///< [in][optional] pointer to extension-specific structure
void* pUserData; ///< [in] pointer passed to every tracer's callbacks
} zel_tracer_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Creates a tracer
///
/// @details
/// - The tracer is created in the disabled state.
/// - The application may call this function from simultaneous threads.
/// - The implementation of this function must be thread-safe.
///
/// @returns
/// - ::ZE_RESULT_SUCCESS
/// - ::ZE_RESULT_ERROR_UNINITIALIZED
/// - ::ZE_RESULT_ERROR_DEVICE_LOST
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == desc`
/// + `nullptr == desc->pUserData`
/// + `nullptr == phTracer`
/// - ::ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY
ZE_APIEXPORT ze_result_t ZE_APICALL
zelTracerCreate(
const zel_tracer_desc_t* desc, ///< [in] pointer to tracer descriptor
zel_tracer_handle_t* phTracer ///< [out] pointer to handle of tracer object created
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Destroys a tracer.
///
/// @details
/// - The application must **not** call this function from simultaneous
/// threads with the same tracer handle.
/// - The implementation of this function must be thread-safe.
/// - The implementation of this function will stall and wait on any
/// outstanding threads executing callbacks before freeing any Host
/// allocations associated with this tracer.
///
/// @returns
/// - ::ZE_RESULT_SUCCESS
/// - ::ZE_RESULT_ERROR_UNINITIALIZED
/// - ::ZE_RESULT_ERROR_DEVICE_LOST