linux-kernel - [PATCH RESEND] xarray: document that xa

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>] [day] [month] [year] [list]

Message-ID: <20240930131929.1424352-1-aliceryhl@google.com>
Date: Mon, 30 Sep 2024 13:19:29 +0000
From: Alice Ryhl <aliceryhl@...gle.com>
To: Matthew Wilcox <willy@...radead.org>, Jonathan Corbet <corbet@....net>
Cc: linux-fsdevel@...r.kernel.org, linux-doc@...r.kernel.org, 
	linux-kernel@...r.kernel.org, Alice Ryhl <aliceryhl@...gle.com>
Subject: [PATCH RESEND] xarray: document that xa_alloc uses the smallest index

The deprecated IDR data structure was used to allocate *small* ids for
things, and the property that the ids are small is often desireable for
various reasons. However, the IDR interface is deprecated in favor of
XArray.

Clarify that when replacing IDR with XArray, you do not give up the
guarantee that the generated ids are small, even if you use a very large
range such as xa_limit_32b.

Signed-off-by: Alice Ryhl <aliceryhl@...gle.com>
---
Sent previously here:
https://lore.kernel.org/all/20240201084739.1452854-1-aliceryhl@google.com/

 include/linux/xarray.h | 6 ++++++
 lib/xarray.c           | 2 ++
 2 files changed, 8 insertions(+)

diff --git a/include/linux/xarray.h b/include/linux/xarray.h
index 0b618ec04115..b525113d8d47 100644
--- a/include/linux/xarray.h
+++ b/include/linux/xarray.h
@@ -860,6 +860,8 @@ static inline int __must_check xa_insert_irq(struct xarray *xa,
  * stores the index into the @id pointer, then stores the entry at
  * that index.  A concurrent lookup will not see an uninitialised @id.
  *
+ * Always allocates the entry at the smallest possible index.
+ *
  * Must only be operated on an xarray initialized with flag XA_FLAGS_ALLOC set
  * in xa_init_flags().
  *
@@ -893,6 +895,8 @@ static inline __must_check int xa_alloc(struct xarray *xa, u32 *id,
  * stores the index into the @id pointer, then stores the entry at
  * that index.  A concurrent lookup will not see an uninitialised @id.
  *
+ * Always allocates the entry at the smallest possible index.
+ *
  * Must only be operated on an xarray initialized with flag XA_FLAGS_ALLOC set
  * in xa_init_flags().
  *
@@ -926,6 +930,8 @@ static inline int __must_check xa_alloc_bh(struct xarray *xa, u32 *id,
  * stores the index into the @id pointer, then stores the entry at
  * that index.  A concurrent lookup will not see an uninitialised @id.
  *
+ * Always allocates the entry at the smallest possible index.
+ *
  * Must only be operated on an xarray initialized with flag XA_FLAGS_ALLOC set
  * in xa_init_flags().
  *
diff --git a/lib/xarray.c b/lib/xarray.c
index 32d4bac8c94c..f0579aa37534 100644
--- a/lib/xarray.c
+++ b/lib/xarray.c
@@ -1831,6 +1831,8 @@ EXPORT_SYMBOL(xa_get_order);
  * stores the index into the @id pointer, then stores the entry at
  * that index.  A concurrent lookup will not see an uninitialised @id.
  *
+ * Always allocates the entry at the smallest possible index.
+ *
  * Must only be operated on an xarray initialized with flag XA_FLAGS_ALLOC set
  * in xa_init_flags().
  *
-- 
2.46.1.824.gd892dcdcdd-goog