diff --git a/README.md b/README.md index 24f1c8a24b..f0e91e3026 100644 --- a/README.md +++ b/README.md @@ -102,16 +102,17 @@ The user has two options for building: ```bash # Normal Build - ./build.sh --build + ./build.sh --build OR ./build.sh -b # Clean Build - ./build.sh --clean-build + ./build.sh --clean-build OR ./build.sh -cb ``` - Optionally, For testing, run the following ```bash - ./rocprofv2 -t + cd build && ./rocprofv2 -t ``` + For more information on tests, please see the Tests section - Option 2 (Where ROCM_PATH envronment need to be set with the current installation directory of rocm), run the following: @@ -156,12 +157,12 @@ The user has two options for building: ```bash cmake --build . -- check ``` + For more information on tests, please see the Tests section -## Usage -### Features +## Features & Usage -- Tools: +### Tool: - rocsys: This is a frontend command line utility to launch/start/stop/exit a session with the required application to be traced or profiled in rocprofv2 context. Usage: @@ -178,9 +179,6 @@ The user has two options for building: # Exit a session with a given identifier created at launch rocsys –session session_name exit ``` - - - Device Profiling: A device profiling session allows the user to profile the GPU device for counters irrespective of the running applications on the GPU. This is different from application profiling. device profiling session doesn't care about the host running processes and threads. It directly provides low level profiling information. - - rocprofv2: - Counters and Metric Collection: HW counters and derived metrics can be collected using following option: @@ -213,28 +211,28 @@ The user has two options for building: # HIP & HSA API and asynchronous activity and kernel dispatches tracing rocprofv2 --sys-trace ``` - + For complete usage options, please run rocprofv2 help ```bash rocprofv2 --help - ``` - - Advanced Thread Trace: It can collect kernel running time, granular hardware metrics per kernel dispatch and provide hotspot analysis at source code level via hardware tracing. + ``` + - (ATT) Advanced Thread Trace: It can collect kernel running time, granular hardware metrics per kernel dispatch and provide hotspot analysis at source code level via hardware tracing. ```bash # ATT(Advanced Thread Trace) needs few proeconditions before running. #1. Make sure to generate the assembly file for application export HIPCC_COMPILE_FLAGS_APPEND="--save-temps -g" - - #2. Install plugin package - rocprofiler-plugins_2.0.0-local_amd64.deb - + + #2. Install plugin package + see Plugin Support section for installation + #3. Additionally you might need to install few python packages.e.g: pip3 install websockets - pip3 install matplotlib + pip3 install matplotlib # Run the following to view the trace rocprofv2 --plugin att -i input.txt - + # app_assembly_file_relative_path is the assembly file with .s extension generated in 1st step # app_relative_path is the path for the application binary # input.txt gives flexibility to to target the compute unit and provide filters. @@ -246,17 +244,24 @@ The user has two options for building: - file plugin: outputs the data in txt files. - Perfetto plugin: outputs the data in protobuf format. - Adavced thread tracer plugin: advanced hardware traces data in binary format. - - Grafana plugin: streaming the data to Prometheus and Jaeger services, so that it can be used by Grafana ROCProfilerV2 dashboard, for more details please refer to [Grafana Plugin Documentation](plugins/grafana/README.md) + - ctf plugin: Outputs the data in ctf format(a binary trace format) + installtion: + ```bash + rocprofiler-plugins_2.0.0-local_amd64.deb + rocprofiler-plugins-2.0.0-local.x86_64.rpm + ``` usage: ```bash - # plugin_name can be file, perfetto, att or grafana + # plugin_name can be file, perfetto , ctf ./rocprofv2 --plugin plugin_name -i samples/input.txt ``` - Profile Replay Modes: Different replay modes are provided for flexibility to support kernel profiling. The API provides functionality for profiling GPU applications in kernel and application and user mode and also with no replay mode at all and it provides the records pool support with an easy sequence of calls, so the user can be able to profile and trace in easy small steps. Currently, Kernel replay mode is the only supported mode. +- Device Profiling: A device profiling session allows the user to profile the GPU device for counters irrespective of the running applications on the GPU. This is different from application profiling. device profiling session doesn't care about the host running processes and threads. It directly provides low level profiling information. + - Session Support: A session is a unique identifier for a profiling/tracing/pc-sampling task. A ROCProfilerV2 Session has enough information about what needs to be collected or traced and it allows the user to start/stop profiling/tracing whenever required. A simple session API usage: ```c++ @@ -266,31 +271,44 @@ The user has two options for building: // Creating the session with given replay mode rocprofiler_session_id_t session_id; rocprofiler_create_session(rocprofiler_KERNEL_REPLAY_MODE, &session_id); - - // Start Session + + // Start Session rocprofiler_start_session(session_id); - + // profile a kernel -kernelA hipLaunchKernelGGL(kernelA, dim3(1), dim3(1), 0, 0); - + // Deactivating session rocprofiler_terminate_session(session_id); // Destroy sessions rocprofiler_destroy_session(session_id); - + // Destroy all profiling related objects rocprofiler_finalize(); ``` -- Quality Control: We make use of the GoogleTest (Gtest) framework to automatically find and add test cases to the CMAKE testing environment. ROCProfilerV2 testing is categorized as following: + ## Tests: + We make use of the GoogleTest (Gtest) framework to automatically find and add test cases to the CMAKE testing environment. ROCProfilerV2 testing is categorized as following: - unittests (Gtest Based) : These includes tests for core classes. Any newly added functionality should have a unit test written to it. - featuretests (standalone and Gtest Based): These includes both API tests and tool tests. Tool is tested against different applications to make sure we have right output in evry run. - memorytests (standalone): This includes running address sanitizer for memory leaks, corruptions. -- Documentation: We make use of doxygen to autmatically generate API documentation. Generated document can be found in the following path: + installation: + ```bash + rocprofiler-tests_2.0.0-local_amd64.deb + rocprofiler-tests-2.0.0-local.x86_64.rpm + ``` + usage: + From build directory: + ```bash + ./run_tests.sh OR make -j check + ``` + +## Documentation: +We make use of doxygen to autmatically generate API documentation. Generated document can be found in the following path: ```bash # ROCM_PATH by default is /opt/rocm @@ -298,6 +316,25 @@ The user has two options for building: /share/doc/rocprofv2 ``` + installtion: + ```bash + rocprofiler-docs_2.0.0-local_amd64.deb + rocprofiler-docs-2.0.0-local.x86_64.rpm + ``` +## Samples + +- Profiling: Profiling Samples depending on replay mode +- Tracing: Tracing Samples + +insalltion: +```bash +rocprofiler-samples_2.0.0-local_amd64.deb +rocprofiler-samples-2.0.0-local.x86_64.rpm +``` +usage: + +samples can be run as independent executables once installed + ## Project Structure - Doc: Documentation settings for doxygen @@ -328,11 +365,6 @@ The user has two options for building: - Tests: Tests folder - CMakeLists.txt: Handles cmake list for the whole project -## Samples - -- Profiling: Profiling Samples depending on replay mode -- Tracing: Tracing Samples - ## Support Please report in the Github Issues diff --git a/bin/rocprofv2 b/bin/rocprofv2 index f22fb61937..e8a356ec8f 100755 --- a/bin/rocprofv2 +++ b/bin/rocprofv2 @@ -1,5 +1,5 @@ #!/bin/bash - +CURRENT_DIR="$( dirname -- "$0"; )"; ROCPROFV2_DIR=$(dirname -- $(realpath ${BASH_SOURCE[0]})); ROCM_DIR=$(dirname -- ${ROCPROFV2_DIR}) RUN_FROM_BUILD=0 @@ -74,8 +74,12 @@ while [ 1 ] ; do if [ $RUN_FROM_BUILD == 1 ]; then export ROCPROFILER_METRICS_PATH=$ROCM_DIR/build/counters/derived_counters.xml TO_CLEAN=no $ROCM_DIR/build.sh - pushd build - ./run_tests.sh + if [ "$CURRENT_DIR/build" -ef "./build" ] ; then + ./run_tests.sh + else + pushd build + ./run_tests.sh + fi exit 1 fi elif [[ "$1" = "-mt" || "$1" = "--mem-test" ]] ; then @@ -87,8 +91,12 @@ while [ 1 ] ; do elif [[ "$1" = "-ct" || "$1" = "--clean-build-test" ]] ; then if [ $RUN_FROM_BUILD == 1 ]; then TO_CLEAN=yes $ROCM_DIR/build.sh - pushd build - ./run_tests.sh + if [ "$CURRENT_DIR/build" -ef "./build" ] ; then + ./run_tests.sh + else + pushd build + ./run_tests.sh + fi exit 1 fi elif [[ "$1" = "--install" ]] ; then