dotnet · AaronRobinsonMSFT · Mar 14, 2026 · Mar 14, 2026
diff --git a/docs/design/coreclr/INDEX.md b/docs/design/coreclr/INDEX.md
@@ -0,0 +1,129 @@
+# CoreCLR Design Documentation Index
+
+This index maps topics to their design documents and primary source locations,
+to help navigate the CoreCLR codebase. All source paths are relative to the
+repository root.
+
+## How to Use This Index
+
+- **"I want to understand X"** → find the topic below, read the linked doc, then explore the source files listed.
+- **"I'm changing file Y"** → use the [Source Directory Map](#source-directory-map) to find related design docs.
+- **Recommended reading order for newcomers**: start with [Introduction to the CLR](botr/intro-to-clr.md), then [Type System](botr/type-system.md), then the topic relevant to your work.
+
+---
+
+## Topic → Document → Source Files
+
+### Runtime Core (Book of the Runtime)
+
+| Topic | Document | Primary Source Files |
+|-------|----------|---------------------|
+| CLR overview | [intro-to-clr.md](botr/intro-to-clr.md) | `src/coreclr/vm/ceemain.cpp` (startup) |
+| Type system | [type-system.md](botr/type-system.md) | `src/coreclr/vm/methodtable.h`, `src/coreclr/vm/class.h`, `src/coreclr/vm/typedesc.h`, `src/coreclr/vm/typehandle.h` |
+| Type loading | [type-loader.md](botr/type-loader.md) | `src/coreclr/vm/clsload.hpp`, `src/coreclr/vm/methodtablebuilder.cpp` |
+| Method descriptors | [method-descriptor.md](botr/method-descriptor.md) | `src/coreclr/vm/method.hpp`, `src/coreclr/vm/precode.h` |
+| Virtual stub dispatch | [virtual-stub-dispatch.md](botr/virtual-stub-dispatch.md) | `src/coreclr/vm/virtualcallstub.h` |
+| Garbage collection | [garbage-collection.md](botr/garbage-collection.md) | `src/coreclr/gc/gc.cpp`, `src/coreclr/gc/gcinterface.h`; `src/coreclr/vm/gchelpers.cpp` |
+| Threading | [threading.md](botr/threading.md) | `src/coreclr/vm/threads.h`, `src/coreclr/vm/threadsuspend.h` |
+| Exceptions (CLR internal) | [exceptions.md](botr/exceptions.md) | `src/coreclr/inc/ex.h`; `src/coreclr/vm/excep.h`, `src/coreclr/vm/exceptionhandling.h` |
+| Stack walking | [stackwalking.md](botr/stackwalking.md) | `src/coreclr/vm/stackwalk.h`, `src/coreclr/vm/frames.h` |
+| System.Private.CoreLib | [corelib.md](botr/corelib.md) | `src/coreclr/System.Private.CoreLib/` |
+| DAC (diagnostics) | [dac-notes.md](botr/dac-notes.md) | `src/coreclr/debug/daccess/` |
+| Profiling | [profiling.md](botr/profiling.md) | `src/coreclr/vm/proftoeeinterfaceimpl.h` |
+| Profilability | [profilability.md](botr/profilability.md) | `src/coreclr/vm/proftoeeinterfaceimpl.cpp` |
+| ReadyToRun | [readytorun-overview.md](botr/readytorun-overview.md) | `src/coreclr/vm/readytoruninfo.h` |
+| ReadyToRun format | [readytorun-format.md](botr/readytorun-format.md) | `src/coreclr/inc/readytorun.h` |
+| Shared generics | [shared-generics.md](botr/shared-generics.md) | `src/coreclr/vm/generics.h` |
+| Managed type system | [managed-type-system.md](botr/managed-type-system.md) | `src/coreclr/tools/Common/TypeSystem/` |
+| CLR ABI | [clr-abi.md](botr/clr-abi.md) | `src/coreclr/jit/codegencommon.cpp`, `src/coreclr/inc/corinfo.h` |
+| Vectors and intrinsics | [vectors-and-intrinsics.md](botr/vectors-and-intrinsics.md) | `src/coreclr/jit/hwintrinsic.h` |
+| Async codegen | [runtime-async-codegen.md](botr/runtime-async-codegen.md) | `src/coreclr/jit/` |
+| Porting guide | [guide-for-porting.md](botr/guide-for-porting.md) | — |
+| Logging | [logging.md](botr/logging.md) | `src/coreclr/inc/log.h` |
+| ILC architecture (NativeAOT) | [ilc-architecture.md](botr/ilc-architecture.md) | `src/coreclr/tools/aot/ILCompiler.Compiler/` |
+
+### JIT Compiler
+
+| Topic | Document | Primary Source Files |
+|-------|----------|---------------------|
+| **JIT overview (start here)** | [ryujit-overview.md](jit/ryujit-overview.md) | `src/coreclr/jit/compiler.h`, `src/coreclr/jit/ee_il_dll.cpp` |
+| JIT tutorial | [ryujit-tutorial.md](jit/ryujit-tutorial.md) | `src/coreclr/jit/` |
+| Register allocation (LSRA) | [lsra-detail.md](jit/lsra-detail.md) | `src/coreclr/jit/lsra.h`, `src/coreclr/jit/lsra.cpp` |
+| LSRA heuristic tuning | [lsra-heuristic-tuning.md](jit/lsra-heuristic-tuning.md) | `src/coreclr/jit/lsra.cpp` |
+| LSRA throughput | [lsra-throughput.md](jit/lsra-throughput.md) | `src/coreclr/jit/lsra.cpp` |
+| Struct handling | [first-class-structs.md](jit/first-class-structs.md) | `src/coreclr/jit/promotion.cpp`, `src/coreclr/jit/morph.cpp` |
+| Struct ABI | [struct-abi.md](jit/struct-abi.md) | `src/coreclr/jit/compiler.h` |
+| Inlining | [inlining-plans.md](jit/inlining-plans.md) | `src/coreclr/jit/inlinepolicy.h`, `src/coreclr/jit/inline.h` |
+| Inline size estimates | [inline-size-estimates.md](jit/inline-size-estimates.md) | `src/coreclr/jit/inlinepolicy.cpp` |
+| GC write barriers | [GC-write-barriers.md](jit/GC-write-barriers.md) | `src/coreclr/jit/gcinfo.cpp` |
+| GC info (x86) | [jit-gc-info-x86.md](jit/jit-gc-info-x86.md) | `src/coreclr/jit/gcinfo.cpp` |
+| Viewing JIT dumps | [viewing-jit-dumps.md](jit/viewing-jit-dumps.md) | `src/coreclr/jit/jitconfigvalues.h` |
+| Guarded devirtualization | [GuardedDevirtualization.md](jit/GuardedDevirtualization.md) | `src/coreclr/jit/indirectcalltransformer.cpp` |
+| Call morphing | [jit-call-morphing.md](jit/jit-call-morphing.md) | `src/coreclr/jit/morph.cpp` |
+| Finally optimizations | [finally-optimizations.md](jit/finally-optimizations.md) | `src/coreclr/jit/fgehopt.cpp` |
+| EH write-through | [eh-writethru.md](jit/eh-writethru.md) | `src/coreclr/jit/lsra.cpp` |
+| Multi-reg call nodes | [multi-reg-call-nodes.md](jit/multi-reg-call-nodes.md) | `src/coreclr/jit/gentree.h` |
+| Hot/cold splitting | [hot-cold-splitting.md](jit/hot-cold-splitting.md) | `src/coreclr/jit/flowgraph.cpp` |
+| Object stack allocation | [object-stack-allocation.md](jit/object-stack-allocation.md) | `src/coreclr/jit/objectalloc.cpp` |
+| Escape analysis | [DeabstractionAndConditionalEscapeAnalysis.md](jit/DeabstractionAndConditionalEscapeAnalysis.md) | `src/coreclr/jit/objectalloc.cpp` |
+| Value numbering | [Optimization of Heap Access in Value Numbering.md](jit/Optimization%20of%20Heap%20Access%20in%20Value%20Numbering.md) | `src/coreclr/jit/valuenum.h` |
+| Profile count reconstruction | [profile-count-reconstruction.md](jit/profile-count-reconstruction.md) | `src/coreclr/jit/flowgraph.cpp` |
+| Perf score | [Perf-Score.md](jit/Perf-Score.md) | `src/coreclr/jit/emitarm64.cpp`, `src/coreclr/jit/emitxarch.cpp` |
+| Porting RyuJIT | [porting-ryujit.md](jit/porting-ryujit.md) | `src/coreclr/jit/target.h` |
+| ARM64 frame layout | [arm64-jit-frame-layout.md](jit/arm64-jit-frame-layout.md) | `src/coreclr/jit/codegenarm64.cpp` |
+| Longs on 32-bit | [longs-on-32bit-arch.md](jit/longs-on-32bit-arch.md) | `src/coreclr/jit/decomposelongs.cpp` |
+| Variable tracking | [variabletracking.md](jit/variabletracking.md) | `src/coreclr/jit/codegencommon.cpp` |
+| Optimizer planning | [JitOptimizerPlanningGuide.md](jit/JitOptimizerPlanningGuide.md) | `src/coreclr/jit/optimizer.cpp` |
+| Optimizer TODO | [JitOptimizerTodoAssessment.md](jit/JitOptimizerTodoAssessment.md) | `src/coreclr/jit/optimizer.cpp` |
+| Stack buffer overflow protection | [Stack Buffer Overflow Protection.md](jit/Stack%20Buffer%20Overflow%20Protection.md) | `src/coreclr/jit/gschecks.cpp` |
+| Stress testing | [investigate-stress.md](jit/investigate-stress.md) | `src/coreclr/jit/jitconfigvalues.h` |
+| WASM JIT | [WebAssembly overview for JIT.md](jit/WebAssembly%20overview%20for%20JIT.md) | `src/coreclr/jit/` |
+
+### Profiling
+
+| Topic | Document | Primary Source Files |
+|-------|----------|---------------------|
+| Profiling overview | [profiling/README.md](profiling/README.md) | `src/coreclr/vm/proftoeeinterfaceimpl.h` |
+| Profiler attach | [Profiler Attach on CoreCLR.md](profiling/Profiler%20Attach%20on%20CoreCLR.md) | `src/coreclr/vm/proftoeeinterfaceimpl.cpp` |
+| ReJIT on attach | [ReJIT on Attach.md](profiling/ReJIT%20on%20Attach.md) | `src/coreclr/vm/rejit.h` |
+| IL rewriting | [IL Rewriting Basics.md](profiling/IL%20Rewriting%20Basics.md) | `src/coreclr/vm/proftoeeinterfaceimpl.cpp` |
+| Breaking changes | [Profiler Breaking Changes.md](profiling/Profiler%20Breaking%20Changes.md) | — |
+| Blog archive (historical) | [davbr-blog-archive/](profiling/davbr-blog-archive/README.md) | — |
+
+---
+
+## Source Directory Map
+
+Use this to find design docs relevant to source directories you're working in.
+
+| Source Directory | Description | Related Design Docs |
+|-----------------|-------------|---------------------|
+| `src/coreclr/vm/` | Runtime VM (core execution engine) | [type-system](botr/type-system.md), [type-loader](botr/type-loader.md), [threading](botr/threading.md), [exceptions](botr/exceptions.md), [gc](botr/garbage-collection.md), [profiling](botr/profiling.md) |
+| `src/coreclr/jit/` | JIT compiler (RyuJIT) | [ryujit-overview](jit/ryujit-overview.md), [lsra-detail](jit/lsra-detail.md), [first-class-structs](jit/first-class-structs.md), all jit/ docs |
+| `src/coreclr/gc/` | Garbage collector | [garbage-collection](botr/garbage-collection.md) |
+| `src/coreclr/inc/` | Shared headers (corjit.h, corinfo.h, etc.) | [ryujit-overview](jit/ryujit-overview.md) (JIT/EE interface), [clr-abi](botr/clr-abi.md) |
+| `src/coreclr/debug/` | Debugger and DAC | [dac-notes](botr/dac-notes.md) |
+| `src/coreclr/pal/` | Platform Abstraction Layer | [guide-for-porting](botr/guide-for-porting.md) |
+| `src/coreclr/nativeaot/` | NativeAOT compiler | [ilc-architecture](botr/ilc-architecture.md) |
+| `src/coreclr/tools/` | Crossgen2, ILVerify, R2RDump, etc. | [readytorun-overview](botr/readytorun-overview.md) |
+| `src/coreclr/System.Private.CoreLib/` | Managed core library | [corelib](botr/corelib.md) |
+| `src/coreclr/interpreter/` | IL interpreter | *(no design doc yet)* |
+
+---
+
+## Key Entry Points
+
+These are the most important functions to start from when tracing a subsystem:
+
+| Subsystem | Entry Point | File |
+|-----------|-------------|------|
+| JIT compilation | `CILJit::compileMethod()` | `src/coreclr/jit/ee_il_dll.cpp` |
+| Runtime startup | `EEStartup()` | `src/coreclr/vm/ceemain.cpp` |
+| Type loading | `ClassLoader::LoadTypeHandleThrowing()` | `src/coreclr/vm/clsload.cpp` |
+| Method table building | `MethodTableBuilder::BuildMethodTableThrowing()` | `src/coreclr/vm/methodtablebuilder.cpp` |
+| GC allocation | `GCHeapUtilities::GetGCHeap()` | `src/coreclr/vm/gcheaputilities.h` |
+| GC collection | `GCHeap::GarbageCollect()` | `src/coreclr/gc/gc.cpp` |
+| Thread creation | `SetupThread()` | `src/coreclr/vm/threads.cpp` |
+| Exception throw | `COMPlusThrow()` | `src/coreclr/vm/excep.h` |
+| Stack walk | `Thread::StackWalkFramesEx()` | `src/coreclr/vm/stackwalk.cpp` |
+| Virtual dispatch | `VirtualCallStubManager::ResolveWorker()` | `src/coreclr/vm/virtualcallstub.cpp` |
diff --git a/docs/design/coreclr/botr/exceptions.md b/docs/design/coreclr/botr/exceptions.md
@@ -300,3 +300,20 @@ Miscellaneous
 =============
 
 There are actually a lot of macros involved in EX_TRY. Most of them should never, ever, be used outside of the macro implementations.
+
+Key Source Files
+================
+
+All paths relative to repository root:
+
+| Component | Header | Implementation |
+|-----------|--------|----------------|
+| EX_TRY/EX_CATCH macros | `src/coreclr/inc/ex.h` | — |
+| Exception "kinds" | `src/coreclr/vm/rexcep.h` | — |
+| COMPlusThrow and helpers | `src/coreclr/vm/excep.h` | `src/coreclr/vm/excep.cpp` |
+| Managed exception handling | `src/coreclr/vm/exceptionhandling.h` | `src/coreclr/vm/exceptionhandling.cpp` |
+
+Key entry points:
+
+- `COMPlusThrow()` — throw a CLR internal exception by "kind" (`src/coreclr/vm/excep.h`)
+- `EX_TRY` / `EX_CATCH` / `EX_END_CATCH` — CLR internal exception handling macros (`src/coreclr/inc/ex.h`)
diff --git a/docs/design/coreclr/botr/garbage-collection.md b/docs/design/coreclr/botr/garbage-collection.md
@@ -327,6 +327,28 @@ Given WKS GC with concurrent GC on (default case), the code flow for a backgroun
 Resources
 =========
 
+Key Source Files
+----------------
+
+All paths relative to repository root:
+
+| Component | Header | Implementation |
+|-----------|--------|----------------|
+| GC implementation | `src/coreclr/gc/gc.h` | `src/coreclr/gc/gc.cpp` |
+| GC/EE interface | `src/coreclr/gc/gcinterface.h` | — |
+| GC heap utilities | `src/coreclr/vm/gcheaputilities.h` | `src/coreclr/vm/gcheaputilities.cpp` |
+| Allocation helpers | `src/coreclr/vm/gchelpers.h` | `src/coreclr/vm/gchelpers.cpp` |
+| Frozen object heap | `src/coreclr/vm/frozenobjectheap.h` | `src/coreclr/vm/frozenobjectheap.cpp` |
+
+Key entry points:
+
+- `GCHeapUtilities::GetGCHeap()` — access the GC heap singleton (`src/coreclr/vm/gcheaputilities.h`)
+- Managed allocations go through helpers in `src/coreclr/vm/gchelpers.cpp`
+- The GC's internal allocation and collection logic is in `src/coreclr/gc/gc.cpp`
+
+References
+----------
+
 - [.NET CLR GC Implementation](https://raw.githubusercontent.com/dotnet/runtime/main/src/coreclr/gc/gc.cpp)
 - [The Garbage Collection Handbook: The Art of Automatic Memory Management](http://www.amazon.com/Garbage-Collection-Handbook-Management-Algorithms/dp/1420082795)
 - [Garbage collection (Wikipedia)](http://en.wikipedia.org/wiki/Garbage_collection_(computer_science))

diff --git a/docs/design/coreclr/botr/method-descriptor.md b/docs/design/coreclr/botr/method-descriptor.md
@@ -281,3 +281,15 @@ PInvokeImportPrecode looks like this on x86:
 	mov eax,pMethodDesc
 	mov eax,eax // dummy instruction that marks the type of the precode
 	jmp PInvokeImportThunk // loads P/Invoke target for pMethodDesc lazily
+
+Key Source Files
+================
+
+All paths relative to repository root:
+
+| Component | Header | Implementation |
+|-----------|--------|----------------|
+| MethodDesc | `src/coreclr/vm/method.hpp` | `src/coreclr/vm/method.cpp` |
+| Precodes | `src/coreclr/vm/precode.h` | `src/coreclr/vm/precode.cpp` |
+| Method iteration | `src/coreclr/vm/method.hpp` | — |
+| Stub generation | `src/coreclr/vm/stubmgr.h` | `src/coreclr/vm/stubmgr.cpp` |
diff --git a/docs/design/coreclr/botr/stackwalking.md b/docs/design/coreclr/botr/stackwalking.md
@@ -83,3 +83,19 @@ For instance the CrawlFrame indicates the MethodDesc* for managed frames and the
 # Stackwalk Implementation Details
 
 Further low-level details of the stack walk implementation are currently outside the scope of this document. If you have knowledge of these and would care to share that knowledge please feel free to update this document.
+
+# Key Source Files
+
+All paths relative to repository root:
+
+| Component | Header | Implementation |
+|-----------|--------|----------------|
+| Stack walker | `src/coreclr/vm/stackwalk.h` | `src/coreclr/vm/stackwalk.cpp` |
+| CrawlFrame | `src/coreclr/vm/stackwalk.h` | — |
+| Frame types | `src/coreclr/vm/frames.h` | `src/coreclr/vm/frames.cpp` |
+| Thread (StackWalkFramesEx) | `src/coreclr/vm/threads.h` | `src/coreclr/vm/stackwalk.cpp` |
+
+Key entry points:
+
+- `Thread::StackWalkFramesEx()` — main API to walk a thread's stack (`src/coreclr/vm/stackwalk.cpp`)
+- `CrawlFrame` — context passed to stack walk callbacks (`src/coreclr/vm/stackwalk.h`)
diff --git a/docs/design/coreclr/botr/threading.md b/docs/design/coreclr/botr/threading.md
@@ -27,7 +27,7 @@ Every managed thread has an associated Thread object, defined in [threads.h][thr
 
 All Thread objects are stored in the ThreadStore (also defined in [threads.h][threads.h]), which is a simple list of all known Thread objects. To enumerate all managed threads, one must first acquire the ThreadStoreLock, then use ThreadStore::GetAllThreadList to enumerate all Thread objects. This list may include managed threads which are not currently assigned to native threads (for example, they may not yet be started, or the native thread may already have exited).
 
-[threads.h]: ../../../../src/coreclr/vm/threads.h
+[threads.h]: https://github.com/dotnet/runtime/blob/main/src/coreclr/vm/threads.h
 
 Each managed thread that is currently assigned to a native thread is reachable via a native thread-local storage (TLS) slot on that native thread. This allows code that is executing on that native thread to get the corresponding Thread object, via GetThread().
 
@@ -208,3 +208,21 @@ ThreadPool Threads
 ------------------
 
 The CLR's ThreadPool maintains a collection of managed threads for executing user "work items."  These managed threads are bound to native threads owned by the ThreadPool. The ThreadPool also maintains a small number of native threads to handle functions like "thread injection," timers, and "registered waits."
+
+Key Source Files
+================
+
+All paths relative to repository root:
+
+| Component | Header | Implementation |
+|-----------|--------|----------------|
+| Thread object | `src/coreclr/vm/threads.h` | `src/coreclr/vm/threads.cpp` |
+| ThreadStore (list of all threads) | `src/coreclr/vm/threads.h` | `src/coreclr/vm/threads.cpp` |
+| Thread suspension | `src/coreclr/vm/threadsuspend.h` | `src/coreclr/vm/threadsuspend.cpp` |
+| Thread statics | `src/coreclr/vm/threadstatics.h` | `src/coreclr/vm/threadstatics.cpp` |
+
+Key entry points:
+
+- `GetThread()` — retrieve the Thread object for the current native thread
+- `ThreadStore::GetAllThreadList()` — enumerate all managed threads (requires `ThreadStoreLock`)
+- `ThreadSuspend::SuspendRuntime()` — suspend all managed threads for GC
diff --git a/docs/design/coreclr/botr/type-loader.md b/docs/design/coreclr/botr/type-loader.md
@@ -3,6 +3,16 @@ Type Loader Design
 
 Author: Ladi Prosek - 2007
 
+Key source files (all paths relative to repository root):
+
+| Component | Header | Implementation |
+|-----------|--------|----------------|
+| ClassLoader | `src/coreclr/vm/clsload.hpp` | `src/coreclr/vm/clsload.cpp` |
+| MethodTable builder | `src/coreclr/vm/methodtablebuilder.h` | `src/coreclr/vm/methodtablebuilder.cpp` |
+| Class loading levels | `src/coreclr/vm/classloadlevel.h` | — |
+
+Key entry point: `ClassLoader::LoadTypeHandleThrowing()` in `src/coreclr/vm/clsload.cpp`
+
 # Introduction
 
 In a class-based object oriented system, types are templates