[PATCH v3 3/3] Documentation: riscv: correct sv57 kernel behavior

[Yangyu Chen]

The original documentation treated the hint address on mmap as the upper
bound, since we have already removed this behavior, this document should
be updated. Most of the content is copied from the corresponding feature
in x86_64 with some modifications to align with the current kernel's
behavior on RISC-V.

Signed-off-by: Yangyu Chen <cyy at cyyself.name>
---
 Documentation/arch/riscv/vm-layout.rst | 43 +++++++++++++++++---------
 1 file changed, 29 insertions(+), 14 deletions(-)

diff --git a/Documentation/arch/riscv/vm-layout.rst b/Documentation/arch/riscv/vm-layout.rst
index 077b968dcc81..826d0a3f4cbf 100644
--- a/Documentation/arch/riscv/vm-layout.rst
+++ b/Documentation/arch/riscv/vm-layout.rst
@@ -136,17 +136,32 @@ RISC-V Linux Kernel SV57
   __________________|____________|__________________|_________|____________________________________________________________
 
 
-Userspace VAs
---------------------
-To maintain compatibility with software that relies on the VA space with a
-maximum of 48 bits the kernel will, by default, return virtual addresses to
-userspace from a 48-bit range (sv48). This default behavior is achieved by
-passing 0 into the hint address parameter of mmap. On CPUs with an address space
-smaller than sv48, the CPU maximum supported address space will be the default.
-
-Software can "opt-in" to receiving VAs from another VA space by providing
-a hint address to mmap. When a hint address is passed to mmap, the returned
-address will never use more bits than the hint address. For example, if a hint
-address of `1 << 40` is passed to mmap, a valid returned address will never use
-bits 41 through 63. If no mappable addresses are available in that range, mmap
-will return `MAP_FAILED`.
+User-space and large virtual address space
+==========================================
+On RISC-V, Sv57 paging enables 56-bit userspace virtual address space. Not all
+user space is ready to handle wide addresses. It's known that at least some JIT
+compilers use higher bits in pointers to encode their information. It collides
+with valid pointers with Sv57 paging and leads to crashes.
+
+To mitigate this, we are not going to allocate virtual address space above
+47-bit by default.
+
+But userspace can ask for allocation from full address space by specifying hint
+address (with or without MAP_FIXED) above 47-bits, or hint address + size above
+47-bits with MAP_FIXED.
+
+If hint address set above 47-bit, but MAP_FIXED is not specified, we try to look
+for unmapped area by specified address. If it's already occupied, we look for
+unmapped area in *full* address space, rather than from 47-bit window.
+
+A high hint address would only affect the allocation in question, but not any
+future mmap()s.
+
+Specifying high hint address without MAP_FIXED on older kernel or on machine
+without Sv57 paging support is safe. The hint will be treated as the upper bound
+of the address space to search, but this was removed in the future version of
+kernels. On machine without Sv57 paging support, the kernel will fall back to
+allocation from the supported address space.
+
+This approach helps to easily make application's memory allocator aware about
+large address space without manually tracking allocated virtual address space.
-- 
2.45.2