From 707730f33d9c859eb7f8b41be0493fbfe42c93b8 Mon Sep 17 00:00:00 2001
From: Maisam Arif <maisarif@amd.com>
Date: Fri, 5 Apr 2024 02:30:08 -0500
Subject: [PATCH] Added amdsmi_get_gpu_process_info python library
 documentation

Signed-off-by: Maisam Arif <maisarif@amd.com>
Change-Id: I2218bf664a8a155e6b3085378db0fb20f3be3f70


[ROCm/amdsmi commit: 50450a2a69bfe33da51d5398deed381a340530cc]
---
 projects/amdsmi/py-interface/README.md | 60 ++++++++++++++++++++------
 1 file changed, 46 insertions(+), 14 deletions(-)

diff --git a/projects/amdsmi/py-interface/README.md b/projects/amdsmi/py-interface/README.md
index 4199f1a906..19454121ae 100644
--- a/projects/amdsmi/py-interface/README.md
+++ b/projects/amdsmi/py-interface/README.md
@@ -882,24 +882,13 @@ except AmdSmiException as e:
 
 ### amdsmi_get_gpu_process_list
 
-Description: Returns the list of processes for the given GPU.
-The list is of type `amdsmi_proc_info_t` and holds information about the running process.
+Description: Returns the list of processes running on the target GPU.
 
 Input parameters:
 
 * `processor_handle` device which to query
 
-Output: List of process processes with fields
-
-Output: Dictionary with fields
-
-Field | Description
----|---
-`name` | Name of process
-`pid` | Process ID
-`mem` | Process memory usage
-`engine_usage` | <table><thead><tr> <th> Subfield </th> <th> Description</th> </tr></thead><tbody><tr><td>`gfx`</td><td>GFX engine usage in ns</td></tr><tr><td>`enc`</td><td>Encode engine usage in ns</td></tr></tbody></table>
-`memory_usage` | <table><thead><tr> <th> Subfield </th> <th> Description</th> </tr></thead><tbody><tr><td>`gtt_mem`</td><td>GTT memory usage</td></tr><tr><td>`cpu_mem`</td><td>CPU memory usage</td></tr><tr><td>`vram_mem`</td><td>VRAM memory usage</td></tr> </tbody></table>
+Output: List of `amdsmi_proc_info_t` process objects running on the target GPU; can be empty
 
 Exceptions that can be thrown by `amdsmi_get_gpu_process_list` function:
 
@@ -921,7 +910,50 @@ try:
                 print("No processes running on this GPU")
             else:
                 for process in processes:
-                    print(process)
+                    print(amdsmi_get_gpu_process_info(device, process))
+except AmdSmiException as e:
+    print(e)
+```
+
+### amdsmi_get_gpu_process_info
+
+Description: Returns info about process given the target GPU and the corresponding `amdsmi_proc_info_t` object
+
+Input parameters:
+
+* `processor_handle` device which to query
+
+Output: Dictionary with fields
+
+Field | Description
+---|---
+`name` | Name of process
+`pid` | Process ID
+`mem` | Process memory usage
+`engine_usage` | <table><thead><tr> <th> Subfield </th> <th> Description</th> </tr></thead><tbody><tr><td>`gfx`</td><td>GFX engine usage in ns</td></tr><tr><td>`enc`</td><td>Encode engine usage in ns</td></tr></tbody></table>
+`memory_usage` | <table><thead><tr> <th> Subfield </th> <th> Description</th> </tr></thead><tbody><tr><td>`gtt_mem`</td><td>GTT memory usage</td></tr><tr><td>`cpu_mem`</td><td>CPU memory usage</td></tr><tr><td>`vram_mem`</td><td>VRAM memory usage</td></tr> </tbody></table
+
+Exceptions that can be thrown by `amdsmi_get_gpu_process_info` function:
+
+* `AmdSmiLibraryException`
+* `AmdSmiRetryException`
+* `AmdSmiParameterException`
+
+Example:
+
+```python
+try:
+    devices = amdsmi_get_processor_handles()
+    if len(devices) == 0:
+        print("No GPUs on machine")
+    else:
+        for device in devices:
+            processes = amdsmi_get_gpu_process_list(device)
+            if len(processes) == 0:
+                print("No processes running on this GPU")
+            else:
+                for process in processes:
+                    print(amdsmi_get_gpu_process_info(device, process))
 except AmdSmiException as e:
     print(e)
 ```