rocprofv3: docs and help menu updates (#1129)

* doc updates * Correcting ROCtx information * Making ROCTx string consistent * missing occurence [ROCm/rocprofiler-sdk commit: 320427b5f5]
2024-10-17 13:28:53 +05:30
@@ -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
@@ -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,
@@ -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
@@ -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 <rocprofiler-sdk-roctx/roctx.h>
+    
    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
 ++++++++++++++++++++++
@@ -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 <stddef.h>
@@ -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.
 *
@@ -26,7 +26,7 @@

 #include <stdint.h>

-/** \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
 */
@@ -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,
@@ -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)
@@ -26,7 +26,7 @@ THE SOFTWARE.
 // hip header file
 #include <hip/hip_runtime.h>

-// roctx header file
+// ROCTx header file
 #include <rocprofiler-sdk-roctx/roctx.h>

 #define WIDTH 1024