From e55c31db27096436475254391f35b487efec3147 Mon Sep 17 00:00:00 2001 From: "Bhardwaj, Gopesh" Date: Wed, 28 May 2025 09:09:21 +0530 Subject: [PATCH] SWDEV-533894 Documentation for python bindings (#404) * SWDEV-533894 Documenation for python bindings * Fixing missing-new line check * Addressed Feedback [ROCm/rocprofiler-sdk commit: 7f7827fb30f560273bf70d6f399b79d116c8ac94] --- .../source/docs/data/python_bindings.csv | 7 ++ .../how-to/using-rocprofiler-sdk-roctx.rst | 103 ++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 projects/rocprofiler-sdk/source/docs/data/python_bindings.csv diff --git a/projects/rocprofiler-sdk/source/docs/data/python_bindings.csv b/projects/rocprofiler-sdk/source/docs/data/python_bindings.csv new file mode 100644 index 0000000000..803b3589ff --- /dev/null +++ b/projects/rocprofiler-sdk/source/docs/data/python_bindings.csv @@ -0,0 +1,7 @@ +"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp" +"MARKER_CORE_API","MatrixTranspose: rows=4, cols=5",15964,15964,1,1392141764711512,1392141764711512 +"MARKER_CORE_API","generate_matrix(rows=4, cols=5)",15964,15964,4,1392141765500646,1392141765523276 +"MARKER_CORE_API","transpose(nrows=4, ncols=5)",15964,15964,7,1392141765527536,1392141765531786 +"MARKER_CORE_API","matrix_transpose",15964,15964,6,1392141765525156,1392141765532696 +"MARKER_CORE_API","run(rows=4, cols=5)",15964,15964,3,1392141765498106,1392141765534186 +"MARKER_CORE_API","main",15964,15964,2,1392141765494795,1392141765574506 diff --git a/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofiler-sdk-roctx.rst b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofiler-sdk-roctx.rst index 161fb89e66..94ba3e66a1 100644 --- a/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofiler-sdk-roctx.rst +++ b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofiler-sdk-roctx.rst @@ -188,3 +188,106 @@ The following table lists the APIs available for labeling the given resources: * - HSA runtime - ``roctxNameHsaAgent(const char* name, const struct hsa_agent_s*)`` - Labels the given HSA agent with the given name in the output. + +Using ROCTx in the python application +++++++++++++++++++++++++++++++++++++++ + +ROCTx APIs can be used in a python application using the ``roctx`` module. The APIs are available as functions in the module. The API names are prefixed with ``roctx`` to avoid name conflicts with other libraries. + +The following sample code from the MatrixTranspose application shows the usage of ROCTx APIs in a python application: + +.. code-block:: python + + import os + import roctx + import random + from roctx.context_decorators import RoctxRange + + _prefix = os.path.basename(__file__) + + @RoctxRange("matrix_transpose") + def matrix_transpose(matrix): + nrows = len(matrix) + ncols = len(matrix[0]) if nrows > 0 else 0 + with RoctxRange(f"transpose(nrows={nrows}, ncols={ncols})"): + # Transpose the matrix + transposed = [[matrix[j][i] for j in range(nrows)] for i in range(ncols)] + return transposed + + def generate_matrix(rows, cols): + with RoctxRange(f"generate_matrix(rows={rows}, cols={cols})"): + return [[random.randint(0, 100) for _ in range(cols)] for _ in range(rows)] + + def run(rows, cols): + idx = roctx.rangeStart(f"run(rows={rows}, cols={cols})") + matrix = generate_matrix(rows, cols) + transposed = matrix_transpose(matrix) + roctx.rangeStop(idx) + return matrix, transposed + + if __name__ == "__main__": + import argparse + + parser = argparse.ArgumentParser() + parser.add_argument("-r", "--rows", type=int, default=4, help="Number of rows") + parser.add_argument("-c", "--cols", type=int, default=5, help="Number of columns") + args = parser.parse_args() + + roctx.mark(f"MatrixTranspose: rows={args.rows}, cols={args.cols}") + with RoctxRange("main"): + matrix, transposed = run(args.rows, args.cols) + print(f"[{_prefix}] Original matrix:") + for row in matrix: + print(row) + print(f"\n[{_prefix}] Transposed matrix:") + for row in transposed: + print(row) + + +Before using the ``roctx`` module for python application, ensure that the ``roctx`` module is built, installed and available in your python environment. + +An example to build and install ``roctx`` module is as follows: + +.. code-block:: shell + + cmake -B build-sdk -DCMAKE_INSTALL_PREFIX=/opt/rocm -DROCPROFILER_PYTHON_VERSIONS="3.10" -DCMAKE_PREFIX_PATH=/opt/rocm + +If you are using a different python version, replace ``3.10`` with the appropriate version in the above command. +Multiple python versions can be specified in the ``ROCPROFILER_PYTHON_VERSIONS`` variable. The roctx module will be built and installed for all the specified python versions. + +.. code-block:: shell + + ``cmake -B build-sdk -DCMAKE_INSTALL_PREFIX=/opt/rocm -DROCPROFILER_PYTHON_VERSIONS="3.8;3.9;3.10;3.11;3.12" -DCMAKE_PREFIX_PATH=/opt/rocm`` + +Based on the python major.minor version and the roctx module install path ("/opt/rocm" in above example), set the ``PYTHONPATH`` environment variable to include the path to the ``roctx`` module. + +.. code-block:: shell + + export PYTHONPATH="/lib/pythonX.Y/site-packages:$PYTHONPATH" + +Above example will install the roctx module in ``/opt/rocm/lib/python3.10/site-packages``, set the ``PYTHONPATH`` as follows: + +.. code-block:: shell + + export PYTHONPATH=/opt/rocm/lib/python3.10/site-packages:$PYTHONPATH + + +Once the ``PYTHONPATH`` is set, user should be able to import the `roctx` package: + +.. code-block:: shell + + python3 -c "import roctx" + +User can profile the python application which is annotated with ROCTx markers using ``rocprofv3`` as follows: + +.. code-block:: shell + + rocprofv3 --marker-trace -- $(which python) + +The preceding command generates a ``marker_api_trace.csv`` file prefixed with the process ID. + +.. csv-table:: Marker api trace for python application + :file: /data/python_bindings.csv + :widths: 10,10,10,10,10,20,20 + :header-rows: 1 +