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``. [...]
