From 821d74a2a9342ef3cdeda63661b14cd6dea62c1b Mon Sep 17 00:00:00 2001 From: Jeffrey Novotny Date: Mon, 15 Jul 2024 09:11:15 -0400 Subject: [PATCH] Additional changes and edits based on external review --- docs/conceptual/omnitrace-feature-set.rst | 2 +- docs/how-to/using-omnitrace-api.rst | 47 ++++++++++++++++------- docs/index.rst | 1 - docs/reference/compiling-cmake.rst | 28 -------------- docs/sphinx/_toc.yml.in | 3 -- 5 files changed, 35 insertions(+), 46 deletions(-) delete mode 100644 docs/reference/compiling-cmake.rst diff --git a/docs/conceptual/omnitrace-feature-set.rst b/docs/conceptual/omnitrace-feature-set.rst index 3cfa51b86..7ea52a212 100644 --- a/docs/conceptual/omnitrace-feature-set.rst +++ b/docs/conceptual/omnitrace-feature-set.rst @@ -129,7 +129,7 @@ broad picture. .. note:: For insight into the execution of individual kernels on the GPU, - use `Omniperf `_. + use `Omniperf `_. In terms of CPU analysis, Omnitrace does not target any specific vendor. It works just as well on AMD and non-AMD CPUs. diff --git a/docs/how-to/using-omnitrace-api.rst b/docs/how-to/using-omnitrace-api.rst index 6ef065877..59032e2b9 100644 --- a/docs/how-to/using-omnitrace-api.rst +++ b/docs/how-to/using-omnitrace-api.rst @@ -6,7 +6,15 @@ Using the Omnitrace API **************************************************** -The following example shows how a program invokes the Omnitrace API to analyze a program. +The following example shows how a program can use the Omnitrace API to analyze a program. + +Omnitrace user API example program +======================================== + +The Omnitrace API allows you to define custom regions to profile and trace. +The following C++ program demonstrates this technique by calling several functions from the +Omnitrace API, such as ``omnitrace_user_push_region`` and +``omnitrace_user_stop_thread_trace``. .. note:: @@ -19,13 +27,6 @@ The following example shows how a program invokes the Omnitrace API to analyze a recorded, regardless of whether ``omnitrace_user_start_*`` or ``omnitrace_user_stop_*`` has been called. -Omnitrace user API example program -======================================== - -The following C++ program demonstrates how to call several functions from the -Omnitrace API, such as ``omnitrace_user_push_region`` and -``omnitrace_user_stop_thread_trace``. - .. code-block:: shell #include @@ -154,16 +155,36 @@ Omnitrace API, such as ``omnitrace_user_push_region`` and return (*original_callbacks.push_region)(name); } +Linking the Omnitrace libraries to another program +======================================================= + +To link the ``omnitrace-user-library`` to another program, +use the following CMake and ``g++`` directives. + +CMake +------------------------------------------------------- + +.. code-block:: cmake + + find_package(omnitrace REQUIRED COMPONENTS user) + add_executable(foo foo.cpp) + target_link_libraries(foo PRIVATE omnitrace::omnitrace-user-library) + +g++ compilation +------------------------------------------------------- + +Assuming Omnitrace is installed in ``/opt/omnitrace``, use the ``g++`` compiler +to build the application. + +.. code-block:: shell + + g++ -I/opt/omnitrace foo.cpp -o foo -lomnitrace-user + Output from the API example program ======================================== First, instrument and run the program. -.. note:: - - For information on compiling and building Omnitrace, - see :doc:`Compiling Omnitrace with CMake <../reference/compiling-cmake>`. - .. code-block:: shell $ omnitrace-instrument -l --min-instructions=8 -E custom_push_region -o -- ./user-api diff --git a/docs/index.rst b/docs/index.rst index 7e57a432c..cf8aac692 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -55,7 +55,6 @@ The documentation is structured as follows: * :doc:`API library <./doxygen/html/files>` * :doc:`Functions <./doxygen/html/globals>` * :doc:`Data structures <./doxygen/html/annotated>` - * :doc:`Compiling Omnitrace with CMake <./reference/compiling-cmake>` * :doc:`Development guide <./reference/development-guide>` diff --git a/docs/reference/compiling-cmake.rst b/docs/reference/compiling-cmake.rst deleted file mode 100644 index 5589a2ce7..000000000 --- a/docs/reference/compiling-cmake.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. meta:: - :description: Omnitrace documentation and reference - :keywords: Omnitrace, ROCm, profiler, tracking, visualization, tool, Instinct, accelerator, AMD - -**************************************************** -Compiling Omnitrace with CMake -**************************************************** - -To compile and build Omnitrace, use the following CMake and ``g++`` directives. - -CMake -======================================== - -.. code-block:: cmake - - find_package(omnitrace REQUIRED COMPONENTS user) - add_executable(foo foo.cpp) - target_link_libraries(foo PRIVATE omnitrace::omnitrace-user-library) - -g++ compilation -======================================== - -Assuming Omnitrace is installed in ``/opt/omnitrace``, use the ``g++`` compiler -to build the application. - -.. code-block:: shell - - g++ -I/opt/omnitrace foo.cpp -o foo -lomnitrace-user diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 507cff404..233b44a18 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -52,9 +52,6 @@ subtrees: - caption: Reference entries: - - file: reference/compiling-cmake.rst - title: Compiling Omnitrace with CMake - - file: reference/development-guide.rst title: Development guide