[XPTI][INFRA] Refactored API implementations to improve performance (#19160)

As a part of the performance study to improve SYCL runtime performance,
it was documented that XPTI when enabled by a tool or collector was
having higher than usual performance impact. This is the second PR to
address the specific xptiMakeEvent* API and current implementation is
~30% faster than previous implementation. The last PR in this series
will change the instrumentation in SYCL to address the large performance
impact caused by mixing debug and performance streams in the runtime
today.

 - Also fixes issues in XPTI samples due to changes in PR#18786

---------

Signed-off-by: Vasanth Tovinkere <[email protected]>

Author: tovinkere

xpti/include/xpti/xpti_data_types.h

@@ -358,7 +358,7 @@ enum class payload_flag_t {
 //
 using trace_point_t = uint16_t;
 using event_type_t = uint16_t;
-using string_id_t = int32_t;
+using string_id_t = uint32_t;
 using object_id_t = int32_t;
 
 using safe_flag_t = std::atomic<bool>;
@@ -455,60 +455,105 @@ struct payload_t {
 
   payload_t() = default;
 
-  //  If the address of the kernel/function name is provided, we mark it as
-  //  valid since we can potentially reconstruct the name and the source file
-  //  information during post-processing step of symbol resolution; this
-  //  indicates a partial but valid payload.
+  ///
+  /// @brief Constructs a payload_t with only a code pointer.
+  ///
+  /// @details
+  /// Initializes the payload with the provided code pointer address. All other
+  /// fields (name, source file, line number, column number) are set to invalid
+  /// or null values. If a valid code pointer is provided, the corresponding
+  /// flag is set to indicate its availability.
+  ///
+  /// If the address of the kernel/function name is provided, we mark it as
+  /// valid since we can potentially reconstruct the name and the source file
+  /// information during post-processing step of symbol resolution; this
+  /// indicates a partial but valid payload.
+  ///
+  /// @param codeptr Pointer to the code location associated with this payload.
+  ///
   payload_t(const void *codeptr) {
-    code_ptr_va = codeptr;
-    name = nullptr;           ///< Invalid name string pointer
-    source_file = nullptr;    ///< Invalid source file string pointer
-    line_no = invalid_id<>;   ///< Invalid line number
-    column_no = invalid_id<>; ///< Invalid column number
+    code_ptr_va = codeptr; ///< Override the default initialization
+    // If the incoming code ptr is null, we ensure that the flags are set
+    // correctly
     if (codeptr) {
       flags = (uint64_t)payload_flag_t::CodePointerAvailable;
     }
   }
 
-  //  If neither an address or the fully identifyable source file name and
-  //  location are not available, we take in the name of the
-  //  function/task/user-defined name as input and create a hash from it. We
-  //  mark it as valid since we can display the name in a timeline view, but
-  //  the payload is considered to be a partial but valid payload.
+  ///
+  /// @brief Constructs a payload_t with only a function or kernel name.
+  ///
+  /// @details
+  /// Initializes the payload with the provided function or kernel name.
+  /// If neither an address or the fully identifyable source file name and
+  /// location are not available, we take in the name of the
+  /// function/task/user-defined name as input and create a hash from it. We
+  /// mark it as valid since we can display the name in a timeline view, but
+  /// the payload is considered to be a partial but valid payload.
+  ///
+  /// @param func_name Name of the function, kernel, or user-defined entity.
+  ///
   payload_t(const char *func_name) {
-    code_ptr_va = nullptr;
-    name = func_name;      ///< Invalid name string pointer
-    source_file = nullptr; ///< Invalid source file string pointer
+    name = func_name; ///< Override the default initialization
+    // If the incoming name is null, we ensure that the flags are set correctly
     if (func_name) {
       flags = (uint64_t)(payload_flag_t::NameAvailable);
     }
   }
 
+  ///
+  /// @brief Constructs a payload_t with a function or kernel name and code
+  /// pointer.
+  ///
+  /// @details
+  /// Initializes the payload with the provided function or kernel name and code
+  /// pointer. The source file is set to null. Flags are set to indicate which
+  /// fields are available. The payload is considered partial, but valid.
+  ///
+  /// @param func_name Name of the function, kernel, or user-defined entity.
+  /// @param codeptr Pointer to the code location associated with this payload.
+  ///
   payload_t(const char *func_name, const void *codeptr) {
-    code_ptr_va = codeptr;
-    name = func_name;      ///< Invalid name string pointer
-    source_file = nullptr; ///< Invalid source file string pointer
+    code_ptr_va = codeptr; ///< Override the default initialization
+    name = func_name;      ///< Override the default initialization
+    // If the incoming name is null, we ensure that the flags are set correctly
     if (func_name) {
       flags = (uint64_t)(payload_flag_t::NameAvailable);
     }
+    // If the incoming code ptr is null, we ensure that the flags are set
+    // correctly
     if (codeptr) {
       flags |= (uint64_t)payload_flag_t::CodePointerAvailable;
     }
   }
 
-  //  When the end user opts out of preserving the code location information and
-  //  the KernelInfo is not available from the given entry point, we will rely
-  //  on dynamic backtrace as a possibility. In this case, we send in the
-  //  caller/callee information as a string in the form "caller->callee" that
-  //  will be used to generate the unique ID.
+  ///
+  /// @brief Constructs a payload_t with a name, stack trace, and code pointer.
+  ///
+  /// @details
+  /// Used when code location information is not preserved and dynamic backtrace
+  /// is used. Initializes the payload with the provided kernel name,
+  /// caller-callee stack trace, and code pointer. Sets flags to indicate which
+  /// fields are available.
+  ///
+  /// When the end user opts out of preserving the code location information and
+  /// the KernelInfo is not available from the given entry point, we will rely
+  /// on dynamic backtrace as a possibility. In this case, we send in the
+  /// caller/callee information as a string in the form "caller->callee" that
+  /// will be used to generate the unique ID.
+  ///
+  /// @param kname Name of the kernel or function.
+  /// @param caller_callee String representing the caller->callee relationship.
+  /// @param codeptr Pointer to the code location associated with this payload.
+  ///
   payload_t(const char *kname, const char *caller_callee, const void *codeptr) {
     if (codeptr) {
-      code_ptr_va = codeptr;
+      code_ptr_va = codeptr; ///< Override the default initialization
       flags |= (uint64_t)payload_flag_t::CodePointerAvailable;
     }
-    /// Capture the rest of the parameters
+    // If the incoming name is null, we ensure that the flags are set correctly
     if (kname) {
-      name = kname;
+      name = kname; ///< Override the default initialization
       flags |= (uint64_t)payload_flag_t::NameAvailable;
     }
     if (caller_callee) {
@@ -517,34 +562,69 @@ struct payload_t {
     }
   }
 
-  //  We need the payload to contain at the very least, the code pointer
-  //  information of the kernel or function. In the full payload case, we will
-  //  also have the function name and source file name along with the line and
-  //  column number of the trace point that forms the payload.
+  ///
+  /// @brief Constructs a fully populated payload_t.
+  ///
+  /// @details
+  /// Initializes the payload with the provided kernel name, source file, line
+  /// number, column number, and optionally a code pointer. Sets flags to
+  /// indicate which fields are available. This would constitute a fully
+  /// populated payload.
+  ///
+  /// @param kname Name of the kernel or function.
+  /// @param sf Source file name.
+  /// @param line Line number in the source file.
+  /// @param col Column number in the source file.
+  /// @param codeptr (Optional) Pointer to the code location associated with
+  /// this payload.
+  ///
   payload_t(const char *kname, const char *sf, int line, int col,
             const void *codeptr = nullptr) {
-    code_ptr_va = codeptr;
-    /// Capture the rest of the parameters
-    name = kname;
-    source_file = sf;
-    line_no = static_cast<uint32_t>(line);
-    column_no = static_cast<uint32_t>(col);
+    code_ptr_va = codeptr; ///< Override the default initialization
+    name = kname;          ///< Override the default initialization
+    source_file = sf;      ///< Override the default initialization
+    line_no =
+        static_cast<uint32_t>(line); ///< Override the default initialization
+    column_no =
+        static_cast<uint32_t>(col); ///< Override the default initialization
+    // If the incoming name is null, we ensure that the flags are set correctly
     if (kname && kname[0] != '\0') {
       flags = (uint64_t)payload_flag_t::NameAvailable;
     }
+    // If the incoming source file name is null, we ensure that the flags are
+    // set correctly
     if (sf && sf[0] != '\0') {
       flags |= (uint64_t)payload_flag_t::SourceFileAvailable |
                (uint64_t)payload_flag_t::LineInfoAvailable |
                (uint64_t)payload_flag_t::ColumnInfoAvailable;
     }
+    // If the incoming code ptr is null, we ensure that the flags are set
+    // correctly
     if (codeptr) {
       flags |= (uint64_t)payload_flag_t::CodePointerAvailable;
     }
   }
 
-  int32_t name_sid() const { return (int32_t)(uid.p2 & 0x00000000ffffffff); }
-  int32_t stacktrace_sid() const { return (int32_t)(uid.p2 >> 32); }
-  int32_t source_file_sid() const { return (int32_t)(uid.p1 >> 32); }
+  /// @brief Retrieves the string ID (SID) for the name.
+  /// @details Extracts the lower 32 bits of the uid.p2 member, which represents
+  /// the xpti::string_id_t in legacy implementations or XPTI_USE_STRICT_HASH
+  /// mode and contains the FNV1a hash value associated with the name.
+  /// @return The 32-bit name string ID.
+  uint32_t name_sid() const { return (uint32_t)(uid.p2 & 0x00000000ffffffff); }
+
+  /// @brief Retrieves the string ID (SID) for the stack trace.
+  /// @details Extracts the upper 32 bits of the uid.p2 member, which represents
+  /// the xpti::string_id_t in legacy implementations or XPTI_USE_STRICT_HASH
+  /// mode and contains the FNV1a hash value associated with the stack trace.
+  /// @return The 32-bit stack trace string ID.
+  uint32_t stacktrace_sid() const { return (uint32_t)(uid.p2 >> 32); }
+
+  /// @brief Retrieves the string ID (SID) for the source file.
+  /// @details Extracts the upper 32 bits of the uid.p1 member, which represents
+  /// the xpti::string_id_t in legacy implementations or XPTI_USE_STRICT_HASH
+  /// mode and contains the FNV1a hash value associated with the source file.
+  /// @return The 32-bit source file string ID.
+  uint32_t source_file_sid() const { return (uint32_t)(uid.p1 >> 32); }
 };
 
 /// A data structure that holds information about an API function call and its

xpti/include/xpti/xpti_trace_framework.h

@@ -696,6 +696,11 @@ XPTI_EXPORT_API const xpti_trace_event_t *xptiLookupEvent(uint64_t uid);
 /// @param column_no A uint32_t value representing the column number on the
 /// specified line where the tracepoint is located. This provides the most
 /// precise location of the tracepoint.
+/// @param code_ptr_va A void pointer representing the virtual address of the
+/// code where the tracepoint is located. This can be used to associate the
+/// tracepoint with a specific code location in memory, which is particularly
+/// useful for debugging and performance analysis. If not provided, it defaults
+/// to nullptr, indicating that the code pointer is not specified.
 ///
 /// @return A pointer to the created `xpti_tracepoint_t` structure, which
 /// represents the tracepoint. If the tracepoint cannot be created, the function
@@ -704,10 +709,10 @@ XPTI_EXPORT_API const xpti_trace_event_t *xptiLookupEvent(uint64_t uid);
 /// @note In order to preserve ABI compatibility, an interface pointer to
 /// `xpti_tracepoint_t` is returned.
 
-XPTI_EXPORT_API xpti_tracepoint_t *xptiCreateTracepoint(const char *func_name,
-                                                        const char *file_name,
-                                                        uint32_t line_no,
-                                                        uint32_t column_no);
+XPTI_EXPORT_API xpti_tracepoint_t *
+xptiCreateTracepoint(const char *func_name, const char *file_name,
+                     uint32_t line_no, uint32_t column_no,
+                     void *code_ptr_va = nullptr);
 
 /// @brief Deletes a tracepoint object.
 ///
@@ -916,12 +921,16 @@ XPTI_EXPORT_API void xptiUnsetTracepointScopeData();
 /// @param columnNo The column number in the source file where the trace point
 ///                 is defined. If column information is not available, this can
 ///                 be set to 0.
+/// @param codePtrVa The code pointer value associated with the trace point.
+///                 If code pointer information is not available, this can
+///                 be set to nullptr.
 /// @return Returns a pointer to the registered `xpti_tracepoint_t` structure if
 ///                 the registration is successful; otherwise, returns NULL. The
 ///                 returned pointer should not be freed by the caller.
 XPTI_EXPORT_API const xpti_tracepoint_t *
 xptiRegisterTracepointScope(const char *funcName, const char *fileName,
-                            uint32_t lineNo, uint32_t columnNo);
+                            uint32_t lineNo, uint32_t columnNo,
+                            void *codePtrVa = nullptr);
 
 /// @brief Retrieves the default stream ID.
 /// @details This function is used to get the default stream ID that is
@@ -1042,7 +1051,8 @@ typedef xpti::result_t (*xpti_make_key_from_payload_t)(xpti::payload_t *,
                                                        xpti::uid128_t *);
 typedef const xpti_tracepoint_t *(*xpti_get_trace_point_scope_data_t)();
 typedef const xpti_tracepoint_t *(*xpti_register_tracepoint_scope_t)(
-    const char *func, const char *file, uint32_t line, uint32_t col);
+    const char *func, const char *file, uint32_t line, uint32_t col,
+    void *code_ptr_va);
 typedef xpti::result_t (*xpti_set_trace_point_scope_data_t)(
     xpti_tracepoint_t *);
 typedef void (*xpti_unset_trace_point_scope_data_t)();
@@ -1059,6 +1069,6 @@ typedef const xpti_payload_t *(*xpti_lookup_payload_t)(uint64_t);
 typedef const xpti_trace_event_t *(*xpti_lookup_event_t)(uint64_t);
 typedef xpti_tracepoint_t *(*xpti_create_tracepoint_t)(const char *,
                                                        const char *, uint32_t,
-                                                       uint32_t);
+                                                       uint32_t, void *);
 typedef xpti::result_t (*xpti_delete_tracepoint_t)(xpti_tracepoint_t *);
 }

xpti/include/xpti/xpti_trace_framework.hpp

@@ -56,6 +56,8 @@ typedef void *xpti_plugin_function_t;
 #endif
 
 namespace xpti {
+constexpr const char *g_unknown_function = "<unknown-function>";
+constexpr const char *g_unknown_file = "<unknown-file>";
 namespace utils {
 /// @class StringHelper
 /// @brief A helper class for string manipulations.
@@ -575,12 +577,28 @@ inline std::string readMetadata(const metadata_t::value_type &MD) {
 inline bool is_valid_payload(const xpti::payload_t *Payload) {
   if (!Payload)
     return false;
-  else
-    return (Payload->flags != 0) &&
-           ((Payload->flags &
-                 static_cast<uint64_t>(payload_flag_t::SourceFileAvailable) ||
-             (Payload->flags &
-              static_cast<uint64_t>(payload_flag_t::NameAvailable))));
+  else {
+    bool isValid = false;
+    bool hasSourceFile =
+        (Payload->flags &
+         static_cast<uint64_t>(payload_flag_t::SourceFileAvailable)) &&
+        Payload->source_file;
+    bool hasName = (Payload->flags &
+                    static_cast<uint64_t>(payload_flag_t::NameAvailable)) &&
+                   Payload->name;
+    bool hasCodePtrVa =
+        (Payload->flags &
+         static_cast<uint64_t>(payload_flag_t::CodePointerAvailable)) &&
+        Payload->code_ptr_va;
+    bool hasLineInfo =
+        (Payload->flags &
+         static_cast<uint64_t>(payload_flag_t::LineInfoAvailable)) &&
+        Payload->line_no != xpti::invalid_id<uint32_t>;
+    // We ignore checking for column info as it may not always be available
+    isValid = ((hasSourceFile && hasLineInfo) || hasName || hasCodePtrVa);
+
+    return isValid;
+  }
 }
 
 /// @brief Generates a default payload object with unknown details.
@@ -595,11 +613,11 @@ inline bool is_valid_payload(const xpti::payload_t *Payload) {
 ///
 /// @return A `xpti::payload_t` object with its members set to represent an
 /// unknown or unspecified payload. This includes setting the function name and
-/// file name to "unknown", line and column numbers to 0, and the module handle
-/// to nullptr.
+/// file name to "<unknown-function>" and "<unknown-file>" respectively, line
+/// and column numbers to 0, and the module handle to nullptr.
 ///
 inline xpti::payload_t unknown_payload() {
-  xpti::payload_t Payload("unknown", "unknown-file", 0, 0, nullptr);
+  xpti::payload_t Payload(g_unknown_function, g_unknown_file, 0, 0, nullptr);
   return Payload;
 }
 
@@ -951,7 +969,8 @@ class tracepoint_scope_t {
   /// @note MSFT compiler 2019/2022 support __builtin_FUNCTION() macro
   ///
   tracepoint_scope_t(const char *fileName, const char *funcName, int line,
-                     int column, bool selfNotify = false,
+                     int column, void *codePtrVa = nullptr,
+                     bool selfNotify = false,
                      const char *callerFuncName = __builtin_FUNCTION())
       : MTop(false), MSelfNotify(selfNotify), MCallerFuncName(callerFuncName) {
     if (!xptiTraceEnabled())
@@ -962,9 +981,9 @@ class tracepoint_scope_t {
     if (!MData) {
       if (funcName && fileName)
         init(funcName, fileName, static_cast<uint32_t>(line),
-             static_cast<uint32_t>(column));
+             static_cast<uint32_t>(column), codePtrVa);
       else
-        init(callerFuncName, nullptr, 0u, 0u);
+        init(callerFuncName, nullptr, 0u, 0u, codePtrVa);
     } else {
       MTraceEvent = MData->event_ref();
     }
@@ -1014,11 +1033,11 @@ class tracepoint_scope_t {
   /// tracepoint data.
   ///
   void init(const char *FuncName, const char *FileName, uint32_t LineNo,
-            uint32_t ColumnNo) {
+            uint32_t ColumnNo, void *CodePtrVa) {
     // Register the payload and prepare the tracepoint data. The function
     // returns a UID, associated payload and trace event
-    MData = const_cast<xpti_tracepoint_t *>(
-        xptiRegisterTracepointScope(FuncName, FileName, LineNo, ColumnNo));
+    MData = const_cast<xpti_tracepoint_t *>(xptiRegisterTracepointScope(
+        FuncName, FileName, LineNo, ColumnNo, CodePtrVa));
     if (MData) {
       // Set the tracepoint scope with the prepared data so all nested functions
       // will have access to it; this call also sets the Universal ID separately