[PATCH v3] xarray: Document necessary flag in alloc-functions

[PATCH v3] xarray: Document necessary flag in alloc-functions

[Philipp Stanner]

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@redhat.com>
---
I used the time available until we can get this merged to create a
version-3, improving a few things.

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

Re: [PATCH v3] xarray: Document necessary flag in alloc-functions

[Matthew Wilcox]

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@redhat.com>
> ---
> 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
> 

Re: [PATCH v3] xarray: Document necessary flag in alloc-functions

[Philipp Stanner]

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@redhat.com>
> > ---
> > 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
> > 
>