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

[Vlastimil Babka <vbabka@suse.cz>]

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@suse.cz>
>> Cc: Mike Rapoport <rppt@kernel.org>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Cc: "Paul E. McKenney" <paulmck@kernel.org>
>> Cc: Frederic Weisbecker <frederic@kernel.org>
>> Cc: Neeraj Upadhyay <quic_neeraju@quicinc.com>
>> Cc: Josh Triplett <josh@joshtriplett.org>
>> Cc: Steven Rostedt <rostedt@goodmis.org>
>> Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
>> Cc: Lai Jiangshan <jiangshanlai@gmail.com>
>> Cc: Joel Fernandes <joel@joelfernandes.org>
>> ---
>>  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?

> 
>> +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.
+
+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`.