From ac1fa8dccbcd9118e3c3d08162e0a9a73df0888a Mon Sep 17 00:00:00 2001
From: koushikbillakanti-amd <koushik.billakanti@amd.com>
Date: Thu, 8 Jan 2026 08:04:23 -0600
Subject: [PATCH] [SWDEV-567284] AMDSMI conceptual documentation for setting
 perf determinism (#2529)

Authored-by: Koushik Billakanti <kbillaka@amd.com>
---
 .../docs/conceptual/perf-determinism.md       | 66 +++++++++++++++++++
 projects/amdsmi/docs/index.md                 |  1 +
 projects/amdsmi/docs/sphinx/_toc.yml.in       |  2 +
 3 files changed, 69 insertions(+)
 create mode 100644 projects/amdsmi/docs/conceptual/perf-determinism.md

diff --git a/projects/amdsmi/docs/conceptual/perf-determinism.md b/projects/amdsmi/docs/conceptual/perf-determinism.md
new file mode 100644
index 0000000000..2afbf74909
--- /dev/null
+++ b/projects/amdsmi/docs/conceptual/perf-determinism.md
@@ -0,0 +1,66 @@
+---
+myst:
+  html_meta:
+    "description lang=en": "AMD SMI guide for setting performance determinism."
+    "keywords": "system, management, interface, performance, determinism, clock, frequency, gfxclk, benchmark"
+---
+
+# Performance determinism
+
+Performance determinism mode enables consistent GPU performance by enforcing a fixed maximum GFXCLK
+(graphics clock) frequency. This prevents clock frequency variations when running the same workload
+across different GPUs, making it useful for benchmarking and performance analysis.
+
+## How it works
+
+When enabled, performance determinism sets a user-defined SoftMax limit for the GFXCLK frequency.
+This prevents the GFXCLK PLL from stretching during workload execution, minimizing performance
+variation. The GPU performance level changes to `DETERMINISM` when this mode is active.
+
+## Supported hardware
+
+Performance determinism is supported on AMD Instinct MI200 series and AMD Radeon RX 7000 series
+(RDNA 3) GPUs. Support may vary by ASIC -- MI300 series GPUs may not support this feature.
+
+## From concept to action
+
+AMD SMI provides tools to enable and manage performance determinism mode.
+
+:::::{tab-set}
+::::{tab-item} C/C++
+The AMD SMI library provides APIs to enable performance determinism and query the current
+performance level.
+
+See [Clock, Power, and Performance Control](/doxygen/docBin/html/group__tagClkPowerPerfControl) for
+available APIs.
+::::
+
+::::{tab-item} Python
+See related APIs:
+
+- [](/reference/amdsmi-py-api.md#amdsmi_set_gpu_perf_determinism_mode)
+- [](/reference/amdsmi-py-api.md#amdsmi_get_gpu_perf_level)
+- [](/reference/amdsmi-py-api.md#amdsmi_set_gpu_perf_level)
+::::
+
+::::{tab-item} amd-smi CLI
+See [`amd-smi set --help`](/how-to/amdsmi-cli-tool.md#amd-smi-set) and
+[`amd-smi reset --help`](/how-to/amdsmi-cli-tool.md#amd-smi-reset) for details and available options.
+
+```shell
+# Enable performance determinism with GFXCLK set to 1900 MHz
+amd-smi set --perf-determinism 1900
+
+# Disable performance determinism
+amd-smi reset --perf-determinism
+
+# Query current performance level
+amd-smi metric --perf-level
+```
+::::
+:::::
+
+## Further reading
+
+- [PowerPlay (Linux kernel)](https://docs.kernel.org/gpu/amdgpu/driver-misc.html#powerplay)
+- [AMDGPU Documentation](https://docs.kernel.org/gpu/amdgpu/index.html)
diff --git a/projects/amdsmi/docs/index.md b/projects/amdsmi/docs/index.md
index cd58b91afb..b5d746d75e 100644
--- a/projects/amdsmi/docs/index.md
+++ b/projects/amdsmi/docs/index.md
@@ -47,6 +47,7 @@ AMD SMI is the successor to <https://github.com/ROCm/rocm_smi_lib>.
 :::
 
 :::{grid-item-card} Conceptual
+* [Performance determinism](./conceptual/perf-determinism.md)
 * [Reliability, availability, serviceability](./conceptual/ras.md)
 :::
 
diff --git a/projects/amdsmi/docs/sphinx/_toc.yml.in b/projects/amdsmi/docs/sphinx/_toc.yml.in
index 13f864206e..58cc96a396 100644
--- a/projects/amdsmi/docs/sphinx/_toc.yml.in
+++ b/projects/amdsmi/docs/sphinx/_toc.yml.in
@@ -53,6 +53,8 @@ subtrees:
 
 - caption: Conceptual
   entries:
+  - file: conceptual/perf-determinism.md
+    title: Performance determinism
   - file: conceptual/ras.md
 
 - caption: Tutorials