Skip to content

Commit 961d3bb

Browse files
EgorBoEgorBo
authored
Add a copilot prompt file for JIT-EE interface modifications (#115889)
1 parent ac7f8e0 commit 961d3bb

File tree

2 files changed

+244
-7
lines changed

2 files changed

+244
-7
lines changed

‎.github/prompts/add-new-jit-ee-api.prompt.md

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
---
2+
mode: 'agent'
3+
tools: ['githubRepo', 'codebase', 'terminalLastCommand']
4+
description: 'Add a new API to the JIT-VM (aka JIT-EE) interface in the codebase.'
5+
---
6+
7+
#### 1 — Goal
8+
9+
Implement **one** new JIT-VM (also known as JIT-EE) API and all supporting glue.
10+
The JIT-VM interface defines the APIs through which the JIT compiler communicates with the runtime (VM).
11+
12+
#### 2 — Prerequisites for the model
13+
14+
* You have full repo access
15+
* You may run scripts (e.g., `.sh` or `.bat`)
16+
* Ask **clarifying questions** before the first code change if anything (signature, types, platform constraints) is unclear.
17+
18+
#### 3 — Required user inputs
19+
20+
Ask the user for a C-like signature of the new API if it's not provided.
21+
Suggest `<repo_root>/src/coreclr/tools/Common/JitInterface/ThunkGenerator/ThunkInput.txt` file as a reference. Example:
22+
23+
```
24+
CORINFO_METHOD_HANDLE getUnboxedEntry(CORINFO_METHOD_HANDLE ftn, bool* requiresInstMethodTableArg);
25+
```
26+
27+
#### 4 — Implementation steps (must be completed in order)
28+
29+
1. Update the `ThunkInput.txt` file with the new API definition. Example:
30+
31+
```diff
32+
+CORINFO_METHOD_HANDLE getUnboxedEntry(CORINFO_METHOD_HANDLE ftn, bool* requiresInstMethodTableArg);
33+
```
34+
35+
Insert the new API definition without removing any existing entries, placing it near similar signatures.
36+
37+
2. Invoke `<repo_root>/src/coreclr/tools/Common/JitInterface/ThunkGenerator/gen.sh` script
38+
(or `<repo_root>/src/coreclr/tools/Common/JitInterface/ThunkGenerator/gen.bat` on Windows) to update auto-generated files.
39+
Use the correct directory for the script to run.
40+
41+
3. Open `<repo_root>/src/coreclr/inc/corinfo.h` and add the new API inside `class ICorStaticInfo` class as the last member. Example:
42+
43+
```diff
44+
+ virtual CORINFO_METHOD_HANDLE getUnboxedEntry(
45+
+ CORINFO_METHOD_HANDLE ftn,
46+
+ bool* requiresInstMethodTableArg
47+
+ ) = 0;
48+
```
49+
50+
4. Open `<repo_root>/src/coreclr/tools/Common/JitInterface/CorInfoImpl.cs` and add the new API in the end of `class CorInfoImpl` class declaration. Use `<repo_root>/src/coreclr/tools/Common/JitInterface/CorInfoImpl_generated.cs` to inspect how type parameters look like for C# for the newly added API since it is expected to be auto-generated there by the gen.sh(bat) script. Example:
51+
52+
```diff
53+
+ private CORINFO_METHOD_STRUCT_* getUnboxedEntry(CORINFO_METHOD_STRUCT_* ftn, ref bool requiresInstMethodTableArg)
54+
+ {
55+
+ // Hint for the developer: Use CorInfoImpl.RyuJit.cs and CorInfoImpl.ReadyToRun.cs if the implementation
56+
+ // is not shared for NativeAOT and R2R.
57+
+ throw new NotImplementedException();
58+
+ }
59+
```
60+
61+
5. Open `<repo_root>/src/coreclr/vm/jitinterface.cpp` and add a dummy implementation at the file's end. Example:
62+
63+
```diff
64+
+CORINFO_METHOD_HANDLE CEEInfo::getUnboxedEntry(
65+
+ CORINFO_METHOD_HANDLE ftn,
66+
+ bool* requiresInstMethodTableArg)
67+
+{
68+
+ CONTRACTL {
69+
+ THROWS;
70+
+ GC_TRIGGERS;
71+
+ MODE_PREEMPTIVE;
72+
+ } CONTRACTL_END;
73+
+
74+
+ CORINFO_METHOD_HANDLE result = NULL;
75+
+
76+
+ JIT_TO_EE_TRANSITION();
77+
+
78+
+ UNREACHABLE(); // To be implemented
79+
+
80+
+ EE_TO_JIT_TRANSITION();
81+
+
82+
+ return result;
83+
+}
84+
```
85+
86+
6. Now implement the most complex part - SuperPMI. SuperPMI acts as a (de)serializer for JIT-VM queries in order
87+
to then replay them without the actual VM to speed up jit-diffs and other scenarios. All parameters and return
88+
values recorded/restored using special primitve types and helpers. We need to update the following files:
89+
90+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/agnostic.h`:
91+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/lwmlist.h`:
92+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/methodcontext.h`:
93+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/methodcontext.cpp`:
94+
95+
Go through each of them one by one.
96+
97+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/agnostic.h`:
98+
Define two `Agnostic_*` types for input arguments and another one for output parameters (return value, output arguments).
99+
Do not create them if one of the generics ones can be re-used such as `DLD`, `DD`, `DLDL`, etc. Use `DWORD*`
100+
like types for integers. Inspect the whole file to see how other APIs are defined.
101+
102+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/lwmlist.h`:
103+
Add a new entry to the `LWM` list. Example:
104+
105+
```diff
106+
+LWM(GetUnboxedEntry, DWORDLONG, DLD);
107+
```
108+
109+
NOTE: Use upper-case for the first letter of the API name here.
110+
Add the new record after the very last LWM one.
111+
112+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/methodcontext.h`:
113+
Define 3 methods in this header file inside `class MethodContext` class (at the end of its definition).
114+
115+
The methods are prefixed with `rec*` (record), `dmp*` (dump to console) and `rep*` (replay). Example
116+
117+
```diff
118+
+ void recGetUnboxedEntry(CORINFO_METHOD_HANDLE ftn, bool* requiresInstMethodTableArg, CORINFO_METHOD_HANDLE result);
119+
+ void dmpGetUnboxedEntry(DWORDLONG key, DLD value);
120+
+ CORINFO_METHOD_HANDLE repGetUnboxedEntry(CORINFO_METHOD_HANDLE ftn, bool* requiresInstMethodTableArg);
121+
```
122+
Now add a new element to `enum mcPackets` enum in the same file. Example:
123+
124+
```diff
125+
+ Packet_GetUnboxedEntry = <last value + 1>,
126+
```
127+
128+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/methodcontext.cpp`:
129+
Add the implementation of the 3 methods to `methodcontext.cpp` at the end of it.
130+
Consider other similar methods in the file for reference. Do not change implementations of other methods in the file. Example:
131+
132+
```diff
133+
+void MethodContext::recGetUnboxedEntry(CORINFO_METHOD_HANDLE ftn,
134+
+ bool* requiresInstMethodTableArg,
135+
+ CORINFO_METHOD_HANDLE result)
136+
+{
137+
+ // Initialize the "input - output" map if it is not already initialized
138+
+ if (GetUnboxedEntry == nullptr)
139+
+ {
140+
+ GetUnboxedEntry = new LightWeightMap<DWORDLONG, DLD>();
141+
+ }
142+
+
143+
+ // Create a key out of the input arguments
144+
+ DWORDLONG key = CastHandle(ftn);
145+
+ DLD value;
146+
+ value.A = CastHandle(result);
147+
+
148+
+ // Create a value out of the return value and out parameters
149+
+ if (requiresInstMethodTableArg != nullptr)
150+
+ {
151+
+ value.B = (DWORD)*requiresInstMethodTableArg ? 1 : 0;
152+
+ }
153+
+ else
154+
+ {
155+
+ value.B = 0;
156+
+ }
157+
+
158+
+ // Save it to the map
159+
+ GetUnboxedEntry->Add(key, value);
160+
+ DEBUG_REC(dmpGetUnboxedEntry(key, value));
161+
+}
162+
+void MethodContext::dmpGetUnboxedEntry(DWORDLONG key, DLD value)
163+
+{
164+
+ // Dump key and value to the console for debug purposes.
165+
+ printf("GetUnboxedEntry ftn-%016" PRIX64 ", result-%016" PRIX64 ", requires-inst-%u", key, value.A, value.B);
166+
+}
167+
+CORINFO_METHOD_HANDLE MethodContext::repGetUnboxedEntry(CORINFO_METHOD_HANDLE ftn, bool* requiresInstMethodTableArg)
168+
+{
169+
+ // Create a key out of the input arguments
170+
+ DWORDLONG key = CastHandle(ftn);
171+
+
172+
+ // Perform the lookup to obtain the value (output arguments and return value)
173+
+ DLD value = LookupByKeyOrMiss(GetUnboxedEntry, key, ": key %016" PRIX64 "", key);
174+
+ DEBUG_REP(dmpGetUnboxedEntry(key, value));
175+
+
176+
+ // propagate result to output arguments and return value (if exists)
177+
+ if (requiresInstMethodTableArg != nullptr)
178+
+ {
179+
+ *requiresInstMethodTableArg = (value.B == 1);
180+
+ }
181+
+ return (CORINFO_METHOD_HANDLE)(value.A);
182+
+}
183+
```
184+
185+
7. Add a new function to `<repo_root>/src/coreclr/tools/superpmi/superpmi/icorjitinfo.cpp` that calls the `rep*` method. Example:
186+
187+
```diff
188+
+CORINFO_METHOD_HANDLE MyICJI::getUnboxedEntry(CORINFO_METHOD_HANDLE ftn, bool* requiresInstMethodTableArg)
189+
+{
190+
+ jitInstance->mc->cr->AddCall("getUnboxedEntry");
191+
+ CORINFO_METHOD_HANDLE result = jitInstance->mc->repGetUnboxedEntry(ftn, requiresInstMethodTableArg);
192+
+ return result;
193+
+}
194+
```
195+
196+
8. Add a new function to `<repo_root>/src/coreclr/tools/superpmi/superpmi-shim-collector/icorjitinfo.cpp` that calls the `rec*` method. Example:
197+
198+
```diff
199+
+CORINFO_METHOD_HANDLE interceptor_ICJI::getUnboxedEntry(CORINFO_METHOD_HANDLE ftn, bool* requiresInstMethodTableArg)
200+
+{
201+
+ mc->cr->AddCall("getUnboxedEntry");
202+
+ bool localRequiresInstMethodTableArg = false;
203+
+ CORINFO_METHOD_HANDLE result = original_ICorJitInfo->getUnboxedEntry(ftn, &localRequiresInstMethodTableArg);
204+
+ mc->recGetUnboxedEntry(ftn, &localRequiresInstMethodTableArg, result);
205+
+ if (requiresInstMethodTableArg != nullptr)
206+
+ {
207+
+ *requiresInstMethodTableArg = localRequiresInstMethodTableArg;
208+
+ }
209+
+ return result;
210+
+}
211+
```
212+
213+
#### 5 — Definition of Done (self-check list)
214+
215+
* [ ] New API present in **all** layers.
216+
* [ ] Each source file changed exactly once; no unrelated edits. The following files must be changed:
217+
* `<repo_root>/src/coreclr/tools/Common/JitInterface/ThunkGenerator/ThunkInput.txt`
218+
* `<repo_root>/src/coreclr/inc/corinfo.h`
219+
* `<repo_root>/src/coreclr/tools/Common/JitInterface/CorInfoImpl.cs`
220+
* `<repo_root>/src/coreclr/vm/jitinterface.cpp`
221+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/agnostic.h`:
222+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/lwmlist.h`:
223+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/methodcontext.h`:
224+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/methodcontext.cpp`:
225+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/agnostic.h` [optional]
226+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shared/lwmlist.h`
227+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi/icorjitinfo.cpp`
228+
* `<repo_root>/src/coreclr/tools/superpmi/superpmi-shim-collector/icorjitinfo.cpp`
229+
* [ ] All TODO/UNREACHABLE markers remain for future functional implementation.

‎docs/project/updating-jitinterface.md

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,6 @@
22

33
JitInterface is the binary interface that is used to communicate with the JIT. The bulk of the interface consists of the ICorStaticInfo and ICorDynamicInfo interfaces and enums/structs used by those interfaces.
44

5-
Following header files define parts of the JIT interface: cordebuginfo.h, corinfo.h, corjit.h, corjitflags.h, corjithost.h.
6-
75
The JitInterface serves two purposes:
86
* Standardizes the interface between the runtime and the JIT (potentially allowing mixing and matching JITs and runtimes)
97
* Allows the JIT to be used elsewhere (outside of the runtime)
@@ -12,12 +10,22 @@ There are several components that consume the JIT outside of the runtime. Since
1210

1311
The JitInterface is versioned by a GUID. Any change to JitInterface is required to update the JitInterface GUID located in jiteeversionguid.h (look for `JITEEVersionIdentifier`). Not doing so has consequences that are sometimes hard to debug.
1412

15-
If a method was added or modified in ICorStaticInfo or ICorDynamicInfo, port the change to src/coreclr/tools/Common/JitInterface/ThunkGenerator/ThunkInput.txt. Functions must be in the same order in ThunkInput.txt as they exist in corinfo.h and corjit.h. Run gen.bat or gen.sh to regenerate all \*_generated.\* files from ThunkInput.txt. Provide a managed implementation of the method in CorInfoImpl.cs.
13+
## Adding a new JIT-VM API manually
1614

17-
## Porting JitInterface changes to crossgen2
15+
It's a good idea to choose an existing API that is similar to the one you want to add and use it as a template. The following steps are required to add a new JIT-VM API:
1816

19-
Crossgen2 is the AOT compiler for CoreCLR. It generates native code for .NET apps ahead of time and uses the JIT to do that. Since crossgen2 is written in managed code, it doesn't consume the C++ headers and maintains a managed copy of them. Changes to JitInterface need to be ported managed code.
17+
1) Start from adding a new entry in the `ThunkInput.txt` file. This file is used to generate the JIT-VM interface and is located in `src/coreclr/tools/Common/JitInterface/ThunkGenerator/`. For complex types, you may need to also configure type mapping in the beginning of the file.
18+
2) Invoke the `gen.sh` script (or `gen.bat` on Windows) to update the auto-generated files `*_generated.*` and update the JIT-EE guid.
19+
3) Open `src/coreclr/inc/corinfo.h` and add the new API in `ICorStaticInfo`
20+
4) Open `src/coreclr/tools/Common/JitInterface/CorInfoImpl.cs` and add the new API in `CorInfoImpl` class. If the implementation is not shared for NativeAOT and R2R, use `CorInfoImpl.RyuJit.cs` and `CorInfoImpl.ReadyToRun.cs` to implement the API.
21+
5) Open `src/coreclr/vm/jitinterface.cpp` and add the CoreCLR-specific implementation
22+
6) Open `lwmlist.h` and add a definition of "input-args" - "output-args" map. Either use the generic `DLD`-like structs or create new ones in `agnostic.h`
23+
7) Open `src/coreclr/tools/superpmi/superpmi-shared/methodcontext.h` and add the necessary recording, dumping, and replaying methods for the new API and then implement them in `methodcontext.cpp`
24+
8) Update `enum mcPackets` in `src/coreclr/tools/superpmi/superpmi-shared/methodcontext.h` to include an entry for the new API and bump the max value of the enum
25+
9) Use the `rec*` and `rep*` methods in `src/coreclr/tools/superpmi/superpmi/icorjitinfo.cpp` and `src/coreclr/tools/superpmi/superpmi-shim-collector/icorjitinfo.cpp` accordingly
2026

21-
1. If an enum/struct was modified or added, port the change to CorInfoTypes.cs.
22-
2. If a method was added or modified in ICorStaticInfo or ICorDynamicInfo, if the managed implementation is specific to CoreCLR ReadyToRun (and doesn't apply to full AOT compilation), provide the implementation in CorInfoImpl.ReadyToRun.cs instead or CorInfoImpl.cs.
27+
## Adding a new JIT-VM API through an agent
2328

29+
[add-new-jit-ee-api.prompt.md](../../.github/prompts/add-new-jit-ee-api.prompt.md) contains a prompt that can be used to add a new JIT-VM API through an agent. Example usage in VSCode:
30+
* Open the Copilot Chat Window
31+
* Type "/add-new-jit-ee-api.prompt" and either hit enter and follow the instructions or provide the API signature directly. Gpt-4.1 and Claude Sonnet 4 or 3.7 are recommended for this task.

0 commit comments

Comments
 (0)