Re: [PATCH 7/7] mm/slab: document kfree() as allowed for kmem_cache_alloc() objects

[Mike Rapoport]

On Wed, Mar 15, 2023 at 02:38:47PM +0100, Vlastimil Babka wrote:
> On 3/12/23 10:59, Mike Rapoport wrote:
> > On Fri, Mar 10, 2023 at 11:32:09AM +0100, Vlastimil Babka wrote:
> >> This will make it easier to free objects in situations when they can
> >> come from either kmalloc() or kmem_cache_alloc(), and also allow
> >> kfree_rcu() for freeing objects from kmem_cache_alloc().
> >> 
> >> For the SLAB and SLUB allocators this was always possible so with SLOB
> >> gone, we can document it as supported.
> >> 
> >> Signed-off-by: Vlastimil Babka <vbabka@xxxxxxx>
> >> Cc: Mike Rapoport <rppt@xxxxxxxxxx>
> >> Cc: Jonathan Corbet <corbet@xxxxxxx>
> >> Cc: "Paul E. McKenney" <paulmck@xxxxxxxxxx>
> >> Cc: Frederic Weisbecker <frederic@xxxxxxxxxx>
> >> Cc: Neeraj Upadhyay <quic_neeraju@xxxxxxxxxxx>
> >> Cc: Josh Triplett <josh@xxxxxxxxxxxxxxxx>
> >> Cc: Steven Rostedt <rostedt@xxxxxxxxxxx>
> >> Cc: Mathieu Desnoyers <mathieu.desnoyers@xxxxxxxxxxxx>
> >> Cc: Lai Jiangshan <jiangshanlai@xxxxxxxxx>
> >> Cc: Joel Fernandes <joel@xxxxxxxxxxxxxxxxx>
> >> ---
> >>  Documentation/core-api/memory-allocation.rst | 15 +++++++++++----
> >>  include/linux/rcupdate.h                     |  6 ++++--
> >>  mm/slab_common.c                             |  5 +----
> >>  3 files changed, 16 insertions(+), 10 deletions(-)
> >> 
> >> diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
> >> index 5954ddf6ee13..f9e8d352ed67 100644
> >> --- a/Documentation/core-api/memory-allocation.rst
> >> +++ b/Documentation/core-api/memory-allocation.rst
> >> @@ -170,7 +170,14 @@ should be used if a part of the cache might be copied to the userspace.
> >>  After the cache is created kmem_cache_alloc() and its convenience
> >>  wrappers can allocate memory from that cache.
> >>  
> >> -When the allocated memory is no longer needed it must be freed. You can
> >> -use kvfree() for the memory allocated with `kmalloc`, `vmalloc` and
> >> -`kvmalloc`. The slab caches should be freed with kmem_cache_free(). And
> >> -don't forget to destroy the cache with kmem_cache_destroy().
> >> +When the allocated memory is no longer needed it must be freed. Objects
> > 
> > I'd add a line break before Objects                               ^
> > 
> >> +allocated by `kmalloc` can be freed by `kfree` or `kvfree`.
> >> +Objects allocated by `kmem_cache_alloc` can be freed with `kmem_cache_free`
> >> +or also by `kfree` or `kvfree`, which can be more convenient as it does
> > 
> > Maybe replace 'or also by' with a coma:
> > 
> > Objects allocated by `kmem_cache_alloc` can be freed with `kmem_cache_free`,
> > `kfree` or `kvfree`, which can be more convenient as it does
> 
> But then I need to clarify what the "which" applies to?

Yeah, I kinda missed that...

> > 
> >> +not require the kmem_cache pointed.
> > 
> >                              ^ pointer.
> > 
> >> +The rules for _bulk and _rcu flavors of freeing functions are analogical.
> > 
> > Maybe 
> > 
> > The same rules apply to _bulk and _rcu flavors of freeing functions.
> 
> So like this incremental diff?
 
> diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
> index f9e8d352ed67..1c58d883b273 100644
> --- a/Documentation/core-api/memory-allocation.rst
> +++ b/Documentation/core-api/memory-allocation.rst
> @@ -170,12 +170,14 @@ should be used if a part of the cache might be copied to the userspace.
>  After the cache is created kmem_cache_alloc() and its convenience
>  wrappers can allocate memory from that cache.
>  
> -When the allocated memory is no longer needed it must be freed. Objects
> -allocated by `kmalloc` can be freed by `kfree` or `kvfree`.
> -Objects allocated by `kmem_cache_alloc` can be freed with `kmem_cache_free`
> -or also by `kfree` or `kvfree`, which can be more convenient as it does
> -not require the kmem_cache pointed.
> -The rules for _bulk and _rcu flavors of freeing functions are analogical.
> +When the allocated memory is no longer needed it must be freed.
> +
> +Objects allocated by `kmalloc` can be freed by `kfree` or `kvfree`. Objects
> +allocated by `kmem_cache_alloc` can be freed with `kmem_cache_free`, `kfree`
> +or `kvfree`, where the latter two might be more convenient thanks to not
> +needing the kmem_cache pointer.

... but this way it's more explicit that kfree and kvfree don't need
kmem_cache pointer.

> +
> +The same rules apply to _bulk and _rcu flavors of freeing functions.
>  
>  Memory allocated by `vmalloc` can be freed with `vfree` or `kvfree`.
>  Memory allocated by `kvmalloc` can be freed with `kvfree`.
> 

-- 
Sincerely yours,
Mike.