From 63c5f87b85b9c145e0035ad6faec71fd994ab340 Mon Sep 17 00:00:00 2001 From: Gopesh Bhardwaj Date: Thu, 17 Oct 2024 13:28:53 +0530 Subject: [PATCH] rocprofv3: docs and help menu updates (#1129) * doc updates * Correcting ROCtx information * Making ROCTx string consistent * missing occurence [ROCm/rocprofiler-sdk commit: 320427b5f5a56110cb16289cde55d9768de18518] --- projects/rocprofiler-sdk/README.md | 2 +- .../rocprofiler-sdk/source/bin/rocprofv3.py | 6 +++--- .../comparing-with-legacy-tools.rst | 2 +- .../source/docs/how-to/using-rocprofv3.rst | 20 +++++++++++++------ .../include/rocprofiler-sdk-roctx/roctx.h | 12 +++++------ .../include/rocprofiler-sdk-roctx/types.h | 8 ++++---- .../source/lib/rocprofiler-sdk/hsa/hsa.cpp | 2 +- .../lib/rocprofiler-sdk/registration.cpp | 4 ++-- .../bin/simple-transpose/simple-transpose.cpp | 2 +- 9 files changed, 33 insertions(+), 25 deletions(-) diff --git a/projects/rocprofiler-sdk/README.md b/projects/rocprofiler-sdk/README.md index a83678fbb5..8d2a50065d 100644 --- a/projects/rocprofiler-sdk/README.md +++ b/projects/rocprofiler-sdk/README.md @@ -17,7 +17,7 @@ ROCProfiler-SDK is AMD’s new and improved tooling infrastructure, providing a - HIP kernel tracing - HSA API tracing - HSA operation tracing -- Marker(ROCtx) tracing +- Marker(ROCTx) tracing - PC Sampling (Beta) ## Tool Support diff --git a/projects/rocprofiler-sdk/source/bin/rocprofv3.py b/projects/rocprofiler-sdk/source/bin/rocprofv3.py index 59de3d116d..e361be5d7d 100755 --- a/projects/rocprofiler-sdk/source/bin/rocprofv3.py +++ b/projects/rocprofiler-sdk/source/bin/rocprofv3.py @@ -106,7 +106,7 @@ For MPI applications (or other job launchers such as SLURM), place rocprofv3 ins io_options.add_argument( "-o", "--output-file", - help="For the output file name", + help="For the output file name. If nothing specified default path is `%%hostname%%/%%pid%%`", default=os.environ.get("ROCPROF_OUTPUT_FILE_NAME", None), type=str, required=False, @@ -114,7 +114,7 @@ For MPI applications (or other job launchers such as SLURM), place rocprofv3 ins io_options.add_argument( "-d", "--output-directory", - help="For adding output path where the output files will be saved", + help="For adding output path where the output files will be saved. If nothing specified default path is `%%hostname%%/%%pid%%`", default=os.environ.get("ROCPROF_OUTPUT_PATH", None), type=str, required=False, @@ -161,7 +161,7 @@ For MPI applications (or other job launchers such as SLURM), place rocprofv3 ins add_parser_bool_argument( basic_tracing_options, "--marker-trace", - help="For collecting Marker (ROCTx) Traces. Similar to --roctx-trace option in earlier rocprof versions but with improved ROCtx library with more features", + help="For collecting Marker (ROCTx) Traces. Similar to --roctx-trace option in earlier rocprof versions but with improved ROCTx library with more features", ) add_parser_bool_argument( basic_tracing_options, diff --git a/projects/rocprofiler-sdk/source/docs/conceptual/comparing-with-legacy-tools.rst b/projects/rocprofiler-sdk/source/docs/conceptual/comparing-with-legacy-tools.rst index 3965167f24..2fdc0253c7 100644 --- a/projects/rocprofiler-sdk/source/docs/conceptual/comparing-with-legacy-tools.rst +++ b/projects/rocprofiler-sdk/source/docs/conceptual/comparing-with-legacy-tools.rst @@ -78,7 +78,7 @@ ROCprofiler-SDK introduces a new command-line tool, `rocprofv3`, which is a more - `--roctx-trace` - `--roctx-trace` - `--marker-trace` - - Improved ROCtx library with more features + - Improved ROCTx library with more features - * - Basic tracing options - Memory Copy Trace diff --git a/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst index fef9e267d9..8c9938eee8 100644 --- a/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst +++ b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst @@ -154,7 +154,7 @@ Here is the sample of commonly used ``rocprofv3`` command-line options. Some opt - Perfetto shared memory size hint in KB. default: 64 KB - Extension -You can also see all the ``rocprofv3`` options using: +To see exhaustive list of ``rocprofv3`` options, run: .. code-block:: bash @@ -247,7 +247,7 @@ Marker trace In certain situations, such as debugging performance issues in large-scale GPU programs, API-level tracing might be too fine-grained to provide a big picture of the program execution. In such cases, it is helpful to define specific tasks to be traced. -To specify the tasks for tracing, enclose the respective source code with the API calls provided by the ``ROCTX`` library. This process is also known as instrumentation. As the scope of code for instrumentation is defined using the enclosing API calls, it is called a range. A range is a programmer-defined task that has a well-defined start and end code scope. You can also refine the scope specified within a range using further nested ranges. ``rocprofv3`` also reports the timelines for these nested ranges. +To specify the tasks for tracing, enclose the respective source code with the API calls provided by the ``ROCTx`` library. This process is also known as instrumentation. As the scope of code for instrumentation is defined using the enclosing API calls, it is called a range. A range is a programmer-defined task that has a well-defined start and end code scope. You can also refine the scope specified within a range using further nested ranges. ``rocprofv3`` also reports the timelines for these nested ranges. Here is a list of useful APIs for code instrumentation. @@ -257,10 +257,18 @@ Here is a list of useful APIs for code instrumentation. - ``roctxRangePop``: Stops the current nested range. - ``roctxRangeStop``: Stops the given range. -See how to use ``rocTX`` APIs in the MatrixTranspose application below: +.. note:: + To use ``rocprofv3`` for marker tracing, including and linking to old ROCTx works but it is recommended to switch to new ROCTx because + it has been extended with new APIs. + To use new ROCTx, please include header ``"rocprofiler-sdk-roctx/roctx.h"`` and link your application with ``librocprofiler-sdk-roctx.so``. + Above list of APIs is not exhaustive. See public header file ``"rocprofiler-sdk-roctx/roctx.h"`` for full list. + +See how to use ``ROCTx`` APIs in the MatrixTranspose application below: .. code-block:: bash - + + #include + roctxMark("before hipLaunchKernel"); int rangeId = roctxRangeStart("hipLaunchKernel range"); roctxRangePush("hipLaunchKernel"); @@ -366,7 +374,7 @@ memory operations (copies and scratch). rocprofv3 –-runtime-trace -- < app_relative_path > -Running the above command generates ``hip_api_trace.csv``, ``kernel_trace.csv``, ``memory_copy_trace.csv``, ``scratch_memory_trace.csv``,and ``marker_api_trace.csv`` (if ``rocTX`` APIs are specified in the application) files prefixed with the process ID. +Running the above command generates ``hip_api_trace.csv``, ``kernel_trace.csv``, ``memory_copy_trace.csv``, ``scratch_memory_trace.csv``,and ``marker_api_trace.csv`` (if ``ROCTx`` APIs are specified in the application) files prefixed with the process ID. System trace ++++++++++++++ @@ -377,7 +385,7 @@ This is an all-inclusive option to collect all the above-mentioned traces. rocprofv3 –-sys-trace -- < app_relative_path > -Running the above command generates ``hip_api_trace.csv``, ``hsa_api_trace.csv``, ``kernel_trace.csv``, ``memory_copy_trace.csv``, and ``marker_api_trace.csv`` (if ``rocTX`` APIs are specified in the application) files prefixed with the process ID. +Running the above command generates ``hip_api_trace.csv``, ``hsa_api_trace.csv``, ``kernel_trace.csv``, ``memory_copy_trace.csv``, and ``marker_api_trace.csv`` (if ``ROCTx`` APIs are specified in the application) files prefixed with the process ID. Scratch memory trace ++++++++++++++++++++++ diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/roctx.h b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/roctx.h index 724c0d2f77..827cff12e3 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/roctx.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/roctx.h @@ -22,16 +22,16 @@ #pragma once -/** \mainpage ROCTX API Specification +/** \mainpage ROCTx API Specification * * \section introduction Introduction - * ROCTX is a library that implements the AMD code annotation API. It provides + * ROCTx is a library that implements the AMD code annotation API. It provides * the support necessary to annotate events and code ranges in applications. */ /** * \file - * ROCTX API interface. + * ROCTx API interface. */ #include @@ -43,7 +43,7 @@ ROCTX_EXTERN_C_INIT -/** \defgroup marker_group ROCTX Markers +/** \defgroup marker_group ROCTx Markers * * Marker annotations are used to describe events in a ROCm application. * @@ -60,7 +60,7 @@ roctxMarkA(const char* message) ROCTX_API ROCTX_NONNULL(1); /** @} */ -/** \defgroup range_group ROCTX Ranges +/** \defgroup range_group ROCTx Ranges * * Range annotations are used to describe events in a ROCm application. * @@ -114,7 +114,7 @@ roctxRangeStop(roctx_range_id_t id) ROCTX_API; /** @} */ -/** \defgroup PROFILER_COMM ROCTX Application control/customization of profiling tools +/** \defgroup PROFILER_COMM ROCTx Application control/customization of profiling tools * * Applications can invoke these functions to control/customize profiling tool behavior. * diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/types.h b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/types.h index 5659f2aaca..9107afab0d 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/types.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/types.h @@ -26,7 +26,7 @@ #include -/** \defgroup DATA_TYPE ROCTX Data types +/** \defgroup DATA_TYPE ROCTx Data types * * Data types defined or aliased by ROCTx * @@ -34,20 +34,20 @@ */ /** - * ROCTX range ID. + * ROCTx range ID. * * This is the range ID used to identify start/end ranges. */ /** - * @brief ROCTX range ID. + * @brief ROCTx range ID. * * This is the range ID used to identify start/end ranges. */ typedef uint64_t roctx_range_id_t; /** - * @brief ROCTX thread ID. + * @brief ROCTx thread ID. * * This is the thread ID used to identify OS threads */ diff --git a/projects/rocprofiler-sdk/source/lib/rocprofiler-sdk/hsa/hsa.cpp b/projects/rocprofiler-sdk/source/lib/rocprofiler-sdk/hsa/hsa.cpp index 00cb3a0f9e..b119c80c71 100644 --- a/projects/rocprofiler-sdk/source/lib/rocprofiler-sdk/hsa/hsa.cpp +++ b/projects/rocprofiler-sdk/source/lib/rocprofiler-sdk/hsa/hsa.cpp @@ -626,7 +626,7 @@ update_table(const context::context_array_t& _contexts, // make sure we don't access a field that doesn't exist in input table if(_info.offset() >= _orig->version.minor_id) return; - // check to see if there are any contexts which enable this operation in the ROCTX API + // check to see if there are any contexts which enable this operation in the ROCTx API // domain if(!should_wrap_functor(_contexts, _info.callback_domain_idx, diff --git a/projects/rocprofiler-sdk/source/lib/rocprofiler-sdk/registration.cpp b/projects/rocprofiler-sdk/source/lib/rocprofiler-sdk/registration.cpp index 65d788938b..6ca4694bf0 100644 --- a/projects/rocprofiler-sdk/source/lib/rocprofiler-sdk/registration.cpp +++ b/projects/rocprofiler-sdk/source/lib/rocprofiler-sdk/registration.cpp @@ -708,7 +708,7 @@ rocprofiler_set_api_table(const char* name, static auto _once = std::once_flag{}; std::call_once(_once, rocprofiler::registration::initialize); - // pass to roctx init + // pass to ROCTx init ROCP_ERROR_IF(num_tables == 0) << "rocprofiler expected " << name << " library to pass at least one table, not " << num_tables; ROCP_ERROR_IF(tables == nullptr) << "rocprofiler expected pointer to array of tables from " @@ -813,7 +813,7 @@ rocprofiler_set_api_table(const char* name, } else if(std::string_view{name} == "roctx") { - // pass to roctx init + // pass to ROCTx init ROCP_FATAL_IF(num_tables < 3) << "rocprofiler expected ROCTX library to pass 3 API tables, not " << num_tables; ROCP_ERROR_IF(num_tables > 3) diff --git a/projects/rocprofiler-sdk/tests/bin/simple-transpose/simple-transpose.cpp b/projects/rocprofiler-sdk/tests/bin/simple-transpose/simple-transpose.cpp index b5faac265c..a4704a47f6 100644 --- a/projects/rocprofiler-sdk/tests/bin/simple-transpose/simple-transpose.cpp +++ b/projects/rocprofiler-sdk/tests/bin/simple-transpose/simple-transpose.cpp @@ -26,7 +26,7 @@ THE SOFTWARE. // hip header file #include -// roctx header file +// ROCTx header file #include #define WIDTH 1024