[PATCH v6 4/4] RISC-V: mm: Document mmap changes

[Charlie Jenkins]

On Thu, Jul 20, 2023 at 08:59:12AM +0200, Alexandre Ghiti wrote:
> On Fri, Jul 14, 2023 at 6:56 PM Charlie Jenkins <charlie at rivosinc.com> wrote:
> >
> > The behavior of mmap is modified with this patch series, so explain the
> > changes to the mmap hint address behavior.
> >
> > Signed-off-by: Charlie Jenkins <charlie at rivosinc.com>
> > ---
> >  Documentation/riscv/vm-layout.rst | 22 ++++++++++++++++++++++
> >  1 file changed, 22 insertions(+)
> >
> > diff --git a/Documentation/riscv/vm-layout.rst b/Documentation/riscv/vm-layout.rst
> > index 5462c84f4723..892412b91300 100644
> > --- a/Documentation/riscv/vm-layout.rst
> > +++ b/Documentation/riscv/vm-layout.rst
> > @@ -133,3 +133,25 @@ RISC-V Linux Kernel SV57
> >     ffffffff00000000 |  -4     GB | ffffffff7fffffff |    2 GB | modules, BPF
> >     ffffffff80000000 |  -2     GB | ffffffffffffffff |    2 GB | kernel
> >    __________________|____________|__________________|_________|____________________________________________________________
> > +
> > +
> > +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. A call to mmap is guaranteed to return an address
> > +that will not override the unset left-aligned bits in the hint address,
> > +unless there is no space left in the address space. If there is no space
> > +available in the requested address space, an address in the next smallest
> > +available address space will be returned.
> > +
> > +For example, in order to obtain 48-bit VA space, a hint address greater than
> > +:code:`1 << 38` must be provided.
> 
> Is this correct? Shouldn't the hint be strictly greater than the
> address space it targets? In patch 1, you state that "A hint address
> passed to mmap will cause the largest address space that fits entirely
> into the hint to be used", it seems contradictory to me.
> 
That is a mistake, it should have a hint address greater than 1 << 47. I
will fix up the wording here.
> > Note that this is 38 due to sv39 userspace
> > +ending at :code:`1 << 38` and the addresses beyond this are reserved for the
> > +kernel. Similarly, to obtain 57-bit VA space addresses, a hint address greater
> > +than or equal to :code:`1 << 47` must be provided.
> > --
> > 2.41.0
> >