<h2> Testing Scope </h2>

JEP 8171181 facilitates users to allocate Java heap on an alternate memory device. A new command line flag -XX:AllocateHeapAt is added to specify the backing memory to be used for Java heap allocation. This flag takes a directory path and the Java VM, using memory mapping, allocates Java heap on the device which is managed by the file system where the path resides.<br><br>
The implementation modifies the JVM initialization code specifically while reserving memory for Java Heap. The ergonomics for heap size, compressed oops, etc, do not change. Example Java command lines to use the feature are:<br>

 - java -XX:AllocateHeapAt=&lt;directory path&gt; MyApplication <br>
 - java -Xmx32g -Xms32g -XX:AllocateHeapAt=&lt;directory path&gt; MyApplication <br>

<br>
To test this patch we need to test different paths taken to reserve the heap, both success and error scenarios. There are multiple paths taken to allocate heap which all eventually call different flavors of os::reserve_memory() to reserve memory. Below is the list of tests that need to be conducted to exercise the different paths.

 1. Heap allocation with AllocateHeapAt option specifying a valid directory path (plain command line, only other flags are -Xmx and -Xms).
 2. Heap allocation with compressed oops enabled (either ergonomically or on command line) <br>
<tab> In this case heap allocation is done by ReservedHeapSpace::initialize_compressed_heap() which computes possible heap base addresses before reserving memory.
 3. Heap allocation with compressed oops disabled (either ergonomically or on command line) <br>
Heap allocation bifurcates between this and above case depending on whether compressed oops are enabled. Here heap allocation is done by ReservedSpace:initialize() which does not involve compressed oops handling. 
 4. Heap allocation with flag HeapBaseMinAddress set on command line. <br>
With this flag VM tries to allocated Heap at user specified address. This tests a different path in ReservedHeapSpace::initialize_compressed_heap().
 5. Specifying AllocateHeapAt with an invalid directory. <br>
	In this case Java VM should fail at initialization with correct message.

<h2> Testing Methodology </h2>
The tests described above will be written as a mix of Jtreg and Gtest tests. The implementation generates a log "Successfully allocated Java heap at location.." with tags 'heap+gc' on successful allocation of heap with AllocateHeapAt option. On error Java VM exits with message "Error occurred during initialization of VM" along with specific message depending on error. These logs can be used to verify the correctness of the tests. <br>
We do not need special memory device for the purpose of testing. The directory path specified to -XX:AllocateHeapAt can be the test base directory.

<h2> Success criteria </h2>

*Describe criteria which would be used to consider the testing successful. Update "result" column at the end of test development for future reference*

|Criteria|Planned|Status|Result|Comments|
|-|-|-|-|-|
| Test pass rate| *100%* |  |  | *All tests should pass* |
| Test stability | *99%* |  |  | *make sure the test itself runs successfully* |
| Line coverage for new/changed C/C++ code | *80%* |  |  |  |