From 63da8d2e0814b92fe3689398a65682eb195b31f0 Mon Sep 17 00:00:00 2001 From: Maisam Arif Date: Tue, 9 Dec 2025 16:16:50 -0600 Subject: [PATCH] [SWDEV-568673] Updated Docmentation Examples for Python APIs (#2017) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [SWDEV-568673] Updated Docmentation Examples for Python APIs * amdsmi_get_processor_type * amdsmi_gpu_create_counter * amdsmi_gpu_destroy_counter Signed-off-by: Maisam Arif * [SWDEV-568997] - Updated Docmentation Examples for Python APIs * amdsmi_topo_get_p2p_status Signed-off-by: Sumanth Gavini * [SWDEV-568997] - Updated Docmentation Examples for Python APIs * [SWDEV-568997] - amdsmi_topo_get_p2p_status * [SWDEV-568990] - amdsmi_set_gpu_clk_range * [SWDEV-568987] - amdsmi_set_gpu_od_clk_info * [SWDEV-568969] - AmdSmiEventReader * [SWDEV-568964] - amdsmi_set_gpu_power_profile * [SWDEV-568953] - amdsmi_gpu_create_counter * [SWDEV-568939] - amdsmi_set_cpu_pcie_link_rate * [SWDEV-568937] - amdsmi_get_cpu_socket_lclk_dpm_level Signed-off-by: Sumanth Gavini * Fixes: SWDEV-568716 [TCT][amd-smi]: NameError: name 'handle' is not defined when calling amdsmi_get_processor_handles(handle) SWDEV-568726 [TCT][amd-smi]: TypeError: list indices must be integers or slices, not str when accessing cache_values['cache_properties'] SWDEV-568526 [TCT][amd-smi]: AMD SMI Python API Documentation Error – Incorrect variable name in sample code SWDEV-569017 [TCT][amd-smi]: correction required for amdsmi_set_clk_freq API in python API document page SWDEV-569025 [TCT][amd-smi]: amdsmi_get_link_metrics python API raises key error, correction required in python API sample documentation Signed-off-by: Joseph Narlo * Fix: SWDEV-568727 [TCT][amd-smi]: Mandatory arguements 'encoding' and 'link_name' needs to be updated in Python API Sample documentation Signed-off-by: amd-josnarlo --------- Signed-off-by: Maisam Arif Signed-off-by: Sumanth Gavini Signed-off-by: Joseph Narlo Signed-off-by: amd-josnarlo Co-authored-by: Sumanth Gavini Co-authored-by: Joseph Narlo Co-authored-by: amd-josnarlo --- projects/amdsmi/.github/CODEOWNERS | 2 +- .../amdsmi/docs/reference/amdsmi-py-api.md | 101 ++++++++++-------- 2 files changed, 58 insertions(+), 45 deletions(-) diff --git a/projects/amdsmi/.github/CODEOWNERS b/projects/amdsmi/.github/CODEOWNERS index d160084c6c..fa35e10aed 100644 --- a/projects/amdsmi/.github/CODEOWNERS +++ b/projects/amdsmi/.github/CODEOWNERS @@ -1,4 +1,4 @@ -* @maisarif_amdeng @shuzhliu_amdeng @dgalants_amdeng @charpoag_amdeng @daolivei_amdeng @marifamd @bill-shuzhou-liu @dmitrii-galantsev @charis-poag-amd @oliveiradan @gabrpham_amdeng +* @bill-shuzhou-liu @dmitrii-galantsev @charis-poag-amd @oliveiradan @marifamd @gabrpham @adam360x docs/* @ROCm/rocm-documentation *.md @ROCm/rocm-documentation diff --git a/projects/amdsmi/docs/reference/amdsmi-py-api.md b/projects/amdsmi/docs/reference/amdsmi-py-api.md index 7f39dd227e..029e45b7f6 100644 --- a/projects/amdsmi/docs/reference/amdsmi-py-api.md +++ b/projects/amdsmi/docs/reference/amdsmi-py-api.md @@ -105,7 +105,17 @@ Description: Checks the type of device with provided handle. Input parameters: device handle as an instance of `amdsmi_processor_handle` -Output: Integer, type of gpu +Output: Dictionary with fields + +Field | Content +---|--- +`processor_type` | A string representing the processor type name. + +* Possible `processor_type` values include: + * `"AMD_GPU"` - AMD GPU processor + * `"AMD_CPU"` - AMD CPU processor + * `"AMD_CPU_CORE"` - AMD CPU core processor + * `"UNKNOWN"` - Unknown processor type Exceptions that can be thrown by `amdsmi_get_processor_type` function: @@ -122,8 +132,9 @@ Example: ```python try: - type_of_GPU = amdsmi_get_processor_type(processor_handle) - if type_of_GPU == 1: + info = amdsmi_get_processor_type(processor_handle) + processor_type = info["processor_type"] + if processor_type == AmdSmiProcessorType.AMD_GPU.name: print("This is an AMD GPU") except AmdSmiException as e: print(e) @@ -689,7 +700,7 @@ Example: ```python try: - devices = amdsmi_get_processor_handles(handle) + devices = amdsmi_get_processor_handles() if len(devices) == 0: print("No GPUs on machine") else: @@ -755,12 +766,12 @@ try: else: for device in devices: cache_info = amdsmi_get_gpu_cache_info(device) - for cache_index, cache_values in cache_info.items(): - print(cache_values['cache_properties']) - print(cache_values['cache_size']) - print(cache_values['cache_level']) - print(cache_values['max_num_cu_shared']) - print(cache_values['num_cache_instance']) + for cache_values in cache_info.values(): + for cache_value in cache_values: + print(cache_value['cache_properties']) + print(cache_value['cache_level']) + print(cache_value['max_num_cu_shared']) + print(cache_value['num_cache_instance']) except AmdSmiException as e: print(e) ``` @@ -1754,7 +1765,7 @@ try: if len(devices) == 0: print("No GPUs on machine") else: - event = AmdSmiEventReader(device[0], AmdSmiEvtNotificationType.GPU_PRE_RESET, AmdSmiEvtNotificationType.GPU_POST_RESET) + event = AmdSmiEventReader(devices[0], [AmdSmiEvtNotificationType.GPU_PRE_RESET, AmdSmiEvtNotificationType.GPU_POST_RESET]) event.read(10000) except AmdSmiException as e: print(e) @@ -1770,7 +1781,7 @@ try: if len(devices) == 0: print("No GPUs on machine") else: - with AmdSmiEventReader(device[0], AmdSmiEvtNotificationType.GPU_PRE_RESET, AmdSmiEvtNotificationType.GPU_POST_RESET) as event: + with AmdSmiEventReader(devices[0], [AmdSmiEvtNotificationType.GPU_PRE_RESET, AmdSmiEvtNotificationType.GPU_POST_RESET]) as event: event.read(10000) except AmdSmiException as e: print(e) @@ -1897,7 +1908,7 @@ try: print("No GPUs on machine") else: for device in devices: - profile = ... + profile = AmdSmiPowerProfilePresetMasks.BOOTUP_DEFAULT amdsmi_set_gpu_power_profile(device, 0, profile) except AmdSmiException as e: print(e) @@ -1913,7 +1924,7 @@ Input parameters: * `processor_handle` handle for the given device * `min_clk_value` minimum clock value for desired clock range * `max_clk_value` maximum clock value for desired clock range -* `clk_type`AMDSMI_CLK_TYPE_SYS | AMDSMI_CLK_TYPE_MEM range type +* `clk_type` SYS | MEM range type Output: None @@ -1939,7 +1950,7 @@ try: print("No GPUs on machine") else: for device in devices: - amdsmi_set_gpu_clk_range(device, 0, 1000, AmdSmiClkType.AMDSMI_CLK_TYPE_SYS) + amdsmi_set_gpu_clk_range(device, 0, 1000, AmdSmiClkType.SYS) except AmdSmiException as e: print(e) ``` @@ -2266,10 +2277,10 @@ It is not supported on virtual machine guest Input parameters: * `processor_handle` handle for the given device -* `level` AMDSMI_FREQ_IND_MIN|AMDSMI_FREQ_IND_MAX to set the minimum (0) +* `level` MIN | MAX to set the minimum (0) or maximum (1) speed * `clk_value` value to apply to the clock range -* `clk_type` AMDSMI_CLK_TYPE_SYS | AMDSMI_CLK_TYPE_MEM range type +* `clk_type` SYS | MEM range type Output: None @@ -2297,9 +2308,9 @@ try: for device in devices: amdsmi_set_gpu_od_clk_info( device, - AmdSmiFreqInd.AMDSMI_FREQ_IND_MAX, + AmdSmiFreqInd.MAX, 1000, - AmdSmiClkType.AMDSMI_CLK_TYPE_SYS + AmdSmiClkType.SYS ) except AmdSmiException as e: print(e) @@ -2732,7 +2743,7 @@ try: print("No GPUs on machine") else: for device in devices: - perf_level = amdsmi_get_gpu_perf_level(dev) + perf_level = amdsmi_get_gpu_perf_level(device) print(perf_level) except AmdSmiException as e: print(e) @@ -3413,7 +3424,7 @@ try: print("No GPUs on machine") else: for device in devices: - event_handle = amdsmi_gpu_create_counter(device, AmdSmiEventGroup.XGMI) + event_handle = amdsmi_gpu_create_counter(device, AmdSmiEventType.XGMI_0_REQUEST_TX) except AmdSmiException as e: print(e) ``` @@ -3450,7 +3461,7 @@ try: print("No GPUs on machine") else: for device in devices: - event_handle = amdsmi_gpu_create_counter(device, AmdSmiEventGroup.XGMI) + event_handle = amdsmi_gpu_create_counter(device, AmdSmiEventType.XGMI_0_REQUEST_TX) amdsmi_gpu_destroy_counter(event_handle) except AmdSmiException as e: print(e) @@ -3535,6 +3546,7 @@ try: else: for device in devices: event_handle = amdsmi_gpu_create_counter(device, AmdSmiEventType.XGMI_1_REQUEST_TX) + amdsmi_gpu_control_counter(event_handle, AmdSmiCounterCommand.CMD_START) amdsmi_gpu_read_counter(event_handle) except AmdSmiException as e: print(e) @@ -3738,7 +3750,7 @@ Input parameters: * `processor_handle` handle for the given device * `clk_type` the type of clock for which the set of frequencies will be modified -as AmdSmiClkType +as a string of AmdSmiClkType. Example AmdSmiClkType.SCLK becomes "SCLK". * `freq_bitmask` bitmask indicating the indices of the frequencies that are to be enabled (1) and disabled (0). Only the lowest ::amdsmi_frequencies_t.num_supported bits of this mask are relevant. @@ -3767,7 +3779,7 @@ try: else: for device in devices: freq_bitmask = 0 - amdsmi_set_clk_freq(device, AmdSmiClkType.GFX, freq_bitmask) + amdsmi_set_clk_freq(device, "SCLK", freq_bitmask) except AmdSmiException as e: print(e) ``` @@ -4700,21 +4712,20 @@ try: if len(devices) == 0: print("No GPUs on machine") else: - for device in devices: + for device_num, device in enumerate(devices): link_metrics = amdsmi_get_link_metrics(device) - print(link_metrics['bit_rate']) - print(link_metrics['max_bandwidth']) - for idx, link in enumerate(link_metrics['links']): - print(f"{idx}: {link['bdf']}, {link['read']} KB, {link['write']} KB") - if link_type['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_INTERNAL: + print(link_metrics['num_links']) + for idx, links in enumerate(link_metrics['links']): + print(f"{idx}: {links['bdf']}, {links['read']} KB, {links['write']} KB") + if links['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_INTERNAL: print('internal') - if link_type['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_PCIE: + if links['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_PCIE: print('pcie') - if link_type['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_XGMI: + if links['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_XGMI: print('xgmi') - if link_type['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_NOT_APPLICABLE: + if links['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_NOT_APPLICABLE: print('not applicable') - if link_type['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_UNKNOWN: + if links['link_type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_UNKNOWN: print('unknown') except AmdSmiException as e: print(e) @@ -4775,7 +4786,7 @@ except AmdSmiException as e: print(e) ``` -### amdsmi_get_P2P_status +### amdsmi_topo_get_p2p_status Description: Retrieve the connection type and P2P capabilities between 2 GPUs @@ -4791,7 +4802,7 @@ Fields | Description `type` | The connection type as an int. This should be translated according to the enum amdsmi_link_type_t. Refer to the example below for more details. `cap` |
Subfield Description
`is_iolink_coherent`1 == True; 0 == False; Uint_max = Undefined
`is_iolink_atomics_32bit`Supports 32bit atomics
`is_iolink_atomics_64bit`Supports 64bit atomics
`is_iolink_dma`Supports DMA
`is_iolink_bi_directional`Is the IOLink Bidirectional
-Exceptions that can be thrown by `amdsmi_get_P2P_status` function: +Exceptions that can be thrown by `amdsmi_topo_get_p2p_status` function: * `AmdSmiLibraryException` * `AmdSmiParameterException` @@ -4814,7 +4825,7 @@ try: else: processor_handle_src = devices[0] processor_handle_dest = devices[1] - link_type = amdsmi_get_P2P_status(processor_handle_src, processor_handle_dest) + link_type = amdsmi_topo_get_p2p_status(processor_handle_src, processor_handle_dest) if link_type['type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_INTERNAL: print('internal') if link_type['type'] == AmdSmiLinkType.AMDSMI_LINK_TYPE_PCIE: @@ -6278,8 +6289,8 @@ Example: ```python try: - processor_handles = amdsmi_get_cpusocket_handles() - if len(processor_handles) == 0: + socket_handles = amdsmi_get_cpusocket_handles() + if len(socket_handles) == 0: print("No CPU sockets on machine") else: for socket in socket_handles: @@ -6315,9 +6326,9 @@ try: print("No CPU sockets on machine") else: for processor in processor_handles: - nbio = amdsmi_get_cpu_socket_lclk_dpm_level(processor) - print(nbio['max_dpm_level']) - print(nbio['max_dpm_level']) + nbio = amdsmi_get_cpu_socket_lclk_dpm_level(processor, 0) + print(nbio['nbio_max_dpm_level']) + print(nbio['nbio_max_dpm_level']) except AmdSmiException as e: print(e) ``` @@ -6349,7 +6360,7 @@ try: print("No CPU sockets on machine") else: for processor in processor_handles: - link_rate = amdsmi_set_cpu_pcie_link_rate(processor, 0, 0) + link_rate = amdsmi_set_cpu_pcie_link_rate(processor, 0) except AmdSmiException as e: print(e) ``` @@ -6443,8 +6454,10 @@ try: if len(processor_handles) == 0: print("No CPU sockets on machine") else: + encoding = 0 + link_name = "P0" for processor in processor_handles: - xgmi_bw = amdsmi_get_cpu_current_xgmi_bw(processor) + xgmi_bw = amdsmi_get_cpu_current_xgmi_bw(processor, encoding, link_name) print(xgmi_bw) except AmdSmiException as e: print(e)