Re: [PATCH v5 06/78] xarray: Change definition of sibling entries

[Matthew Wilcox]

On Tue, Dec 26, 2017 at 08:21:53PM +0300, Kirill A. Shutemov wrote:
> > +/**
> > + * xa_is_internal() - Is the entry an internal entry?
> > + * @entry: Entry retrieved from the XArray
> > + *
> > + * Return: %true if the entry is an internal entry.
> > + */
> 
> What does it mean "internal entry"? Is it just a term for non-value and
> non-data pointer entry? Do we allow anybody besides xarray implementation to
> use internal entires?
> 
> Do we have it documented?

We do!  include/linux/radix-tree.h has it documented right now:

/*
 * The bottom two bits of the slot determine how the remaining bits in the
 * slot are interpreted:
 *
 * 00 - data pointer
 * 01 - internal entry
 * 10 - exceptional entry
 * 11 - this bit combination is currently unused/reserved

Slightly further down this same patch you're commenting on, this comment
is added:

+/*
+ * Internal entries have the bottom two bits set to the value 10b.  Most
+ * internal entries are pointers to the next node in the tree.  Since the
+ * kernel unmaps page 0 to trap NULL pointer dereferences, we can use values
+ * 0-1023 for special purposes.  Values 0-62 are used for sibling
+ * entries.  Value 256 is used for the retry entry.
+ */

That comment is later changed to:

/*
 * Internal entries have the bottom two bits set to the value 10b.  Most
 * internal entries are pointers to the next node in the tree.  Since the
 * kernel unmaps page 0 to trap NULL pointer dereferences, we can use values
 * 0-1023 for special purposes.  Values 0-62 are used for sibling
 * entries.  Value 256 is used for zero entries.  Value 257 is used for the
 * retry entry.
 *
 * Errors are also represented as internal entries, but use the negative
 * space (-4094 to -2).  They're never stored in the slots array; only
 * generated by the normal API.
 */

Also, this section exists in the documentation patch:

+Internal Entries
+----------------
+
+The XArray reserves some entries for its own purposes.  These are never
+exposed through the normal API, but when using the advanced API, it's
+possible to see them.  Usually the best way to handle them is to pass them
+to :c:func:`xas_retry`, and retry the operation if it returns ``true``.

[...]