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

[Wei-Lin Chang]

On Tue, May 12, 2026 at 04:50:36PM -0400, Liam R. Howlett wrote:
> On 26/05/07 11:09PM, Wei-Lin Chang wrote:
> > 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.
> 
> Hmm, maybe I answered too quickly here.  We filter out XA_ZERO_ENTRY on
> normal API searches, which is in the reserved range.
> 
> > However, I'm confused how this shows my comment incorrect?
> 
> It matters if you use the xa_(mk, to}_value since the top bit will be
> lost.  Re-reading your comment, you don't specifically say that though,
> you said 'if the user uses..', so I was confused by your wording of what
> you were saying.

Ah, sorry for not being clear.

> 
> > 
> > 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 think you are missing the part where the top bit may be lost?
> 
> I also don't think the reserved values will matter if you use the
> advanced API exclusively.  You would have to filter the special cases or
> whatever you want - that is, if you mix the interfaces then you may see
> odd behaviour in regards to the special cases in the normal API while
> the advanced API would return the reserved items and need to be filtered
> at a higher level than the maple tree code.

I see.

> 
> > 
> > I was genuinely confused when I was reading the doc and trying to use
> > this data structure.
> 
> Then we need to rework the wording somehow.  Thanks.
> 
> > 
> > > 
> > > > 
> > > > Signed-off-by: Wei-Lin Chang <weilin.chang at arm.com>
> > > > ---
> > > >  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).
> 
> You can't break the tree by storing reserved values.  The normal API
> will outright not allow storing it while the advanced API will store and
> return it.
> 
> The issue comes from when you mix and match - if you store a reserved
> value using the advanced api and then iterate through with the normal
> api, some values may be lost.  Today, that's XA_ZERO_ENTRY only, but we
> reserve the right to change that if it is necessary for some tree
> version.
> 
> Does that make sense?

Yes! Thanks for taking the time to explain.

Thanks,
Wei-Lin Chang

> 
> Thanks,
> Liam