mm, slab: restore kerneldoc for kmem_cache_create()
Subsystems (2)
PATCH 1/1 mm, slab: restore kerneldoc for kmem_cache_create()
As kmem_cache_create() became a _Generic() wrapper macro, it currently has no kerneldoc despite being the main API to use. Add it. Also adjust kmem_cache_create_usercopy() kerneldoc to indicate it is now a legacy wrapper.
Also expand the kerneldoc for struct kmem_cache_args, especially for the freeptr_offset field, where important details were removed with the removal of kmem_cache_create_rcu().
---
A late change, but only changes comments and it means we won't regress the kerneldocs due to the refactoring. Further improvements are possible (i.e. turning descriptions of the main SLAB_ flags to kerneldocs) but that can wait.
include/linux/slab.h | 114 ++++++++++++++++++++++++++++++++++--------- mm/slab_common.c | 10 ++-- 2 files changed, 98 insertions(+), 26 deletions(-)
include/linux/slab.h +91 -23
@@ -242,19 +242,72 @@ bool slab_is_available(void);/** * struct kmem_cache_args - Less common arguments for kmem_cache_create() -* @align: The required alignment for the objects. -* @useroffset: Usercopy region offset -* @usersize: Usercopy region size -* @freeptr_offset: Custom offset for the free pointer in RCU caches -* @use_freeptr_offset: Whether a @freeptr_offset is used -* @ctor: A constructor for the objects. +* +* Any uninitialized fields of the structure are interpreted as unused. The +* exception is @freeptr_offset where %0 is a valid value, so +* @use_freeptr_offset must be also set to %true in order to interpret the field +* as used. For @useroffset %0 is also valid, but only with non-%0 +* @usersize. +* +* When %NULL args is passed to kmem_cache_create(), it is equivalent to all +* fields unused. */ struct kmem_cache_args { +/** +* @align: The required alignment for the objects. +* +* %0 means no specific alignment is requested. +*/ unsigned int align; +/** +* @useroffset: Usercopy region offset. +* +* %0 is a valid offset, when @usersize is non-%0 +*/ unsigned int useroffset; +/** +* @usersize: Usercopy region size. +* +* %0 means no usercopy region is specified. +*/ unsigned int usersize; +/** +* @freeptr_offset: Custom offset for the free pointer +* in &SLAB_TYPESAFE_BY_RCU caches +* +* By default &SLAB_TYPESAFE_BY_RCU caches place the free pointer +* outside of the object. This might cause the object to grow in size. +* Cache creators that have a reason to avoid this can specify a custom +* free pointer offset in their struct where the free pointer will be +* placed. +* +* Note that placing the free pointer inside the object requires the +* caller to ensure that no fields are invalidated that are required to +* guard against object recycling (See &SLAB_TYPESAFE_BY_RCU for +* details). +* +* Using %0 as a value for @freeptr_offset is valid. If @freeptr_offset +* is specified, %use_freeptr_offset must be set %true. +* +* Note that @ctor currently isn't supported with custom free pointers +* as a @ctor requires an external free pointer. +*/ unsigned int freeptr_offset; +/** +* @use_freeptr_offset: Whether a @freeptr_offset is used. +*/ bool use_freeptr_offset; +/** +* @ctor: A constructor for the objects. +* +* The constructor is invoked for each object in a newly allocated slab +* page. It is the cache user's responsibility to free object in the +* same state as after calling the constructor, or deal appropriately +* with any differences between a freshly constructed and a reallocated +* object. +* +* %NULL means no constructor. +*/ void (*ctor)(void *); };
@@ -275,30 +328,20 @@ __kmem_cache_create(const char *name, unsigned int size, unsigned int align, }/** -* kmem_cache_create_usercopy - Create a cache with a region suitable -* for copying to userspace +* kmem_cache_create_usercopy - Create a kmem cache with a region suitable +* for copying to userspace. * @name: A string which is used in /proc/slabinfo to identify this cache. * @size: The size of objects to be created in this cache. * @align: The required alignment for the objects. * @flags: SLAB flags * @useroffset: Usercopy region offset * @usersize: Usercopy region size -* @ctor: A constructor for the objects. -* -* Cannot be called within a interrupt, but can be interrupted. -* The @ctor is run when new pages are allocated by the cache. -* -* The flags are +* @ctor: A constructor for the objects, or %NULL. * -* %SLAB_POISON - Poison the slab with a known test pattern (a5a5a5a5) -* to catch references to uninitialised memory. -* -* %SLAB_RED_ZONE - Insert `Red` zones around the allocated memory to check -* for buffer overruns. -* -* %SLAB_HWCACHE_ALIGN - Align the objects in this cache to a hardware -* cacheline. This can be beneficial if you're counting cycles as closely -* as davem. +* This is a legacy wrapper, new code should use either KMEM_CACHE_USERCOPY() +* if whitelisting a single field is sufficient, or kmem_cache_create() with +* the necessary parameters passed via the args parameter (see +* &struct kmem_cache_args) * * Return: a pointer to the cache on success, NULL on failure. */
@@ -333,6 +376,31 @@ __kmem_cache_default_args(const char *name, unsigned int size,return __kmem_cache_create_args (name, size, &kmem_default_args, flags); } +/** +* kmem_cache_create - Create a kmem cache. +* @__name: A string which is used in /proc/slabinfo to identify this cache. +* @__object_size: The size of objects to be created in this cache. +* @__args: Optional arguments, see &struct kmem_cache_args. Passing %NULL +* means defaults will be used for all the arguments. +* +* This is currently implemented as a macro using ``_Generic()`` to call +* either the new variant of the function, or a legacy one. +* +* The new variant has 4 parameters: +* ``kmem_cache_create(name, object_size, args, flags)`` +* +* See __kmem_cache_create_args() which implements this. +* +* The legacy variant has 5 parameters: +* ``kmem_cache_create(name, object_size, align, flags, ctor)`` +* +* The align and ctor parameters map to the respective fields of +* &struct kmem_cache_args +* +* Context: Cannot be called within a interrupt, but can be interrupted. +* +* Return: a pointer to the cache on success, NULL on failure. +*/ #define kmem_cache_create (__name, __object_size, __args, ...) \ _Generic((__args), \ struct kmem_cache_args *: __kmem_cache_create_args, \
mm/slab_common.c +7 -3
@@ -239,13 +239,17 @@ static struct kmem_cache *create_cache(const char *name, }/** -* __kmem_cache_create_args - Create a kmem cache +* __kmem_cache_create_args - Create a kmem cache. * @name: A string which is used in /proc/slabinfo to identify this cache. * @object_size: The size of objects to be created in this cache. -* @args: Arguments for the cache creation (see struct kmem_cache_args). +* @args: Additional arguments for the cache creation (see +* &struct kmem_cache_args). * @flags: See %SLAB_* flags for an explanation of individual @flags. * -* Cannot be called within a interrupt, but can be interrupted. +* Not to be called directly, use the kmem_cache_create() wrapper with the same +* parameters. +* +* Context: Cannot be called within a interrupt, but can be interrupted. * * Return: a pointer to the cache on success, NULL on failure. */
Signature · 1 line
2.46.0
Quoted 9 lines · Vlastimil Babka
As
kmem_cache_create()became a_Generic()wrapper macro, it currently has no kerneldoc despite being the main API to use. Add it. Also adjustkmem_cache_create_usercopy()kerneldoc to indicate it is now a legacy wrapper.Also expand the kerneldoc for struct
kmem_cache_args, especially for thefreeptr_offsetfield, where important details were removed with the removal ofkmem_cache_create_rcu().
Quoted 6 lines
Signed-off-by Vlastimil Babka <[email protected]>---
A late change, but only changes comments and it means we won't regress the kerneldocs due to the refactoring. Further improvements are possible (i.e. turning descriptions of the mainSLAB_flags to kerneldocs) but that can wait.
Looks good to me,
Quoted 10 lines · Vlastimil Babka
As
kmem_cache_create()became a_Generic()wrapper macro, it currently has no kerneldoc despite being the main API to use. Add it. Also adjustkmem_cache_create_usercopy()kerneldoc to indicate it is now a legacy wrapper.Also expand the kerneldoc for struct
kmem_cache_args, especially for thefreeptr_offsetfield, where important details were removed with the removal ofkmem_cache_create_rcu().Signed-off-by Vlastimil Babka <[email protected]>