Skip to content

Commit 088401b

Browse files
pbalcerpbalcer
committed
[ur][loader] add code location callback for tracing layer
This addresses the gap between XPTI support in PI and UR, where UR implementation was unable to provide code location information in traces, by adding an optional callback that, when set, allows language runtimes to provide this information.
1 parent eb9e8c2 commit 088401b

23 files changed

+531
-23
lines changed

‎include/ur.py

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,7 @@ class ur_function_v(IntEnum):
202202
KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 194## Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
203203
COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 195 ## Enumerator for ::urCommandBufferAppendUSMPrefetchExp
204204
COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 196 ## Enumerator for ::urCommandBufferAppendUSMAdviseExp
205+
LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK = 197 ## Enumerator for ::urLoaderConfigSetCodeLocationCallback
205206

206207
class ur_function_t(c_int):
207208
def __str__(self):
@@ -518,6 +519,24 @@ def __str__(self):
518519
return str(ur_loader_config_info_v(self.value))
519520

520521

522+
###############################################################################
523+
## @brief Code location data
524+
class ur_code_location_t(Structure):
525+
_fields_ = [
526+
("functionName", c_char_p), ## [in][out] Function name.
527+
("sourceFile", c_char_p), ## [in][out] Source code file.
528+
("lineNumber", c_ulong), ## [in][out] Source code line number.
529+
("columnNumber", c_ulong) ## [in][out] Source code column number.
530+
]
531+
532+
###############################################################################
533+
## @brief Code location callback with user data.
534+
def ur_code_location_callback_t(user_defined_callback):
535+
@CFUNCTYPE(ur_code_location_t, c_void_p)
536+
def ur_code_location_callback_t_wrapper(pUserData):
537+
return user_defined_callback(pUserData)
538+
return ur_code_location_callback_t_wrapper
539+
521540
###############################################################################
522541
## @brief Supported adapter info
523542
class ur_adapter_info_v(IntEnum):

‎include/ur_api.h

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,7 @@ typedef enum ur_function_t {
211211
UR_FUNCTION_KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 194, ///< Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
212212
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 195, ///< Enumerator for ::urCommandBufferAppendUSMPrefetchExp
213213
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 196, ///< Enumerator for ::urCommandBufferAppendUSMAdviseExp
214+
UR_FUNCTION_LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK = 197, ///< Enumerator for ::urLoaderConfigSetCodeLocationCallback
214215
/// @cond
215216
UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
216217
/// @endcond
@@ -675,6 +676,49 @@ urLoaderConfigEnableLayer(
675676
///< enable.
676677
);
677678

679+
///////////////////////////////////////////////////////////////////////////////
680+
/// @brief Code location data
681+
typedef struct ur_code_location_t {
682+
const char *functionName; ///< [in][out] Function name.
683+
const char *sourceFile; ///< [in][out] Source code file.
684+
uint32_t lineNumber; ///< [in][out] Source code line number.
685+
uint32_t columnNumber; ///< [in][out] Source code column number.
686+
687+
} ur_code_location_t;
688+
689+
///////////////////////////////////////////////////////////////////////////////
690+
/// @brief Code location callback with user data.
691+
typedef ur_code_location_t (*ur_code_location_callback_t)(
692+
void *pUserData ///< [in][out] pointer to data to be passed to callback
693+
);
694+
695+
///////////////////////////////////////////////////////////////////////////////
696+
/// @brief Set a function callback for use by the loader to retrieve code
697+
/// location information.
698+
///
699+
/// @details
700+
/// - The code location callback is optional and provides additional
701+
/// information to the tracing layer about the entry point of the current
702+
/// execution flow.
703+
/// - This functionality can be used to match traced unified runtime
704+
/// function calls with higher-level user calls.
705+
///
706+
/// @returns
707+
/// - ::UR_RESULT_SUCCESS
708+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
709+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
710+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
711+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
712+
/// + `NULL == hLoaderConfig`
713+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
714+
/// + `NULL == pfnCodeloc`
715+
UR_APIEXPORT ur_result_t UR_APICALL
716+
urLoaderConfigSetCodeLocationCallback(
717+
ur_loader_config_handle_t hLoaderConfig, ///< [in] Handle to config object the layer will be enabled for.
718+
ur_code_location_callback_t pfnCodeloc, ///< [in] Function pointer to code location callback.
719+
void *pUserData ///< [in][out][optional] pointer to data to be passed to callback.
720+
);
721+
678722
///////////////////////////////////////////////////////////////////////////////
679723
/// @brief Initialize the 'oneAPI' loader
680724
///
@@ -8618,6 +8662,16 @@ typedef struct ur_loader_config_enable_layer_params_t {
86188662
const char **ppLayerName;
86198663
} ur_loader_config_enable_layer_params_t;
86208664

8665+
///////////////////////////////////////////////////////////////////////////////
8666+
/// @brief Function parameters for urLoaderConfigSetCodeLocationCallback
8667+
/// @details Each entry is a pointer to the parameter passed to the function;
8668+
/// allowing the callback the ability to modify the parameter's value
8669+
typedef struct ur_loader_config_set_code_location_callback_params_t {
8670+
ur_loader_config_handle_t *phLoaderConfig;
8671+
ur_code_location_callback_t *ppfnCodeloc;
8672+
void **ppUserData;
8673+
} ur_loader_config_set_code_location_callback_params_t;
8674+
86218675
///////////////////////////////////////////////////////////////////////////////
86228676
/// @brief Function parameters for urPlatformGet
86238677
/// @details Each entry is a pointer to the parameter passed to the function;

‎scripts/core/loader.yml

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,53 @@ returns:
140140
- $X_RESULT_ERROR_LAYER_NOT_PRESENT:
141141
- "If layer specified with `pLayerName` can't be found by the loader."
142142
--- #--------------------------------------------------------------------------
143+
type: struct
144+
desc: "Code location data"
145+
class: $xLoaderConfig
146+
name: $x_code_location_t
147+
members:
148+
- type: const char*
149+
name: functionName
150+
desc: "[in][out] Function name."
151+
- type: const char*
152+
name: sourceFile
153+
desc: "[in][out] Source code file."
154+
- type: uint32_t
155+
name: lineNumber
156+
desc: "[in][out] Source code line number."
157+
- type: uint32_t
158+
name: columnNumber
159+
desc: "[in][out] Source code column number."
160+
--- #--------------------------------------------------------------------------
161+
type: fptr_typedef
162+
desc: "Code location callback with user data."
163+
name: $x_code_location_callback_t
164+
return: $x_code_location_t
165+
params:
166+
- type: void*
167+
name: pUserData
168+
desc: "[in][out] pointer to data to be passed to callback"
169+
--- #--------------------------------------------------------------------------
170+
type: function
171+
desc: "Set a function callback for use by the loader to retrieve code location information."
172+
details:
173+
- "The code location callback is optional and provides additional information to the tracing layer about the entry point of the current execution flow."
174+
- "This functionality can be used to match traced unified runtime function calls with higher-level user calls."
175+
class: $xLoaderConfig
176+
loader_only: True
177+
name: SetCodeLocationCallback
178+
decl: static
179+
params:
180+
- type: $x_loader_config_handle_t
181+
name: hLoaderConfig
182+
desc: "[in] Handle to config object the layer will be enabled for."
183+
- type: $x_code_location_callback_t
184+
name: pfnCodeloc
185+
desc: "[in] Function pointer to code location callback."
186+
- type: void*
187+
name: pUserData
188+
desc: "[in][out][optional] pointer to data to be passed to callback."
189+
--- #--------------------------------------------------------------------------
143190
type: function
144191
desc: "Initialize the $OneApi loader"
145192
class: $xLoader

‎scripts/core/registry.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -547,6 +547,9 @@ etors:
547547
- name: COMMAND_BUFFER_APPEND_USM_ADVISE_EXP
548548
desc: Enumerator for $xCommandBufferAppendUSMAdviseExp
549549
value: '196'
550+
- name: LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK
551+
desc: Enumerator for $xLoaderConfigSetCodeLocationCallback
552+
value: '197'
550553
---
551554
type: enum
552555
desc: Defines structure types

‎scripts/templates/trcddi.cpp.mako

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,13 +104,16 @@ namespace ur_tracing_layer
104104

105105
${x}_result_t
106106
context_t::init(ur_dditable_t *dditable,
107-
const std::set<std::string> &enabledLayerNames) {
107+
const std::set<std::string> &enabledLayerNames,
108+
codeloc_data codelocData) {
108109
${x}_result_t result = ${X}_RESULT_SUCCESS;
109110

110111
if(!enabledLayerNames.count(name)) {
111112
return result;
112113
}
113114

115+
ur_tracing_layer::context.codelocData = codelocData;
116+
114117
%for tbl in th.get_pfntables(specs, meta, n, tags):
115118
if( ${X}_RESULT_SUCCESS == result )
116119
{

‎scripts/templates/valddi.cpp.mako

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -160,9 +160,10 @@ namespace ur_validation_layer
160160
%endfor
161161
${x}_result_t
162162
context_t::init(ur_dditable_t *dditable,
163-
const std::set<std::string> &enabledLayerNames) {
163+
const std::set<std::string> &enabledLayerNames,
164+
codeloc_data) {
164165
${x}_result_t result = ${X}_RESULT_SUCCESS;
165-
166+
166167
if (enabledLayerNames.count(nameFullValidation)) {
167168
enableParameterValidation = true;
168169
enableLeakChecking = true;

‎source/common/ur_params.hpp

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -240,6 +240,9 @@ inline std::ostream &operator<<(std::ostream &os,
240240
enum ur_device_init_flag_t value);
241241
inline std::ostream &operator<<(std::ostream &os,
242242
enum ur_loader_config_info_t value);
243+
inline std::ostream &
244+
operator<<(std::ostream &os,
245+
[[maybe_unused]] const struct ur_code_location_t params);
243246
inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_info_t value);
244247
inline std::ostream &operator<<(std::ostream &os,
245248
enum ur_adapter_backend_t value);
@@ -1202,6 +1205,10 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
12021205
case UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP:
12031206
os << "UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP";
12041207
break;
1208+
1209+
case UR_FUNCTION_LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK:
1210+
os << "UR_FUNCTION_LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK";
1211+
break;
12051212
default:
12061213
os << "unknown enumerator";
12071214
break;
@@ -2170,6 +2177,32 @@ inline void serializeTagged(std::ostream &os, const void *ptr,
21702177
}
21712178
}
21722179
} // namespace ur_params
2180+
inline std::ostream &operator<<(std::ostream &os,
2181+
const struct ur_code_location_t params) {
2182+
os << "(struct ur_code_location_t){";
2183+
2184+
os << ".functionName = ";
2185+
2186+
ur_params::serializePtr(os, (params.functionName));
2187+
2188+
os << ", ";
2189+
os << ".sourceFile = ";
2190+
2191+
ur_params::serializePtr(os, (params.sourceFile));
2192+
2193+
os << ", ";
2194+
os << ".lineNumber = ";
2195+
2196+
os << (params.lineNumber);
2197+
2198+
os << ", ";
2199+
os << ".columnNumber = ";
2200+
2201+
os << (params.columnNumber);
2202+
2203+
os << "}";
2204+
return os;
2205+
}
21732206
inline std::ostream &operator<<(std::ostream &os,
21742207
enum ur_adapter_info_t value) {
21752208
switch (value) {
@@ -13873,6 +13906,27 @@ operator<<(std::ostream &os,
1387313906
return os;
1387413907
}
1387513908

13909+
inline std::ostream &
13910+
operator<<(std::ostream &os, [[maybe_unused]] const struct
13911+
ur_loader_config_set_code_location_callback_params_t *params) {
13912+
13913+
os << ".hLoaderConfig = ";
13914+
13915+
ur_params::serializePtr(os, *(params->phLoaderConfig));
13916+
13917+
os << ", ";
13918+
os << ".pfnCodeloc = ";
13919+
13920+
os << reinterpret_cast<void *>(*(params->ppfnCodeloc));
13921+
13922+
os << ", ";
13923+
os << ".pUserData = ";
13924+
13925+
ur_params::serializePtr(os, *(params->ppUserData));
13926+
13927+
return os;
13928+
}
13929+
1387613930
inline std::ostream &
1387713931
operator<<(std::ostream &os,
1387813932
[[maybe_unused]] const struct ur_mem_image_create_params_t *params) {
@@ -16146,6 +16200,10 @@ inline int serializeFunctionParams(std::ostream &os, uint32_t function,
1614616200
case UR_FUNCTION_LOADER_CONFIG_ENABLE_LAYER: {
1614716201
os << (const struct ur_loader_config_enable_layer_params_t *)params;
1614816202
} break;
16203+
case UR_FUNCTION_LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK: {
16204+
os << (const struct ur_loader_config_set_code_location_callback_params_t
16205+
*)params;
16206+
} break;
1614916207
case UR_FUNCTION_MEM_IMAGE_CREATE: {
1615016208
os << (const struct ur_mem_image_create_params_t *)params;
1615116209
} break;

‎source/loader/CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ target_sources(ur_loader
8888
${CMAKE_CURRENT_SOURCE_DIR}/ur_libddi.cpp
8989
${CMAKE_CURRENT_SOURCE_DIR}/ur_lib.hpp
9090
${CMAKE_CURRENT_SOURCE_DIR}/ur_lib.cpp
91+
${CMAKE_CURRENT_SOURCE_DIR}/ur_codeloc.hpp
9192
${CMAKE_CURRENT_SOURCE_DIR}/layers/validation/ur_valddi.cpp
9293
${CMAKE_CURRENT_SOURCE_DIR}/layers/validation/ur_validation_layer.cpp
9394
)

‎source/loader/layers/tracing/ur_tracing_layer.cpp

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
#include "ur_util.hpp"
1515
#include "xpti/xpti_data_types.h"
1616
#include "xpti/xpti_trace_framework.h"
17+
#include <optional>
1718
#include <sstream>
1819

1920
namespace ur_tracing_layer {
@@ -23,6 +24,8 @@ constexpr auto CALL_STREAM_NAME = "ur";
2324
constexpr auto STREAM_VER_MAJOR = UR_MAJOR_VERSION(UR_API_VERSION_CURRENT);
2425
constexpr auto STREAM_VER_MINOR = UR_MINOR_VERSION(UR_API_VERSION_CURRENT);
2526

27+
static thread_local xpti_td *activeEvent;
28+
2629
///////////////////////////////////////////////////////////////////////////////
2730
context_t::context_t() {
2831
xptiFrameworkInitialize();
@@ -39,11 +42,21 @@ bool context_t::isAvailable() const { return xptiTraceEnabled(); }
3942
void context_t::notify(uint16_t trace_type, uint32_t id, const char *name,
4043
void *args, ur_result_t *resultp, uint64_t instance) {
4144
xpti::function_with_args_t payload{id, name, args, resultp, nullptr};
42-
xptiNotifySubscribers(call_stream_id, trace_type, nullptr, nullptr,
45+
xptiNotifySubscribers(call_stream_id, trace_type, nullptr, activeEvent,
4346
instance, &payload);
4447
}
4548

4649
uint64_t context_t::notify_begin(uint32_t id, const char *name, void *args) {
50+
if (auto loc = codelocData.get_codeloc()) {
51+
xpti::payload_t payload =
52+
xpti::payload_t(loc->functionName, loc->sourceFile, loc->lineNumber,
53+
loc->columnNumber, nullptr);
54+
uint64_t InstanceNumber{};
55+
activeEvent = xptiMakeEvent("Unified Runtime call", &payload,
56+
xpti::trace_graph_event, xpti_at::active,
57+
&InstanceNumber);
58+
}
59+
4760
uint64_t instance = xptiGetUniqueId();
4861
notify((uint16_t)xpti::trace_point_type_t::function_with_args_begin, id,
4962
name, args, nullptr, instance);

‎source/loader/layers/tracing/ur_tracing_layer.hpp

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ namespace ur_tracing_layer {
2424
class __urdlllocal context_t : public proxy_layer_context_t {
2525
public:
2626
ur_dditable_t urDdiTable = {};
27+
codeloc_data codelocData;
2728

2829
context_t();
2930
~context_t();
@@ -32,7 +33,8 @@ class __urdlllocal context_t : public proxy_layer_context_t {
3233

3334
std::vector<std::string> getNames() const override { return {name}; }
3435
ur_result_t init(ur_dditable_t *dditable,
35-
const std::set<std::string> &enabledLayerNames) override;
36+
const std::set<std::string> &enabledLayerNames,
37+
codeloc_data codelocData) override;
3638
ur_result_t tearDown() override { return UR_RESULT_SUCCESS; }
3739
uint64_t notify_begin(uint32_t id, const char *name, void *args);
3840
void notify_end(uint32_t id, const char *name, void *args,

0 commit comments

Comments
 (0)