Re: [PATCH 2/2] Documentation: maple_tree: Clarify behavior when using reserved values

[Wei-Lin Chang]

On Thu, May 07, 2026 at 05:24:11AM +0200, Liam R. Howlett wrote:
> On 26/05/04 05:57PM, Wei-Lin Chang wrote:
> > It doesn't matter whether the normal or the advanced API is used if the
> > user uses xa_{mk, to}_value when storing and retrieving the values. Just
> > specify that the normal API blocks usages of reserved values while the
> > advanced API does not.
> 
> Your comment above is incorrect.
> 
> The normal API will filter out reserved values on return while the
> advanced API will return whatever is stored there regardless of the
> value.
> 
> Meaning, if you store a reserved value with the advanced API, it will
> not be returned by the normal API.

This is valuable information, thanks for explaining.
However, I'm confused how this shows my comment incorrect?

>From the original doc:

<quote>
If the user needs to use a reserved value, then the user can convert the
value when using the :ref:`maple-tree-advanced-api`, but are blocked by
the normal API.
</quote>

To me this is conveying the following points:

1. User can convert the value with xa_{mk, to}_value() when using the
   advanced API if reserved values are being stored. This works because
   those functions transform the reserved values into non-reserved ones.
2. User can not use reserved values with or without xa_{mk, to}_value()
   with the normal API.
3. What happens when reserved values are stored is not clearly stated,
   but the normal API will block it.

In my understanding 2. is incorrect because if xa_{mk, to}_value() are
deployed, it doesn't matter whether the normal or advanced API is used,
they both work since the values stored aren't reserved.

Please do you mind pointing out what I am getting wrong here?

I was genuinely confused when I was reading the doc and trying to use
this data structure.

> 
> > 
> > Signed-off-by: Wei-Lin Chang <weilin.chang@xxxxxxx>
> > ---
> >  Documentation/core-api/maple_tree.rst | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/core-api/maple_tree.rst b/Documentation/core-api/maple_tree.rst
> > index 87020a30ba69..e5ccafb84804 100644
> > --- a/Documentation/core-api/maple_tree.rst
> > +++ b/Documentation/core-api/maple_tree.rst
> > @@ -30,9 +30,9 @@ Tree reserves values with the bottom two bits set to '10' which are below 4096
> >  (ie 2, 6, 10 .. 4094) for internal use.  If the entries may use reserved
> >  entries then the users can convert the entries using xa_mk_value() and convert
> >  them back by calling xa_to_value().  Note that xa_{mk, to}_value() bit shifts
> > -the given data, so the top bit will be lost.  If the user needs to use a
> > -reserved value, then the user can convert the value when using the
> > -:ref:`maple-tree-advanced-api`, but are blocked by the normal API.
> > +the given data, so the top bit will be lost.  Usage of reserved values is
> > +blocked by the normal API, and will cause undefined behavior if used with the
> > +:ref:`maple-tree-advanced-api`.
> 
> Which behaviour is undefined?

I originally thought storing reserved values could break the tree
because of its internal use (see 3. above).

Thanks,
Wei-Lin Chang

> 
> >  
> >  The Maple Tree can also be configured to support searching for a gap of a given
> >  size (or larger).
> > -- 
> > 2.43.0
> > 
> > 
> > -- 
> > maple-tree mailing list
> > maple-tree@xxxxxxxxxxxxxxxxxxx
> > https://lists.infradead.org/mailman/listinfo/maple-tree