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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Tue, 26 Dec 2017 19:13:26 -0800
From:   Matthew Wilcox <willy@...radead.org>
To:     "Kirill A. Shutemov" <kirill@...temov.name>
Cc:     linux-kernel@...r.kernel.org,
        Matthew Wilcox <mawilcox@...rosoft.com>,
        Ross Zwisler <ross.zwisler@...ux.intel.com>,
        David Howells <dhowells@...hat.com>,
        Shaohua Li <shli@...nel.org>, Jens Axboe <axboe@...nel.dk>,
        Rehas Sachdeva <aquannie@...il.com>,
        Marc Zyngier <marc.zyngier@....com>, linux-mm@...ck.org,
        linux-fsdevel@...r.kernel.org,
        linux-f2fs-devel@...ts.sourceforge.net,
        linux-nilfs@...r.kernel.org, linux-btrfs@...r.kernel.org,
        linux-xfs@...r.kernel.org, linux-usb@...r.kernel.org,
        linux-raid@...r.kernel.org
Subject: Re: [PATCH v5 06/78] xarray: Change definition of sibling entries

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

[...]