Add multi-GPU support through a --gpu selector

Every GPU-bound command takes --gpu <index>|all (default 0). Persisted
tunings and reference curves are stored per GPU - GPU 0 keeps the plain
file names - and the logon re-apply covers every GPU with a persisted
tuning, so one card's failure or a removed card doesn't stop the others.
'clear' drops the selected GPUs' files, and the logon task once none is
left.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AtzmtEDzU3bHpXfMECYb57

Author: vuplea

CURVE-FILES.md

@@ -119,3 +119,6 @@ The same documents are how the app stores its own state, under `data\` in the in
   `--out-tuning-file` exports). It lives under Program Files deliberately: the file is admin-only
   writable, and the elevated logon task must not consume user-writable data. `clear` removes it
   along with the task.
+
+Both are per GPU: these plain names are GPU 0's, and another GPU's carry its index as a suffix
+(`persisted-tuning.gpu1.json`).

README.md

@@ -106,6 +106,16 @@ A tuning run **persists by default**: it copies the app to Program Files, and re
 task that re-applies the same undervolt at logon, elevated. If apply ever fails you get a message box
 so you are aware. Pass `--no-persist` to skip persistence.
 
+### Multiple GPUs
+
+Commands act on GPU 0 (the first NVIDIA GPU the driver enumerates) unless `--gpu <index>` picks
+another; `status` shows each card's index. `--gpu all` runs the command on every GPU in turn — the
+same request planned from each card's own stock curve, so identical cards get the same tuning
+without sharing one card's offsets. Persisted tunings and reference curves are kept per GPU, and
+the logon task re-applies every GPU's persisted tuning; `clear` removes the selected GPU's, and the
+task only once none is left. A saved shortcut carries its `--gpu`. The active checkmark tracks one
+live link per folder, so keep per-card profile links in separate folders.
+
 ### Saving a shortcut
 
 `--save-shortcut` writes a `.lnk` in the current directory named for the settings (e.g.

e2e/ReferenceCurveBackup.cs

@@ -13,16 +13,16 @@ internal sealed class ReferenceCurveBackup
 
     /// <summary>Captures the reference file's content, or null when nothing is saved.</summary>
     public static ReferenceCurveBackup Create()
-        => new(File.Exists(ReferenceCurve.FilePath()) ? File.ReadAllText(ReferenceCurve.FilePath()) : null);
+        => new(File.Exists(ReferenceCurve.FilePath(0)) ? File.ReadAllText(ReferenceCurve.FilePath(0)) : null);
 
     /// <summary>Removes the saved reference, if any. Guarded like <see cref="PersistedTuning.Remove"/>:
     /// on a host that never installed anything the data directory itself is missing, and a bare
     /// <see cref="File.Delete(string)"/> would throw instead of doing nothing.</summary>
     public static void Remove()
     {
-        if (File.Exists(ReferenceCurve.FilePath()))
+        if (File.Exists(ReferenceCurve.FilePath(0)))
         {
-            File.Delete(ReferenceCurve.FilePath());
+            File.Delete(ReferenceCurve.FilePath(0));
         }
     }
 
@@ -32,8 +32,8 @@ public void Restore()
         Remove();
         if (_content is not null)
         {
-            Directory.CreateDirectory(Path.GetDirectoryName(ReferenceCurve.FilePath())!);
-            File.WriteAllText(ReferenceCurve.FilePath(), _content);
+            Directory.CreateDirectory(Path.GetDirectoryName(ReferenceCurve.FilePath(0))!);
+            File.WriteAllText(ReferenceCurve.FilePath(0), _content);
         }
     }
 }

e2e/ReferenceCurveTests.cs

@@ -93,9 +93,9 @@ public void Undervolt_WithAReferenceFromAnotherCard_WarnsAndFallsBackToTheLiveCu
             // Re-key the saved reference to a card this isn't: the identity check must reject it
             // rather than plan another card's curve onto this one.
             ReferenceCurveDoc doc = TuningDocuments.ParseReferenceCurveDoc(
-                File.ReadAllText(ReferenceCurve.FilePath()), "the saved reference");
+                File.ReadAllText(ReferenceCurve.FilePath(0)), "the saved reference");
             doc.GpuPciIds = "DEADBEEF-DEADBEEF-DEADBEEF-DEADBEEF";
-            File.WriteAllText(ReferenceCurve.FilePath(), TuningDocuments.Render(doc));
+            File.WriteAllText(ReferenceCurve.FilePath(0), TuningDocuments.Render(doc));
 
             var (exitCode, output) = App.RunUndervolt("--mv", "900");
 

src/Args.cs

@@ -10,6 +10,10 @@ internal static class Args
     public static readonly Options Global = Options.Empty
         .WithBare("--silent");
 
+    /// <summary>The options every GPU-bound command accepts: <see cref="Global"/> plus the GPU
+    /// selector (see <see cref="GpuSelector"/>). 'install' touches no GPU and stays on Global.</summary>
+    public static readonly Options GpuBound = Global.WithValue(GpuSelector.Flag);
+
     /// <summary>How a flag consumes the token after it.</summary>
     private enum Kind
     {
@@ -47,8 +51,7 @@ private Options With(Kind kind, string[] flags)
 
         public Parsed Parse(string[] args) => Args.Parse(args, _flags, allowPositionals: false);
 
-        public string[] Positionals(string[] args)
-            => Args.Parse(args, _flags, allowPositionals: true).Positionals;
+        public Parsed ParseWithPositionals(string[] args) => Args.Parse(args, _flags, allowPositionals: true);
     }
 
     /// <summary>The parsed token stream: each given flag mapped to its value (null for a bare flag, or

src/GpuSelector.cs

@@ -0,0 +1,101 @@
+using System.Globalization;
+
+namespace SimpleNvidiaUndervolt;
+
+/// <summary>
+/// Which of the enumerated NVIDIA GPUs a command runs against, from <c>--gpu</c>: one index into
+/// <see cref="NvApi.EnumeratePhysicalGpus"/> (0 when the flag is absent), or <c>all</c> of them in
+/// turn. Every GPU-bound command takes it. The logon re-apply, which names no GPU, instead covers
+/// every GPU a tuning was persisted for (see <see cref="PersistedTuning.StoredSelector"/>).
+/// </summary>
+internal sealed class GpuSelector
+{
+    public const string Flag = "--gpu";
+
+    public static readonly GpuSelector Default = new(new[] { 0 }, arg: null, fromStore: false);
+
+    /// <summary>The selected indexes, ascending, or null for every enumerated GPU.</summary>
+    public IReadOnlyList<int>? Indexes { get; }
+
+    /// <summary>The flag's value as typed, re-emitted into a saved shortcut; null when the flag was
+    /// absent (the index-0 default) or the selection isn't from the command line.</summary>
+    private readonly string? _arg;
+
+    /// <summary>Whether the indexes are the persisted set rather than a request — what decides how
+    /// a missing GPU is explained.</summary>
+    private readonly bool _fromStore;
+
+    private GpuSelector(IReadOnlyList<int>? indexes, string? arg, bool fromStore)
+    {
+        Indexes = indexes;
+        _arg = arg;
+        _fromStore = fromStore;
+    }
+
+    /// <summary>Whether <c>--gpu</c> was given, as opposed to the index-0 default.</summary>
+    public bool Given => _arg is not null;
+
+    public bool IsAll => Indexes is null;
+
+    /// <summary>The GPUs a tuning is persisted for — what the logon re-apply runs against.</summary>
+    public static GpuSelector Stored(IReadOnlyList<int> indexes) => new(indexes, arg: null, fromStore: true);
+
+    public static GpuSelector Parse(Args.Parsed parsed)
+    {
+        if (parsed.Value(Flag) is not { } raw)
+        {
+            return Default;
+        }
+
+        if (raw.Equals("all", StringComparison.OrdinalIgnoreCase))
+        {
+            return new(null, "all", fromStore: false);
+        }
+
+        if (!int.TryParse(raw, NumberStyles.None, CultureInfo.InvariantCulture, out int index))
+        {
+            throw new CliError($"{Flag} takes a GPU index (0, 1, ...) or 'all'.");
+        }
+
+        return new(new[] { index }, raw, fromStore: false);
+    }
+
+    /// <summary>The indexes to run against, in order, on a machine with <paramref name="gpuCount"/>
+    /// GPUs. Not range-checked: the caller reports an index past the enumeration with
+    /// <see cref="MissingGpu"/> — as that GPU's own failure when others are selected too.</summary>
+    public IReadOnlyList<int> IndexesOn(int gpuCount)
+        => Indexes ?? Enumerable.Range(0, gpuCount).ToArray();
+
+    /// <summary>The error for a selected index past the enumeration. A stored index with no card
+    /// means a persisted tuning outlived its GPU, which <c>clear</c> drops.</summary>
+    public CliError MissingGpu(int index, int gpuCount)
+        => new($"GPU {index} doesn't exist: {gpuCount} NVIDIA GPU(s) found (indexes 0-{gpuCount - 1})."
+               + (_fromStore ? $" Its persisted tuning is dropped with 'clear {Flag} {index}'." : string.Empty));
+
+    /// <summary>Rejects <c>all</c> alongside an option naming one output file: an export can't
+    /// come from several GPUs.</summary>
+    public void RequireOneForExport(string flag, string? file)
+    {
+        if (IsAll && file is not null)
+        {
+            throw new CliError($"{flag} exports one GPU's document - pass {Flag} <index> instead of 'all'.");
+        }
+    }
+
+    /// <summary>The flag for a saved shortcut's command line: nothing for the default.</summary>
+    public string[] ToArgs() => _arg is null ? Array.Empty<string>() : new[] { Flag, _arg };
+
+    /// <summary>The selection as a name token: "GPU 1", "all GPUs".</summary>
+    public string Describe()
+        => Indexes is null ? "all GPUs" : "GPU " + string.Join(", ", Indexes);
+}
+
+/// <summary>One GPU a command runs against: its NVAPI handle, its index in the enumeration and the
+/// enumeration's size. The index keys the GPU's own store files (see
+/// <see cref="Persistence.DataFilePath"/>) and, on a multi-GPU machine, names the card.</summary>
+internal readonly record struct SelectedGpu(IntPtr Handle, int Index, int Count)
+{
+    /// <summary>The card's name for headers, with its index once the machine has more than one GPU.</summary>
+    public string Label
+        => Count > 1 ? $"{NvApi.SafeFullName(Handle)} (GPU {Index} of {Count})" : NvApi.SafeFullName(Handle);
+}

src/PersistedTuning.cs

@@ -4,59 +4,90 @@ namespace SimpleNvidiaUndervolt;
 /// The tuning document every persisting run stores for the logon task, which re-applies it with
 /// <c>tune --apply-persisted</c>. Persisting the resolved offsets as data — rather than a command
 /// line to re-plan — makes the logon re-apply exact: per-anchor deltas are temperature-independent,
-/// so nothing is re-derived from a boot-time curve read. Stored as a JSON file in the install
-/// directory's data subfolder — the same document <c>--out-tuning-file</c> exports, so it can be
-/// read or copied directly — which is under Program Files and thus admin-only writable, so the
-/// elevated logon re-apply never consumes user-writable data.
+/// so nothing is re-derived from a boot-time curve read. Stored per GPU as a JSON file in the
+/// install directory's data subfolder (see <see cref="Persistence.DataFilePath"/>) — the same
+/// document <c>--out-tuning-file</c> exports, so it can be read or copied directly — which is
+/// under Program Files and thus admin-only writable, so the elevated logon re-apply never
+/// consumes user-writable data.
 /// </summary>
 internal static class PersistedTuning
 {
-    public static string FilePath() => Path.Combine(Persistence.DataDir(), "persisted-tuning.json");
+    private const string FileStem = "persisted-tuning";
 
-    /// <summary>Stores the document, replacing any previous one. Requires administrator (the
-    /// install directory); the environment refusing the write is reported as the anticipated
+    public static string FilePath(int gpuIndex) => Persistence.DataFilePath(FileStem, gpuIndex);
+
+    /// <summary>The GPUs a tuning is stored for, ascending.</summary>
+    public static IReadOnlyList<int> StoredGpuIndexes() => Persistence.StoredGpuIndexes(FileStem);
+
+    /// <summary>What the logon re-apply runs against: every GPU with a stored tuning. Nothing
+    /// stored must fail loudly — silence would read as an applied tuning.</summary>
+    public static GpuSelector StoredSelector()
+    {
+        IReadOnlyList<int> stored = StoredGpuIndexes();
+        return stored.Count > 0 ? GpuSelector.Stored(stored) : throw NothingStored(0);
+    }
+
+    /// <summary>Stores the document, replacing any previous one for the GPU. Requires administrator
+    /// (the install directory); the environment refusing the write is reported as the anticipated
     /// failure it is.</summary>
-    public static void Save(TuningDoc doc)
-        => TuningDocuments.WriteFile(FilePath(), TuningDocuments.Render(doc), "the persisted tuning");
+    public static void Save(TuningDoc doc, int gpuIndex)
+        => TuningDocuments.WriteFile(FilePath(gpuIndex), TuningDocuments.Render(doc), "the persisted tuning");
 
     /// <summary>The stored document. An <c>--apply-persisted</c> run with nothing (usable) stored
     /// must fail loudly — it is the logon re-apply, and silence would read as an applied tuning.</summary>
-    public static TuningDoc Load()
+    public static TuningDoc Load(int gpuIndex)
     {
-        if (!File.Exists(FilePath()))
+        if (!File.Exists(FilePath(gpuIndex)))
         {
-            throw new CliError($"No persisted tuning is stored at {FilePath()} - nothing to apply. "
-                               + "Re-run your tune command to persist one.");
+            throw NothingStored(gpuIndex);
         }
 
-        return TuningDocuments.ReadTuningFile(FilePath());
+        return TuningDocuments.ReadTuningFile(FilePath(gpuIndex));
     }
 
-    /// <summary>One phrase for status's logon line: the stored document's capture date when it
+    private static CliError NothingStored(int gpuIndex)
+        => new($"No persisted tuning is stored at {FilePath(gpuIndex)} - nothing to apply. "
+               + "Re-run your tune command to persist one.");
+
+    /// <summary>One phrase for status's logon line: each stored document's capture date when it
     /// reads, else the inconsistency — an apply-persisted task with nothing to apply fails at the
-    /// next logon, and status must say so rather than "yes".</summary>
+    /// next logon, and status must say so rather than "yes". GPUs are named only past the
+    /// single-GPU case.</summary>
     public static string DescribeForStatus()
+    {
+        IReadOnlyList<int> stored = StoredGpuIndexes();
+        if (stored.Count == 0)
+        {
+            return "which is missing - re-run your tune command";
+        }
+
+        return stored is [0]
+            ? Describe(0)
+            : string.Join("; ", stored.Select(index => $"GPU {index}: {Describe(index)}"));
+    }
+
+    private static string Describe(int gpuIndex)
     {
         try
         {
-            return TuningDocuments.DescribeCapture(Load().SavedAt);
+            return TuningDocuments.DescribeCapture(Load(gpuIndex).SavedAt);
         }
         catch (CliError)
         {
-            return "which is missing or unreadable - re-run your tune command";
+            return "unreadable - re-run your tune command";
         }
     }
 
-    /// <summary>Deletes the stored document, returning whether one existed. Throws when the delete
-    /// itself fails, so <c>clear</c> doesn't report persisted state as gone when it isn't.</summary>
-    public static bool Remove()
+    /// <summary>Deletes the GPU's stored document, returning whether one existed. Throws when the
+    /// delete itself fails, so <c>clear</c> doesn't report persisted state as gone when it isn't.</summary>
+    public static bool Remove(int gpuIndex)
     {
-        if (!File.Exists(FilePath()))
+        if (!File.Exists(FilePath(gpuIndex)))
         {
             return false;
         }
 
-        File.Delete(FilePath());
+        File.Delete(FilePath(gpuIndex));
         return true;
     }
 }

src/Persistence.cs

@@ -1,3 +1,4 @@
+using System.Globalization;
 using System.Security.Cryptography;
 using System.Xml.Linq;
 
@@ -56,6 +57,50 @@ internal static string InstallDir()
     /// install directory, which is what lets the elevated logon re-apply consume it.</summary>
     internal static string DataDir() => Path.Combine(InstallDir(), "data");
 
+    /// <summary>The data file holding one document kind for one GPU: the plain name for GPU 0, so
+    /// a single-GPU install never sees a suffix, and a <c>.gpuN</c> suffix for the others.</summary>
+    internal static string DataFilePath(string stem, int gpuIndex)
+        => Path.Combine(DataDir(), gpuIndex == 0 ? $"{stem}.json" : $"{stem}.gpu{gpuIndex}.json");
+
+    /// <summary>The GPU indexes a document kind is stored for, ascending.</summary>
+    internal static IReadOnlyList<int> StoredGpuIndexes(string stem)
+    {
+        if (!Directory.Exists(DataDir()))
+        {
+            return Array.Empty<int>();
+        }
+
+        return Directory.GetFiles(DataDir(), $"{stem}*.json")
+            .Select(file => DataFileGpuIndex(stem, Path.GetFileName(file)))
+            .OfType<int>()
+            .Order()
+            .ToArray();
+    }
+
+    /// <summary>The GPU index a file name of the kind encodes (the inverse of
+    /// <see cref="DataFilePath"/>), or null for a file that isn't one.</summary>
+    internal static int? DataFileGpuIndex(string stem, string fileName)
+    {
+        if (fileName.Equals($"{stem}.json", StringComparison.OrdinalIgnoreCase))
+        {
+            return 0;
+        }
+
+        string prefix = $"{stem}.gpu";
+        const string suffix = ".json";
+        if (fileName.Length <= prefix.Length + suffix.Length
+            || !fileName.StartsWith(prefix, StringComparison.OrdinalIgnoreCase)
+            || !fileName.EndsWith(suffix, StringComparison.OrdinalIgnoreCase))
+        {
+            return null;
+        }
+
+        string digits = fileName[prefix.Length..^suffix.Length];
+        return int.TryParse(digits, NumberStyles.None, CultureInfo.InvariantCulture, out int index) && index > 0
+            ? index
+            : null;
+    }
+
     private const string NoCmdSuffix = "-nocmd";
 
     /// <summary>The installed executable, copied as-is (console subsystem).</summary>