Skip to content

Commit 6410fb4

Browse files
0xdaryl0xdaryl
authored
Merge pull request eclipse-openj9#21003 from dsouzai/bootstrapdoc
Document the JIT bootstrap process
2 parents 04ddd2e + 7259f2d commit 6410fb4

File tree

2 files changed

+118
-0
lines changed

2 files changed

+118
-0
lines changed

‎doc/compiler/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,7 @@ In the end code generators perform binary encoding to write the appropriate bits
170170
* [Dynamic Loop Transfer (DLT) (OpenJ9)](https://github.com/eclipse-openj9/openj9/issues/12505)
171171
* Stack Walker
172172
* [J9JITExceptionTable (OpenJ9)](runtime/J9JITExceptionTable.md)
173+
* [Bootstrap (OpenJ9)](runtime/Bootstrap.md)
173174
</details>
174175

175176
* <details><summary><b>8. Memory</b></summary>

‎doc/compiler/runtime/Bootstrap.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<!--
2+
Copyright IBM Corp. and others 2025
3+
4+
This program and the accompanying materials are made available under
5+
the terms of the Eclipse Public License 2.0 which accompanies this
6+
distribution and is available at https://www.eclipse.org/legal/epl-2.0/
7+
or the Apache License, Version 2.0 which accompanies this distribution and
8+
is available at https://www.apache.org/licenses/LICENSE-2.0.
9+
10+
This Source Code may also be made available under the following
11+
Secondary Licenses when the conditions for such availability set
12+
forth in the Eclipse Public License, v. 2.0 are satisfied: GNU
13+
General Public License, version 2 with the GNU Classpath
14+
Exception [1] and GNU General Public License, version 2 with the
15+
OpenJDK Assembly Exception [2].
16+
17+
[1] https://www.gnu.org/software/classpath/license.html
18+
[2] https://openjdk.org/legal/assembly-exception.html
19+
20+
SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0 OR GPL-2.0-only WITH OpenJDK-assembly-exception-1.0
21+
-->
22+
23+
# Background
24+
25+
The OpenJ9 VM bootstraps in a staged approach. These stages are enumerated in
26+
the [`INIT_STAGE` enum](https://github.com/eclipse-openj9/openj9/blob/d4f97df2b8d823389467d4e9114c557b53a5d311/runtime/oti/jvminit.h#L196-L217).
27+
Among these stages, there are a few that are relevant to the JIT. This document
28+
describes the initialization that the JIT performs in each stage.
29+
30+
The VM invokes the JIT hook
31+
```
32+
IDATA J9VMDllMain(J9JavaVM* vm, IDATA stage, void * reserved)
33+
```
34+
for each stage, passing the stage as an argument. The JIT then switches on
35+
`stage`; in each case it does work appropriate for that stage.
36+
37+
# Stages
38+
39+
The following stages are in chronological order (in a JVM that starts up
40+
without error).
41+
42+
## `DLL_LOAD_TABLE_FINALIZED`
43+
44+
This stage is used to perform some very early bootstrap initialization via
45+
```
46+
bool initializeJIT(J9JavaVM *vm)
47+
```
48+
as well as to consume external JVM command line options relevant to the JIT.
49+
50+
## `SYSTEM_CLASSLOADER_SET` (`AOT_INIT_STAGE`)
51+
52+
The JIT defines `AOT_INIT_STAGE` to `SYSTEM_CLASSLOADER_SET`, to contrast with
53+
`JIT_INITIALIZED` as well as to make explicit that very early AOT initialization
54+
occurs first. Specifically, this stage is used to set the `J9JIT_AOT_ATTACHED`
55+
runtime flag in the `J9JITConfig` (though this gets reset and set yet again
56+
later on), as well as to set the `aotrtInitialized` boolean variable.
57+
58+
## `JIT_INITIALIZED`
59+
60+
This stage is used to perform the bulk of the main initialization of the
61+
JIT. `-Xjit` and `-Xaot` arguments are preprocessed here, as well as the
62+
initialization of a significant portion of the `J9JITConfig` via
63+
```
64+
J9JITConfig * codert_onload(J9JavaVM * javaVM)
65+
```
66+
Finally, The bulk of the initialization performed in this stage occurs in
67+
```
68+
jint onLoadInternal(J9JavaVM * javaVM, J9JITConfig *jitConfig, char *xjitCommandLine, char *xaotCommandLine, UDATA flagsParm, void *reserved0, I_32 xnojit);
69+
```
70+
which includes initializing
71+
* `J9JITConfig` function pointers
72+
* Verbose Log infrastructure
73+
* Persistent Memory
74+
* CH Table
75+
* Compilation Info
76+
* Options (including JITServer client configuration)
77+
* Runtime Assumption Table
78+
* Code and Data Caches
79+
* Compilation Threads
80+
* IProfiler
81+
82+
## `ABOUT_TO_BOOTSTRAP`
83+
84+
This stage is used to perform the remainder of the main initialization of the
85+
JIT. This stage does some early `TR_J9SharedCache` initialization followed by
86+
the bulk of remaining initialization performed in
87+
```
88+
int32_t aboutToBootstrap(J9JavaVM * javaVM, J9JITConfig * jitConfig);
89+
```
90+
which includes
91+
* Options Post Processing (including FSD)
92+
* Performing SCC Validations
93+
* Setting up Hooks
94+
* Creating the Sampler Thread
95+
96+
## `VM_INITIALIZATION_COMPLETE`
97+
98+
This stage is used to finish initializing the Sampler, IProfiler, and
99+
Compilation Threads.
100+
101+
## `INTERPRETER_SHUTDOWN`
102+
103+
This stage is used to shut down the infrastructure of various components in the
104+
JIT (including the Sampler, IProfiler, and Compilation Threads) via
105+
```
106+
void JitShutdown(J9JITConfig * jitConfig);
107+
```
108+
109+
## `LIBRARIES_ONUNLOAD` and `JVM_EXIT_STAGE`
110+
111+
This stage can also invoke `JitShutdown` if the `INTERPRETER_SHUTDOWN` stage was
112+
skipped. In addition, it frees the `J9JITConfig` as well as various data
113+
structures allocated by the JIT.
114+
115+
`LIBRARIES_ONUNLOAD` is used to do an early unload of the JIT dll if the JIT
116+
detects (in the `DLL_LOAD_TABLE_FINALIZED` stage) that the
117+
`TR_DisableFullSpeedDebug` environment variable is set.

0 commit comments

Comments
 (0)