From 419602f446c8553e6a668a00e8af7dec0d4600f3 Mon Sep 17 00:00:00 2001
From: Sreekala Gopakumar <Sreekala.Gopakumar@ibm.com>
Date: Thu, 7 Dec 2023 19:43:37 +0530
Subject: [PATCH] Enforce/Disable IProfiler during startup phase with
 -XX:[+/-]IProfileDuringStartupPhase

https://github.com/eclipse-openj9/openj9-docs/issues/1204

Added a new topic for the new option, XX:[+/-]IProfileDuringStartupPhase. Updated the What's new in version 0.42.0 topic and the yaml file.

Closes #1204
Signed-off-by: Sreekala Gopakumar <sreekala.gopakumar@ibm.com>
---
 docs/version0.42.md                  |  5 +++
 docs/xxiprofileduringstartupphase.md | 49 ++++++++++++++++++++++++++++
 mkdocs.yml                           |  1 +
 3 files changed, 55 insertions(+)
 create mode 100644 docs/xxiprofileduringstartupphase.md

diff --git a/docs/version0.42.md b/docs/version0.42.md
index 4e3610f93e..6dbf762c82 100644
--- a/docs/version0.42.md
+++ b/docs/version0.42.md
@@ -28,6 +28,7 @@ The following new features and notable changes since version 0.41.0 are included
 - [New binaries and changes to supported environments](#binaries-and-supported-environments)
 - ![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) [OpenJ9 `jextract` removed](#openj9-jextract-removed) ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
 - [Change in the `System.gc()` call behavior](#change-in-the-systemgc-call-behavior)
+- [New `-XX:[+|-]IProfileDuringStartupPhase` option added](#new-xx-iprofileduringstartupphase-option-added)
 - ![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) [New JDK 21 features](#new-jdk-21-features) ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
 
 ## Features and changes
@@ -52,6 +53,10 @@ Now, the `System.gc()` call triggers the GC cycle twice internally to clear the
 
 For more information, see [Garbage collection](gc_overview.md).
 
+### New `-XX:[+|-]IProfileDuringStartupPhase` option added
+
+The VM uses heuristics to decide whether to collect interpreter profiling information during the VM startup. You can overrule the heuristics and control the collection of the profiling information during the startup phase by using the [`-XX:[+|-]IProfileDuringStartupPhase`](xxiprofileduringstartupphase.md) option.
+
 ### ![Start of content that applies to Java 21 plus](cr/java21plus.png) New JDK 21 features
 
 The following features are supported by OpenJ9:
diff --git a/docs/xxiprofileduringstartupphase.md b/docs/xxiprofileduringstartupphase.md
new file mode 100644
index 0000000000..9cf147a346
--- /dev/null
+++ b/docs/xxiprofileduringstartupphase.md
@@ -0,0 +1,49 @@
+<!--
+* Copyright (c) 2017, 2023 IBM Corp. and others
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which accompanies this distribution and is available at
+* https://www.eclipse.org/legal/epl-2.0/ or the Apache
+* License, Version 2.0 which accompanies this distribution and
+* is available at https://www.apache.org/licenses/LICENSE-2.0.
+*
+* This Source Code may also be made available under the
+* following Secondary Licenses when the conditions for such
+* availability set forth in the Eclipse Public License, v. 2.0
+* are satisfied: GNU General Public License, version 2 with
+* the GNU Classpath Exception [1] and GNU General Public
+* License, version 2 with the OpenJDK Assembly Exception [2].
+*
+* [1] https://www.gnu.org/software/classpath/license.html
+* [2] https://openjdk.org/legal/assembly-exception.html
+*
+* 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
+-->
+
+# -XX:[+|-]IProfileDuringStartupPhase
+
+This option enables or disables the data collection by the interpreter profiler during a VM startup.
+
+## Syntax
+
+        -XX:[+|-]IProfileDuringStartupPhase
+
+| Setting                          | Effect  |
+|----------------------------------|---------|
+|`-XX:+IProfileDuringStartupPhase` | Enable  |
+|`-XX:-IProfileDuringStartupPhase` | Disable |
+
+## Explanation
+
+The VM collects interpreter profiling data that is used to optimize methods at the time of JIT compilation. To reduce the CPU usage of the interpreter profiler during the startup phase, the VM stores such profiling data in the shared classes cache. During startup, the VM uses heuristics to determine when to turn on data collection and when to rely on the data that was collected by a previous VM and stored in the cache. You can overrule the heuristics and control the collection of the profiling information during the startup phase by using the `-XX:[+|-]IProfileDuringStartupPhase` option.
+
+- If the `-XX:+IProfileDuringStartupPhase` option is specified, the VM always collects the latest interpreter profiling information during startup and stores the information in the shared classes cache. By using this option, the quality of the generated code might increase, leading to better long-term throughput. But, this option might increase the startup time of applications.
+- If the `-XX:-IProfileDuringStartupPhase` option is specified, the VM does not collect interpreter profiling information during the startup phase. Use this option if the shared classes cache already contains sufficient interpreter profiling information and therefore, you don't have to collect new information and affect the startup time.
+
+## See also
+
+- [The JIT compiler](jit.md)
+
+
+<!-- ==== END OF TOPIC ==== xxiprofileduringstartupphase.md ==== -->
diff --git a/mkdocs.yml b/mkdocs.yml
index 6cfb6a04c3..f4d925fabb 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -409,6 +409,7 @@ nav:
             - "-XX:InitialRAMPercentage"                                         : xxinitialrampercentage.md
             - "-XX:InitialHeapSize"                                              : xxinitialheapsize.md
             - "-XX:[+|-]InterleaveMemory"                                        : xxinterleavememory.md
+            - "-XX:[+|-]IProfileDuringStartupPhase"                              : xxiprofileduringstartupphase.md
             - "-XX:[+|-]JITInlineWatches"                                        : xxjitinlinewatches.md
             - "-XX:JITServerAddress"                                             : xxjitserveraddress.md
             - "-XX:JITServerAOTCacheDir"                                         : xxjitserveraotcachedir.md