doc improvements for 1.0.0 (#367)
* correcting rocprofiler_configure
* Fix indexing order
* doc feedback
[ROCm/rocprofiler-sdk commit: bbe9eab53a]
Este commit está contenido en:
Bhardwaj, Gopesh
GitHub
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 -- <application_path>
|
||||
|
||||
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 -- <application_path>
|
||||
|
||||
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}% -- <application_path>
|
||||
|
||||
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 -- <application_path>
|
||||
|
||||
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}% -- <application_path>
|
||||
|
||||
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 -- <application_path>
|
||||
|
||||
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 -- <application_path>
|
||||
|
||||
The above command generates an ``%hostname%/%pid%_hip_api_trace.csv`` file.
|
||||
|
||||
|
||||
Collection period
|
||||
+++++++++++++++++++
|
||||
|
||||
@@ -29,20 +29,20 @@ The documentation is structured as follows:
|
||||
|
||||
.. grid-item-card:: How to
|
||||
|
||||
* :doc:`Samples <how-to/samples>`
|
||||
* :ref:`using-rocprofv3`
|
||||
* :ref:`using-rocprofiler-sdk-roctx`
|
||||
* :ref:`using-pc-sampling`
|
||||
* :doc:`Samples <how-to/samples>`
|
||||
* :ref:`using-rocprofv3-with-mpi`
|
||||
* :ref:`using-pc-sampling`
|
||||
|
||||
.. grid-item-card:: API reference
|
||||
|
||||
* :doc:`Tool library <api-reference/tool_library>`
|
||||
* :ref:`runtime-intercept-tables`
|
||||
* :doc:`Buffered services <api-reference/buffered_services>`
|
||||
* :doc:`Callback services <api-reference/callback_services>`
|
||||
* :doc:`Counter collection services <api-reference/counter_collection_services>`
|
||||
* :ref:`runtime-intercept-tables`
|
||||
* :doc:`PC sampling <api-reference/pc_sampling>`
|
||||
* :doc:`Tool library <api-reference/tool_library>`
|
||||
* :doc:`ROCprofiler-SDK API library <_doxygen/rocprofiler-sdk/html/index>`
|
||||
* :doc:`ROCTx API library <_doxygen/roctx/html/index>`
|
||||
|
||||
|
||||
Referencia en una nueva incidencia
Block a user