Adds lines to the docstrings in xarray.h and xarray.c to inform about
the necessity of the XA_FLAGS_ALLOC flag being set when using
xa_alloc().
The documentation so far says that xa_alloc() is supposed to return
either -ENOMEM or -EBUSY in case of an error. If the xarray has been
initialized without the flag XA_FLAGS_ALLOC, however, xa_alloc() fails
with a different error code.
As hinted at in Documentation/core-api/xarray.rst, calling this function
requires that flag being set. The function's documentation should
reflect that as well.
Signed-off-by: Philipp Stanner <[email protected]>
---
I would pick up the other places where this information has to be
added if someone can provide me with a list :)
---
include/linux/xarray.h | 3 +++
lib/xarray.c | 6 ++++++
2 files changed, 9 insertions(+)
diff --git a/include/linux/xarray.h b/include/linux/xarray.h
index 741703b45f61..2970014fca54 100644
--- a/include/linux/xarray.h
+++ b/include/linux/xarray.h
@@ -856,6 +856,9 @@ 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.
*
+ * Must only be called on an xarray initialized with flag XA_FLAGS_ALLOC set
+ * in xa_init_flags().
+ *
* Context: Any context. Takes and releases the xa_lock. May sleep if
* the @gfp flags permit.
* Return: 0 on success, -ENOMEM if memory could not be allocated or
diff --git a/lib/xarray.c b/lib/xarray.c
index 2071a3718f4e..73b3f8b33a56 100644
--- a/lib/xarray.c
+++ b/lib/xarray.c
@@ -1802,6 +1802,9 @@ 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.
*
+ * Must only be called on an xarray initialized with flag XA_FLAGS_ALLOC set
+ * in xa_init_flags().
+ *
* Context: Any context. Expects xa_lock to be held on entry. May
* release and reacquire xa_lock if @gfp flags permit.
* Return: 0 on success, -ENOMEM if memory could not be allocated or
@@ -1850,6 +1853,9 @@ EXPORT_SYMBOL(__xa_alloc);
* The search for an empty entry will start at @next and will wrap
* around if necessary.
*
+ * Must only be called on an xarray initialized with flag XA_FLAGS_ALLOC set
+ * in xa_init_flags().
+ *
* Context: Any context. Expects xa_lock to be held on entry. May
* release and reacquire xa_lock if @gfp flags permit.
* Return: 0 if the allocation succeeded without wrapping. 1 if the
--
2.39.3
On Thu, Jul 13, 2023 at 06:17:11PM +0200, Philipp Stanner wrote:
> I would pick up the other places where this information has to be
> added if someone can provide me with a list :)
I'd suggest every wrapper function that calls __xa_alloc() or
__xa_alloc_cyclic() needs this same information (I think you caught
one of the six in the header file?).
Thanks for this, I think it's the right idea.
On Fri, 2023-07-14 at 06:14 +0100, Matthew Wilcox wrote:
> On Thu, Jul 13, 2023 at 06:17:11PM +0200, Philipp Stanner wrote:
> > I would pick up the other places where this information has to be
> > added if someone can provide me with a list :)
>
> I'd suggest every wrapper function that calls __xa_alloc() or
> __xa_alloc_cyclic() needs this same information (I think you caught
> one of the six in the header file?).
Alright, got them. I'll send a follow-up.
But what do you think about __xa_alloc() and __xa_alloc_cyclic()
themselves? They are part of the advanced user API afaik.
P.