| Message ID | 20230713161712.3163-1-pstanner@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [1/1] xarray: Document necessary flag in alloc-functions | expand |
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.
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
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 <pstanner@redhat.com> --- 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(+)