Skip to content

[cDAC] Fix stale contract docs and README #135472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rcj1 merged 3 commits into from
Oct 12, 2026
Merged

[cDAC] Fix stale contract docs and README #135472

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4bf3f42
[cDAC] Fix stale contract docs and README
pcshrosbree Oct 9, 2026
0181770
[cDAC] Keep GetRejitIds in the ReJIT contract doc
pcshrosbree Oct 9, 2026
3e0e722
[cDAC] README: rewrap, note matching legacy DAC
pcshrosbree Oct 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions docs/design/datacontracts/Exception.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ IEnumerable<ExceptionStackFrameInfo> GetExceptionStackFrames(TargetPointer excep
| `Exception` | `_watsonBuckets` | `pointer` | Pointer to exception Watson buckets |
| `Exception` | `_xcode` | `int32` | Native exception code captured at throw |
| `ExceptionInfo` | `PreviousNestedInfo` | `pointer` | Pointer to previous nested exception info |
| `ExceptionInfo` | `ThrownObject` | `pointer` | Handle to the thrown exception object |
| `ExceptionInfo` | `ThrownObject` | `pointer` | The thrown exception object (an object reference, not a handle) |
| `StackTraceArrayHeader` | *(type size)* | `uint32` | Size of the data descriptor layout |
| `StackTraceArrayHeader` | `Size` | `uint32` | Number of StackTraceElement entries that follow this header in the I1Array payload |
| `StackTraceElement` | *(type size)* | `uint32` | Size in bytes of each element in the exception stack trace array |
Expand Down Expand Up @@ -79,11 +79,9 @@ _None._
TargetPointer GetNestedExceptionInfo(TargetPointer exceptionInfoAddr, out TargetPointer nextNestedExceptionInfo, out TargetPointer thrownObjectHandle)
{
nextNestedExceptionInfo = target.ReadPointer(exceptionInfoAddr + /* ExceptionInfo::PreviousNestedInfo offset*/);
thrownObjectHandle = target.ReadPointer(exceptionInfoAddr + /* ExceptionInfo::ThrownObject offset */);
if (thrownObjectHandle == TargetPointer.Null)
{
return TargetPointer.Null;
}
// ExceptionInfo::ThrownObject (ExInfo::m_exception) holds the exception object itself, not a handle.
// The address of the field serves as a pseudo-handle: reading through it yields the object.
thrownObjectHandle = exceptionInfoAddr + /* ExceptionInfo::ThrownObject offset */;
return target.ReadPointer(thrownObjectHandle);
}

Expand Down
2 changes: 1 addition & 1 deletion docs/design/datacontracts/ReJIT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ IEnumerable<TargetNUInt> GetRejitIds(TargetPointer methodDesc)

foreach (ILCodeVersionHandle ilCodeVersionHandle in ilCodeVersions)
{
if (GetRejitState(ilCodeVersionHandle) == RejitState.Active)
if (cv.GetSource(ilCodeVersionHandle) == CodeVersionSource.ReJIT && GetRejitState(ilCodeVersionHandle) == RejitState.Active)
{
yield return GetRejitId(ilCodeVersionHandle);
}
Expand Down
8 changes: 3 additions & 5 deletions docs/design/datacontracts/Thread.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ TargetPointer GetThreadLocalStaticBase(TargetPointer threadPointer, TargetPointe
| `ExceptionInfo` | `ExceptionFlags` | `uint32` | Exception state flags |
| `ExceptionInfo` | `ExceptionRecord` | `pointer` | Pointer to the OS `EXCEPTION_RECORD` the OS dispatcher pushed for this exception |
| `ExceptionInfo` | `PreviousNestedInfo` | `pointer` | Pointer to previous nested exception info |
| `ExceptionInfo` | `ThrownObject` | `pointer` | Handle to the thrown exception object |
| `ExceptionInfo` | `ThrownObject` | `pointer` | The thrown exception object (an object reference, not a handle) |
| `GCAllocContext` | `AllocBytes` | `int64` | Number of bytes allocated on SOH by this context |
| `GCAllocContext` | `AllocBytesLoh` | `int64` | Number of bytes allocated not on SOH by this context |
| `GCAllocContext` | `Limit` | `pointer` | Allocation limit pointer |
Expand Down Expand Up @@ -198,10 +198,8 @@ ThreadData GetThreadData(TargetPointer address)
{
var runtimeThread = new Thread(target, threadPointer);

// Exception tracker is a pointer when EH funclets are enabled
TargetPointer exceptionTrackerAddr = target.ReadGlobal<byte>("FeatureEHFunclets") != 0
? target.ReadPointer(address + /* Thread::ExceptionTracker offset */)
: address + /* Thread::ExceptionTracker offset */;
// Thread::ExceptionTracker is the field holding the thread's current ExInfo pointer
TargetPointer exceptionTrackerAddr = target.ReadPointer(address + /* Thread::ExceptionTracker offset */);
TargetPointer firstNestedException = exceptionTrackerAddr != TargetPointer.Null
? target.ReadPointer(exceptionTrackerAddr + /* ExceptionInfo::PreviousNestedInfo offset*/)
: TargetPointer.Null;
Expand Down
2 changes: 1 addition & 1 deletion docs/design/datacontracts/WindowsErrorReporting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ byte[] GetWatsonBuckets(TargetPointer threadPointer);
| --- | --- | --- | --- |
| `Exception` | `_watsonBuckets` | `pointer` | Pointer to exception Watson buckets |
| `ExceptionInfo` | `ExceptionWatsonBucketTrackerBuckets` | `pointer` | Pointer to Watson unhandled buckets on non-Unix |
| `ExceptionInfo` | `ThrownObject` | `pointer` | Handle to the thrown exception object |
| `ExceptionInfo` | `ThrownObject` | `pointer` | The thrown exception object (an object reference, not a handle) |
| `Thread` | `ExceptionTracker` | `pointer` | Pointer to exception tracking information |
| `Thread` | `UEWatsonBucketTrackerBuckets` | `pointer` | Pointer to thread Watson buckets data (optional, Windows only) |

Expand Down
2 changes: 1 addition & 1 deletion docs/design/datacontracts/data-descriptor-meanings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@
"ExceptionInfo.PreviousNestedInfo": "Pointer to previous nested exception info",
"ExceptionInfo.StackHighBound": "High bound of the stack range unwound by this exception",
"ExceptionInfo.StackLowBound": "Low bound of the stack range unwound by this exception",
"ExceptionInfo.ThrownObject": "Handle to the thrown exception object",
"ExceptionInfo.ThrownObject": "The thrown exception object (an object reference, not a handle)",
"ExceptionLookupTableEntry.ExceptionInfoRVA": "RVA of the exception clause data",
"ExceptionLookupTableEntry.MethodStartRVA": "RVA of the method start",
"ExceptionLookupTableEntry.Size": "Size of an exception lookup table entry in bytes",
Expand Down
15 changes: 9 additions & 6 deletions src/native/managed/cdac/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,9 +161,11 @@ Build from the runtime repo root:
./build.sh clr+clr.hosts+libs+tools.cdac -c Debug -lc Release
```

The debug build of the runtime (`-rc Debug`, which is the default when `-c Debug` is used)
is required for the brittle DAC to delegate to the cDAC. Release build of the libraries
(`-lc Release`) is highly recommended for a faster inner loop.
A Debug runtime is not required: when the cDAC is enabled, the legacy DAC can delegate to
it in Debug, Checked and Release runtime builds on the platforms that support it. The
`#if DEBUG` cross-validation still requires the legacy DAC to match the runtime build; the
testhost produced by the command above has both from the same build. Release build of the
libraries (`-lc Release`) is highly recommended for a faster inner loop.

Once the initial build is done, shorter incremental rebuilds can be done with:

Expand Down Expand Up @@ -194,9 +196,10 @@ to set `DOTNET_ENABLE_CDAC=1` on each test process.
### CI pipeline

The `runtime-diagnostics.yml` pipeline runs the SOS tests automatically on every PR that
touches `src/native/managed/cdac/**` or `src/coreclr/debug/runtimeinfo/**`. It runs the
tests twice — once with `-useCdac` (cDAC path) and once without (legacy DAC path) — on
Windows x64.
touches `src/native/managed/cdac/**` or `src/coreclr/debug/runtimeinfo/**`. The SOSTests
stage builds a Release runtime and the cDAC for each platform in `sosPlatforms` (Windows
x64, x86 and arm64, Linux x64 and arm64, macOS x64 and arm64), and SOS.Tests covers both
the legacy DAC and the cDAC configurations.

> **Note:** The runtime and diagnostics repos must be on the same major version. CLRMD
> validates the DAC binary version against the runtime, so a cross-major-version mismatch
Expand Down
Loading