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

Matthew Wilcox
2023-09-11T21:17:39Z

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
>