Gobhardw/imp doc updates

.azuredevops/rocm-ci.yml

@@ -0,0 +1,42 @@
+resources:
+  repositories:
+  - repository: pipelines_repo
+    type: github
+    endpoint: ROCm
+    name: ROCm/ROCm
+
+variables:
+- group: common
+- template: /.azuredevops/variables-global.yml@pipelines_repo
+
+trigger:
+  batch: true
+  branches:
+    include:
+    - amd-staging
+    - amd-mainline
+  paths:
+    exclude:
+    - .github
+    - ISSUE_TEMPLATE
+    - '*.md'
+    - CODEOWNERS
+    - LICENSE
+
+pr:
+  autoCancel: true
+  branches:
+    include:
+    - amd-staging
+    - amd-mainline
+  paths:
+    exclude:
+    - .github
+    - ISSUE_TEMPLATE
+    - '*.md'
+    - CODEOWNERS
+    - LICENSE
+  drafts: false
+
+jobs:
+  - template: ${{ variables.CI_COMPONENT_PATH }}/rocprofiler-sdk.yml@pipelines_repo

.github/workflows/continuous_integration.yml

@@ -64,6 +64,7 @@ jobs:
         echo "LD_LIBRARY_PATH: ${LD_LIBRARY_PATH}"
         which-realpath() { echo -e "\n$1 resolves to $(realpath $(which $1))"; echo "$($(which $1) --version &> /dev/stdout | head -n 1)"; }
         for i in python3 git cmake ctest gcc g++ gcov; do which-realpath $i; done
+        cat /opt/rocm/.info/version
         ls -la
 
     - name: Exclude PC Sampling Tests
@@ -189,6 +190,7 @@ jobs:
         echo "LD_LIBRARY_PATH: ${LD_LIBRARY_PATH}"
         which-realpath() { echo -e "\n$1 resolves to $(realpath $(which $1))"; echo "$($(which $1) --version &> /dev/stdout | head -n 1)"; }
         for i in python3 git cmake ctest gcc g++ gcov; do which-realpath $i; done
+        cat /opt/rocm/.info/version
         ls -la
 
     - name: Exclude PC Sampling Tests
@@ -356,6 +358,7 @@ jobs:
         echo "LD_LIBRARY_PATH: ${LD_LIBRARY_PATH}"
         which-realpath() { echo -e "\n$1 resolves to $(realpath $(which $1))"; echo "$($(which $1) --version &> /dev/stdout | head -n 1)"; }
         for i in python3 git cmake ctest gcc g++ gcov; do which-realpath $i; done
+        cat /opt/rocm/.info/version
         ls -la
 
     - name: Configure, Build, and Test (Total Code Coverage)
@@ -555,6 +558,7 @@ jobs:
       run: |
         which-realpath() { echo -e "\n$1 resolves to $(realpath $(which $1))"; echo "$($(which $1) --version &> /dev/stdout | head -n 1)"; }
         for i in python3 git cmake ctest gcc g++ gcov; do which-realpath $i; done
+        cat /opt/rocm/.info/version
         ls -la
 
     - name: Exclude PC Sampling Tests

CHANGELOG.md

@@ -102,9 +102,16 @@ Full documentation for ROCprofiler-SDK is available at [Click Here](source/docs/
 
 - Support `--marker-trace` on application linked against old (roctracer) ROCTx (i.e. `libroctx64.so`)
 - Replaced deprecated hipHostMalloc and hipHostFree functions with hipExtHostAlloc and hipFreeHost in when ROCm version is greater than or equal to 6.3
+- Updated `rocprofv3` `--help` options.
 
 ### Fixes
 
 - Creation of subdirection when rocprofv3 `--output-file` contains a folder path
 - Fix misaligned stores (undefined behavior) for buffer records
 - Fix crash when only scratch reporting is enabled
+- Fixed MeanOccupancy* metrics
+- Fix aborted-app validation test to properly check for hipExtHostAlloc command now that it is supported
+- Fix for SQ and GRBM metrics implicitly reduced.
+
+### Removed
+- Removed gfx8 metric definitions.

source/bin/rocprofv3.py

@@ -106,15 +106,15 @@ def add_parser_bool_argument(gparser, *args, **kwargs):
     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,
     )
     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,
@@ -129,7 +129,7 @@ def add_parser_bool_argument(gparser, *args, **kwargs):
     )
     io_options.add_argument(
         "--log-level",
-        help="Set the log level",
+        help="Set the desired log level",
         default=None,
         choices=("fatal", "error", "warning", "info", "trace", "env"),
         type=str.lower,
@@ -156,12 +156,12 @@ def add_parser_bool_argument(gparser, *args, **kwargs):
     add_parser_bool_argument(
         basic_tracing_options,
         "--hip-trace",
-        help="For collecting HIP Traces (runtime + compiler)",
+        help="Combination of --hip-runtime-trace and --hip-compiler-trace. This option only enables the tracing of the HIP API. Unlike previous iterations of rocprof, this does not enable kernel tracing, memory copy tracing, etc",
     )
     add_parser_bool_argument(
         basic_tracing_options,
         "--marker-trace",
-        help="For collecting Marker (ROCTx) Traces",
+        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,
@@ -171,22 +171,22 @@ def add_parser_bool_argument(gparser, *args, **kwargs):
     add_parser_bool_argument(
         basic_tracing_options,
         "--memory-copy-trace",
-        help="For collecting Memory Copy Traces",
+        help="For collecting Memory Copy Traces. This was part of HIP and HSA traces in previous rocprof versions but is now a separate option",
     )
     add_parser_bool_argument(
         basic_tracing_options,
         "--scratch-memory-trace",
-        help="For collecting Scratch Memory operations Traces",
+        help="For collecting Scratch Memory operations Traces. Helps in determining scratch allocations and manage them efficiently",
     )
     add_parser_bool_argument(
         basic_tracing_options,
         "--hsa-trace",
-        help="For collecting HSA Traces (core + amd + image + finalizer)",
+        help="For collecting --hsa-core-trace, --hsa-amd-trace,--hsa-image-trace and --hsa-finalizer-trace. This option only enables the tracing of the HSA API. Unlike previous iterations of rocprof, this does not enable kernel tracing, memory copy tracing, etc",
     )
     add_parser_bool_argument(
         basic_tracing_options,
         "--rccl-trace",
-        help="For collecting RCCL Traces",
+        help="For collecting RCCL(ROCm Communication Collectives Library. Also pronounced as 'Rickle' ) Traces",
     )
     add_parser_bool_argument(
         basic_tracing_options,
@@ -232,7 +232,7 @@ def add_parser_bool_argument(gparser, *args, **kwargs):
     add_parser_bool_argument(
         post_processing_options,
         "--stats",
-        help="For collecting statistics of enabled tracing types",
+        help="For collecting statistics of enabled tracing types. Must be combined with one or more tracing options. No default kernel stats unlike previous rocprof versions",
     )
     add_parser_bool_argument(
         post_processing_options,
@@ -284,12 +284,12 @@ def add_parser_bool_argument(gparser, *args, **kwargs):
         kernel_naming_options,
         "-T",
         "--truncate-kernels",
-        help="Truncate the demangled kernel names",
+        help="Truncate the demangled kernel names. In earlier rocprof versions, this was known as --basenames [on/off]",
     )
     add_parser_bool_argument(
         kernel_naming_options,
         "--kernel-rename",
-        help="Use region names defined by roctxRangePush/roctxRangePop regions to rename the kernels",
+        help="Use region names defined by roctxRangePush/roctxRangePop regions to rename the kernels. Known as --roctx-rename in earlier rocprof versions",
     )
 
     filter_options = parser.add_argument_group("Filtering options")
@@ -354,7 +354,7 @@ def add_parser_bool_argument(gparser, *args, **kwargs):
         display_options,
         "-L",
         "--list-metrics",
-        help="List metrics for counter collection",
+        help="List metrics for counter collection. Backed by a valid YAML file. In earlier rocprof versions, this was known as --list-basic, --list-derived and --list-counters",
     )
 
     advanced_options = parser.add_argument_group("Advanced options")

source/docs/api-reference/buffered_services.md

@@ -248,4 +248,4 @@ function. One can also iterate over all the buffer tracing kinds and operations
 `rocprofiler_iterate_buffer_tracing_kinds` and `rocprofiler_iterate_buffer_tracing_kind_operations` functions.
 
 The buffer tracing record data types can be found in the `rocprofiler-sdk/buffer_tracing.h` header
-(`source/include/rocprofiler-sdk/buffer_tracing.h` in the [rocprofiler-sdk GitHub repository](https://github.com/ROCm/rocproifler-sdk)).
+(`source/include/rocprofiler-sdk/buffer_tracing.h` in the [rocprofiler-sdk GitHub repository](https://github.com/ROCm/rocprofiler-sdk)).

source/docs/data/memory_copy_trace.csv

@@ -1,3 +1,3 @@
 "Kind","Direction","Source_Agent_Id","Destination_Agent_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
-"MEMORY_COPY","HOST_TO_DEVICE",0,1,0,14955949675563,14955950239443
-"MEMORY_COPY","DEVICE_TO_HOST",1,0,0,14955952733485,14955953315285
+"MEMORY_COPY","MEMORY_COPY_HOST_TO_DEVICE",0,1,0,14955949675563,14955950239443
+"MEMORY_COPY","MEMORY_COPY_DEVICE_TO_HOST",1,0,0,14955952733485,14955953315285

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
 
@@ -257,10 +257,16 @@ Here is a list of useful APIs for code instrumentation.
 - ``roctxRangePop``: Stops the current nested range.
 - ``roctxRangeStop``: Stops the given range.
 
+.. note::
+  Above list is not exhaustive. See public header file <rocprofiler-sdk-roctx/roctx.h> for more APIs.
+  To use ``rocprofv3`` for marker tracing, please include header <rocprofiler-sdk-roctx/roctx.h> and link your application with ``librocprofiler-sdk-roctx.so``.
+
 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");

source/include/rocprofiler-sdk/CMakeLists.txt

@@ -29,6 +29,7 @@ set(ROCPROFILER_HEADER_FILES
     pc_sampling.h
     profile_config.h
     registration.h
+    rccl.h
     spm.h
     ${CMAKE_CURRENT_BINARY_DIR}/version.h)
 

source/include/rocprofiler-sdk/rccl/details/rccl.h

@@ -35,7 +35,7 @@ extern "C" {
 /*! @brief      Opaque handle to communicator
     @details    A communicator contains information required to facilitate collective communications
    calls */
-typedef struct ncclComm* ncclComm_t;
+typedef const struct ncclComm* ncclComm_t;
 #define NCCL_COMM_NULL NULL
 
 #define NCCL_UNIQUE_ID_BYTES 128

source/lib/rocprofiler-sdk-tool/generateCSV.cpp

@@ -487,7 +487,7 @@ generate_csv(tool_table*                                                     too
     for(const auto& record : data)
     {
         auto kernel_id          = record.dispatch_data.dispatch_info.kernel_id;
-        auto counter_name_value = std::map<std::string, uint64_t>{};
+        auto counter_name_value = std::map<std::string, double>{};
         for(uint64_t i = 0; i < record.counter_count; i++)
         {
             const auto& count        = record.records.at(i);
@@ -496,7 +496,7 @@ generate_csv(tool_table*                                                     too
             auto        search       = counter_name_value.find(counter_name);
             if(search == counter_name_value.end())
                 counter_name_value.emplace(
-                    std::pair<std::string, uint64_t>{counter_name, rec.counter_value});
+                    std::pair<std::string, double>{counter_name, rec.counter_value});
             else
                 search->second = search->second + rec.counter_value;
         }

source/lib/rocprofiler-sdk-tool/helper.hpp

@@ -272,7 +272,7 @@ struct rocprofiler_tool_record_counter_t
 struct rocprofiler_tool_counter_collection_record_t
 {
     rocprofiler_profile_counting_dispatch_data_t       dispatch_data    = {};
-    std::array<rocprofiler_tool_record_counter_t, 256> records          = {};
+    std::array<rocprofiler_tool_record_counter_t, 512> records          = {};
     uint64_t                                           thread_id        = 0;
     uint64_t                                           arch_vgpr_count  = 0;
     uint64_t                                           sgpr_count       = 0;