Add RecommendedReaderVersion advisory mechanism to cDAC RuntimeInfo contract

Adds a new CDAC_RECOMMENDED_READER_VERSION constant and RecommendedReaderVersion
global to datadescriptor.inc. The runtime team can increment this value when making
changes where updating diagnostic tools is recommended. This is purely advisory and
does not necessarily mean a breaking change occurred.

The RuntimeInfo contract exposes two new properties:
- CurrentReaderVersion: a compile-time constant representing the reader version this
  contract was authored against (currently 1)
- RecommendedReaderVersion: reads the runtime global of the same name

Diagnostic tools can compare these to determine whether to recommend an update to
the user. When the runtime ships a higher RecommendedReaderVersion than a tool's
CurrentReaderVersion, the tool knows newer contracts are available.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: noahfalk

docs/design/datacontracts/RuntimeInfo.md

@@ -30,6 +30,12 @@ RuntimeInfoArchitecture GetTargetArchitecture();
 
 // Gets the targets operating system. If this information is not available returns Unknown.
 RuntimeInfoOperatingSystem GetTargetOperatingSystem();
+
+// Returns the runtime's RecommendedReaderVersion global. Returns 0 if the global is absent.
+uint RecommendedReaderVersion { get; }
+
+// An embedded version constant indicating how much runtime functionality this reader knows how to parse.
+uint CurrentReaderVersion { get; }
 ```
 
 ## Version 1
@@ -39,5 +45,15 @@ Global variables used:
 | --- | --- | --- |
 | Architecture | string | Target architecture |
 | OperatingSystem | string | Target operating system |
+| RecommendedReaderVersion | uint32 | Incremented when an update to the latest contracts is recommended |
+
+The contract implementation returns the architecture and operating system global values parsed as the
+respective enum case-insensitively. If these globals are not available, the contract returns Unknown.
+
+### Reader versioning scheme
 
-The contract implementation simply returns the contract descriptor global values parsed as the respective enum case-insensitively. If these globals are not available, the contract returns Unknown.
+When the .NET runtime team wants to signal that an update is recommended we update both the
+`CurrentReaderVersion` constant in the cDAC implementation and the `RecommendedReaderVersion`
+global value in the runtime. This causes older tools on older cDAC versions to observe
+RecommendedReaderVersion > CurrentReaderVersion. The tool can notify the user that an update
+is recommended.

src/coreclr/vm/datadescriptor/datadescriptor.inc

@@ -6,6 +6,20 @@
 // This file is compiled using the target architecture.  Preprocessor defines for the target
 // platform will be available.  It is ok to use `#ifdef`.
 
+// Increment this when making a change where we'd like to recommend users update their diagnostic tools.
+// Tools can use this to display an advisory notice to users encouraging them to update. Changing
+// this value on its own is not considered a breaking change. See the RuntimeInfo.md data contract for details.
+// When incrementing this value, also implement the new functionality in the cDAC reader and update the
+// CurrentReaderVersion property on the IRuntimeInfo contract in
+// src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/RuntimeInfo_1.cs
+// to match.
+#ifndef CDAC_RECOMMENDED_READER_VERSION
+#define CDAC_RECOMMENDED_READER_VERSION 1
+#endif
+
+// When changes will break existing diagnostic tools (changes that are incompatible with the existing data contracts)
+// you should also update the contract versions at the bottom of this file for any contract that is being broken.
+
 
 CDAC_BASELINE("empty")
 CDAC_TYPES_BEGIN()
@@ -1082,6 +1096,7 @@ CDAC_GLOBAL(ObjectToMethodTableUnmask, uint8, 1 | 1 << 1 | 1 << 2)
 CDAC_GLOBAL(ObjectToMethodTableUnmask, uint8, 1 | 1 << 1)
 #endif //TARGET_64BIT
 CDAC_GLOBAL(SOSBreakingChangeVersion, uint8, SOS_BREAKING_CHANGE_VERSION)
+CDAC_GLOBAL(RecommendedReaderVersion, uint32, CDAC_RECOMMENDED_READER_VERSION)
 CDAC_GLOBAL(DirectorySeparator, uint8, (uint8_t)DIRECTORY_SEPARATOR_CHAR_A)
 CDAC_GLOBAL(HashMapSlotsPerBucket, uint32, SLOTS_PER_BUCKET)
 CDAC_GLOBAL(HashMapValueMask, uint64, VALUE_MASK)

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/Contracts/IRuntimeInfo.cs

@@ -34,6 +34,8 @@ public interface IRuntimeInfo : IContract
     static string IContract.Name { get; } = nameof(RuntimeInfo);
     RuntimeInfoArchitecture GetTargetArchitecture() => throw new NotImplementedException();
     RuntimeInfoOperatingSystem GetTargetOperatingSystem() => throw new NotImplementedException();
+    uint CurrentReaderVersion { get => throw new NotImplementedException(); }
+    uint RecommendedReaderVersion { get => throw new NotImplementedException(); }
 }
 
 public readonly struct RuntimeInfo : IRuntimeInfo

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Constants.cs

@@ -19,6 +19,7 @@ public static class Globals
 
         public const string ObjectToMethodTableUnmask = nameof(ObjectToMethodTableUnmask);
         public const string SOSBreakingChangeVersion = nameof(SOSBreakingChangeVersion);
+        public const string RecommendedReaderVersion = nameof(RecommendedReaderVersion);
 
         public const string ExceptionMethodTable = nameof(ExceptionMethodTable);
         public const string FreeObjectMethodTable = nameof(FreeObjectMethodTable);

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/RuntimeInfo_1.cs

@@ -39,4 +39,16 @@ readonly RuntimeInfoOperatingSystem IRuntimeInfo.GetTargetOperatingSystem()
 
         return RuntimeInfoOperatingSystem.Unknown;
     }
+
+    readonly uint IRuntimeInfo.CurrentReaderVersion => 1;
+
+    readonly uint IRuntimeInfo.RecommendedReaderVersion
+    {
+        get
+        {
+            if (_target.TryReadGlobal(Constants.Globals.RecommendedReaderVersion, out uint runtimeVersion))
+                return runtimeVersion;
+            return 0;
+        }
+    }
 }

src/native/managed/cdac/tests/RuntimeInfoTests.cs

@@ -13,10 +13,11 @@ public class RuntimeInfoTests
 {
     internal static Target CreateTarget(
         MockTarget.Architecture arch,
-        (string Name, string Value)[] globalStrings)
+        (string Name, string Value)[] globalStrings,
+        (string Name, ulong Value)[] globals = null)
     {
         MockMemorySpace.Builder builder = new MockMemorySpace.Builder(new TargetTestHelpers(arch));
-        TestPlaceholderTarget target = new TestPlaceholderTarget(arch, builder.GetMemoryContext().ReadFromTarget, [], [], globalStrings);
+        TestPlaceholderTarget target = new TestPlaceholderTarget(arch, builder.GetMemoryContext().ReadFromTarget, [], globals, globalStrings);
 
         IContractFactory<IRuntimeInfo> runtimeInfoFactory = new RuntimeInfoFactory();
 
@@ -99,4 +100,21 @@ public void GetTargetOperatingSystemTest(
         var actualArchitecture = runtimeInfo.GetTargetOperatingSystem();
         Assert.Equal(expectedOS, actualArchitecture);
     }
+
+    private static readonly MockTarget.Architecture DefaultArch = new MockTarget.Architecture { IsLittleEndian = true, Is64Bit = true };
+
+    [Fact]
+    public void RecommendedReaderVersion_GlobalPresent_ReturnsValue()
+    {
+        var target = CreateTarget(DefaultArch, [],
+            [(Constants.Globals.RecommendedReaderVersion, (ulong)2)]);
+        Assert.Equal((uint)2, target.Contracts.RuntimeInfo.RecommendedReaderVersion);
+    }
+
+    [Fact]
+    public void RecommendedReaderVersion_GlobalAbsent_ReturnsZero()
+    {
+        var target = CreateTarget(DefaultArch, []);
+        Assert.Equal((uint)0, target.Contracts.RuntimeInfo.RecommendedReaderVersion);
+    }
 }