Two files, one repository
dotnet/runtime ships 2 formats across 24 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 12 | 0% |
| Commands | 0 | 0 | 1 | 0% |
| Section tags | 0 | 0 | 4 | 0% |
What each file covers
Sections
0 shared · 1 only in A · 12 only in B- − `eng/common`
- + Native code (C/C++/asm) & interop
- + Correctness & Safety
- + Error Handling & Assertions
- + JIT-Specific Correctness
- + Performance & Allocations
- + Code Structure for Performance
- + Code Style & Formatting
- + Platform & Cross-Platform
- + Native Code & Interop
- + C++ Style
- + Runtime & VM Patterns
- + P/Invoke & Marshalling
Commands
0 shared · 0 only in A · 1 only in B- + python3 src/coreclr/scripts/jitformat.py -r . -o <os> -a <arch>
Section tags
0 shared · 0 only in A · 4 only in B- + lint-format
- + code-style
- + architecture
- + performance
Line diff
dotnet/runtime · eng/common/AGENTS.md
@@ −1 @@
1# `eng/common`
2
3Files under `eng/common` come from [Arcade](https://github.com/dotnet/arcade).
4Edits in `eng/common` will be overwritten by automation unless the changes are made directly in the Arcade repository.
5For more information, see the [Arcade documentation](https://github.com/dotnet/arcade/tree/main/Documentation).
6
dotnet/runtime · .github/instructions/native.instructions.md
@@ +1 @@
1---
2applyTo: "**/*.c,**/*.cc,**/*.cpp,**/*.cxx,**/*.h,**/*.hpp,**/*.inc,**/*.S,**/*.s,**/*.asm"
3---
4
5# Native code (C/C++/asm) & interop
6
7Conventions for native runtime code (CoreCLR VM, JIT, `src/native`, Mono native). Also apply
8`conventions`, `tests` for test changes, and `core-runtime` for CoreCLR and native host changes.
9For JIT specifics see `jit`; for networking interop see `system-net-interop`.
10
11## Correctness & Safety
12
13### Error Handling & Assertions
14
15- **Handle OOM with exceptions or fail-fast, never asserts.** Use `ThrowOutOfMemory` or `EEPOLICY_HANDLE_FATAL_ERROR`, not asserts. In interpreter loops, use `nothrow new` and check for null.
16- **Use `_ASSERTE(!"message")` for unreachable native paths.** Keep native assertion guidance in native code rather than applying managed exception patterns.
17- **Guard native size and offset arithmetic against overflow.** Validate multiplication and addition used for allocation sizes, buffer indexes, and pointer offsets before performing the operation. Prefer patterns and helpers that are correct by construction rather than checking an already-overflowed result.
18
19### JIT-Specific Correctness
20
21- **JIT lowering must not double-lower nodes.** Never call `LowerNode` on an already-lowered node. Return newly created nodes for the caller to lower. Constant folding belongs in import/morph, not lowering.
22- **Mark collectible ALC test methods `NoInlining`.** Methods that touch collectible assembly load contexts must be `[MethodImpl(MethodImplOptions.NoInlining)]` to prevent the JIT from keeping references alive.
23
24## Performance & Allocations
25
26### Code Structure for Performance
27
28- **Separate hot data from rarely-used data in runtime structures.** Keep frequently accessed data inline; move rarely-used data (GCInfo, DebugInfo) to separate structures.
29- **Compute constant data at compile time, not execution time.** In interpreter and similar hot paths, pre-compute metadata lookups and type checks during the compilation phase.
30
31## Code Style & Formatting
32
33- **Prefer table-driven approaches over excessive case statements.** For hardware intrinsics and pattern-heavy code, use lookup tables (`AuxiliaryJitType`, `SpecialCodeGen` flags) instead of many explicit case entries.
34- **Order struct fields to minimize padding.** In C/C++ struct definitions, order fields by size (pointers first) to reduce padding.
35- **Run `jit-format` before pushing JIT changes.** JIT code must pass `jit-format` to avoid immediately failing CI. Run it with `python3 src/coreclr/scripts/jitformat.py -r . -o <os> -a <arch>` in the repo root. This should be done automatically when authoring JIT code and prior to pushing.
36
37## Platform & Cross-Platform
38
39- **Use correct platform/feature defines.** Use `TARGET_*`/`HOST_*` defines rather than compiler-provided defines (`__wasm__`). Use `HOST_*` for build machine code, `TARGET_*` for target platform. Use `PORTABILITY_ASSERT` for unimplemented platform code.
40
41## Native Code & Interop
42
43### C++ Style
44
45- **Don't use `auto` in the runtime C++ codebase.** Use explicit types. Exception: unspeakable types like lambdas.
46- **Use `nullptr`, `void*`, and native C++ types over legacy aliases.** Prefer `nullptr` over `NULL`, `void*` over `LPVOID`. Use `WCHAR` (not `wchar_t`) in Windows host code. Use `.inc` suffix for multiply-included files.
47- **Match `#endif` comments to `#ifdef` exactly.** Add comments on `#else`/`#endif` for non-trivial blocks. Consistent brace placement and four-space indentation.
48- **Prefer `static_cast` over C-style casts.** C-style casts are more permissive than needed and can silently degrade to `reinterpret_cast`.
49
50### Runtime & VM Patterns
51
52- **Use correct VM contracts and QCall patterns.** QCalls that may throw need `BEGIN_QCALL`/`END_QCALL`. Simple QCalls use `QCALL_CONTRACT_NO_GC_TRANSITION`. All VM methods need `STANDARD_VM_CONTRACT` or `WRAPPER_NO_CONTRACT`.
53- **Append new GC-EE interface methods last.** Preserve vtable slot ordering by adding methods only at the end of the interface.
54- **Keep GC protection correct around managed references.** Ensure all GC references are `GCPROTECT`-ed before GC-triggering calls. After GC-triggering calls, use `ObjectFromHandle(handle)` for a fresh reference.
55- **Avoid dynamic allocation on fatal error paths.** Use stack-allocated buffers. Use simple synchronization (Interlocked with spin-wait) instead of Monitor/lock.
56- **Avoid thread-local objects with destructors in CoreCLR.** Destruction order is arbitrary. Tie lifetime to the CoreCLR Thread object. Prefer `PLATFORM_THREAD_LOCAL` from minipal over C++ `thread_local` in perf-critical paths.
57- **Use `SET_UNALIGNED` macros for potentially unaligned writes.** In code generation stubs, use `SET_UNALIGNED_32/64` rather than direct pointer dereferencing.
58- **Zero-initialize arrays and buffers that may be partially used.** Zero-init allocated arrays whose elements have destructors. Zero-init EH tables, C arrays, and similar structures.
59- **Add static asserts for hardcoded structural offsets.** When using hardcoded offsets to access struct fields (especially in assembly), add static asserts to verify them.
60- **Use minipal for new platform abstractions.** Use minipal (new) instead of PAL (legacy) for platform abstraction in new CoreCLR code. Use `ALTERNATE_ENTRY` (not `LOCAL_LABEL`) for assembly labels called from outside their function.
61- **Use `JITDUMP` and `LOG` macros, not `printf`.** In JIT code use `JITDUMP`. In CoreCLR VM use `LOG()`/`LOGGING` defines. Do not use `printf` or `Console.WriteLine` in production native code.
62
63### P/Invoke & Marshalling
64
65- **Prefer 4-byte `BOOL` for native interop marshalling.** Use `UnmanagedType.Bool`. Verify P/Invoke return types match native signatures exactly—mismatches may work on 64-bit but fail on 32-bit/WASM.
66
@@ −1 +1 @@
1−# `eng/common`
1+---
2+applyTo: "**/*.c,**/*.cc,**/*.cpp,**/*.cxx,**/*.h,**/*.hpp,**/*.inc,**/*.S,**/*.s,**/*.asm"
3+---
24
3−Files under `eng/common` come from [Arcade](https://github.com/dotnet/arcade).
4−Edits in `eng/common` will be overwritten by automation unless the changes are made directly in the Arcade repository.
5−For more information, see the [Arcade documentation](https://github.com/dotnet/arcade/tree/main/Documentation).
5+# Native code (C/C++/asm) & interop
6+
7+Conventions for native runtime code (CoreCLR VM, JIT, `src/native`, Mono native). Also apply
8+`conventions`, `tests` for test changes, and `core-runtime` for CoreCLR and native host changes.
9+For JIT specifics see `jit`; for networking interop see `system-net-interop`.
10+
11+## Correctness & Safety
12+
13+### Error Handling & Assertions
14+
15+- **Handle OOM with exceptions or fail-fast, never asserts.** Use `ThrowOutOfMemory` or `EEPOLICY_HANDLE_FATAL_ERROR`, not asserts. In interpreter loops, use `nothrow new` and check for null.
16+- **Use `_ASSERTE(!"message")` for unreachable native paths.** Keep native assertion guidance in native code rather than applying managed exception patterns.
17+- **Guard native size and offset arithmetic against overflow.** Validate multiplication and addition used for allocation sizes, buffer indexes, and pointer offsets before performing the operation. Prefer patterns and helpers that are correct by construction rather than checking an already-overflowed result.
18+
19+### JIT-Specific Correctness
20+
21+- **JIT lowering must not double-lower nodes.** Never call `LowerNode` on an already-lowered node. Return newly created nodes for the caller to lower. Constant folding belongs in import/morph, not lowering.
22+- **Mark collectible ALC test methods `NoInlining`.** Methods that touch collectible assembly load contexts must be `[MethodImpl(MethodImplOptions.NoInlining)]` to prevent the JIT from keeping references alive.
23+
24+## Performance & Allocations
25+
26+### Code Structure for Performance
27+
28+- **Separate hot data from rarely-used data in runtime structures.** Keep frequently accessed data inline; move rarely-used data (GCInfo, DebugInfo) to separate structures.
29+- **Compute constant data at compile time, not execution time.** In interpreter and similar hot paths, pre-compute metadata lookups and type checks during the compilation phase.
30+
31+## Code Style & Formatting
32+
33+- **Prefer table-driven approaches over excessive case statements.** For hardware intrinsics and pattern-heavy code, use lookup tables (`AuxiliaryJitType`, `SpecialCodeGen` flags) instead of many explicit case entries.
34+- **Order struct fields to minimize padding.** In C/C++ struct definitions, order fields by size (pointers first) to reduce padding.
35+- **Run `jit-format` before pushing JIT changes.** JIT code must pass `jit-format` to avoid immediately failing CI. Run it with `python3 src/coreclr/scripts/jitformat.py -r . -o <os> -a <arch>` in the repo root. This should be done automatically when authoring JIT code and prior to pushing.
36+
37+## Platform & Cross-Platform
38+
39+- **Use correct platform/feature defines.** Use `TARGET_*`/`HOST_*` defines rather than compiler-provided defines (`__wasm__`). Use `HOST_*` for build machine code, `TARGET_*` for target platform. Use `PORTABILITY_ASSERT` for unimplemented platform code.
40+
41+## Native Code & Interop
42+
43+### C++ Style
44+
45+- **Don't use `auto` in the runtime C++ codebase.** Use explicit types. Exception: unspeakable types like lambdas.
46+- **Use `nullptr`, `void*`, and native C++ types over legacy aliases.** Prefer `nullptr` over `NULL`, `void*` over `LPVOID`. Use `WCHAR` (not `wchar_t`) in Windows host code. Use `.inc` suffix for multiply-included files.
47+- **Match `#endif` comments to `#ifdef` exactly.** Add comments on `#else`/`#endif` for non-trivial blocks. Consistent brace placement and four-space indentation.
48+- **Prefer `static_cast` over C-style casts.** C-style casts are more permissive than needed and can silently degrade to `reinterpret_cast`.
49+
50+### Runtime & VM Patterns
51+
52+- **Use correct VM contracts and QCall patterns.** QCalls that may throw need `BEGIN_QCALL`/`END_QCALL`. Simple QCalls use `QCALL_CONTRACT_NO_GC_TRANSITION`. All VM methods need `STANDARD_VM_CONTRACT` or `WRAPPER_NO_CONTRACT`.
53+- **Append new GC-EE interface methods last.** Preserve vtable slot ordering by adding methods only at the end of the interface.
54+- **Keep GC protection correct around managed references.** Ensure all GC references are `GCPROTECT`-ed before GC-triggering calls. After GC-triggering calls, use `ObjectFromHandle(handle)` for a fresh reference.
55+- **Avoid dynamic allocation on fatal error paths.** Use stack-allocated buffers. Use simple synchronization (Interlocked with spin-wait) instead of Monitor/lock.
56+- **Avoid thread-local objects with destructors in CoreCLR.** Destruction order is arbitrary. Tie lifetime to the CoreCLR Thread object. Prefer `PLATFORM_THREAD_LOCAL` from minipal over C++ `thread_local` in perf-critical paths.
57+- **Use `SET_UNALIGNED` macros for potentially unaligned writes.** In code generation stubs, use `SET_UNALIGNED_32/64` rather than direct pointer dereferencing.
58+- **Zero-initialize arrays and buffers that may be partially used.** Zero-init allocated arrays whose elements have destructors. Zero-init EH tables, C arrays, and similar structures.
59+- **Add static asserts for hardcoded structural offsets.** When using hardcoded offsets to access struct fields (especially in assembly), add static asserts to verify them.
60+- **Use minipal for new platform abstractions.** Use minipal (new) instead of PAL (legacy) for platform abstraction in new CoreCLR code. Use `ALTERNATE_ENTRY` (not `LOCAL_LABEL`) for assembly labels called from outside their function.
61+- **Use `JITDUMP` and `LOG` macros, not `printf`.** In JIT code use `JITDUMP`. In CoreCLR VM use `LOG()`/`LOGGING` defines. Do not use `printf` or `Console.WriteLine` in production native code.
62+
63+### P/Invoke & Marshalling
64+
65+- **Prefer 4-byte `BOOL` for native interop marshalling.** Use `UnmanagedType.Bool`. Verify P/Invoke return types match native signatures exactly—mismatches may work on 64-bit but fail on 32-bit/WASM.
666
