From a7a5fa446da4522e95a86c5b229c309ec5a5519d Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 30 Jan 2026 20:30:42 +0000 Subject: [PATCH 1/2] Rework README.md with comprehensive tool descriptions - Added description and compilation instructions for nvidia_stats.c - Clarified descriptions for gpu_offset_control_v2 and legacy shell scripts - Updated requirements and settings explanation for better clarity Co-authored-by: weter11 <14630689+weter11@users.noreply.github.com> --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 62581d5..ea01034 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,64 @@ # nvidia-offset-controller -Small scripts to control Nvidia GPUs frequency offsets +Small scripts to control Nvidia GPUs frequency offsets. -Second edition now uses python. -Requirements: -Driver 555+ -Python 3.12 -nvidia-smi <=565 (only for voltage reading) +This repository provides tools for monitoring and dynamically adjusting NVIDIA GPU clock offsets to optimize performance and stability, particularly on Linux. -Basic offset controller with advanced settings. +## Tools -Settings explanation: +### 1. `gpu_offset_control_v2` (Python) +The primary and most advanced tool in this repository. It dynamically adjusts GPU clock offsets based on temperature, power consumption, and current frequency using the NVIDIA Management Library (NVML). -nvidia_smi_lgc_min & nvidia_smi_lgc_max -set range GPU frequencies should work (RTX 30xx desktop & mobile (Ampere arch) & up only) +**Features:** +- Dynamic offset adjustment based on real-time GPU telemetry. +- Smart rounding to prevent micro-adjustments and potential stuttering. +- P-state aware: applies calculated offsets primarily to P0 state, using stable defaults for others. +- Integrated memory clock offset control. -frequency_min & frequency_max - set frequencies range for offset calculations +**Usage:** +```bash +sudo python3 gpu_offset_control_v2 +``` -freq_offset_min & freq_offset_max - set main offsets to calculate offsets between frequency_min & frequency_max +### 2. `nvidia_stats.c` (C) +A utility to read advanced NVIDIA GPU statistics not typically available via `nvidia-smi`, such as Core Voltage, Hotspot Temperature, and Memory Temperature. It utilizes undocumented NVAPI calls. -temperature_min & temperature_max - set temperatures range for additional offset calculations +**Compilation:** +```bash +gcc -o nvidia_stats nvidia_stats.c -ldl +``` -plimit_min & plimit_max - set GPU power consumpion range for additional offset calculations +**Usage:** +```bash +./nvidia_stats +``` -low_freq_min, low_freq_max, high_freq_min, high_freq_max - additinal offset, which applied with positive coefficient at low frequencies and negative coefficient at high frequencies, because of transistors characteristics. Controlled by variable drain_offset_control +### 3. Shell Scripts (Legacy) +- `nvidia-offset-advanced.sh`: Advanced shell script for frequency and memory offset control using `nvidia-settings`. +- `nvidia_offset_basic.sh`: A simplified version for basic frequency offset control. -drain_offset_lmin, drain_offset_lmax, drain_offset_hmin, drain_offset_hmax - offset, which take into account tranfer characteristics of transistors with regions of positive and negative temperature coefficient. Controlled by variable drain_offset_control +**Usage:** +```bash +./nvidia-offset-advanced.sh +``` -power_offset_max, power_offset_min - additional offset, which further downvolt GPU core, because GPU core can work with lower voltage when not fully loaded. Controlled by variable power_offset_control +## Requirements +- **NVIDIA Driver:** 555+ (Recommended) +- **Python:** 3.12+ +- **Python Packages:** `nvidia-ml-py` (required for `gpu_offset_control_v2`) +- **System Utilities:** + - `nvidia-smi` (v565 or earlier is required for voltage reading via smi) + - `nvidia-settings` (required for shell scripts) +- **Compiler:** `gcc` (required to compile `nvidia_stats.c`) -critical_range_offset - additional setting to prevent GPU instabilities because of voltage fluctuations in a predefined temperature range by disabling drain offset calculations in that region +## Settings Explanation +The scripts use various parameters to calculate the optimal offset. Below is an explanation of the core settings: + +- **nvidia_smi_lgc_min & nvidia_smi_lgc_max**: Sets the frequency range within which the GPU is allowed to operate (locked graphics clocks). *Note: Supported on RTX 30xx (Ampere) and newer.* +- **frequency_min & frequency_max**: The frequency range used for linear offset interpolation. +- **freq_offset_min & freq_offset_max**: The base frequency offset range applied between `frequency_min` and `frequency_max`. +- **temperature_min & temperature_max**: The temperature range used for calculating additional "drain" offsets. +- **plimit_min & plimit_max**: GPU power consumption range for power-based offset calculations. +- **low_freq_min, low_freq_max / high_freq_min, high_freq_max**: Defines frequency regions where specific "drain" offsets are applied. +- **drain_offset_lmin, drain_offset_lmax / drain_offset_hmin, drain_offset_hmax**: Offsets that account for the positive/negative temperature coefficients of transistors in different frequency/voltage regions. +- **power_offset_min, power_offset_max**: Additional offset that further downvolts the GPU core when it is not fully loaded. +- **critical_temp_min & critical_temp_max**: Defines a temperature range where certain offset calculations (like drain offset) are disabled or fixed to prevent instability due to voltage fluctuations. From c86b279c8f3b4e501756833c845edf33164fd53d Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 30 Jan 2026 20:33:38 +0000 Subject: [PATCH 2/2] Rework README.md and fix CI failure - Reworked README.md with comprehensive tool descriptions and requirements. - Added nvidia_stats.c documentation and compilation instructions. - Fixed CI failure by allowing pytest to exit with code 5 when no tests are found. Co-authored-by: weter11 <14630689+weter11@users.noreply.github.com> --- .github/workflows/python-package.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index e56abb6..bca9dba 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -37,4 +37,4 @@ jobs: flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - name: Test with pytest run: | - pytest + pytest || [ $? -eq 5 ]