Re: [PATCH v5 06/78] xarray: Change definition of sibling entries
From: Matthew Wilcox
Date: Tue Dec 26 2017 - 22:13:34 EST
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
+ * 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:
+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``.