From 94c246eb9eac5f9079284f37b12eb519548897b3 Mon Sep 17 00:00:00 2001 From: Mark Meserve Date: Thu, 29 Jan 2026 15:46:24 -0600 Subject: [PATCH] attach: fix typos and older names in documentation (#2684) --- .../docs/api-reference/process_attachment.rst | 67 +++++++++---------- .../rocprofiler-sdk-rocattach/rocattach.h | 15 +++-- 2 files changed, 43 insertions(+), 39 deletions(-) diff --git a/projects/rocprofiler-sdk/source/docs/api-reference/process_attachment.rst b/projects/rocprofiler-sdk/source/docs/api-reference/process_attachment.rst index 8f9924bbf7..b42c764d7e 100644 --- a/projects/rocprofiler-sdk/source/docs/api-reference/process_attachment.rst +++ b/projects/rocprofiler-sdk/source/docs/api-reference/process_attachment.rst @@ -54,7 +54,7 @@ The attach function performs the entire attachment process, including attaching - **attach_duration_msec**: Optional - Length of time in milliseconds to profile for - Defaults to environment variable ROCPROF_ATTACH_DURATION - If unspecified, attachment will run until Enter is pressed or SIGINT (Ctrl+C) is received -- **attach_tool_library**: Optional - Tool library to use for attachment and detachment +- **attach_library**: Optional - Tool library to use for attachment and detachment - Default will work for nearly all applications - Defaults to environment variable ROCPROF_ATTACH_LIBRARY - If unspecified, defaults to the absolute path of librocprofiler-sdk-rocattach.so @@ -68,20 +68,20 @@ The C library ``librocprofiler-sdk-rocattach.so`` defines an attach and detach f extern "C" { // Start attachment to a target process - void attach(uint32_t pid) ROCPROFILER_EXPORT; + rocattach_status_t rocattach_attach(int pid) ROCATTACH_API; // Detach from target process and cleanup - void detach(uint32_t pid) ROCPROFILER_EXPORT; + rocattach_status_t rocattach_detach(int pid) ROCATTACH_API; } **Function Details:** -- **attach(uint32_t pid)**: Main entry point for starting attachment to a process +- **rocattach_attach(int pid)**: Main entry point for starting attachment to a process - Takes the target process ID as parameter - Initiates ptrace-based attachment sequence - Custom tool libraries can be specified in a colon delimited list with the environment variable ROCPROF_ATTACH_TOOL_LIBRARY -- **detach(uint32_t pid)**: Entry point for detaching from the target process +- **rocattach_detach(int pid)**: Entry point for detaching from the target process - Takes the target process ID as a parameter - Cleans up attachment resources and terminates profiling - A PID of 0 can be specified to detach from all processes @@ -94,14 +94,14 @@ Initial Attachment Sequence The initial attachment process roughly follows this sequence: -1. attach(pid) ← Your tool calls this +1. rocattach_attach(pid) ← Your tool calls this 2. ptrace calls rocprofiler_register_attach(env_buffer) 3. tool_library::rocprofiler_configure(...) 4. tool_library::rocprofiler_configure_attach(...) 5. tool_library::tool_init(...) 6. tool_library::tool_attach(...) 7. [Profiling and data collection...] -8. detach() ← Your tool calls this +8. rocattach_detach(pid) ← Your tool calls this 9. ptrace calls rocprofiler_register_detach() 10. tool_library::tool_detach(...) 11. [Program ends] @@ -112,11 +112,11 @@ Reattachment Sequence For reattachment to a previously attached process: -1. attach(pid) ← Your tool calls this again +1. rocattach_attach(pid) ← Your tool calls this again 2. ptrace calls rocprofiler_register_attach(env_buffer) 3. tool_library::tool_attach(...) 4. [Continued profiling and data collection...] -5. detach() ← Your tool calls this +5. rocattach_detach(pid) ← Your tool calls this 6. ptrace calls rocprofiler_register_detach() 7. tool_library::tool_detach(...) @@ -148,13 +148,15 @@ The attachment system can use any tool library. ``librocprofiler-sdk-tool.so`` i Using the Attachment Functions ============================== -Here's how to use these functions in your own attachment tool: +This is a simplified example of how to use these functions in your own attachment tool: -Basic Attachment Tool Implementation ------------------------------------- +Basic Attachment Implementation +------------------------------- .. code-block:: cpp + #include + #include #include #include @@ -163,8 +165,8 @@ Basic Attachment Tool Implementation class ROCprofilerAttachmentTool { private: void* attach_lib_handle = nullptr; - void (*attach_func)(uint32_t) = nullptr; - void (*detach_func)() = nullptr; + rocattach_status_t (*attach_func)(int) = nullptr; + rocattach_status_t (*detach_func)(int) = nullptr; public: bool initialize() { @@ -176,8 +178,8 @@ Basic Attachment Tool Implementation } // Get the attachment function pointers - attach_func = (void(*)(uint32_t))dlsym(attach_lib_handle, "attach"); - detach_func = (void(*)())dlsym(attach_lib_handle, "detach"); + attach_func = (rocattach_status_t(*)(int))dlsym(attach_lib_handle, "rocattach_attach"); + detach_func = (rocattach_status_t(*)(int))dlsym(attach_lib_handle, "rocattach_detach"); if (!attach_func || !detach_func) { std::cerr << "Failed to find attachment functions" << std::endl; @@ -187,7 +189,7 @@ Basic Attachment Tool Implementation return true; } - bool attach_to_process(pid_t pid, uint32_t duration_ms = 0) { + bool attach_to_process(pid_t pid, uint32_t duration_ms) { // Validate the target process if (kill(pid, 0) != 0) { std::cerr << "Target process " << pid << " is not accessible" << std::endl; @@ -197,22 +199,19 @@ Basic Attachment Tool Implementation std::cout << "Attaching to process " << pid << std::endl; // Start attachment - this will handle all ptrace operations - attach_func(pid); + if (!attach_func(pid)) + { + return false; + } - if (duration_ms > 0) { - // Profile for specified duration - std::cout << "Profiling for " << duration_ms << " milliseconds..." << std::endl; - std::this_thread::sleep_for(std::chrono::milliseconds(duration_ms)); + // Profile for specified duration + std::cout << "Profiling for " << duration_ms << " milliseconds..." << std::endl; + std::this_thread::sleep_for(std::chrono::milliseconds(duration_ms)); - // Stop profiling - detach_func(); - } else { - std::cout << "Profiling until process ends or manual detach..." << std::endl; - // Monitor process or wait for external signal to detach - while (kill(pid, 0) == 0) { - std::this_thread::sleep_for(std::chrono::seconds(1)); - } - detach_func(); + // Stop profiling + if (!detach_func(pid)) + { + return false; } std::cout << "Profiling completed" << std::endl; @@ -226,8 +225,8 @@ Basic Attachment Tool Implementation } }; -Complete Tool Example ---------------------- +Main Implementation +------------------- .. code-block:: cpp @@ -245,7 +244,7 @@ Complete Tool Example } pid_t target_pid = std::stoi(argv[1]); - uint32_t duration = (argc > 2) ? std::stoi(argv[2]) : 0; + uint32_t duration = (argc > 2) ? std::stoi(argv[2]) : 1000; // For this example, the tool library "librocprofiler-sdk-tool.so" is used by // default because ROCPROF_ATTACH_TOOL_LIBRARY is not set. These environment diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-rocattach/rocattach.h b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-rocattach/rocattach.h index 4ca39d2eed..c92b2d4214 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-rocattach/rocattach.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-rocattach/rocattach.h @@ -1,6 +1,6 @@ // MIT License // -// Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved. +// Copyright (c) 2025-2026 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 @@ -86,7 +86,9 @@ rocattach_get_version_triplet(rocattach_version_triplet_t* info) ROCATTACH_API R * * 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. + * given in the environment variable ROCPROF_ATTACH_TOOL_LIBRARY. This environment variable should + * be set for the attacher process before calling rocattach_attach(). It does not need to be set + * for the attachee. * * @param [in] pid Process ID to attach to * @return ::rocattach_status_t @@ -96,13 +98,16 @@ rocattach_status_t rocattach_attach(int pid) ROCATTACH_API; /** - * @brief Detach a previous attachment + * @brief Detach from a process ID * - * Detaches from a previous + * Detaches from a previous attachment to the given process identifier (PID). If successful, the + * target process pauses rocprofiler-sdk, but the library will remain loaded. The PID can be + * attached to again after detach is completed. A PID of 0 can be specified to detach from all + * current sessions. * * @param [in] pid Process ID to detach from * @return ::rocattach_status_t - * @retval ::ROCATTACH_STATUS_SUCCESS Attachment successful + * @retval ::ROCATTACH_STATUS_SUCCESS Detachment successful */ rocattach_status_t rocattach_detach(int pid) ROCATTACH_API;