Add README.md

Author: christianhaeubl

README.md

@@ -0,0 +1,106 @@
+# Overview
+
+This branch is based on the tag `25+37-jvmci-b04` of this repository and contains infrastructure that simplifies the integration of HotSpot garbage collectors into Native Image.
+
+## Limitations
+
+The current implementation has a few limitations:
+
+- Only `linux/amd64` and `linux/aarch64` are supported at the moment.
+  macOS and Windows support should be easy to add but the build system needs to be changed for that.
+- Only a **single** Native Image isolate is supported at the moment because the C++ code has process-wide global state.
+
+## Structure
+
+The directory structure is modeled closely after the OpenJDK, with a few notable differences:
+
+```
+src/
+└── hotspot/
+    ├── cpu/
+    ├── os/
+    ├── os_cpu/
+    ├── share/
+    ├── jfrfiles/    # JFR-related files (autogenerated)
+    ├── jvmtifiles/  # JVMTI-related files
+    ├── mocks/       # Autogenerated mocks for C/C++ header (see below)
+    └── svm/         # SVM-specific files (see below)
+```
+
+- **mocks/**: Contains autogenerated mocks for all deleted C/C++ headers.
+  This ensures that `#include` directives remain valid, which reduces the need for conditional compilation (`#ifdefs`) around header inclusion.
+- **svm/**: Contains files that either entirely new or significantly different from their OpenJDK counterparts.
+  The structure of the subdirectories mirrors the OpenJDK's `hotspot` directory.
+  - *Example*: `src/hotspot/svm/share/oops/oop.hpp` corresponds to `src/hotspot/share/oops/oop.hpp` in OpenJDK.
+
+## Differences to OpenJDK
+
+All files that were not strictly required were removed from the code base.
+This includes major components such as class loading, metaspace handling, JIT compilation, code generation, garbage collection, and other VM-internal infrastructure.
+
+Outside the `svm/` directory, SVM-specific changes are typically guarded with directives such as `#ifdef SVM`.
+In general, we try to keep the diff against OpenJDK minimal so that updating to new OpenJDK versions is reasonably easy.
+
+In addition, there are several large conceptual differences between Native Image and HotSpot, such as:
+
+- **Heap Management:** Native Image always uses a heap base.
+  So, `UseCompressedOops` is always `true`, regardless of the actual reference size.
+- **Argument & Option Handling:** Argument parsing and option handling are different as Native Image needs to distinguish between hosted and runtime options.
+  HotSpot options that are not relevant for Native Image are reduced to constants when the C++ sources are compiled.
+- **Stack Handling:** The C++ code does not understand the Native Image stack layout.
+  Therefore, the GC must call into Native Image to retrieve stack information.
+- **Thread Management:** All Java threads are managed by Native Image.
+  The GC is restricted to spawning only native (non-Java) worker threads.
+- **Metaspace & Class Loading:** Metaspace handling or class (un)loading are not supported at the moment.
+  Project Crema recently added a metaspace to Native Image, but this C++ GC infrastructure is not yet aware of that.
+- **VM Operations & Safepoints:** The VM operation thread in Native Image is a Java thread.
+  So, the handling of VM operations and safepoints is implemented completely differently than on HotSpot.
+- **Locking:** Only a subset of the HotSpot locks is used.
+  However, more locks must be accessible to Java threads because the VM operation thread is a Java thread. 
+- **Exception Handling:** Java exception support was entirely removed from the C++ code.
+  For example, when the Java heap runs out of memory, the `OutOfMemoryError` must be thrown on the Native Image side (and not by the C++ code).
+- **JIT-Compiled Code:** The lifecycle and handling of JIT compiled code (`nmethods`) are fundamentally different between Native Image and HotSpot.
+- **Hybrid Objects:** Native Image supports hybrid objects (with both instance fields and primitive array elements).
+  Methods like `oop::is_array()`, `oop::is_objArray()`, `oop::is_typeArray()`, `Klass::is_array_klass()`, `Klass::is_objArray_klass()`, and `Klass::is_typeArray_klass()` may return `false` for hybrid objects, so caution is required.
+- **Performance Data:** Code related to `UsePerfData` is different as Native Image is responsible for managing all related memory and data structures (the C++ may only update data in already existing data structures).
+
+## Current Status & Placeholders
+
+In some code parts, `Unimplemented()` serves as a placeholder for GC-specific functionality:
+
+- Core Functionality
+  - `src/hotspot/svm/svmImageHeap.hpp`
+  - `src/hotspot/svm/svmToGC.cpp`
+  - `src/hotspot/share/gc/shared/gcConfig.cpp`
+- Only relevant if `UsePerfData` is enabled in Native Image
+  - `src/hotspot/share/runtime/cpuTimeCounters.cpp`
+  - `src/hotspot/share/gc/shared/gcPolicyCounters.cpp`
+  - `src/hotspot/share/gc/shared/collectorCounters.cpp`
+  - `src/hotspot/share/gc/shared/collectedHeap.cpp`
+  - `src/hotspot/share/gc/shared/generationCounters.cpp`
+  - `src/hotspot/share/gc/shared/hSpaceCounters.cpp`
+  - `src/hotspot/share/gc/shared/ageTable.cpp`
+
+Besides that, the length of 0 for `GCThreadLocalData` in `src/hotspot/share/gc/shared/gcThreadLocalData.hpp` is a placeholder as well.
+
+## Build
+
+This branch uses a simple [Makefile](src/hotspot/Makefile) instead of the OpenJDK build system.
+The following build configurations are supported:
+
+- **Output formats**: Static (`.a`) or shared (`.so`) libraries
+- **Debug level**: `debug`, `fastdebug`, `notproduct`, `product`
+- **Reference size**: Compressed references (`cr`) or uncompressed references (`ur`)
+
+**To build all configurations:**
+```shell
+cd src/hotspot
+make -j16 build_all
+```
+
+**To build a shared library for local debugging:**
+```shell
+cd src/hotspot
+make -j16 build_debug_ur_so
+```
+