diff --git a/source/docs/_toc.yml.in b/source/docs/_toc.yml.in index 7c71c2297e..d4b13f859a 100644 --- a/source/docs/_toc.yml.in +++ b/source/docs/_toc.yml.in @@ -11,26 +11,26 @@ subtrees: - file: install/installation - caption: How to entries: - - file: how-to/using-rocprofv3 - - file: how-to/using-rocprofiler-sdk-roctx - file: how-to/samples title: Samples - - file: how-to/using-pc-sampling + - file: how-to/using-rocprofv3 + - file: how-to/using-rocprofiler-sdk-roctx - file: how-to/using-rocprofv3-with-mpi + - file: how-to/using-pc-sampling - caption: API reference entries: + - file: api-reference/tool_library + title: Tool library + - file: api-reference/intercept_table + title: Runtime intercept tables - file: api-reference/buffered_services title: Buffered services - file: api-reference/callback_services title: Callback tracing services - file: api-reference/counter_collection_services title: Counter collection services - - file: api-reference/intercept_table - title: Runtime intercept tables - file: api-reference/pc_sampling title: PC sampling - - file: api-reference/tool_library - title: Tool library - file: _doxygen/rocprofiler-sdk/html/index title: ROCprofiler-SDK API library - file: _doxygen/roctx/html/index diff --git a/source/docs/api-reference/tool_library.rst b/source/docs/api-reference/tool_library.rst index 1b7153a3ea..c1b3fa845e 100644 --- a/source/docs/api-reference/tool_library.rst +++ b/source/docs/api-reference/tool_library.rst @@ -18,13 +18,13 @@ The ROCm runtimes are designed to directly communicate with a helper library nam Tool library design -------------------- -When ROCprofiler-SDK detects ``rocprofiler_configure`` in a tool's symbol table, ROCprofiler-SDK invokes ``rocprofiler-configure`` with parameters such as ROCprofiler-SDK version that invokes the function, number of tools already invoked, and a unique identifier for the tool. The tool returns a pointer to a ``rocprofiler_tool_configure_result_t`` struct, which, if non-null, provides ROCprofiler-SDK with: +When ROCprofiler-SDK detects ``rocprofiler_configure`` in a tool's symbol table, ROCprofiler-SDK invokes ``rocprofiler_configure`` with parameters such as ROCprofiler-SDK version that invokes the function, number of tools already invoked, and a unique identifier for the tool. The tool returns a pointer to a ``rocprofiler_tool_configure_result_t`` struct, which, if non-null, provides ROCprofiler-SDK with: - Function to be called for tool initialization, which is also the opportunity for context creation. - Function to be called when ROCprofiler-SDK is finalized. - A pointer to data to be provided to the tool when ROCprofiler-SDK calls the initialization and finalization functions. -ROCprofiler-SDK provides a ``rocprofiler-sdk/registration.h`` header file, which forward declares the ``rocprofiler_configure`` function with the necessary compiler function attributes to ensure that the ``rocprofiler-configure`` symbol is publicly visible. +ROCprofiler-SDK provides a ``rocprofiler-sdk/registration.h`` header file, which forward declares the ``rocprofiler_configure`` function with the necessary compiler function attributes to ensure that the ``rocprofiler_configure`` symbol is publicly visible. .. code-block:: cpp @@ -150,7 +150,7 @@ The tool can invoke this function pointer to explicitly invoke the `finalize` ca Otherwise, ROCprofiler-SDK invokes the `finalize` callback via an `atexit` handler. -Full rocprofiler-configure sample +Full rocprofiler_configure sample ---------------------------------- All the code snippets from the previous sections are combined here to demonstrate complete ROCProfiler configuration. diff --git a/source/docs/how-to/using-rocprofv3.rst b/source/docs/how-to/using-rocprofv3.rst index 3c282a21ee..299537c5a9 100644 --- a/source/docs/how-to/using-rocprofv3.rst +++ b/source/docs/how-to/using-rocprofv3.rst @@ -1243,57 +1243,6 @@ I/O control options ``rocprofv3`` provides the following options to control the output. -Output file -++++++++++++ - -To specify the output file name, use ``--output-file`` or ``-o`` option. If not specified, the output file is prefixed with the process ID by default. - -.. code-block:: shell - - rocprofv3 --hip-trace --output-file output -- - -The preceding command generates an ``output_hip_api_trace.csv`` file. - -Output directory -+++++++++++++++++ - -To specify the output directory, use ``--output-directory`` or ``-d`` option. If not specified, the default output path is ``%hostname%/%pid%``. - -.. code-block:: shell - - rocprofv3 --hip-trace --output-directory output_dir -- - -The above command generates an ``output_dir/%hostname%/%pid%_hip_api_trace.csv`` file. - -.. _output_field_format: - -The output directory option supports many placeholders such as: - -- ``%hostname%``: Machine host name -- ``%pid%``: Process ID -- ``%env{NAME}%``: Consistent with other output key formats (starts and ends with `%`) -- ``$ENV{NAME}``: Similar to CMake -- ``%q{NAME}%``: Compatibility with NVIDIA - -To see the complete list, refer to :ref:`output-prefix-keys`. - -The following example shows how to use the output directory option with placeholders: - -.. code-block:: bash - - mpirun -n 2 rocprofv3 --hip-trace -d %h.%p.%env{OMPI_COMM_WORLD_RANK}% -- - -The preceding command runs the application with ``rocprofv3`` and generates the trace file for each rank. The trace files are prefixed with hostname, process ID, and MPI rank. - -Assuming the hostname as `ubuntu-latest` and the process IDs as 3000020 and 3000019, the output file names are: - -.. code-block:: bash - - ubuntu-latest.3000020.1/ubuntu-latest/3000020_agent_info.csv - ubuntu-latest.3000019.0/ubuntu-latest/3000019_agent_info.csv - ubuntu-latest.3000020.1/ubuntu-latest/3000020_hip_api_trace.csv - ubuntu-latest.3000019.0/ubuntu-latest/3000019_hip_api_trace.csv - .. _output-prefix-keys: Output prefix keys @@ -1349,6 +1298,65 @@ Output prefix keys are useful in multiple use cases but are most helpful when de * - ``%s`` - Shorthand for ``%size%`` +Output directory ++++++++++++++++++ + +To specify the output directory, use ``--output-directory`` or ``-d`` option. If not specified, the default output path is ``%hostname%/%pid%``. + +.. code-block:: shell + + rocprofv3 --hip-trace --output-directory output_dir -- + +The above command generates an ``output_dir/%hostname%/%pid%_hip_api_trace.csv`` file. + +.. _output_field_format: + +The output directory option supports many placeholders such as: + +- ``%hostname%``: Machine host name +- ``%pid%``: Process ID +- ``%env{NAME}%``: Consistent with other output key formats (starts and ends with `%`) +- ``$ENV{NAME}``: Similar to CMake +- ``%q{NAME}%``: Compatibility with NVIDIA + +To see the complete list, refer to :ref:`output-prefix-keys`. + +The following example shows how to use the output directory option with placeholders: + +.. code-block:: bash + + mpirun -n 2 rocprofv3 --hip-trace -d %h.%p.%env{OMPI_COMM_WORLD_RANK}% -- + +The preceding command runs the application with ``rocprofv3`` and generates the trace file for each rank. The trace files are prefixed with hostname, process ID, and MPI rank. + +Assuming the hostname as `ubuntu-latest` and the process IDs as 3000020 and 3000019, the output file names are: + +.. code-block:: bash + + ubuntu-latest.3000020.1/ubuntu-latest/3000020_agent_info.csv + ubuntu-latest.3000019.0/ubuntu-latest/3000019_agent_info.csv + ubuntu-latest.3000020.1/ubuntu-latest/3000020_hip_api_trace.csv + ubuntu-latest.3000019.0/ubuntu-latest/3000019_hip_api_trace.csv + +Output file +++++++++++++ + +To specify the output file name, use ``--output-file`` or ``-o`` option. If not specified, the output file is prefixed with the process ID by default. + +.. code-block:: shell + + rocprofv3 --hip-trace --output-file output -- + +The preceding command generates an ``output_hip_api_trace.csv`` file. + +The output file name can also include placeholders such as ``%hostname%`` and ``%pid%``. For example: + +.. code-block:: shell + + rocprofv3 --hip-trace --output-file %hostname%/%pid%_hip_api_trace.csv -- + +The above command generates an ``%hostname%/%pid%_hip_api_trace.csv`` file. + Collection period +++++++++++++++++++ diff --git a/source/docs/index.rst b/source/docs/index.rst index 0949503a2b..884ec48077 100644 --- a/source/docs/index.rst +++ b/source/docs/index.rst @@ -29,20 +29,20 @@ The documentation is structured as follows: .. grid-item-card:: How to + * :doc:`Samples ` * :ref:`using-rocprofv3` * :ref:`using-rocprofiler-sdk-roctx` - * :ref:`using-pc-sampling` - * :doc:`Samples ` * :ref:`using-rocprofv3-with-mpi` + * :ref:`using-pc-sampling` .. grid-item-card:: API reference + * :doc:`Tool library ` + * :ref:`runtime-intercept-tables` * :doc:`Buffered services ` * :doc:`Callback services ` * :doc:`Counter collection services ` - * :ref:`runtime-intercept-tables` * :doc:`PC sampling ` - * :doc:`Tool library ` * :doc:`ROCprofiler-SDK API library <_doxygen/rocprofiler-sdk/html/index>` * :doc:`ROCTx API library <_doxygen/roctx/html/index>`