attach: Formalize ROCAttach API (#1653)

* attach: Formalize ROCAttach API

- Make ROCAttach public with public headers
- Change detach to take a PID
  - attach and detach are now reentrant
- Cleanup of states and signal handling in ptrace session
- Fixes mixed up definition of ROCPROF_ATTACH_TOOL_LIBRARY
  - ROCPROF_ATTACH_TOOL_LIBRARY now always means the tool library loaded by the attachment target
  - ROCPROF_ATTACH_LIBRARY refers to the library used to perform attachment
- Add direct call of rocprof-attach
- Fix python library call of rocprof-attach
  - Function now named attach(), changed from main()

* attach: rocprof-compute ROCAttach updates

- Update to new library names
- Correct usage of C lib detach

* attach: add test for rocattach

- Disable ASan, TSan, and UBSan for the new parallel-attach test
- Lower log level for LSan tests, existing behavior from other tests

---------

Co-authored-by: Ammar ELWazir <aelwazir@amd.com>
This commit is contained in:
Mark Meserve
2026-01-15 14:32:14 -06:00
committed by GitHub
parent 2482bff0b7
commit 8760fb4976
26 changed files with 2426 additions and 795 deletions
@@ -4,5 +4,6 @@
set(CMAKE_INSTALL_DEFAULT_COMPONENT_NAME "development")
add_subdirectory(rocprofiler-sdk)
add_subdirectory(rocprofiler-sdk-rocattach)
add_subdirectory(rocprofiler-sdk-roctx)
add_subdirectory(rocprofiler-sdk-rocpd)
@@ -0,0 +1,18 @@
#
#
# Installation of public headers
#
#
configure_file(${CMAKE_CURRENT_LIST_DIR}/version.h.in
${CMAKE_CURRENT_BINARY_DIR}/version.h @ONLY)
set(ROCATTACH_HEADER_FILES
# core headers
rocattach.h
# secondary headers
defines.h types.h ${CMAKE_CURRENT_BINARY_DIR}/version.h)
install(
FILES ${ROCATTACH_HEADER_FILES}
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/rocprofiler-sdk-rocattach
COMPONENT rocattach)
@@ -0,0 +1,116 @@
// MIT License
//
// Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
#pragma once
/**
* @defgroup SYMBOL_VERSIONING_GROUP Symbol Versions
*
* @brief The names used for the shared library versioned symbols.
*
* Every function is annotated with one of the version macros defined in this
* section. Each macro specifies a corresponding symbol version string. After
* dynamically loading the shared library with @p dlopen, the address of each
* function can be obtained using @p dlsym with the name of the function and
* its corresponding symbol version string. An error will be reported by @p
* dlvsym if the installed library does not support the version for the
* function specified in this version of the interface.
*
* @{
*/
/**
* @brief The function was introduced in version 0.0 of the interface and has the
* symbol version string of ``"ROCPROFILER_SDK_ROCATTACH_0.0"``.
*/
#define ROCPROFILER_SDK_ROCATTACH_VERSION_0_0
/** @} */
#if !defined(ROCATTACH_ATTRIBUTE)
# if defined(_MSC_VER)
# define ROCATTACH_ATTRIBUTE(...) __declspec(__VA_ARGS__)
# else
# define ROCATTACH_ATTRIBUTE(...) __attribute__((__VA_ARGS__))
# endif
#endif
#if !defined(ROCATTACH_PUBLIC_API)
# if defined(_MSC_VER)
# define ROCATTACH_PUBLIC_API ROCATTACH_ATTRIBUTE(dllexport)
# else
# define ROCATTACH_PUBLIC_API ROCATTACH_ATTRIBUTE(visibility("default"))
# endif
#endif
#if !defined(ROCATTACH_HIDDEN_API)
# if defined(_MSC_VER)
# define ROCATTACH_HIDDEN_API
# else
# define ROCATTACH_HIDDEN_API ROCATTACH_ATTRIBUTE(visibility("hidden"))
# endif
#endif
#if !defined(ROCATTACH_EXPORT_DECORATOR)
# define ROCATTACH_EXPORT_DECORATOR ROCATTACH_PUBLIC_API
#endif
#if !defined(ROCATTACH_IMPORT_DECORATOR)
# if defined(_MSC_VER)
# define ROCATTACH_IMPORT_DECORATOR ROCATTACH_ATTRIBUTE(dllimport)
# else
# define ROCATTACH_IMPORT_DECORATOR
# endif
#endif
#define ROCATTACH_EXPORT ROCATTACH_EXPORT_DECORATOR
#define ROCATTACH_IMPORT ROCATTACH_IMPORT_DECORATOR
#if !defined(ROCATTACH_API)
# if defined(ROCATTACH_EXPORTS)
# define ROCATTACH_API ROCATTACH_EXPORT
# else
# define ROCATTACH_API ROCATTACH_IMPORT
# endif
#endif
#if defined(__has_attribute)
# if __has_attribute(nonnull)
# define ROCATTACH_NONNULL(...) __attribute__((nonnull(__VA_ARGS__)))
# else
# define ROCATTACH_NONNULL(...)
# endif
#else
# if defined(__GNUC__)
# define ROCATTACH_NONNULL(...) __attribute__((nonnull(__VA_ARGS__)))
# else
# define ROCATTACH_NONNULL(...)
# endif
#endif
#ifdef __cplusplus
# define ROCATTACH_EXTERN_C_INIT extern "C" {
# define ROCATTACH_EXTERN_C_FINI }
#else
# define ROCATTACH_EXTERN_C_INIT
# define ROCATTACH_EXTERN_C_FINI
#endif
@@ -0,0 +1,136 @@
// MIT License
//
// Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
#pragma once
/**
* @file rocattach.h
* @brief rocAttach API interface for AMD profiling data analysis
*
* @mainpage rocAttach API Specification
*
*/
#include "rocprofiler-sdk-rocattach/defines.h"
#include "rocprofiler-sdk-rocattach/types.h"
/**
* @defgroup VERSIONING_GROUP Library Versioning
* @brief Version information about the interface and the associated installed library.
*
* The semantic version of the interface following semver.org rules. A context
* that uses this interface is only compatible with the installed library if
* the major version numbers match and the interface minor version number is
* less than or equal to the installed library minor version number.
*
* @{
*/
#include "rocprofiler-sdk-rocattach/version.h"
ROCATTACH_EXTERN_C_INIT
/**
* @fn rocattach_status_t rocattach_get_version(uint32_t* major, uint32_t* minor, uint32_t*
* patch)
* @brief Query the version of the installed library.
*
* Returns the version of the rocprofiler-sdk library loaded at runtime. This can be used to check
* if the runtime version is equal to or compatible with the version of rocprofiler-sdk used during
* compilation time. This function can be invoked before tool initialization.
*
* @param [out] major The major version number is stored if non-NULL.
* @param [out] minor The minor version number is stored if non-NULL.
* @param [out] patch The patch version number is stored if non-NULL.
* @return ::rocattach_status_t
* @retval ::ROCATTACH_STATUS_SUCCESS Always returned
*/
rocattach_status_t
rocattach_get_version(uint32_t* major, uint32_t* minor, uint32_t* patch) ROCATTACH_API;
/**
* @brief Simplified alternative to ::rocattach_get_version
*
* Returns the version of the rocprofiler-sdk library loaded at runtime. This can be used to check
* if the runtime version is equal to or compatible with the version of rocprofiler-sdk used during
* compilation time. This function can be invoked before tool initialization.
*
* @param [out] info Pointer to version triplet struct which will be populated by the function call.
* @return ::rocattach_status_t
* @retval ::ROCATTACH_STATUS_SUCCESS Always returned
*/
rocattach_status_t
rocattach_get_version_triplet(rocattach_version_triplet_t* info) ROCATTACH_API ROCATTACH_NONNULL(1);
/**
* @brief Attach to a process ID
*
* Attempts to attach to a rocm process at the given process identifier (PID). If successful, the
* target process will then load rocprofiler-sdk, which will subsequently load any tool libraries
* given in the environment variable ROCP_TOOL_LIBRARIES.
*
* @param [in] pid Process ID to attach to
* @return ::rocattach_status_t
* @retval ::ROCATTACH_STATUS_SUCCESS Attachment successful
*/
rocattach_status_t
rocattach_attach(int pid) ROCATTACH_API;
/**
* @brief Detach a previous attachment
*
* Detaches from a previous
*
* @param [in] pid Process ID to detach from
* @return ::rocattach_status_t
* @retval ::ROCATTACH_STATUS_SUCCESS Attachment successful
*/
rocattach_status_t
rocattach_detach(int pid) ROCATTACH_API;
/**
* @defgroup MISCELLANEOUS_GROUP Miscellaneous Utility Functions
* @brief utility functions for library
* @{
*/
/**
* @fn const char* rocattach_get_status_name(rocattach_status_t status)
* @brief Return the string encoding of ::rocattach_status_t value
* @param [in] status error code value
* @return Will return a nullptr if invalid/unsupported ::rocattach_status_t value is provided.
*/
const char*
rocattach_get_status_name(rocattach_status_t status) ROCATTACH_API;
/**
* @fn const char* rocattach_get_status_string(rocattach_status_t status)
* @brief Return the message associated with ::rocattach_status_t value
* @param [in] status error code value
* @return Will return a nullptr if invalid/unsupported ::rocattach_status_t value is provided.
*/
const char*
rocattach_get_status_string(rocattach_status_t status) ROCATTACH_API;
/** @} */
ROCATTACH_EXTERN_C_FINI
@@ -0,0 +1,81 @@
// MIT License
//
// Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
#pragma once
#include "rocprofiler-sdk-rocattach/defines.h"
#include <stdint.h>
/** @defgroup DATA_TYPE rocAttach Data types
*
* Data types defined or aliased by rocAttach
*
* @{
*/
//--------------------------------------------------------------------------------------//
//
// ENUMERATIONS
//
//--------------------------------------------------------------------------------------//
/**
* @defgroup BASIC_DATA_TYPES Basic data types
* @brief Basic data types and typedefs
*
* @{
*/
/**
* @brief Status codes.
*/
typedef enum rocattach_status_t // NOLINT(performance-enum-size)
{
ROCATTACH_STATUS_SUCCESS = 0, ///< No error occurred
ROCATTACH_STATUS_ERROR, ///< Generalized error
ROCATTACH_STATUS_ERROR_INVALID_ARGUMENT, ///< Invalid function argument
ROCATTACH_STATUS_ERROR_NOT_SUPPORTED, ///< Attachment is not supported on this platform
ROCATTACH_STATUS_ERROR_PTRACE_ERROR, ///< General ptrace error
ROCATTACH_STATUS_ERROR_PTRACE_OPERATION_NOT_PERMITTED, ///< ptrace returned EPERM, operation
///< not permitted
ROCATTACH_STATUS_ERROR_PTRACE_PROCESS_NOT_FOUND, ///< ptrace returned ESRCH, no such process
ROCATTACH_STATUS_LAST,
} rocattach_status_t;
//--------------------------------------------------------------------------------------//
//
// STRUCTS
//
//--------------------------------------------------------------------------------------//
/**
* @brief Versioning info.
*/
typedef struct rocattach_version_triplet_t
{
uint32_t major;
uint32_t minor;
uint32_t patch;
} rocattach_version_triplet_t;
/** @} */
@@ -0,0 +1,115 @@
// MIT License
//
// Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
#pragma once
/**
* @def ROCATTACH_IS_ROCPROFILER_SDK
* @brief Preprocessor define indicating the rocattach header is a rocprofiler-sdk project
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_VERSION_MAJOR
* @brief The major version of the interface as a macro so it can be used
* by the preprocessor.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_VERSION_MINOR
* @brief The minor version of the interface as a macro so it can be used
* by the preprocessor.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_VERSION_PATCH
* @brief The patch version of the interface as a macro so it can be used
* by the preprocessor.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_VERSION
* @brief Numerically increasing version number encoding major, minor, and patch via
computing `((10000 * <MAJOR>) + (100 * <MINOR>) + <PATCH>)`.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_SOVERSION
* @brief Shared object versioning value whose value is at least `(10000 * <MAJOR>)`.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_VERSION_STRING
* @brief Version string in form: `<MAJOR>.<MINOR>.<PATCH>`.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_GIT_DESCRIBE
* @brief String encoding of `git describe --tags` when rocprofiler was built.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_GIT_REVISION
* @brief String encoding of `git rev-parse HEAD` when rocprofiler was built.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_LIBRARY_ARCH
* @brief Architecture triplet of rocprofiler build.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_SYSTEM_NAME
* @brief Target operating system for rocprofiler build, e.g. Linux.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_SYSTEM_PROCESSOR
* @brief Target architecture for rocprofiler build.
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_SYSTEM_VERSION
* @brief Version of the operating system which built rocprofiler
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_COMPILER_ID
* @brief C++ compiler identifier which built rocprofiler, e.g., GNU
* @addtogroup VERSIONING_GROUP
*
* @def ROCATTACH_COMPILER_VERSION
* @brief C++ compiler version which built rocprofiler
* @addtogroup VERSIONING_GROUP
*/
#define ROCATTACH_IS_ROCPROFILER_SDK 1
// clang-format off
#define ROCATTACH_VERSION_MAJOR @PROJECT_VERSION_MAJOR@
#define ROCATTACH_VERSION_MINOR @PROJECT_VERSION_MINOR@
#define ROCATTACH_VERSION_PATCH @PROJECT_VERSION_PATCH@
#define ROCATTACH_SOVERSION (10000 * @PROJECT_VERSION_MAJOR@)
#define ROCATTACH_VERSION_STRING "@FULL_VERSION_STRING@"
#define ROCATTACH_GIT_DESCRIBE "@ROCPROFILER_SDK_GIT_DESCRIBE@"
#define ROCATTACH_GIT_REVISION "@ROCPROFILER_SDK_GIT_REVISION@"
// system info during compilation
#define ROCATTACH_LIBRARY_ARCH "@CMAKE_LIBRARY_ARCHITECTURE@"
#define ROCATTACH_SYSTEM_NAME "@CMAKE_SYSTEM_NAME@"
#define ROCATTACH_SYSTEM_PROCESSOR "@CMAKE_SYSTEM_PROCESSOR@"
#define ROCATTACH_SYSTEM_VERSION "@CMAKE_SYSTEM_VERSION@"
// compiler information
#define ROCATTACH_COMPILER_ID "@CMAKE_CXX_COMPILER_ID@"
#define ROCATTACH_COMPILER_VERSION "@CMAKE_CXX_COMPILER_VERSION@"
// clang-format on
#define ROCATTACH_VERSION \
((10000 * ROCATTACH_VERSION_MAJOR) + (100 * ROCATTACH_VERSION_MINOR) + ROCATTACH_VERSION_PATCH)