Oh – well, nope, that's fine. I just 'abused' v3 as a RESEND as I didn't receive a "merged" message ;) Let's leave it as it is, thx for merging :) P. On Mon, 2023-09-11 at 15:51 +0100, Matthew Wilcox wrote: > On Mon, Sep 11, 2023 at 04:48:37PM +0200, Philipp Stanner wrote: > > Calling functions that wrap __xa_alloc() or __xa_alloc_cyclic() > > without > > the xarray previously having been initialized with the flag > > XA_FLAGS_ALLOC being set in xa_init_flags() results in undefined > > behavior. > > > > Document the necessity of setting this flag in all docstrings of > > functions that wrap said two functions. > > > > Signed-off-by: Philipp Stanner <pstanner@xxxxxxxxxx> > > --- > > I used the time available until we can get this merged to create a > > version-3, improving a few things. > > Umm, too late, v2 went upstream last week during the merge window. > > Do you still want to change the wording? > > > Changes since v2: > > - Phrase the comment differently: say "requires [...] an xarray > > [...]" > > instead of "must be operated on". > > - Improve the commit message and use the canonical format: a) > > describe > > the problem, b) name the solution in imperative form. > > > > Regards, > > P. > > --- > > include/linux/xarray.h | 18 ++++++++++++++++++ > > lib/xarray.c | 6 ++++++ > > 2 files changed, 24 insertions(+) > > > > diff --git a/include/linux/xarray.h b/include/linux/xarray.h > > index 741703b45f61..746a17b64aa6 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. > > * > > + * Requires the xarray to be 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 > > @@ -886,6 +889,9 @@ 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. > > * > > + * Requires the xarray to be initialized with flag XA_FLAGS_ALLOC > > set > > + * in xa_init_flags(). > > + * > > * Context: Any context. Takes and releases the xa_lock while > > * disabling softirqs. May sleep if the @gfp flags permit. > > * Return: 0 on success, -ENOMEM if memory could not be allocated > > or > > @@ -916,6 +922,9 @@ 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. > > * > > + * Requires the xarray to be initialized with flag XA_FLAGS_ALLOC > > set > > + * in xa_init_flags(). > > + * > > * Context: Process context. Takes and releases the xa_lock while > > * disabling interrupts. May sleep if the @gfp flags permit. > > * Return: 0 on success, -ENOMEM if memory could not be allocated > > or > > @@ -949,6 +958,9 @@ static inline int __must_check > > xa_alloc_irq(struct xarray *xa, u32 *id, > > * The search for an empty entry will start at @next and will wrap > > * around if necessary. > > * > > + * Requires the xarray to be 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 if the allocation succeeded without wrapping. 1 if > > the > > @@ -983,6 +995,9 @@ static inline int xa_alloc_cyclic(struct xarray > > *xa, u32 *id, void *entry, > > * The search for an empty entry will start at @next and will wrap > > * around if necessary. > > * > > + * Requires the xarray to be initialized with flag XA_FLAGS_ALLOC > > set > > + * in xa_init_flags(). > > + * > > * Context: Any context. Takes and releases the xa_lock while > > * disabling softirqs. May sleep if the @gfp flags permit. > > * Return: 0 if the allocation succeeded without wrapping. 1 if > > the > > @@ -1017,6 +1032,9 @@ static inline int xa_alloc_cyclic_bh(struct > > xarray *xa, u32 *id, void *entry, > > * The search for an empty entry will start at @next and will wrap > > * around if necessary. > > * > > + * Requires the xarray to be initialized with flag XA_FLAGS_ALLOC > > set > > + * in xa_init_flags(). > > + * > > * Context: Process context. Takes and releases the xa_lock while > > * disabling interrupts. May sleep if the @gfp flags permit. > > * Return: 0 if the allocation succeeded without wrapping. 1 if > > the > > diff --git a/lib/xarray.c b/lib/xarray.c > > index 2071a3718f4e..2b07c332d26b 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. > > * > > + * Requires the xarray to be 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. > > * > > + * Requires the xarray to be 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.41.0 > > >
