os::vm_allocation_granularity() is undocumented and maybe sometimes misunderstood and overused.

It is undocumented, but I believe it exists to describe, in a platform independent manner, the alignment restrictions of mapping address of os::reserve_memory and os::attempt_reserve_memory_at(req_addr) and, possibly, the mapping size. The latter is unclear and technically not needed, see below.

Background:

os::reserve_memory uses platform apis to map memory. These are:
1) mmap on posix platforms
2) virtualalloc on Windows
3) shmat sometimes on posix platforms (linux, for huge pages, and aix in 64K paged mode)

(1) mmap allows mapping to any page aligned address. addresses not page aligned will cause the mapping to be aligned to a page aligned starting address [1]
(2) on windows, VirtualAlloc will only map memory at addresses aligned to Allocation Granularity. If request address is not aligned, it will be aligned (as with mmap). Allocation granularity is usually larger than page size (64k vs 4K) but I am not sure whether it can be equal too [2]
(3) shmat requires mapping addresses to be aligned to SHMLBA. Depending on the system, this may be just page size too (eg Linux x64), it may be larger (eg Cygwin: 64K, since it uses windows alloc granularity; AIX: 256MB; possibly different on other linuxes) [3] [4]

(Side note: (2) and (3) also do not allow partial unmapping)

--

It looks like os::vm_allocation_granularity was introduced to hide this complexity. However, it is broken by design, since this alignment requirement is not a property of the system but of the API we use. E.g. on Linux, you can reserve via mmap or via shmat; the latter happens e.g. when reserving the heap in large page mode. So, it cannot be a system wide constant.

Even ignoring that, the allocation granularity is often misused to align up memory reservation sizes when it only affects memory attach address alignment.

We often specify it as alignment for memory where we do not have a wish address (see e.g. the numerous calls to the ReservedSpace constructor). But if we are fine with any address the OS uses we should not have to specify it. The OS will place the mapping anywhere it deems fit, allocation granularity or not.
We often use it to align the size of the mapped area. That is just unnecessary, since with no API there is a size alignment restriction.

In theory, we should only have to use os::vm_allocation_granularity() if caller code needs a specific wish address*and* is unable to cope with a slightly corrected address the kernel returns.
 
(Side note: currently hotspot does not care much at all for SHMLBA alignment beside asserting; in particular, no caller of these APIs takes care of providing that alignment. I believe this works more out of accident now, either because SHMLBA happens to be page sized, or because the input address is out of accident aligned to SHMLBA.)

--

[1] https://pubs.opengroup.org/onlinepubs/009695399/functions/mmap.html
[2] https://docs.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc
[3] https://pubs.opengroup.org/onlinepubs/007904975/functions/shmget.html
[4] https://pubs.opengroup.org/onlinepubs/009695399/functions/shmat.html